v2.2-paseo-providers: Paseo provider stack + v2.2.1 pane-scoped chat fixes

Ship Paseo-equivalent provider snapshot, AgentComposerBar, ACP dispatch rewrite with streaming/persist, permission prompts, and agent commands. Follow-up: pane-scoped chat resolution, CoderMessageList tool timeline, WS user-delta replace, and inference orphan tool_call stripping. Archive openspec v2-2; update CHANGELOG and CURRENT. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-26 15:18:31 +00:00
parent 04673eaf59
commit 93d3f86c2b
96 changed files with 6694 additions and 1329 deletions
--- a/apps/server/src/index.ts
+++ b/apps/server/src/index.ts
@@ -14,6 +14,7 @@ import { registerArtifactRoutes } from './routes/artifacts.js';
 import { registerChatRoutes } from './routes/chats.js';
 import { registerSidebarRoutes } from './routes/sidebar.js';
 import { registerWebSocket } from './routes/ws.js';
+import { registerCoderProxy } from './routes/coder-proxy.js';
 import { registerModelRoutes } from './routes/models.js';
 import { registerAgentRoutes } from './routes/agents.js';
 import { registerSkillsRoutes } from './routes/skills.js';
@@ -212,36 +213,10 @@ async function main() {
  });
  registerWebSocket(app, sql, broker);

-  // v2.0.0: reverse proxy /api/coder/* to the boocoder container. Keeps the
-  // SPA's HTTP requests going through a single origin (avoids CORS). WS for
-  // the coder pane connects directly to boocoder:9502 from the browser (same
-  // Tailscale network — no CORS issue for WebSocket upgrade requests).
+  // v2.0.0: reverse proxy /api/coder/* to boocoder (HTTP + WS). CoderPane
+  // connects WS through /api/coder/ws/sessions/:id on the same origin.
  const BOOCODER_ORIGIN = process.env.BOOCODER_URL ?? 'http://boocoder:3000';
-  app.all('/api/coder/*', async (req, reply) => {
-    const targetPath = req.url.replace('/api/coder', '/api');
-    const targetUrl = `${BOOCODER_ORIGIN}${targetPath}`;
-    const headers: Record<string, string> = {};
-    if (req.headers['content-type']) headers['content-type'] = req.headers['content-type'] as string;
-    if (req.headers['authorization']) headers['authorization'] = req.headers['authorization'] as string;
-
-    try {
-      const res = await fetch(targetUrl, {
-        method: req.method as string,
-        headers,
-        body: req.method !== 'GET' && req.method !== 'HEAD' ? JSON.stringify(req.body) : undefined,
-      });
-      reply.code(res.status);
-      for (const [key, value] of res.headers) {
-        if (key === 'transfer-encoding') continue;
-        reply.header(key, value);
-      }
-      const body = await res.text();
-      return reply.send(body);
-    } catch (err) {
-      app.log.error({ err, targetUrl }, 'coder proxy error');
-      reply.code(502).send({ error: 'boocoder backend unavailable' });
-    }
-  });
+  registerCoderProxy(app, BOOCODER_ORIGIN);

  const webDist = process.env.WEB_DIST_PATH ?? resolve(process.cwd(), '../web/dist');
  if (existsSync(webDist)) {
--- a/apps/server/src/routes/coder-proxy.ts
+++ b/apps/server/src/routes/coder-proxy.ts
@@ -0,0 +1,91 @@
+import type { FastifyInstance } from 'fastify';
+import WebSocket from 'ws';
+
+function boocoderWsUrl(origin: string, path: string): string {
+  const u = new URL(origin);
+  u.protocol = u.protocol === 'https:' ? 'wss:' : 'ws:';
+  u.pathname = path;
+  u.search = '';
+  return u.toString();
+}
+
+/**
+ * Reverse-proxy BooCoder HTTP + WebSocket through BooChat's single origin.
+ * WS must be registered before the HTTP catch-all — fetch() cannot upgrade.
+ */
+export function registerCoderProxy(app: FastifyInstance, boocoderOrigin: string): void {
+  app.get<{ Params: { sessionId: string } }>(
+    '/api/coder/ws/sessions/:sessionId',
+    { websocket: true },
+    (clientSocket, req) => {
+      const sessionId = req.params.sessionId;
+      const target = boocoderWsUrl(boocoderOrigin, `/api/ws/sessions/${sessionId}`);
+      const upstream = new WebSocket(target);
+
+      upstream.on('open', () => {
+        app.log.debug({ sessionId }, 'coder ws proxy: upstream connected');
+      });
+
+      upstream.on('message', (data, isBinary) => {
+        if (clientSocket.readyState !== clientSocket.OPEN) return;
+        clientSocket.send(data, { binary: isBinary });
+      });
+
+      upstream.on('close', (code, reason) => {
+        if (clientSocket.readyState === clientSocket.OPEN) {
+          clientSocket.close(code, reason.toString());
+        }
+      });
+
+      upstream.on('error', (err) => {
+        app.log.warn({ err, sessionId, target }, 'coder ws proxy: upstream error');
+        if (clientSocket.readyState === clientSocket.OPEN) {
+          clientSocket.close(1011, 'upstream error');
+        }
+      });
+
+      clientSocket.on('message', (data, isBinary) => {
+        if (upstream.readyState !== WebSocket.OPEN) return;
+        upstream.send(data, { binary: isBinary });
+      });
+
+      clientSocket.on('close', () => {
+        if (upstream.readyState === WebSocket.OPEN || upstream.readyState === WebSocket.CONNECTING) {
+          upstream.close();
+        }
+      });
+
+      clientSocket.on('error', () => {
+        if (upstream.readyState === WebSocket.OPEN || upstream.readyState === WebSocket.CONNECTING) {
+          upstream.close();
+        }
+      });
+    },
+  );
+
+  app.all('/api/coder/*', async (req, reply) => {
+    const targetPath = req.url.replace('/api/coder', '/api');
+    const targetUrl = `${boocoderOrigin}${targetPath}`;
+    const headers: Record<string, string> = {};
+    if (req.headers['content-type']) headers['content-type'] = req.headers['content-type'] as string;
+    if (req.headers['authorization']) headers['authorization'] = req.headers['authorization'] as string;
+
+    try {
+      const res = await fetch(targetUrl, {
+        method: req.method as string,
+        headers,
+        body: req.method !== 'GET' && req.method !== 'HEAD' ? JSON.stringify(req.body) : undefined,
+      });
+      reply.code(res.status);
+      for (const [key, value] of res.headers) {
+        if (key === 'transfer-encoding') continue;
+        reply.header(key, value);
+      }
+      const body = await res.text();
+      return reply.send(body);
+    } catch (err) {
+      app.log.error({ err, targetUrl }, 'coder proxy error');
+      reply.code(502).send({ error: 'boocoder backend unavailable' });
+    }
+  });
+}
--- a/apps/server/src/routes/sessions.ts
+++ b/apps/server/src/routes/sessions.ts
@@ -33,7 +33,8 @@ const WorkspacePaneZ = z.object({
  kind: z.enum([
    'chat',
    'terminal',
-    'agent',
+    'coder',
+    'agent', // legacy alias — normalized to coder on write
    'empty',
    'settings',
    'markdown_artifact',
@@ -307,9 +308,12 @@ export function registerSessionRoutes(
        reply.code(400);
        return { error: 'invalid body', details: parsed.error.flatten() };
      }
+      const workspacePanes = parsed.data.workspace_panes.map((pane) =>
+        pane.kind === 'agent' ? { ...pane, kind: 'coder' as const } : pane,
+      );
      const rows = await sql<Session[]>`
        UPDATE sessions
-        SET workspace_panes = ${sql.json(parsed.data.workspace_panes as never)},
+        SET workspace_panes = ${sql.json(workspacePanes as never)},
            updated_at = clock_timestamp()
        WHERE id = ${req.params.id}
        RETURNING id, project_id, name, model, system_prompt, status, created_at, updated_at,
--- a/apps/server/src/routes/skills.ts
+++ b/apps/server/src/routes/skills.ts
@@ -1,9 +1,13 @@
-import { randomUUID } from 'node:crypto';
 import type { FastifyInstance } from 'fastify';
 import { z } from 'zod';
 import type { Sql } from '../db.js';
 import type { Chat } from '../types/api.js';
 import { getSkillBody, listSkills } from '../services/skills.js';
+import {
+  buildSkillInvokeSyntheticFrames,
+  DEFAULT_SKILL_USER_MESSAGE,
+  runSkillInvokeTransaction,
+} from '../services/skill-invoke.js';

 // Batch 9.6 slash-invoke handlers. Mirrors the MessageHandlers shape in
 // routes/messages.ts so index.ts can pass thin adapters around broker +
@@ -35,8 +39,6 @@ const SkillInvokeBody = z.object({
  user_message: z.string().max(64_000).nullable().optional(),
 });

-const DEFAULT_USER_MESSAGE = 'Apply this skill.';
-
 export function registerSkillsRoutes(
  app: FastifyInstance,
  sql: Sql,
@@ -62,7 +64,9 @@ export function registerSkillsRoutes(
        return { error: 'invalid body', details: parsed.error.flatten() };
      }
      const { skill_name } = parsed.data;
-      const userText = parsed.data.user_message?.trim() ? parsed.data.user_message : DEFAULT_USER_MESSAGE;
+      const userText = parsed.data.user_message?.trim()
+        ? parsed.data.user_message
+        : DEFAULT_SKILL_USER_MESSAGE;

      const chatRows = await sql<Chat[]>`
        SELECT id, session_id FROM chats WHERE id = ${req.params.id} AND status = 'open'
@@ -80,87 +84,20 @@ export function registerSkillsRoutes(
        return { error: 'unknown_skill', message: `unknown skill: ${skill_name}` };
      }

-      const toolCallId = randomUUID();
-      const toolCalls = [{ id: toolCallId, name: 'skill_use', args: { name: skill_name } }];
-      const toolResults = { tool_call_id: toolCallId, output: body, truncated: false };
-
-      const result = await sql.begin(async (tx) => {
-        const [synthAssistant] = await tx<{ id: string }[]>`
-          INSERT INTO messages (session_id, chat_id, role, content, status, created_at)
-          VALUES (${sessionId}, ${chat.id}, 'assistant', '', 'complete', clock_timestamp())
-          RETURNING id
-        `;
-        // v1.13.20: parts-only write. Single skill_use tool_call, no text
-        // content, so one part at seq 0.
-        await tx`
-          INSERT INTO message_parts (message_id, sequence, kind, payload)
-          VALUES (${synthAssistant!.id}, 0, 'tool_call', ${tx.json({
-            id: toolCallId,
-            name: 'skill_use',
-            args: { name: skill_name },
-          } as never)})
-        `;
-        const [toolMsg] = await tx<{ id: string }[]>`
-          INSERT INTO messages (session_id, chat_id, role, content, status, created_at)
-          VALUES (${sessionId}, ${chat.id}, 'tool', '', 'complete', clock_timestamp())
-          RETURNING id
-        `;
-        // v1.13.20: parts-only write of the synthetic tool result (skill body).
-        await tx`
-          INSERT INTO message_parts (message_id, sequence, kind, payload)
-          VALUES (${toolMsg!.id}, 0, 'tool_result', ${tx.json(toolResults as never)})
-        `;
-        const [userMsg] = await tx<{ id: string }[]>`
-          INSERT INTO messages (session_id, chat_id, role, content, status, created_at)
-          VALUES (${sessionId}, ${chat.id}, 'user', ${userText}, 'complete', clock_timestamp())
-          RETURNING id
-        `;
-        const [assistantMsg] = await tx<{ id: string }[]>`
-          INSERT INTO messages (session_id, chat_id, role, content, status, created_at)
-          VALUES (${sessionId}, ${chat.id}, 'assistant', '', 'streaming', clock_timestamp())
-          RETURNING id
-        `;
-        await tx`UPDATE sessions SET updated_at = clock_timestamp() WHERE id = ${sessionId}`;
-        await tx`UPDATE chats SET updated_at = clock_timestamp() WHERE id = ${chat.id}`;
-        return {
-          synth_assistant_id: synthAssistant!.id,
-          tool_message_id: toolMsg!.id,
-          user_message_id: userMsg!.id,
-          assistant_message_id: assistantMsg!.id,
-        };
+      const { result, toolCall } = await runSkillInvokeTransaction(sql, {
+        sessionId,
+        chatId: chat.id,
+        skillName: skill_name,
+        skillBody: body,
+        userText,
      });

      // Synthetic frames so useSessionStream's reducer reflects the new
      // history without a refetch. Frame shapes match the streaming-inference
      // protocol (see services/inference.ts InferenceFrame).
-      handlers.publishSessionFrame(sessionId, {
-        type: 'message_started',
-        message_id: result.synth_assistant_id,
-        chat_id: chat.id,
-        role: 'assistant',
-      });
-      handlers.publishSessionFrame(sessionId, {
-        type: 'tool_call',
-        message_id: result.synth_assistant_id,
-        chat_id: chat.id,
-        tool_call: toolCalls[0]!,
-      });
-      handlers.publishSessionFrame(sessionId, {
-        type: 'message_complete',
-        message_id: result.synth_assistant_id,
-        chat_id: chat.id,
-      });
-      // The tool_result frame's reducer branch creates the tool-role message
-      // in-place when it doesn't already exist — no separate message_started
-      // is needed for the tool side.
-      handlers.publishSessionFrame(sessionId, {
-        type: 'tool_result',
-        tool_message_id: result.tool_message_id,
-        tool_call_id: toolCallId,
-        chat_id: chat.id,
-        output: body,
-        truncated: false,
-      });
+      for (const frame of buildSkillInvokeSyntheticFrames(chat.id, result, toolCall, body)) {
+        handlers.publishSessionFrame(sessionId, frame);
+      }
      handlers.publishUserMessage(sessionId, chat.id, result.user_message_id, userText);
      handlers.enqueueInference(sessionId, chat.id, result.assistant_message_id, 'default');

--- a/apps/server/src/services/tests/agents.test.ts
+++ b/apps/server/src/services/tests/agents.test.ts
@@ -0,0 +1,33 @@
+import { describe, it, expect } from 'vitest';
+import { isAgentRegistryMarkdown, parseAgentsMd } from '../agents.js';
+
+describe('isAgentRegistryMarkdown', () => {
+  it('rejects Cursor navigation AGENTS.md at repo root', () => {
+    expect(
+      isAgentRegistryMarkdown('# Agent navigation\n\n## Doc map\n'),
+    ).toBe(false);
+  });
+
+  it('accepts the global data/AGENTS.md registry shape', () => {
+    expect(isAgentRegistryMarkdown('# Agents\n\n## Code Reviewer\n---\n')).toBe(true);
+  });
+});
+
+describe('parseAgentsMd', () => {
+  it('does not emit errors for navigation sections when file is skipped upstream', () => {
+    // When isAgentRegistryMarkdown returns false, getAgentsForProject never calls this.
+    // Sanity: a nav-shaped file would produce six "missing fence" errors if parsed.
+    const nav = `# Agent navigation
+
+## Doc map
+| Need | Read |
+|------|------|
+
+## Task routing
+Start here
+`;
+    const r = parseAgentsMd(nav);
+    expect(r.agents).toHaveLength(0);
+    expect(r.errors.length).toBeGreaterThan(0);
+  });
+});
--- a/apps/server/src/services/tests/inference.test.ts
+++ b/apps/server/src/services/tests/inference.test.ts
@@ -226,6 +226,76 @@ describe('buildMessagesPayload', async () => {
    expect(result[4]).toMatchObject({ role: 'assistant', content: 'here it is' });
  });

+  it('strips assistant tool_calls when matching tool results are missing', async () => {
+    const session = makeSession();
+    const project = makeProject();
+    const toolCall: ToolCall = {
+      id: 'call_orphan',
+      name: 'grep',
+      args: { pattern: 'foo' },
+    };
+    const history: Message[] = [
+      makeMessage('user', 'search'),
+      makeMessage('assistant', 'partial answer', { tool_calls: [toolCall] }),
+      makeMessage('assistant', 'final answer'),
+    ];
+    const result = await buildMessagesPayload(session, project, history);
+    // tool_calls stripped from the orphan turn; text content kept.
+    expect(result).toHaveLength(4);
+    expect(result[1]).toMatchObject({ role: 'user', content: 'search' });
+    expect(result[2]).toMatchObject({ role: 'assistant', content: 'partial answer' });
+    expect(result[2]!.tool_calls).toBeUndefined();
+    expect(result[3]).toMatchObject({ role: 'assistant', content: 'final answer' });
+  });
+
+  it('drops tool-call-only assistant rows when tool results never arrived', async () => {
+    const session = makeSession();
+    const project = makeProject();
+    const toolCall: ToolCall = {
+      id: 'call_orphan_only',
+      name: 'grep',
+      args: { pattern: 'foo' },
+    };
+    const history: Message[] = [
+      makeMessage('user', 'search'),
+      makeMessage('assistant', '', { tool_calls: [toolCall] }),
+      makeMessage('assistant', 'final answer'),
+    ];
+    const result = await buildMessagesPayload(session, project, history);
+    expect(result).toHaveLength(3);
+    expect(result[2]).toMatchObject({ role: 'assistant', content: 'final answer' });
+  });
+
+  it('skips stray tool rows when the owning assistant tool_calls were stripped', async () => {
+    const session = makeSession();
+    const project = makeProject();
+    const toolCallA: ToolCall = {
+      id: 'call_a',
+      name: 'grep',
+      args: { pattern: 'foo' },
+    };
+    const toolCallB: ToolCall = {
+      id: 'call_b',
+      name: 'read',
+      args: { path: 'x' },
+    };
+    const toolResult: ToolResult = {
+      tool_call_id: 'call_a',
+      output: 'match',
+      truncated: false,
+    };
+    const history: Message[] = [
+      makeMessage('user', 'search'),
+      makeMessage('assistant', '', { tool_calls: [toolCallA, toolCallB] }),
+      makeMessage('tool', '', { tool_results: toolResult }),
+      makeMessage('assistant', 'final answer'),
+    ];
+    const result = await buildMessagesPayload(session, project, history);
+    expect(result).toHaveLength(3);
+    expect(result.find((m) => m.role === 'tool')).toBeUndefined();
+    expect(result[2]).toMatchObject({ role: 'assistant', content: 'final answer' });
+  });
+
  it('skips tool rows with no tool_results', async () => {
    const session = makeSession();
    const project = makeProject();
--- a/apps/server/src/services/agents.ts
+++ b/apps/server/src/services/agents.ts
@@ -309,6 +309,14 @@ export function parseAgentsMd(content: string): ParseResult {
  return { agents, errors };
 }

+/** True when a file at `<project>/AGENTS.md` is an agent registry, not Cursor/doc nav. */
+export function isAgentRegistryMarkdown(content: string): boolean {
+  const firstLine = content.trimStart().split('\n')[0]?.trim() ?? '';
+  // BooCode monorepo root AGENTS.md is navigation only; registry is /data/AGENTS.md.
+  if (firstLine === '# Agent navigation') return false;
+  return true;
+}
+
 // ---- mtime-keyed cache + public API ----------------------------------------

 interface CacheEntry {
@@ -397,7 +405,7 @@ export async function getAgentsForProject(projectPath: string): Promise<AgentsRe
    for (const a of r.agents) byName.set(a.name, { ...a, source: 'global' });
    errors.push(...r.errors);
  }
-  if (projectContent !== null) {
+  if (projectContent !== null && isAgentRegistryMarkdown(projectContent)) {
    const r = parseAgentsMd(projectContent);
    for (const a of r.agents) byName.set(a.name, { ...a, source: 'project' });
    errors.push(...r.errors);
--- a/apps/server/src/services/inference/payload.ts
+++ b/apps/server/src/services/inference/payload.ts
@@ -37,6 +37,34 @@ export interface OpenAiMessage {
 // omit it and exercise the byte-stability surface directly through
 // buildSystemPromptWithFingerprint. The observer Map in system-prompt.ts
 // updates regardless of whether log is passed.
+function toolResultIdsFollowing(history: Message[], assistantIdx: number): Set<string> {
+  const ids = new Set<string>();
+  for (let j = assistantIdx + 1; j < history.length; j++) {
+    const row = history[j]!;
+    if (row.role === 'user' || row.role === 'assistant') break;
+    if (row.role === 'tool' && row.tool_results?.tool_call_id) {
+      ids.add(row.tool_results.tool_call_id);
+    }
+  }
+  return ids;
+}
+
+function findAssistantOwnerForToolCall(history: Message[], toolIdx: number, callId: string): number | null {
+  for (let k = toolIdx - 1; k >= 0; k--) {
+    const row = history[k]!;
+    if (row.role === 'user') break;
+    if (row.role === 'assistant' && row.tool_calls?.some((tc) => tc.id === callId)) return k;
+  }
+  return null;
+}
+
+function assistantToolCallsArePayloadComplete(history: Message[], assistantIdx: number): boolean {
+  const assistant = history[assistantIdx]!;
+  if (!assistant.tool_calls?.length) return false;
+  const fulfilled = toolResultIdsFollowing(history, assistantIdx);
+  return assistant.tool_calls.every((tc) => fulfilled.has(tc.id));
+}
+
 export async function buildMessagesPayload(
  session: Session,
  project: Project,
@@ -97,6 +125,10 @@ export async function buildMessagesPayload(
    if (m.role === 'tool') {
      const tr = m.tool_results;
      if (!tr) continue;
+      const ownerIdx = findAssistantOwnerForToolCall(history, i, tr.tool_call_id);
+      if (ownerIdx == null || !assistantToolCallsArePayloadComplete(history, ownerIdx)) {
+        continue;
+      }
      const outputText = tr.error
        ? `error: ${tr.error}`
        : typeof tr.output === 'string'
@@ -115,11 +147,15 @@ export async function buildMessagesPayload(
        content: m.content && m.content.length > 0 ? m.content : null,
      };
      if (m.tool_calls && m.tool_calls.length > 0) {
-        msg.tool_calls = m.tool_calls.map((tc) => ({
-          id: tc.id,
-          type: 'function' as const,
-          function: { name: tc.name, arguments: JSON.stringify(tc.args) },
-        }));
+        if (assistantToolCallsArePayloadComplete(history, i)) {
+          msg.tool_calls = m.tool_calls.map((tc) => ({
+            id: tc.id,
+            type: 'function' as const,
+            function: { name: tc.name, arguments: JSON.stringify(tc.args) },
+          }));
+        }
+        // Orphaned tool_calls (no matching tool rows) are stripped so the
+        // upstream API does not reject the payload on the next user turn.
      }
      // v1.13.1-C: collapse reasoning_parts into a single string. The view
      // returns them ordered by sequence; multiple reasoning parts on one
@@ -127,6 +163,11 @@ export async function buildMessagesPayload(
      if (m.reasoning_parts && m.reasoning_parts.length > 0) {
        msg.reasoning = m.reasoning_parts.map((p) => p.text ?? '').join('');
      }
+      const hasPayload =
+        (msg.content != null && msg.content.trim().length > 0) ||
+        (msg.tool_calls != null && msg.tool_calls.length > 0) ||
+        (msg.reasoning != null && msg.reasoning.length > 0);
+      if (!hasPayload) continue;
      out.push(msg);
      continue;
    }
--- a/apps/server/src/services/skill-invoke.ts
+++ b/apps/server/src/services/skill-invoke.ts
@@ -0,0 +1,148 @@
+import { randomUUID } from 'node:crypto';
+import type { Sql } from '../db.js';
+
+export const DEFAULT_SKILL_USER_MESSAGE = 'Apply this skill.';
+
+export interface SkillInvokeTransactionResult {
+  synth_assistant_id: string;
+  tool_message_id: string;
+  user_message_id: string;
+  assistant_message_id: string;
+}
+
+export interface SkillInvokeToolCall {
+  id: string;
+  name: 'skill_use';
+  args: { name: string };
+}
+
+export type SkillInvokeSessionFrame = Record<string, unknown> & { type: string };
+
+export async function runSkillInvokeTransaction(
+  sql: Sql,
+  args: {
+    sessionId: string;
+    chatId: string;
+    skillName: string;
+    skillBody: string;
+    userText: string;
+  },
+): Promise<{ result: SkillInvokeTransactionResult; toolCall: SkillInvokeToolCall }> {
+  const toolCallId = randomUUID();
+  const toolCall: SkillInvokeToolCall = {
+    id: toolCallId,
+    name: 'skill_use',
+    args: { name: args.skillName },
+  };
+  const toolResults = {
+    tool_call_id: toolCallId,
+    output: args.skillBody,
+    truncated: false,
+  };
+
+  const result = await sql.begin(async (tx) => {
+    const [synthAssistant] = await tx<{ id: string }[]>`
+      INSERT INTO messages (session_id, chat_id, role, content, status, created_at)
+      VALUES (${args.sessionId}, ${args.chatId}, 'assistant', '', 'complete', clock_timestamp())
+      RETURNING id
+    `;
+    await tx`
+      INSERT INTO message_parts (message_id, sequence, kind, payload)
+      VALUES (${synthAssistant!.id}, 0, 'tool_call', ${tx.json({
+        id: toolCallId,
+        name: 'skill_use',
+        args: { name: args.skillName },
+      } as never)})
+    `;
+    const [toolMsg] = await tx<{ id: string }[]>`
+      INSERT INTO messages (session_id, chat_id, role, content, status, created_at)
+      VALUES (${args.sessionId}, ${args.chatId}, 'tool', '', 'complete', clock_timestamp())
+      RETURNING id
+    `;
+    await tx`
+      INSERT INTO message_parts (message_id, sequence, kind, payload)
+      VALUES (${toolMsg!.id}, 0, 'tool_result', ${tx.json(toolResults as never)})
+    `;
+    const [userMsg] = await tx<{ id: string }[]>`
+      INSERT INTO messages (session_id, chat_id, role, content, status, created_at)
+      VALUES (${args.sessionId}, ${args.chatId}, 'user', ${args.userText}, 'complete', clock_timestamp())
+      RETURNING id
+    `;
+    const [assistantMsg] = await tx<{ id: string }[]>`
+      INSERT INTO messages (session_id, chat_id, role, content, status, created_at)
+      VALUES (${args.sessionId}, ${args.chatId}, 'assistant', '', 'streaming', clock_timestamp())
+      RETURNING id
+    `;
+    await tx`UPDATE sessions SET updated_at = clock_timestamp() WHERE id = ${args.sessionId}`;
+    await tx`UPDATE chats SET updated_at = clock_timestamp() WHERE id = ${args.chatId}`;
+    return {
+      synth_assistant_id: synthAssistant!.id,
+      tool_message_id: toolMsg!.id,
+      user_message_id: userMsg!.id,
+      assistant_message_id: assistantMsg!.id,
+    };
+  });
+
+  return { result, toolCall };
+}
+
+export function buildSkillInvokeSyntheticFrames(
+  chatId: string,
+  result: SkillInvokeTransactionResult,
+  toolCall: SkillInvokeToolCall,
+  skillBody: string,
+): SkillInvokeSessionFrame[] {
+  return [
+    {
+      type: 'message_started',
+      message_id: result.synth_assistant_id,
+      chat_id: chatId,
+      role: 'assistant',
+    },
+    {
+      type: 'tool_call',
+      message_id: result.synth_assistant_id,
+      chat_id: chatId,
+      tool_call: toolCall,
+    },
+    {
+      type: 'message_complete',
+      message_id: result.synth_assistant_id,
+      chat_id: chatId,
+    },
+    {
+      type: 'tool_result',
+      tool_message_id: result.tool_message_id,
+      tool_call_id: toolCall.id,
+      chat_id: chatId,
+      output: skillBody,
+      truncated: false,
+    },
+  ];
+}
+
+export function buildSkillInvokeUserFrames(
+  chatId: string,
+  userMessageId: string,
+  userText: string,
+): SkillInvokeSessionFrame[] {
+  return [
+    {
+      type: 'message_started',
+      message_id: userMessageId,
+      chat_id: chatId,
+      role: 'user',
+    },
+    {
+      type: 'delta',
+      message_id: userMessageId,
+      chat_id: chatId,
+      content: userText,
+    },
+    {
+      type: 'message_complete',
+      message_id: userMessageId,
+      chat_id: chatId,
+    },
+  ];
+}
--- a/apps/server/src/services/skills.ts
+++ b/apps/server/src/services/skills.ts
@@ -16,7 +16,7 @@ import { pathGuard, PathScopeError } from './path_guard.js';
 // new skills, per-entry mtime check on body access so a hot-edited SKILL.md
 // is re-read without a restart. No watcher.

-const SKILLS_ROOT = '/data/skills';
+const SKILLS_ROOT = process.env.SKILLS_ROOT ?? '/data/skills';
 const MAX_RESOURCE_BYTES = 5 * 1024 * 1024;
 const LIST_CACHE_TTL_MS = 60_000;

--- a/apps/server/src/types/ws-frames.ts
+++ b/apps/server/src/types/ws-frames.ts
@@ -85,6 +85,13 @@ export const DeltaFrame = z.object({
  content: z.string(),
 });

+export const ReasoningDeltaFrame = z.object({
+  type: z.literal('reasoning_delta'),
+  message_id: Uuid,
+  chat_id: Uuid.optional(),
+  content: z.string(),
+});
+
 export const ToolCallFrame = z.object({
  type: z.literal('tool_call'),
  message_id: Uuid,
@@ -256,6 +263,37 @@ export const ProjectDeletedFrame = z.object({
  project_id: Uuid,
 });

+const PermissionOptionShape = z.object({
+  option_id: z.string(),
+  label: z.string(),
+});
+
+export const PermissionRequestedFrame = z.object({
+  type: z.literal('permission_requested'),
+  task_id: Uuid,
+  session_id: Uuid,
+  tool_title: z.string().optional(),
+  options: z.array(PermissionOptionShape),
+});
+
+export const PermissionResolvedFrame = z.object({
+  type: z.literal('permission_resolved'),
+  task_id: Uuid,
+  session_id: Uuid,
+});
+
+const AgentCommandShape = z.object({
+  name: z.string(),
+  description: z.string().optional(),
+});
+
+export const AgentCommandsFrame = z.object({
+  type: z.literal('agent_commands'),
+  task_id: Uuid,
+  session_id: Uuid,
+  commands: z.array(AgentCommandShape),
+});
+
 // ---- discriminated union ---------------------------------------------------

 export const WsFrameSchema = z.discriminatedUnion('type', [
@@ -263,6 +301,7 @@ export const WsFrameSchema = z.discriminatedUnion('type', [
  SnapshotFrame,
  MessageStartedFrame,
  DeltaFrame,
+  ReasoningDeltaFrame,
  ToolCallFrame,
  ToolResultFrame,
  MessageCompleteFrame,
@@ -271,6 +310,9 @@ export const WsFrameSchema = z.discriminatedUnion('type', [
  ChatRenamedFrame,
  CompactedFrame,
  ErrorFrame,
+  PermissionRequestedFrame,
+  PermissionResolvedFrame,
+  AgentCommandsFrame,
  // per-user
  ChatStatusFrame,
  SessionUpdatedFrame,
@@ -300,6 +342,7 @@ export const KNOWN_FRAME_TYPES: readonly WsFrame['type'][] = [
  'snapshot',
  'message_started',
  'delta',
+  'reasoning_delta',
  'tool_call',
  'tool_result',
  'message_complete',
@@ -308,6 +351,9 @@ export const KNOWN_FRAME_TYPES: readonly WsFrame['type'][] = [
  'chat_renamed',
  'compacted',
  'error',
+  'permission_requested',
+  'permission_resolved',
+  'agent_commands',
  'chat_status',
  'session_updated',
  'session_renamed',