@ahpd/agent-claude 0.3.0 → 0.5.0

package/src/kinds.ts

@@ -0,0 +1,46 @@
+/**
+ * What kind of thing a tool call is, said where the reference client reads it.
+ *
+ * `_meta.toolKind` is not protocol. It is the one well-known key VS Code's
+ * agent window routes a tool call by: `terminal` goes to the command-and-output
+ * renderer, `subagent` to the subagent view, `search` and `read` to theirs, and
+ * a call with none is drawn as a generic tool - a name and a box. The reference
+ * host stamps it in its own adapters, and derives it for a "remote host" from
+ * a Copilot-internal permission payload this backend does not have; so it is
+ * stamped here, from the harness's own tool names, which are the one thing
+ * about a tool call this backend can be sure of.
+ *
+ * Names only. Nothing else about the call decides the kind, and a tool this
+ * table has not heard of is left unstamped rather than guessed at - the
+ * generic renderer is right for a tool nobody here knows.
+ */
+
+export type ToolKind = 'terminal' | 'read' | 'search' | 'subagent';
+
+const KINDS: Readonly<Record<string, ToolKind>> = {
+  Bash: 'terminal',
+  terminal: 'terminal',
+  Read: 'read',
+  Glob: 'search',
+  Grep: 'search',
+  WebSearch: 'search',
+  WebFetch: 'search',
+  Task: 'subagent',
+  Agent: 'subagent',
+};
+
+/** The kind of a tool by its harness name, or nothing for one the table lacks. */
+export const toolKindOf = (name: string): ToolKind | undefined => KINDS[name];
+
+/**
+ * The `_meta` a tool call carries from the moment it is announced.
+ *
+ * The reducer replaces a call's whole `_meta` whenever an action carries one,
+ * so anything added later - a progress line while it runs - has to be spread
+ * over this rather than sent alone. Absent for a tool with no kind, so a call
+ * that has nothing to say carries no empty bag.
+ */
+export const toolMetaOf = (name: string): Record<string, unknown> | undefined => {
+  const toolKind = toolKindOf(name);
+  return toolKind === undefined ? undefined : { toolKind };
+};

package/src/session.ts

@@ -1,10 +1,14 @@
+import { rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { createSdkMcpServer, query } from '@anthropic-ai/claude-agent-sdk';
 import { z } from 'zod';
-import type { PermissionMode } from '@anthropic-ai/claude-agent-sdk';
+import type { HookCallback, PermissionMode } from '@anthropic-ai/claude-agent-sdk';
 import { protectedResource, urlOf } from './mcp.js';
+import { toolMetaOf } from './kinds.js';
 import type { ActiveTurn, McpServerState, ToolCallCompletedState, ToolCallRunningState, ToolResultContent, ToolResultTerminalContent, ToolResultTextContent } from '@microsoft/agent-host-protocol';
 import { Status, idOf, tail } from '@ahpd/sdk';
-import type { Bag, BoundTool, Chosen, OnWire, Session, SessionOptions, WireTurn } from '@ahpd/sdk';
+import type { Bag, BoundTool, Chosen, MessageFrom, OnWire, Session, SessionOptions, WireTurn } from '@ahpd/sdk';
 
 /**
  * The effort levels this backend has, weakest first.
@@ -57,6 +61,43 @@ const bag = (value: unknown): Bag => (typeof value === 'object' && value !== nul
 const list = (value: unknown): unknown[] => (Array.isArray(value) ? value : []);
 const str = (value: unknown): string | undefined => (typeof value === 'string' ? value : undefined);
 
+/** One client-generated script, sourced before every shell command. */
+interface ShellInitScript { shell: 'bash' | 'powershell'; script: string }
+
+/** A generated script is a few hundred bytes; anything near this is not one. */
+const MAX_SHELL_INIT_SCRIPT = 64 * 1024;
+
+/**
+ * The `shellInitScripts` value, checked to the reference host's rule.
+ *
+ * A list of `{ shell, script }`, each script non-empty and no longer than a
+ * generated one could be. `undefined` for anything else, which is what lets
+ * `setConfig` refuse it rather than write it to disk.
+ */
+const shellInitScripts = (value: unknown): ShellInitScript[] | undefined => {
+  if (!Array.isArray(value)) return undefined;
+  const list: ShellInitScript[] = [];
+  for (const entry of value) {
+    const one = bag(entry);
+    if ((one.shell !== 'bash' && one.shell !== 'powershell') || typeof one.script !== 'string') return undefined;
+    if (one.script.length === 0 || one.script.length > MAX_SHELL_INIT_SCRIPT) return undefined;
+    list.push({ shell: one.shell, script: one.script });
+  }
+  return list;
+};
+
+/**
+ * What goes in front of a shell command while a script is in force.
+ *
+ * Sourced, so what it sets is there for the command; its stderr dropped, as
+ * the reference runtime drops it; and a nonzero status reported rather than
+ * hidden, since a profile that fails is something the model should hear.
+ */
+const sourcing = (path: string): string => `{ . '${path.replaceAll("'", "'\\''")}'; } 2>/dev/null || printf 'shell init script exited %s\\n' "$?"`;
+
+/** The CLI's sandbox setting for the reference host's three words; `null` clears it back to the settings files. */
+const sandboxOf = (value: unknown): { enabled: boolean } | null => (value === 'on' ? { enabled: true } : value === 'off' ? { enabled: false } : null);
+
 interface PendingInput {
   id: string;
   entry: Bag;
@@ -536,6 +577,43 @@ export function createSession(options: SessionOptions): Session {
    */
   const settings: Record<string, unknown> = { permissionMode: 'default', ...options.settings };
 
+  /*
+   * The shell init script, on disk where a shell can source it.
+   *
+   * The reference client pushes `shellInitScripts` for the profile and the
+   * Python environment it has selected, and the SDK's shell tool has no
+   * setting for one - so a `PreToolUse` hook on `Bash` puts a `source` of
+   * this file in front of every command. One path for the session's life,
+   * rewritten on each change, because the hook is built once with the query
+   * and reads the file by name. The bash entry only: the CLI's shell tool is
+   * bash on every platform it runs on.
+   */
+  const initScript = join(tmpdir(), `ahpd-shell-init-${crypto.randomUUID()}.sh`);
+  let sourced = false;
+  const setShellInit = (value: unknown): true | string => {
+    const list = shellInitScripts(value);
+    if (list === undefined) return 'shellInitScripts takes a list of { shell, script }';
+    const bash = list.find((one) => one.shell === 'bash');
+    try {
+      if (bash === undefined) rmSync(initScript, { force: true });
+      else writeFileSync(initScript, bash.script, { mode: 0o600 });
+    }
+    catch (error) {
+      return `Could not write the shell init script: ${error instanceof Error ? error.message : String(error)}`;
+    }
+    sourced = bash !== undefined;
+    settings.shellInitScripts = list;
+    return true;
+  };
+  if (settings.shellInitScripts !== undefined) setShellInit(settings.shellInitScripts);
+  const sourceFirst: HookCallback = async (input) => {
+    if (!sourced || input.hook_event_name !== 'PreToolUse') return {};
+    const given = bag(input.tool_input);
+    const command = str(given.command);
+    if (command === undefined) return {};
+    return { hookSpecificOutput: { hookEventName: 'PreToolUse', updatedInput: { ...given, command: `${sourcing(initScript)}\n${command}` } } };
+  };
+
   /**
    * The MCP server a tool belongs to, out of its name.
    *
@@ -926,12 +1004,17 @@ export function createSession(options: SessionOptions): Session {
         const contributor = from === undefined
           ? undefined
           : { kind: 'mcp' as const, customizationId: `mcp:${from}` };
+        // What kind of row to draw, from the name and from the first frame:
+        // a client that waited for the arguments to know it was a shell
+        // command would draw a generic box and then redraw it.
+        const meta = toolMetaOf(name);
         const call: Bag = {
           toolCallId: id,
           toolName: name,
           displayName: name,
           status: 'streaming',
           ...(contributor ? { contributor } : {}),
+          ...(meta ? { _meta: meta } : {}),
         };
         const part: Bag = { id, kind: 'toolCall', toolCall: call };
         parts.set(id, part);
@@ -943,6 +1026,7 @@ export function createSession(options: SessionOptions): Session {
           toolName: name,
           displayName: name,
           ...(contributor ? { contributor } : {}),
+          ...(meta ? { _meta: meta } : {}),
         });
         return;
       }
@@ -1055,12 +1139,14 @@ export function createSession(options: SessionOptions): Session {
         // Running against somebody else's server, and so a call that can end
         // up waiting on a sign-in rather than on its own work.
         if (from !== undefined) onServer.set(id, { server: from, turnId: str(turn.id) ?? '', blocked: false });
+        const meta = toolMetaOf(name);
         const call: Bag = open !== undefined ? bag(open.toolCall) : {
           toolCallId: id,
           toolName: name,
           displayName: name,
           status: 'running',
           ...(contributor ? { contributor } : {}),
+          ...(meta ? { _meta: meta } : {}),
           /*
            * On the call, and not only on the action that announces it.
            *
@@ -1111,6 +1197,7 @@ export function createSession(options: SessionOptions): Session {
             toolName: name,
             displayName: name,
             ...(contributor ? { contributor } : {}),
+            ...(meta ? { _meta: meta } : {}),
           });
         }
         emit('chat', {
@@ -1191,6 +1278,22 @@ export function createSession(options: SessionOptions): Session {
        * itself, and it is checked against the state it completes.
        */
       Object.assign(call, result);
+      /*
+       * The progress line goes with the running state it described.
+       *
+       * Meaningful only while the call runs, and a completed row that still
+       * carries "Running Grep" is a row that says two things. Sent on the
+       * completion only when there was one to take off, because an action
+       * carrying `_meta` replaces the bag whole and an absent one leaves
+       * the kind stamped at the start alone.
+       */
+      const meta = bag(call._meta);
+      const progressed = meta.progressMessage !== undefined;
+      if (progressed) {
+        const { progressMessage: _gone, ...rest } = meta;
+        if (Object.keys(rest).length > 0) call._meta = rest;
+        else delete call._meta;
+      }
       // And as it is now the tool has run. Paired with the `before` above by
       // the call's own id, which is the only thing that survives the gap.
       const changed = id === undefined ? undefined : editing.get(id);
@@ -1203,6 +1306,7 @@ export function createSession(options: SessionOptions): Session {
         turnId: active?.id,
         toolCallId: id,
         result,
+        ...(progressed ? { _meta: call._meta ?? {} } : {}),
       });
     }
   };
@@ -1296,11 +1400,13 @@ export function createSession(options: SessionOptions): Session {
       // The call the assistant message opened, if it arrived first. Which of
       // the two comes first is the CLI's business; either order is one call.
       const held = parts.get(id);
+      const meta = toolMetaOf(toolName);
       const call = held ? bag(held.toolCall) : {
         toolCallId: id,
         toolName,
         displayName,
         ...(command ? { toolInput: command } : {}),
+        ...(meta ? { _meta: meta } : {}),
       } as Bag;
       call.status = 'pending-confirmation';
       call.confirmationTitle = confirmationTitle;
@@ -1312,7 +1418,10 @@ export function createSession(options: SessionOptions): Session {
         const part: Bag = { id, kind: 'toolCall', toolCall: call };
         parts.set(id, part);
         holdPart(turn, part);
-        emit('chat', { type: 'chat/toolCallStart', turnId: turn.id, toolCallId: id, toolName, displayName });
+        emit('chat', {
+          type: 'chat/toolCallStart', turnId: turn.id, toolCallId: id, toolName, displayName,
+          ...(meta ? { _meta: meta } : {}),
+        });
       }
       emit('chat', {
         type: 'chat/toolCallReady',
@@ -1359,6 +1468,17 @@ export function createSession(options: SessionOptions): Session {
        * `setMcpServers` does not touch servers that came from a settings file.
        */
       ...(Object.keys(declared).length > 0 ? { mcpServers: declared as never } : {}),
+      /*
+       * What the host wants said, after the CLI's own prompt.
+       *
+       * The preset with an `append`, not a prompt of this backend's own: the
+       * CLI's prompt is what makes it the CLI. `snapshot`, so the prompt is
+       * recorded once for the conversation and a resume does not rewrite it
+       * under the model's reasoning.
+       */
+      ...(options.instructions && options.instructions.length > 0
+        ? { systemPrompt: { type: 'preset' as const, preset: 'claude_code' as const, append: options.instructions.join('\n\n'), snapshot: true } }
+        : {}),
       includePartialMessages: true,
       /*
        * Over the daemon's own environment, never instead of it.
@@ -1374,6 +1494,11 @@ export function createSession(options: SessionOptions): Session {
       // From the settings, which is where it lives: it is a config key like
       // the others, and a second way in was a second thing to keep in step.
       ...(typeof settings.permissionMode === 'string' ? { permissionMode: settings.permissionMode } : {}),
+      // The flag settings layer, which `applyFlagSettings` moves later: one
+      // place for the sandbox, whether it was set at creation or since.
+      ...(sandboxOf(settings.sandboxEnabled) !== null ? { settings: { sandbox: sandboxOf(settings.sandboxEnabled) } } : {}),
+      // Before every shell command, while a client has a script in force.
+      hooks: { PreToolUse: [{ matcher: 'Bash', hooks: [sourceFirst] }] },
       /*
        * The lists, at the moment the query is built.
        *
@@ -1459,7 +1584,7 @@ export function createSession(options: SessionOptions): Session {
    */
   const ends = new Map<string, string>();
 
-  const beginTurn = (turnId: string, text: string, model?: Chosen, queuedMessageId?: string): void => {
+  const beginTurn = (turnId: string, text: string, model?: Chosen, queuedMessageId?: string, from?: MessageFrom): void => {
     if (model !== undefined && model.id !== chosen) {
       chosen = model.id;
       void handle.setModel(model.id === 'default' ? undefined : model.id).catch(() => {});
@@ -1484,7 +1609,8 @@ export function createSession(options: SessionOptions): Session {
       startedAt: new Date().toISOString(),
       message: {
         text,
-        origin: { kind: 'user' },
+        origin: from?.origin ?? { kind: 'user' },
+        ...(from?._meta ? { _meta: from._meta } : {}),
         ...(chosen ? { model: { id: chosen, ...(model?.config ? { config: model.config } : {}) } } : {}),
       },
       responseParts: [],
@@ -1542,7 +1668,12 @@ export function createSession(options: SessionOptions): Session {
     let model: Chosen | undefined;
     if (id !== undefined)
       model = named.config ? { id, config: named.config as NonNullable<Chosen['config']> } : { id };
-    beginTurn(crypto.randomUUID(), str(message.text) ?? '', model, str(next.id));
+    // With whose it was: a message an agent queued is still an agent's when
+    // its turn comes.
+    const from: MessageFrom = {};
+    if (message.origin !== undefined) from.origin = bag(message.origin) as NonNullable<MessageFrom['origin']>;
+    if (message._meta !== undefined) from._meta = bag(message._meta);
+    beginTurn(crypto.randomUUID(), str(message.text) ?? '', model, str(next.id), from);
   };
 
   /**
@@ -1764,6 +1895,40 @@ export function createSession(options: SessionOptions): Session {
           if (entry !== undefined) ends.set(String(active.id), entry);
         }
 
+        /*
+         * A running subagent, saying how far it has got.
+         *
+         * `task_progress` is the harness's own status line for a `Task`
+         * that is still running: a model-written summary when the option
+         * is on, or the last tool it reached for. It goes on the call as
+         * `_meta.progressMessage` - the reference client's word for a line
+         * drawn on a running row and dropped when the row ends - and never
+         * into the result, which is what the tool answered and not what it
+         * was doing on the way. The reducer replaces a call's whole `_meta`
+         * on any action that carries one, so the kind stamped at the start
+         * is carried along rather than lost. The same line twice is said
+         * once.
+         */
+        if (type === 'system' && str(message.subtype) === 'task_progress') {
+          const id = str(message.tool_use_id);
+          const part = id === undefined ? undefined : parts.get(id);
+          const call = part === undefined ? undefined : bag(part.toolCall);
+          const line = str(message.summary)
+            ?? (str(message.last_tool_name) !== undefined ? `Running ${String(message.last_tool_name)}` : undefined);
+          if (call !== undefined && line !== undefined && str(call.status) === 'running'
+            && str(bag(call._meta).progressMessage) !== line) {
+            call._meta = { ...bag(call._meta), progressMessage: line };
+            emit('chat', {
+              type: 'chat/toolCallContentChanged',
+              turnId: active?.id,
+              toolCallId: id,
+              content: list(call.content),
+              _meta: call._meta,
+            });
+          }
+          continue;
+        }
+
         if (type === 'stream_event') { streamed(bag(message.event)); continue; }
         if (type === 'assistant') { assistant(bag(message.message)); continue; }
         if (type === 'user') {
@@ -1984,7 +2149,14 @@ export function createSession(options: SessionOptions): Session {
         settings.permissions = held;
         return true;
       }
+      if (key === 'shellInitScripts') return setShellInit(value);
       const said = typeof value === 'string' ? value : '';
+      if (key === 'sandboxEnabled') {
+        if (said !== 'default' && said !== 'on' && said !== 'off') return `sandboxEnabled takes default, on or off, not ${said}`;
+        settings.sandboxEnabled = said;
+        void handle.applyFlagSettings({ sandbox: sandboxOf(said) }).catch(() => {});
+        return true;
+      }
       if (key === 'model') {
         try {
           await handle.setModel(said === 'default' ? undefined : said);
@@ -2171,7 +2343,8 @@ export function createSession(options: SessionOptions): Session {
      * that cannot, because the transcript would then credit a turn to a model
      * that never ran it.
      */
-    begin: (turnId, text, model) => beginTurn(turnId, text, model),
+    begin: (turnId, text, model, from) => beginTurn(turnId, text, model, undefined, from),
+    setTitle: (said) => { if (said !== '') title = said; },
 
     /**
      * A turn this host answered itself, with a shell rather than the agent.
@@ -2224,11 +2397,15 @@ export function createSession(options: SessionOptions): Session {
         // The person typed it themselves, so there is nobody left to ask.
         confirmed: 'not-needed',
         status: 'running',
+        _meta: { toolKind: 'terminal' },
       } satisfies OnWire<ToolCallRunningState> as Bag;
-      holdPart(turn, call);
+      // As a part, the way every other call is held: the bare call went
+      // into the snapshot with no `kind`, so a client that subscribed after
+      // the command ran had a row it could not draw.
+      holdPart(turn, { id: toolCallId, kind: 'toolCall', toolCall: call });
       emit('chat', {
         type: 'chat/toolCallStart', turnId, toolCallId, toolName: 'terminal',
-        displayName: 'Terminal', intention: command,
+        displayName: 'Terminal', intention: command, _meta: { toolKind: 'terminal' },
       });
       emit('chat', {
         type: 'chat/toolCallReady', turnId, toolCallId,
@@ -2320,12 +2497,13 @@ export function createSession(options: SessionOptions): Session {
      * immediately started, which is a queue entry a client sees appear and
      * leave rather than one that was never there.
      */
-    queue: (id, text, model) => {
+    queue: (id, text, model, from) => {
       const entry: Bag = {
         id,
         message: {
           text,
-          origin: { kind: 'user' },
+          origin: from?.origin ?? { kind: 'user' },
+          ...(from?._meta ? { _meta: from._meta } : {}),
           ...(model ? { model: { id: model.id, ...(model.config ? { config: model.config } : {}) } } : {}),
         },
       };
@@ -2629,6 +2807,8 @@ export function createSession(options: SessionOptions): Session {
         one.settle({ behavior: 'deny', message: 'The session was disposed' });
       }
       releaseCalls('The session was disposed');
+      try { rmSync(initScript, { force: true }); }
+      catch { /* a script that was never written */ }
       handle.close();
     },
   };

package/src/transcript.ts

@@ -1,6 +1,7 @@
 import { getSessionMessages } from '@anthropic-ai/claude-agent-sdk';
 import type { ResponsePart, ToolCallCompletedState, ToolResultContent, Turn } from '@microsoft/agent-host-protocol';
 import type { Bag, OnWire, WireTurn } from '@ahpd/sdk';
+import { toolMetaOf } from './kinds.js';
 
 /**
  * Reads a session that already happened, as turns.
@@ -149,6 +150,7 @@ export async function turnsOf(sessionId: string, dir: string): Promise<WireTurn<
       } else if (kind === 'tool_use') {
         const name = str(block.name) ?? 'tool';
         const command = summarize(name, bag(block.input));
+        const meta = toolMetaOf(name);
         /*
          * Checked against the state it claims to be in, at the moment it is
          * built.
@@ -167,6 +169,9 @@ export async function turnsOf(sessionId: string, dir: string): Promise<WireTurn<
           // a call still reading `running` would be a spinner that never stops.
           status: 'completed',
           ...(command ? { toolInput: command } : {}),
+          // The same hint a live call carries, so a transcript read back off
+          // disk draws its shell commands as shell commands.
+          ...(meta ? { _meta: meta } : {}),
           /*
            * Required on a completed call, all four of them, and this builder
            * sent one of them sometimes.