Two-way collaboration with the Agent

​

Three channels

​

Let the Agent call your Mini App: managed MCP

• Ordinary plugin MCP: runs independently (for example over stdio) without the Mini App’s Node service. Don’t list it in mcpEndpoints.
• Mini App-managed MCP: implemented by the Mini App’s Node service and available only while it runs. Use it when tools should share business state with the page.

{
  "schemaVersion": 1,
  "mcpServers": {
    "board-summary": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:9/mcp/board-summary",
      "headers": {},
      "description": "Summarizes the current board data.",
      "timeout": 30000
    }
  }
}

{
  "mcpEndpoints": [
    { "server": "board-summary", "path": "/mcp/board-summary" }
  ]
}

• Before start returns, the Node entry must implement Streamable HTTP MCP at that path on context.listen. The host rewrites only this server’s address; tool discovery, ordering, calls, and errors stay with the plugin MCP runtime.
• When the user sends a message that references the Mini App, the host starts the service, connects MCP, and confirms the tools are available before calling the model. If a required managed MCP is unavailable, the request fails instead of letting the model continue without its tools.
• Keep tools/list light: return tool definitions only, without importing data, scanning documents, or calling remote services. Put business initialization in the tool calls that need it.
• A broken MCP handler doesn’t affect the page, but the Agent can’t use those tools until you fix it and publish again.

​

Hand off to the message input

​

Agent API

​

Enable it

{
  "agentAccess": ["session.run"],
  "agentConcurrency": 4
}

• Without agentAccess, access is denied. Declare "session.run" to run turns, "session.read" to read and observe user conversations, or both. Neither permission grants the other.
• agentConcurrency is optional, from 1 to 32, default 4: how many turns this Mini App runs at once. Extra calls wait in order, in a queue up to four times the concurrency. Each session runs one turn at a time.
• Grants take effect with the process: changing agentAccess and publishing again restarts the service.
• Users can switch running and reading permissions off separately in plugin details without a restart. Switching running off aborts this Mini App’s in-flight turns; switching reading off ends the affected observers. The API object stays present, so handle permission errors at the call site.

​

Who owns a session

​

Methods

​

Follow up while a session is busy

const result = await agent.run({ sessionId, text, whenBusy: 'queue' });

• queue: the message runs as its own turn after the current turn finishes and returns that turn’s result.
• steer: hands the message to the running turn to adjust its work. Once read, the follow-up resolves with status: 'steered' and no separate text; the original turn’s call receives the reply. If that turn finishes before reading the message, the message runs as the next turn instead.
• On an idle session, both start a turn immediately. Without whenBusy, a busy session rejects with busy on the page or BUSY in Node.
• After the user stops a session, its existing queue may pause and follow-ups wait for the user to resume it. Waiting keeps a run slot; cancel the call to give it up. A steered message already handed to the running turn cannot be withdrawn.

​

Read and observe user conversations

{
  "agentAccess": ["session.read"]
}

• sessions() returns { sessions }, with up to 50 recently updated user conversations. Mini App, scheduled, and sub-Agent sessions are excluded.
• session(sessionId) returns the conversation’s state, project directory, model, and latest assistant reply when available. On the page, session() without an ID reads the chat it is open in, or returns undefined when it is not in a chat. Node has no current chat and requires an explicit ID.
• observe({ all: true }, { onEvent }) receives turn.started, the final reply in message.committed, and turn.finished from every user conversation. Passing sessionId observes that conversation’s progress instead. Observers never receive approvals or questionnaires.
• Observation is not a run and takes no run slot; each Mini App has up to four subscriptions. The page ends one with the requestId passed to observe and cancel(requestId); Node uses signal in the second argument. Closing the page, ending the service, or switching reading off also ends the affected subscriptions.
• Reading or observing this Mini App’s own sessions can also be authorized by session.run. Other Mini Apps’ sessions and sub-Agent sessions cannot be read.

​

Approvals and questionnaires

• permission.requested → reply: a tool call waits for approval. Only “allow once” and “deny” exist; there is no “always allow”, because a Mini App never writes the user’s global permission rules.
• question.requested → answer: the turn paused on a questionnaire (ask_user, a feature enable, or a Plan review). Call answer after the paused run returns.
• An approval waits only while someone can answer it: the call passed onEvent, or a page has the session open in the sidebar through open. Otherwise it is denied, and the model is told that nobody can approve it and to continue without the tool.
• There is no timeout. A waiting call is released by cancellation, process exit, or republishing.
• When the Agent delegates to a child session, the child’s approvals also arrive through onEvent, with the child’s own sessionId. Don’t filter events by the root turn, or the call waits forever.

​

Page example

const agent = window.mcode?.miniapp?.agent;
if (agent) {
  const result = await agent.run(
    { text: 'Summarize this week\'s risks for the current filters and list what needs my confirmation.' },
    {
      onEvent(event) {
        if (event.type === 'text.delta') output.textContent += event.text;
        if (event.type === 'permission.requested') {
          // Render an approval card on the page; after the user decides, call:
          // agent.reply({ sessionId: event.sessionId, requestId: event.requestId, decision: 'allowOnce' })
          renderApproval(event);
        }
      },
    },
  );
  if (result.pendingQuestion) renderQuestionnaire(result.pendingQuestion.request);
  openInChatButton.onclick = () => agent.open(result.sessionId);
}

​

Node example

import type {
  MiniAppAgentClient,
  MiniAppAgentQuestionAnswer,
  MiniAppAgentQuestionnaire,
  MiniAppAgentRunEvent,
} from './miniapp-api.js';

// Your own UI round trips, for example an SSE push to the page and a POST back.
declare function askUser(request: MiniAppAgentQuestionnaire): Promise<MiniAppAgentQuestionAnswer[]>;
declare function confirmTool(toolName: string, reason: string): Promise<boolean>;

async function runWithQuestions(agent: MiniAppAgentClient, text: string) {
  const onEvent = (event: MiniAppAgentRunEvent) => {
    if (event.type !== 'permission.requested') return;
    // The run waits for this decision; the event names the session even on its first run.
    void confirmTool(event.toolName, event.reason)
      .then((allowed) =>
        agent.reply({
          sessionId: event.sessionId,
          requestId: event.requestId,
          decision: allowed ? 'allowOnce' : 'deny',
        }),
      )
      .catch(() => {}); // REQUEST_NOT_FOUND: the run was cancelled meanwhile.
  };
  let result = await agent.run({ text }, { onEvent });
  // Answer only after the run resolves: until then it holds the session's single-run slot.
  while (result.pendingQuestion) {
    const answers = await askUser(result.pendingQuestion.request);
    result = await agent.answer(
      { sessionId: result.sessionId, requestId: result.pendingQuestion.requestId, answers },
      { onEvent },
    );
  }
  return result;
}

​

Events

​

Design guidance

• Put the task, data scope, required interaction, success criteria, and stop conditions in text. Page labels, form state, and the host chat’s context aren’t carried over automatically.
• deny rejects only that one tool request; it doesn’t put the file off-limits from then on. Enforce boundaries that must hold across calls with host permissions or Hook rules.
• A root turn’s finished status doesn’t mean background child tasks are done. If you need a child’s result, use foreground delegation in the business request.
• AGENT_OUTCOME_UNKNOWN means the turn may already have run. Reconcile the session state first; don’t retry automatically.