mavis_session_messages

Instructions

Implementation Reference

• src/index.js:128-140 (handler)

  The tool 'mavis_session_messages' is defined as a tool spec at lines 128-140. When invoked, its handler (runTool at line 77) calls execMavisJSON (line 84) with args ['session', 'messages', sessionId, '--limit', limit]. The result is JSON.stringify'd and returned as text content.

  {
    name: 'mavis_session_messages',
    description: 'Get the message history (conversation transcript) of a session.',
    inputSchema: z.object({
      sessionId: z.string().describe('Session ID'),
      limit: z.number().optional().describe('Max messages to return (default: 50)')
    }),
    buildArgs: ({ sessionId, limit }) => {
      const args = ['session', 'messages', sessionId];
      if (limit) args.push('--limit', String(limit));
      return args;
    }
  },

• src/index.js:131-134 (schema)

  Input schema for mavis_session_messages: sessionId (required string) and limit (optional number, default 50).

  inputSchema: z.object({
    sessionId: z.string().describe('Session ID'),
    limit: z.number().optional().describe('Max messages to return (default: 50)')
  }),

• src/index.js:98-467 (registration)

  The tool is registered in the `tools` array (line 98-467). The MavisServer class (line 473) creates a toolMap (line 484) and registers handlers via ListToolsRequestSchema (line 486) and CallToolRequestSchema (line 494) to expose it via MCP.

  const tools = [
  
    // ── Session Management ──────────────────────
  
    {
      name: 'mavis_session_list',
      description: 'List Mavis sessions. Returns session IDs, titles, and last-updated timestamps.',
      inputSchema: z.object({
        agentId: z.string().optional().describe('Agent name (default: all agents)'),
        limit: z.number().optional().describe('Max sessions to return (default: 20)'),
        includeArchived: z.boolean().optional().describe('Include compressed/archived sessions')
      }),
      buildArgs: ({ agentId, limit, includeArchived }) => {
        const args = ['session', 'list'];
        if (agentId) args.push(agentId);
        if (limit) args.push('--limit', String(limit));
        if (includeArchived) args.push('--include-compressed');
        return args;
      }
    },
  
    {
      name: 'mavis_session_info',
      description: 'Get detailed info about a specific session (status, workspace, model, etc.)',
      inputSchema: z.object({
        sessionId: z.string().describe('Session ID (e.g. mvs_xxx)')
      }),
      buildArgs: ({ sessionId }) => ['session', 'info', sessionId]
    },
  
    {
      name: 'mavis_session_messages',
      description: 'Get the message history (conversation transcript) of a session.',
      inputSchema: z.object({
        sessionId: z.string().describe('Session ID'),
        limit: z.number().optional().describe('Max messages to return (default: 50)')
      }),
      buildArgs: ({ sessionId, limit }) => {
        const args = ['session', 'messages', sessionId];
        if (limit) args.push('--limit', String(limit));
        return args;
      }
    },
  
    {
      name: 'mavis_session_new',
      description: 'Create a new standalone Mavis session (use --from root for isolated, independent session). For child sessions linked to a parent, use mavis_spawn_worker instead.',
      inputSchema: z.object({
        agent: z.string().describe('Agent name (e.g. mavis, coder, general, verifier)'),
        prompt: z.string().optional().describe('Initial prompt to send to the new session'),
        title: z.string().optional().describe('Optional session title'),
        workspace: z.string().optional().describe('Session workspace directory path'),
        model: z.string().optional().describe('Override LLM model (providerID/modelID format)')
      }),
      buildArgs: ({ agent, prompt, title, workspace, model }) => {
        const args = ['session', 'new', agent, '--from', 'root', '--prompt', prompt || 'hello'];
        if (title) args.push('--title', title);
        if (workspace) args.push('--workspace', workspace);
        if (model) args.push('--model', model);
        return args;
      }
    },
  
    {
      name: 'mavis_session_abort',
      description: 'Abort a running session.',
      inputSchema: z.object({
        sessionId: z.string().describe('Session ID to abort')
      }),
      execFn: execMavis,
      outputMode: OUTPUT_RAW,
      buildArgs: ({ sessionId }) => ['session', 'abort', sessionId]
    },
  
    {
      name: 'mavis_session_rotate',
      description: 'Rotate the current session — archives the old session and creates a fresh one with a handoff prompt.',
      inputSchema: z.object({}),
      buildArgs: () => ['session', 'rotate']
    },
  
    {
      name: 'mavis_session_diff',
      description: 'Show file changes (git diff) made by a session.',
      inputSchema: z.object({
        sessionId: z.string().describe('Session ID')
      }),
      execFn: execMavis,
      outputMode: OUTPUT_RAW,
      buildArgs: ({ sessionId }) => ['session', 'diff', sessionId]
    },
  
    // ── Communication / Messaging ───────────────
  
    {
      name: 'mavis_comm_send',
      description: 'Send a message or command to a running session (prompt/abort/kill/summarize/fork/spawn).',
      inputSchema: z.object({
        to: z.string().describe('Target session ID'),
        command: z.enum(['prompt', 'abort', 'kill', 'summarize', 'fork', 'spawn']).describe('Command to send'),
        content: z.string().optional().describe('Message content (for prompt command)'),
        from: z.string().optional().describe('Sender session ID (default: parent session)')
      }),
      buildArgs: ({ to, command, content, from }) => {
        const args = ['communication', 'send'];
        if (from) args.push('--from', from);
        args.push('--to', to, '--command', command);
        if (content) args.push('--content', content);
        return args;
      }
    },
  
    {
      name: 'mavis_comm_peers',
      description: 'List all reachable (active) sessions in the Mavis network.',
      inputSchema: z.object({
        agent: z.string().optional().describe('Filter by agent name (e.g. mavis, coder, general)'),
        sessionId: z.string().optional().describe('Session ID to query peers for (defaults to __MAVIS_PARENT_SESSION_ID)')
      }),
      buildArgs: ({ agent, sessionId }) => {
        const args = ['communication', 'peers'];
        if (agent) args.push('--agent', agent);
        // validation delegated to buildArgs so the caller can handle the error cleanly
        const effectiveSessionId = sessionId || process.env.__MAVIS_PARENT_SESSION_ID;
        if (!effectiveSessionId) throw new Error('sessionId is required when __MAVIS_PARENT_SESSION_ID is not set');
        args.push('--session', effectiveSessionId);
        return args;
      }
    },
  
    // ── Team Management ─────────────────────────
  
    {
      name: 'mavis_team_plan',
      description: 'List team plans or get status of a specific plan. Use `team plan status <id>` to view details. Create plans via YAML files with `team plan run <yaml>` (not exposed here — use mavis_session_new for one-off tasks).',
      inputSchema: z.object({
        planId: z.string().optional().describe('Plan ID to get status for (omit to list all plans)')
      }),
      buildArgs: ({ planId }) => planId ? ['team', 'plan', 'status', planId] : ['team', 'plan', 'status']
    },
  
    // ── Agent Management ────────────────────────
  
    {
      name: 'mavis_agent_list',
      description: 'List all available Mavis agents (built-in and custom).',
      inputSchema: z.object({}),
      buildArgs: () => ['agent', 'list']
    },
  
    {
      name: 'mavis_agent_info',
      description: 'Get detailed info about a specific agent (skills, system prompt, etc.)',
      inputSchema: z.object({
        agentName: z.string().describe('Agent name')
      }),
      buildArgs: ({ agentName }) => {
        if (!agentName) throw new Error('agentName is required');
        return ['agent', 'info', agentName];
      }
    },
  
    // ── Memory ──────────────────────────────────
  
    {
      name: 'mavis_memory_append',
      description: 'Append a new entry to Mavis memory (user, agent, or project level).',
      inputSchema: z.object({
        scope: z.enum(['user', 'agent', 'project']).describe('Memory scope'),
        agentName: z.string().optional().describe('Agent name (required when scope=agent)'),
        content: z.string().describe('Content to append'),
        topic: z.string().optional().describe('Topic label for the entry')
      }),
      execFn: execMavis,
      outputMode: OUTPUT_RAW,
      stdin: ({ topic, content }) => topic
        ? `### ${topic} (${new Date().toISOString().split('T')[0]})\n${content}`
        : content,
      buildArgs: ({ scope, agentName }) => {
        const args = ['memory', 'append'];
        if (scope !== 'user') args.push(scope);
        if (agentName) args.push(agentName);
        return args;
      }
    },
  
    {
      name: 'mavis_memory_search',
      description: 'Search Mavis memory for entries matching a query.',
      inputSchema: z.object({
        scope: z.enum(['user', 'agent', 'project']).optional().describe('Memory scope to search'),
        query: z.string().describe('Search query')
      }),
      buildArgs: ({ scope, query }) => {
        const args = ['memory', 'search', query];
        if (scope) args.unshift(scope);
        return args;
      }
    },
  
    // ── Cron / Scheduling ───────────────────────
  
    {
      name: 'mavis_cron_create',
      description: 'Create a scheduled cron job (self-reminder, recurring task, etc.)',
      inputSchema: z.object({
        agentName: z.string().describe('Agent name or ID to own the cron task'),
        cronName: z.string().describe('Cron task name'),
        schedule: z.string().describe('Cron schedule expression (e.g. "*/5 * * * *" for every 5 min)'),
        prompt: z.string().describe('Prompt to send when the cron fires'),
        timezone: z.string().optional().describe('Timezone (e.g. Asia/Shanghai)'),
        sessionMode: z.enum(['sessionId', 'new']).optional().describe('Session mode: sessionId or new'),
        sessionId: z.string().optional().describe('Session ID when sessionMode=sessionId'),
        disable: z.boolean().optional().describe('Create the task disabled')
      }),
      execFn: execMavis,
      outputMode: OUTPUT_RAW,
      buildArgs: ({ agentName, cronName, schedule, prompt, timezone, sessionMode, sessionId, disable }) => {
        const args = ['cron', 'create', agentName, cronName, '--schedule', schedule, '--prompt', prompt];
        if (timezone) args.push('--timezone', timezone);
        if (sessionMode) args.push('--session-mode', sessionMode);
        if (sessionId) args.push('--session-id', sessionId);
        if (disable) args.push('--disable');
        return args;
      }
    },
  
    {
      name: 'mavis_cron_list',
      description: 'List all scheduled cron jobs for an agent.',
      inputSchema: z.object({
        agentName: z.string().optional().describe('Agent name to list crons for (default: mavis)')
      }),
      buildArgs: ({ agentName }) => ['cron', 'list', agentName || 'mavis']
    },
  
    {
      name: 'mavis_cron_delete',
      description: 'Delete a cron job.',
      inputSchema: z.object({
        agentName: z.string().describe('Agent name or ID that owns the cron task'),
        cronName: z.string().describe('Cron task name')
      }),
      execFn: execMavis,
      outputMode: OUTPUT_RAW,
      buildArgs: ({ agentName, cronName }) => ['cron', 'delete', agentName, cronName]
    },
  
    // ── Skills ──────────────────────────────────
  
    {
      name: 'mavis_skill_list',
      description: 'List all installed Mavis skills (global and agent-specific).',
      inputSchema: z.object({}),
      buildArgs: () => ['skill', 'list']
    },
  
    {
      name: 'mavis_skill_info',
      description: 'Get detailed info about a specific skill (description, triggers, commands).',
      inputSchema: z.object({
        skillName: z.string().describe('Skill name'),
        agentName: z.string().optional().describe('Agent name to scope the lookup')
      }),
      buildArgs: ({ skillName, agentName }) => {
        if (!skillName) throw new Error('skillName is required');
        const args = ['skill', 'show', skillName];
        if (agentName) args.push('--agent', agentName);
        return args;
      }
    },
  
    // ── Hooks ───────────────────────────────────
  
    {
      name: 'mavis_hook_list',
      description: 'List all registered Mavis hooks (pre/post execution triggers).',
      inputSchema: z.object({}),
      buildArgs: () => ['hook', 'list']
    },
  
    // ── Config ──────────────────────────────────
  
    {
      name: 'mavis_config_show',
      description: 'Show current Mavis daemon configuration (models, provider, nexus settings).',
      inputSchema: z.object({}),
      buildArgs: () => ['config', 'show']
    },
  
    // ── MCP Servers ─────────────────────────────
  
    {
      name: 'mavis_mcp_list',
      description: 'List all registered MCP servers and their available tools.',
      inputSchema: z.object({}),
      buildArgs: () => ['mcp', 'list']
    },
  
    {
      name: 'mavis_mcp_call',
      description: 'Call a specific tool on an MCP server. Useful for delegating to Playwright, Matrix, or other MCP tools from within Mavis.',
      inputSchema: z.object({
        server: z.string().describe('MCP server name (e.g. playwright, matrix, cu)'),
        tool: z.string().describe('Tool name to call'),
        args: z.string().optional().describe('JSON string of tool arguments')
      }),
      execFn: execMavis,
      outputMode: OUTPUT_RAW,
      buildArgs: ({ server, tool, args }) => {
        const callArgs = ['mcp', 'call', server, tool];
        if (args) callArgs.push(args);
        return callArgs;
      }
    },
  
    // ── Daemon / Status ─────────────────────────
  
    {
      name: 'mavis_status',
      description: 'Check Mavis daemon status (running, port, version).',
      inputSchema: z.object({}),
      buildArgs: () => ['status']
    },
  
    // ── Spawn (Worker Agents) ────────────────────
  
    {
      name: 'mavis_spawn_worker',
      description: 'Spawn a single-shot worker/verifier agent as a child session. Use for code review, test, verify tasks. The agent runs independently and reports back. For complex multi-agent tasks, use mavis_team_plan instead.',
      inputSchema: z.object({
        agent: z.string().describe('Agent name (e.g. general, coder, verifier)'),
        prompt: z.string().describe('Task description for the worker agent'),
        workspace: z.string().optional().describe('Working directory for the worker'),
        parentSession: z.string().optional().describe('Parent session ID (for result routing)')
      }),
      buildArgs: ({ agent, prompt, workspace, parentSession }) => {
        const args = ['session', 'new', agent];
        if (parentSession) args.push('--from', parentSession);
        else args.push('--from', 'root');
        if (workspace) args.push('--workspace', workspace);
        args.push('--prompt', prompt);
        return args;
      }
    },
  
    // ── Usage / Stats ────────────────────────────
  
    {
      name: 'mavis_usage',
      description: 'Inspect token usage by session, agent, or globally.',
      inputSchema: z.object({
        sessionId: z.string().optional().describe('Session ID to query usage for'),
        agentName: z.string().optional().describe('Agent name to query usage for'),
        from: z.number().optional().describe('Start of time range (unix-ms)'),
        to: z.number().optional().describe('End of time range (unix-ms)'),
        group: z.enum(['agent', 'session', 'model', 'day']).optional().describe('Group by dimension')
      }).strict(),
      buildArgs: ({ sessionId, agentName, from, to, group }) => {
        const args = sessionId ? ['usage', 'session', sessionId]
          : agentName ? ['usage', 'agent', agentName]
          : ['usage', 'list'];
        if (from !== undefined) args.push('--from', String(from));
        if (to !== undefined) args.push('--to', String(to));
        if (group) args.push('--group', group);
        args.push('--json');
        return args;
      }
    }
  ];

• src/index.js:77-92 (helper)

  runTool (line 77) is the generic helper that executes any tool spec. For mavis_session_messages (no execFn), it calls execMavisJSON(args) which spawns the mavis binary and parses JSON output. The result is JSON.stringify'd as text content.

  function runTool(spec, parsedArgs) {
    const { execFn, outputMode, stdin, buildArgs } = spec;
    const args = buildArgs(parsedArgs);
    const input = typeof stdin === 'function' ? stdin(parsedArgs) : stdin;
  
    const execPromise = execFn
      ? execMavis(args, input || '')
      : execMavisJSON(args);
  
    return execPromise.then(result => {
      const text = outputMode === OUTPUT_RAW
        ? (result || '')
        : JSON.stringify(result, null, 2);
      return [{ type: 'text', text }];
    });
  }

• src/index.js:55-64 (helper)

  execMavisJSON wraps execMavis to parse JSON output. This is the execution helper used by mavis_session_messages (since no execFn is specified).

  function execMavisJSON(args) {
    return execMavis(args).then(raw => {
      try {
        return JSON.parse(raw);
      } catch {
        const jsonStart = raw.indexOf('{');
        return JSON.parse(jsonStart >= 0 ? raw.slice(jsonStart) : raw);
      }
    });
  }