feat: add interactive app server protocol

Author: t

apps/server/README.md

@@ -3,7 +3,8 @@
 Experimental line-delimited JSON runtime server for DeepCode clients.
 
 The server owns lifecycle state and delegates model work to `RuntimeHost`. Completed items and
-terminal turn state are persisted; streaming deltas are notifications only. The initial transport
+terminal turn state are persisted; streaming and interactive requests are notifications only.
+Approval and user-input responses are bound to their active thread and turn. The initial transport
 is single-client stdio, matching the desktop packaging decision in
 `docs/adr/0001-desktop-runtime-sidecar.md`.
 

apps/server/src/default-runtime.ts

@@ -7,7 +7,7 @@ import { RuntimeHostExecutor } from './runtime-executor.js';
 
 export function createDefaultTurnExecutor(): RuntimeHostExecutor {
   return new RuntimeHostExecutor({
-    createHost: async (cwd) => {
+    createHost: async (cwd, mode) => {
       const credentials = await resolveCredentials({ store: new CredentialsStore() });
       if (!credentials.apiKey && !credentials.authToken) {
         throw new Error(
@@ -22,7 +22,7 @@ export function createDefaultTurnExecutor(): RuntimeHostExecutor {
         }),
         tools: new ToolRegistry(BUILTIN_TOOLS),
         cwd,
-        mode: 'default',
+        mode,
         permissions: { allow: [...SAFE_READONLY_TOOLS] },
       });
     },

apps/server/src/runtime-executor.test.ts

@@ -10,6 +10,16 @@ import { describe, expect, it } from 'vitest';
 
 import { RuntimeHostExecutor, historyFromThread } from './runtime-executor.js';
 
+function protocolCallbacks() {
+  return {
+    publishToolStarted: () => undefined,
+    publishToolCompleted: () => undefined,
+    publishUsage: () => undefined,
+    requestApproval: async () => 'deny' as const,
+    requestUserInput: async () => '',
+  };
+}
+
 const priorAssistant = {
   role: 'assistant' as const,
   content: [{ type: 'text' as const, text: 'prior answer' }],
@@ -61,6 +71,28 @@ class StreamingProvider implements Provider {
   }
 }
 
+class ToolProvider implements Provider {
+  readonly name = 'tool-test';
+  calls = 0;
+
+  async runTurn(options: ProviderRunOpts): Promise<ProviderResult> {
+    this.calls++;
+    if (this.calls === 1) {
+      return {
+        content: [{ type: 'tool_use', id: 'tool-1', name: 'WriteTest', input: { value: 'ok' } }],
+        stopReason: 'tool_use',
+        usage: { inputTokens: 3, outputTokens: 4, reasoningTokens: 1, cacheReadTokens: 2 },
+      };
+    }
+    options.handlers?.onTextDelta?.('done');
+    return {
+      content: [{ type: 'text', text: 'done' }],
+      stopReason: 'end_turn',
+      usage: { inputTokens: 5, outputTokens: 6, reasoningTokens: 0, cacheReadTokens: 0 },
+    };
+  }
+}
+
 describe('RuntimeHostExecutor', () => {
   it('reconstructs history and returns only messages created by the new turn', async () => {
     const provider = new StreamingProvider();
@@ -85,6 +117,7 @@ describe('RuntimeHostExecutor', () => {
       input: { text: 'current question' },
       signal: new AbortController().signal,
       publishDelta: (_itemId, delta) => deltas.push(delta),
+      ...protocolCallbacks(),
     });
 
     expect(provider.seenMessages).toEqual([
@@ -133,4 +166,55 @@ describe('RuntimeHostExecutor', () => {
 
     expect(historyFromThread(withError)).toHaveLength(2);
   });
+
+  it('projects tool, usage, and approval activity onto protocol callbacks', async () => {
+    const provider = new ToolProvider();
+    const tools = new ToolRegistry();
+    tools.register({
+      name: 'WriteTest',
+      definition: { name: 'WriteTest', description: 'test', inputSchema: { type: 'object' } },
+      execute: async () => ({ content: 'wrote test value' }),
+    });
+    const host = new RuntimeHost({ provider, tools, cwd: '/workspace', mode: 'default' });
+    const executor = new RuntimeHostExecutor({ createHost: () => host });
+    const turn: TurnSnapshot = {
+      id: 'turn-tool',
+      threadId: thread.id,
+      status: 'in_progress',
+      startedAt: '2026-08-01T00:00:02.000Z',
+      items: [],
+    };
+    const started: string[] = [];
+    const completed: string[] = [];
+    const usage: number[] = [];
+    const approvals: string[] = [];
+
+    const result = await executor.execute({
+      thread,
+      turn,
+      input: { text: 'write it', effort: 'low' },
+      signal: new AbortController().signal,
+      publishDelta: () => undefined,
+      publishToolStarted: (itemId) => started.push(itemId),
+      publishToolCompleted: (itemId) => completed.push(itemId),
+      publishUsage: (value) => usage.push(value.inputTokens),
+      requestApproval: async (toolName) => {
+        approvals.push(toolName);
+        return 'allow';
+      },
+      requestUserInput: async () => '',
+    });
+
+    expect(started).toEqual(['tool-1']);
+    expect(completed).toEqual(['tool-1']);
+    expect(usage).toEqual([3, 5]);
+    expect(approvals).toEqual(['WriteTest']);
+    expect(result.items).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ type: 'approval' }),
+        expect.objectContaining({ type: 'assistant_message' }),
+        expect.objectContaining({ type: 'tool_result' }),
+      ]),
+    );
+  });
 });

apps/server/src/runtime-executor.ts

@@ -1,10 +1,17 @@
-import { type AgentEvent, type RuntimeHost, type StoredMessage } from '@deepcode/core';
+import {
+  type AgentEvent,
+  type Effort,
+  type Mode,
+  type RuntimeHost,
+  type StoredMessage,
+} from '@deepcode/core';
+import { EFFORT_PARAMS } from '@deepcode/core/dist/providers/deepseek.js';
 import type { CompletedItem, ThreadSnapshot } from '@deepcode/protocol';
 
 import type { TurnExecutionArgs, TurnExecutionItem, TurnExecutor } from './server.js';
 
 export interface RuntimeHostExecutorOptions {
-  createHost: (cwd: string) => Promise<RuntimeHost> | RuntimeHost;
+  createHost: (cwd: string, mode: Mode) => Promise<RuntimeHost> | RuntimeHost;
   systemPrompt?: string;
   model?: string;
 }
@@ -16,29 +23,71 @@ export class RuntimeHostExecutor implements TurnExecutor {
   constructor(private readonly options: RuntimeHostExecutorOptions) {}
 
   async execute(args: TurnExecutionArgs) {
-    const host = await this.options.createHost(args.thread.cwd);
+    const mode = parseMode(args.input.mode);
+    const host = await this.options.createHost(args.thread.cwd, mode);
     const history = historyFromThread(args.thread);
     const baselineLength = history.length;
     const text = typeof args.input.text === 'string' ? args.input.text : JSON.stringify(args.input);
     const streamingItemId = `${args.turn.id}-assistant`;
     const events: AgentEvent[] = [];
+    const interactionItems: TurnExecutionItem[] = [];
+    const effort = parseEffort(args.input.effort);
+    const effortParams = EFFORT_PARAMS[effort];
     const result = await host.run({
       cwd: args.thread.cwd,
       systemPrompt: this.options.systemPrompt ?? DEFAULT_SYSTEM_PROMPT,
       userMessage: text,
       history,
-      model: this.options.model ?? 'deepseek-chat',
+      model:
+        typeof args.input.model === 'string'
+          ? args.input.model
+          : (this.options.model ?? 'deepseek-chat'),
+      maxTokens: effortParams.maxTokens,
+      temperature: effortParams.temperature,
       signal: args.signal,
       systemReminders: false,
-      approval: async () => false,
+      approval: async (toolName, _input, verdict) => {
+        const decision = await args.requestApproval(
+          toolName,
+          verdict.reason ?? `Approve ${toolName}?`,
+        );
+        interactionItems.push({
+          type: 'approval',
+          payload: { toolName, decision, reason: verdict.reason },
+        });
+        return decision === 'always' ? 'always' : decision === 'allow';
+      },
+      askUser: async (request) => {
+        const answer = await args.requestUserInput(request);
+        interactionItems.push({ type: 'ask_user', payload: { ...request, answer } });
+        return answer;
+      },
       onEvent: (event) => {
         events.push(event);
-        if (event.type === 'text_delta') args.publishDelta(streamingItemId, event.text);
+        switch (event.type) {
+          case 'text_delta':
+            args.publishDelta(streamingItemId, event.text);
+            break;
+          case 'tool_use':
+            args.publishToolStarted(event.id, event.name, event.input);
+            break;
+          case 'tool_result':
+            args.publishToolCompleted(event.id, event.result);
+            break;
+          case 'usage':
+            args.publishUsage({
+              inputTokens: event.inputTokens,
+              outputTokens: event.outputTokens,
+              reasoningTokens: event.reasoningTokens,
+              cacheReadTokens: event.cacheReadTokens,
+            });
+            break;
+        }
       },
     });
 
     const newMessages = result.history.slice(baselineLength);
-    const items = completedItemsFromMessages(newMessages, text);
+    const items = [...interactionItems, ...completedItemsFromMessages(newMessages, text)];
     if (result.stopReason === 'error') {
       const error = [...events].reverse().find((event) => event.type === 'error');
       if (error?.type === 'error') items.push({ type: 'error', payload: { message: error.error } });
@@ -50,6 +99,24 @@ export class RuntimeHostExecutor implements TurnExecutor {
   }
 }
 
+const MODES = new Set<Mode>([
+  'default',
+  'acceptEdits',
+  'plan',
+  'auto',
+  'dontAsk',
+  'bypassPermissions',
+]);
+const EFFORTS = new Set<Effort>(['low', 'medium', 'high', 'xhigh', 'max']);
+
+function parseMode(value: unknown): Mode {
+  return typeof value === 'string' && MODES.has(value as Mode) ? (value as Mode) : 'default';
+}
+
+function parseEffort(value: unknown): Effort {
+  return typeof value === 'string' && EFFORTS.has(value as Effort) ? (value as Effort) : 'high';
+}
+
 export function historyFromThread(thread: ThreadSnapshot): StoredMessage[] {
   const history: StoredMessage[] = [];
   for (const turn of thread.turns) {

apps/server/src/server.test.ts

@@ -56,8 +56,11 @@ describe('AppServer', () => {
   it('persists completed items and terminal state while publishing deltas transiently', async () => {
     const events: ProtocolEvent[] = [];
     const executor: TurnExecutor = {
-      execute: async ({ publishDelta }) => {
+      execute: async ({ publishDelta, publishToolStarted, publishToolCompleted, publishUsage }) => {
         publishDelta('assistant-stream', 'hel');
+        publishToolStarted('tool-1', 'Read', { file_path: 'README.md' });
+        publishToolCompleted('tool-1', { content: 'contents' });
+        publishUsage({ inputTokens: 1, outputTokens: 2 });
         return {
           items: [{ type: 'assistant_message', payload: { text: 'hello' } }],
         };
@@ -94,6 +97,9 @@ describe('AppServer', () => {
       }),
     });
     expect(events.map((event) => event.type)).toContain('item.delta');
+    expect(events.map((event) => event.type)).toEqual(
+      expect.arrayContaining(['tool.started', 'tool.completed', 'usage.updated']),
+    );
     expect((read.result as { turns: Array<{ items: unknown[] }> }).turns[0]?.items).toHaveLength(2);
   });
 
@@ -136,6 +142,102 @@ describe('AppServer', () => {
     expect(events.filter((event) => event.type === 'turn.completed')).toHaveLength(0);
   });
 
+  it('round-trips approval and user-input requests through the active turn', async () => {
+    const events: ProtocolEvent[] = [];
+    const responses: string[] = [];
+    const executor: TurnExecutor = {
+      execute: async ({ requestApproval, requestUserInput }) => {
+        responses.push(await requestApproval('Bash', 'Run tests?'));
+        responses.push(
+          await requestUserInput({
+            question: 'Choose scope',
+            options: [{ label: 'All', description: 'Run every test' }],
+          }),
+        );
+        return {};
+      },
+    };
+    const server = new AppServer({ executor, onEvent: (event) => events.push(event) });
+    const thread = await server.handle(request(1, 'thread/start', { cwd: '/workspace' }));
+    const threadId = (thread.result as { id: string }).id;
+    const started = await server.handle(
+      request(2, 'turn/start', { threadId, input: { text: 'test' } }),
+    );
+    const turnId = (started.result as { id: string }).id;
+    const approval = events.find((event) => event.type === 'approval.requested');
+    expect(approval).toEqual(
+      expect.objectContaining({ type: 'approval.requested', threadId, turnId, toolName: 'Bash' }),
+    );
+
+    await expect(
+      server.handle(
+        request(3, 'approval/respond', {
+          threadId,
+          turnId,
+          requestId: approval?.type === 'approval.requested' ? approval.requestId : '',
+          decision: 'allow',
+        }),
+      ),
+    ).resolves.toEqual({ id: 3, result: { accepted: true } });
+    await Promise.resolve();
+
+    const question = events.find((event) => event.type === 'user-input.requested');
+    expect(question).toEqual(
+      expect.objectContaining({ type: 'user-input.requested', threadId, turnId }),
+    );
+    await server.handle(
+      request(4, 'user-input/respond', {
+        threadId,
+        turnId,
+        requestId: question?.type === 'user-input.requested' ? question.requestId : '',
+        answer: 'All',
+      }),
+    );
+    await server.waitForIdle();
+
+    expect(responses).toEqual(['allow', 'All']);
+    expect(events.filter((event) => event.type === 'turn.completed')).toHaveLength(1);
+    await expect(
+      server.handle(
+        request(5, 'approval/respond', {
+          threadId,
+          turnId,
+          requestId: approval?.type === 'approval.requested' ? approval.requestId : '',
+          decision: 'allow',
+        }),
+      ),
+    ).resolves.toEqual({
+      id: 5,
+      error: expect.objectContaining({ code: 'invalid_request' }),
+    });
+  });
+
+  it('releases a pending interaction when its turn is interrupted', async () => {
+    let decision: string | undefined;
+    const executor: TurnExecutor = {
+      execute: async ({ requestApproval }) => {
+        decision = await requestApproval('Bash', 'Run forever?');
+        return {};
+      },
+    };
+    const server = new AppServer({ executor });
+    const thread = await server.handle(request(1, 'thread/start', { cwd: '/workspace' }));
+    const threadId = (thread.result as { id: string }).id;
+    const started = await server.handle(
+      request(2, 'turn/start', { threadId, input: { text: 'wait' } }),
+    );
+    const turnId = (started.result as { id: string }).id;
+
+    await server.handle(request(3, 'turn/interrupt', { threadId, turnId }));
+    await server.waitForIdle();
+
+    expect(decision).toBe('deny');
+    const read = await server.handle(request(4, 'thread/read', { threadId }));
+    expect(read.result).toEqual(
+      expect.objectContaining({ turns: [expect.objectContaining({ status: 'interrupted' })] }),
+    );
+  });
+
   it('marks an orphaned active turn interrupted when a new process resumes it', async () => {
     const root = await mkdtemp(join(tmpdir(), 'deepcode-app-server-'));
     temporaryRoots.push(root);