@ahpd/agent-claude 0.3.0 → 0.5.0

package/dist/session.js

@@ -1,6 +1,10 @@
+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 { protectedResource, urlOf } from './mcp.js';
+import { toolMetaOf } from './kinds.js';
 import { Status, idOf, tail } from '@ahpd/sdk';
 /**
  * The effort levels this backend has, weakest first.
@@ -39,6 +43,39 @@ const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const bag = (value) => (typeof value === 'object' && value !== null ? value : {});
 const list = (value) => (Array.isArray(value) ? value : []);
 const str = (value) => (typeof value === 'string' ? value : undefined);
+/** 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) => {
+    if (!Array.isArray(value))
+        return undefined;
+    const list = [];
+    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) => `{ . '${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) => (value === 'on' ? { enabled: true } : value === 'off' ? { enabled: false } : null);
 /**
  * What a tool call is *about*, in one line.
  *
@@ -498,6 +535,48 @@ export function createSession(options) {
      * backend declared a string are narrowed where they are read.
      */
     const settings = { 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) => {
+        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 = 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.
      *
@@ -866,12 +945,17 @@ export function createSession(options) {
                 const contributor = from === undefined
                     ? undefined
                     : { kind: 'mcp', 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 = {
                     toolCallId: id,
                     toolName: name,
                     displayName: name,
                     status: 'streaming',
                     ...(contributor ? { contributor } : {}),
+                    ...(meta ? { _meta: meta } : {}),
                 };
                 const part = { id, kind: 'toolCall', toolCall: call };
                 parts.set(id, part);
@@ -883,6 +967,7 @@ export function createSession(options) {
                     toolName: name,
                     displayName: name,
                     ...(contributor ? { contributor } : {}),
+                    ...(meta ? { _meta: meta } : {}),
                 });
                 return;
             }
@@ -999,12 +1084,14 @@ export function createSession(options) {
                 // 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 = 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.
                      *
@@ -1056,6 +1143,7 @@ export function createSession(options) {
                         toolName: name,
                         displayName: name,
                         ...(contributor ? { contributor } : {}),
+                        ...(meta ? { _meta: meta } : {}),
                     });
                 }
                 emit('chat', {
@@ -1138,6 +1226,24 @@ export function createSession(options) {
              * 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);
@@ -1150,6 +1256,7 @@ export function createSession(options) {
                 turnId: active?.id,
                 toolCallId: id,
                 result,
+                ...(progressed ? { _meta: call._meta ?? {} } : {}),
             });
         }
     };
@@ -1241,11 +1348,13 @@ export function createSession(options) {
             // 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 } : {}),
             };
             call.status = 'pending-confirmation';
             call.confirmationTitle = confirmationTitle;
@@ -1257,7 +1366,10 @@ export function createSession(options) {
                 const part = { 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',
@@ -1301,6 +1413,17 @@ export function createSession(options) {
              * `setMcpServers` does not touch servers that came from a settings file.
              */
             ...(Object.keys(declared).length > 0 ? { mcpServers: declared } : {}),
+            /*
+             * 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', preset: 'claude_code', append: options.instructions.join('\n\n'), snapshot: true } }
+                : {}),
             includePartialMessages: true,
             /*
              * Over the daemon's own environment, never instead of it.
@@ -1316,6 +1439,11 @@ export function createSession(options) {
             // 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.
              *
@@ -1397,7 +1525,7 @@ export function createSession(options) {
      * remembers giving.
      */
     const ends = new Map();
-    const beginTurn = (turnId, text, model, queuedMessageId) => {
+    const beginTurn = (turnId, text, model, queuedMessageId, from) => {
         if (model !== undefined && model.id !== chosen) {
             chosen = model.id;
             void handle.setModel(model.id === 'default' ? undefined : model.id).catch(() => { });
@@ -1422,7 +1550,8 @@ export function createSession(options) {
             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: [],
@@ -1480,7 +1609,14 @@ export function createSession(options) {
         let model;
         if (id !== undefined)
             model = named.config ? { id, config: named.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 = {};
+        if (message.origin !== undefined)
+            from.origin = bag(message.origin);
+        if (message._meta !== undefined)
+            from._meta = bag(message._meta);
+        beginTurn(crypto.randomUUID(), str(message.text) ?? '', model, str(next.id), from);
     };
     /**
      * Ask the CLI what it can do, without asking it to do anything.
@@ -1699,6 +1835,39 @@ export function createSession(options) {
                     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;
@@ -1921,7 +2090,16 @@ export function createSession(options) {
                 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);
@@ -2106,7 +2284,9 @@ export function createSession(options) {
          * 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.
          *
@@ -2159,11 +2339,15 @@ export function createSession(options) {
                 // The person typed it themselves, so there is nobody left to ask.
                 confirmed: 'not-needed',
                 status: 'running',
+                _meta: { toolKind: 'terminal' },
             };
-            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,
@@ -2256,12 +2440,13 @@ export function createSession(options) {
          * 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 = {
                 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 } : {}) } } : {}),
                 },
             };
@@ -2575,6 +2760,10 @@ export function createSession(options) {
                 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();
         },
     };