super-dsh 0.1.0 → 0.1.2

package/agent-claude/dist/claude-client.js

@@ -0,0 +1,357 @@
+/**
+ * ClaudeSdkClient — the lazy, host-binary-driven Claude Agent SDK bridge client.
+ *
+ * The Claude Agent SDK is a *bridge*: `query()` spawns a real Claude Code CLI
+ * subprocess and speaks the stream-json control protocol to it. This client owns
+ * that bridge's lifecycle for the adapter. It hands `query()` a streaming-input
+ * iterable (an {@link InputQueue}, which is what makes the `Query` control
+ * methods exist at all), drives the bridge lazily per session, and fans every
+ * message out through `projectClaudeEvent` (claude-events.ts).
+ *
+ * ## The two hard deviations from the codex precedent
+ *
+ * 1. **No shared singleton.** `agent-codex` multiplexes all clients through one
+ *    module-level refcounted SDK instance. That is impossible here: the Claude
+ *    SDK's `Query` owns its own CLI subprocess AND its own streaming-input
+ *    iterator, so one `Query` cannot serve multiple sessions. Each
+ *    `ClaudeSdkClient` instance therefore owns its own `Query`. The module-level
+ *    `claudeClientRefCount()` still tracks how many instances are live (it goes
+ *    1 -> 0 across construction and `close()`), but it never shares a query
+ *    between instances.
+ *
+ * 2. **`Options.env` REPLACES the subprocess environment.** Verified verbatim
+ *    from `sdk.d.ts`: "When set, this value REPLACES the subprocess environment
+ *    entirely — it is not merged with `process.env`. Spread `process.env`
+ *    yourself if the subprocess still needs inherited variables like `PATH`,
+ *    `HOME`, or `ANTHROPIC_API_KEY`." So the options built here are always
+ *    `env: { ...process.env }`. A bare partial env would strip PATH/HOME/the
+ *    API key and the CLI would fail with an opaque startup error far from the
+ *    cause. NO `CLAUDE_CONFIG_DIR` is injected: the CLI resolves its own
+ *    native `~/.claude` (2026-09-17 home ruling; tests redirect via the
+ *    ambient env).
+ *
+ * ## Design decisions the brief left open (each pinned by a test)
+ *
+ * - **Zero-IO construction**: the injectable factory is never called until the
+ *   first `prompt()` runs `ensureStarted()`.
+ * - **Pending control calls** (`setModel` / `setPermissionMode` / `interrupt`)
+ *   made before the query exists are *buffered and replayed in order* inside
+ *   `ensureStarted()` — never silently dropped. They do NOT spawn the CLI on
+ *   their own (a control call is not a turn).
+ * - **Reader loop**: consumes the query's async iterator, projects each message,
+ *   and delivers the wire events to listeners. On normal iterator end it emits
+ *   `{ type: "agent_end" }`; on a throw it emits
+ *   `{ type: "agent_end", isError: true, error }` and records the failure. The
+ *   loop catches its own errors, so a stream that ends never leaves a dangling
+ *   or unhandled promise.
+ * - **`close()`** is idempotent and safe before `ensureStarted()`; it closes the
+ *   input queue (if any), closes the query (if any), and decrements the refcount
+ *   exactly once.
+ * - **Post-close pushes**: the client guards with a clear
+ *   `"agent-claude: client is closed"` error *before* reaching the input queue,
+ *   rather than surfacing the queue's lower-level "input queue is closed".
+ * - **`followUp`** is surface parity with `prompt` — in streaming-input mode
+ *   every push is queued in order and there is no separate follow-up channel.
+ *   `steer` differs by pushing with `priority: "now"`.
+ */
+import { query as officialQuery } from "@anthropic-ai/claude-agent-sdk";
+import { InputQueue } from "./input-queue.js";
+import { projectClaudeEvent } from "./claude-events.js";
+/** Host Claude Code binary driven through the SDK's bridge (spec ruling R5). */
+export const DEFAULT_CLAUDE_EXECUTABLE = "/home/u1/.local/bin/claude";
+const defaultFactory = (o) => officialQuery({
+    prompt: o.prompt,
+    options: o.options,
+});
+const defaultExecutableResolver = () => process.env.CLAUDE_EXECUTABLE ?? DEFAULT_CLAUDE_EXECUTABLE;
+let factory = defaultFactory;
+let executableResolver = defaultExecutableResolver;
+let refcount = 0;
+/** Replace the SDK entry point (tests inject a fake query). */
+export function setClaudeFactory(next) {
+    factory = next;
+}
+/** Replace the pathToClaudeCodeExecutable resolution. */
+export function setClaudeExecutableResolver(next) {
+    executableResolver = next;
+}
+/** Test/observability hook: current live-instance refcount (0 = none alive). */
+export function claudeClientRefCount() {
+    return refcount;
+}
+/** Restore module-level seams and refcount (test isolation only). */
+export function resetClaudeClientState() {
+    refcount = 0;
+    factory = defaultFactory;
+    executableResolver = defaultExecutableResolver;
+}
+/**
+ * Boot model probe (RC-3): spawn ONE ephemeral SDK query — a streaming-input
+ * queue with NO user prompt — ask its `supportedModels()`, and close (the
+ * hermes probe-client-then-close precedent). Runs through the module factory,
+ * so tests inject a fake query. `persistSession: false` keeps the probe from
+ * leaving a session in the CLI's native home. Failure (including the timeout
+ * race, which guards against a wedged startup pinning a subprocess forever)
+ * is the caller's to trace; the boot catalog stays as-is.
+ */
+export async function probeClaudeModels(config = {}) {
+    const queue = new InputQueue();
+    const query = factory({
+        prompt: queue,
+        options: {
+            cwd: config.cwd ?? process.cwd(),
+            env: { ...process.env },
+            pathToClaudeCodeExecutable: executableResolver(),
+            persistSession: false,
+        },
+    });
+    const timeoutMs = config.timeoutMs ?? 20_000;
+    try {
+        const ask = typeof query.supportedModels === "function"
+            ? query.supportedModels()
+            : Promise.resolve([]);
+        const models = await Promise.race([
+            ask,
+            new Promise((_, reject) => {
+                const timer = setTimeout(() => reject(new Error(`boot model probe timed out after ${timeoutMs}ms`)), timeoutMs);
+                timer.unref?.();
+            }),
+        ]);
+        return Array.isArray(models) ? models : [];
+    }
+    finally {
+        queue.close();
+        query.close();
+    }
+}
+export class ClaudeSdkClient {
+    cwdPath;
+    claudeSessionId;
+    resumeSessionId;
+    canUseTool;
+    allowDangerouslySkipPermissions;
+    /** True while a user turn is in flight (set on push, cleared on `turn_end`/`agent_end`). */
+    turnActive = false;
+    queue;
+    query;
+    pendingControls = [];
+    listeners = new Set();
+    threadIdValue = null;
+    closed = false;
+    terminated = false;
+    failure = null;
+    constructor(config) {
+        if (config.claudeSessionId !== undefined && config.resumeSessionId !== undefined) {
+            throw new Error("agent-claude: claudeSessionId and resumeSessionId are mutually exclusive");
+        }
+        this.cwdPath = config.cwd ?? process.cwd();
+        this.claudeSessionId = config.claudeSessionId;
+        this.resumeSessionId = config.resumeSessionId;
+        this.canUseTool = config.canUseTool;
+        this.allowDangerouslySkipPermissions = config.allowDangerouslySkipPermissions;
+        refcount += 1;
+    }
+    /**
+     * Whether the query has been constructed yet (lazy spawn). This reports
+     * "the query was constructed", not "the session is alive": `close()` does
+     * not clear it.
+     */
+    get spawned() {
+        return this.query !== undefined;
+    }
+    /** The cwd the CLI will be spawned in (constructor fact, read by the agent). */
+    get cwd() {
+        return this.cwdPath;
+    }
+    /** The SDK session id, filled from the session-init message when it arrives. */
+    get threadId() {
+        return this.threadIdValue;
+    }
+    /** The client's own running/streaming attestation (idle-TTL revalidation gate). */
+    async getState() {
+        return { isStreaming: this.turnActive };
+    }
+    /** Advertise the CLI's supported models; empty before the query exists. */
+    async supportedModels() {
+        if (this.query === undefined)
+            return [];
+        if (this.query.supportedModels === undefined)
+            return [];
+        return this.query.supportedModels();
+    }
+    /**
+     * Advertise the CLI's slash commands (name + description + argument hint);
+     * empty before the query exists, and empty on a CLI/fake without the control.
+     * The SDK returns its latest pushed snapshot; nothing here re-fetches the
+     * CLI mid-session, so a command the runtime learns about after `session_init`
+     * (unless the `inject` re-run reports it) never appears. That is a known
+     * limitation, not a freshness guarantee.
+     */
+    async supportedCommands() {
+        if (this.query === undefined)
+            return [];
+        if (this.query.supportedCommands === undefined)
+            return [];
+        return this.query.supportedCommands();
+    }
+    /** Register a wire event listener; returns the unsubscriber. */
+    on(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /**
+     * Lazily construct the query (zero-IO until this runs). Everything up to the
+     * `this.query = query` assignment is synchronous, so concurrent first prompts
+     * can never build two queries: the first caller assigns `this.query` before
+     * any `await` yields control. This single-query invariant therefore depends
+     * on the `ClaudeFactory` contract staying synchronous (it must return the
+     * `Query` without awaiting). The reader loop is started fire-and-forget before
+     * any pending control call is replayed, so a throwing control can never leave
+     * the CLI undrained.
+     */
+    async ensureStarted() {
+        if (this.query !== undefined)
+            return;
+        const queue = new InputQueue();
+        const query = factory({ prompt: queue, options: this.buildOptions() });
+        this.queue = queue;
+        this.query = query;
+        void this.runReader(query);
+        const controls = this.pendingControls;
+        this.pendingControls = [];
+        for (const control of controls) {
+            await control();
+        }
+    }
+    /**
+     * Queue a user turn (plain priority). Accepts plain text OR transcoded
+     * Anthropic blocks; the block array is handed through unchanged.
+     */
+    async prompt(content) {
+        this.ensureUsable();
+        await this.ensureStarted();
+        this.push(content, undefined);
+    }
+    /** Surface parity with prompt: a plain queued user turn. */
+    async followUp(content) {
+        this.ensureUsable();
+        await this.ensureStarted();
+        this.push(content, undefined);
+    }
+    /** Steer the in-flight turn: a user message with priority "now". */
+    async steer(content) {
+        this.ensureUsable();
+        await this.ensureStarted();
+        this.push(content, "now");
+    }
+    /** Select the active model (buffered until the query exists, then replayed). */
+    async setModel(model) {
+        this.ensureUsable();
+        if (this.query === undefined) {
+            this.pendingControls.push(() => this.query?.setModel(model));
+            return;
+        }
+        await this.query.setModel(model);
+    }
+    /** Change the permission mode (buffered until the query exists, then replayed). */
+    async setPermissionMode(mode) {
+        this.ensureUsable();
+        if (this.query === undefined) {
+            this.pendingControls.push(() => this.query?.setPermissionMode(mode));
+            return;
+        }
+        await this.query.setPermissionMode(mode);
+    }
+    /** Interrupt the current turn (buffered until the query exists, then replayed). */
+    async interrupt() {
+        this.ensureUsable();
+        if (this.query === undefined) {
+            this.pendingControls.push(() => this.query?.interrupt());
+            return undefined;
+        }
+        return this.query.interrupt();
+    }
+    /** Close the queue, close the query, and release the refcount (idempotent). */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.queue?.close();
+        this.query?.close();
+        refcount = Math.max(0, refcount - 1);
+    }
+    // --- internals ------------------------------------------------------------
+    buildOptions() {
+        return {
+            cwd: this.cwdPath,
+            env: { ...process.env },
+            pathToClaudeCodeExecutable: executableResolver(),
+            persistSession: true,
+            ...(this.claudeSessionId !== undefined ? { sessionId: this.claudeSessionId } : {}),
+            ...(this.resumeSessionId !== undefined ? { resume: this.resumeSessionId } : {}),
+            ...(this.canUseTool !== undefined ? { canUseTool: this.canUseTool } : {}),
+            ...(this.allowDangerouslySkipPermissions !== undefined ? { allowDangerouslySkipPermissions: this.allowDangerouslySkipPermissions } : {}),
+        };
+    }
+    /**
+     * Push one turn through the queue. A plain string keeps the historical
+     * single-text-block normalization; a block array is handed through AS-IS so
+     * the transcoder's one-block-per-input-block shape reaches the SDK unchanged.
+     */
+    push(content, priority) {
+        this.turnActive = true;
+        this.queue.pushContent(content, {
+            parent_tool_use_id: null,
+            ...(this.claudeSessionId !== undefined ? { session_id: this.claudeSessionId } : {}),
+            ...(priority !== undefined ? { priority } : {}),
+        });
+    }
+    ensureUsable() {
+        if (this.closed)
+            throw new Error("agent-claude: client is closed");
+        if (this.failure !== null)
+            throw this.failure;
+        if (this.terminated)
+            throw new Error("agent-claude: session has ended");
+    }
+    async runReader(query) {
+        try {
+            for await (const message of query) {
+                const wire = projectClaudeEvent(message);
+                if (wire === null)
+                    continue;
+                const events = Array.isArray(wire) ? wire : [wire];
+                for (const event of events) {
+                    if (event.type === "session_init" && typeof event.sessionId === "string") {
+                        this.threadIdValue = event.sessionId;
+                    }
+                    if (event.type === "turn_end")
+                        this.turnActive = false;
+                    this.emit(event);
+                }
+            }
+            this.terminated = true;
+            this.turnActive = false;
+            this.emit({ type: "agent_end" });
+        }
+        catch (error) {
+            this.terminated = true;
+            this.failure = error instanceof Error ? error : new Error(String(error));
+            process.stderr.write(`agent-claude: query stream error: ${String(error)}\n`);
+            this.turnActive = false;
+            this.emit({ type: "agent_end", isError: true, error: this.failure.message });
+        }
+    }
+    emit(event) {
+        for (const listener of [...this.listeners]) {
+            try {
+                listener(event);
+            }
+            catch (error) {
+                process.stderr.write(`agent-claude: listener error: ${String(error)}\n`);
+            }
+        }
+    }
+}

package/agent-claude/dist/claude-events.js

@@ -0,0 +1,223 @@
+let toolNames = new Map();
+export function resetProjectionState() {
+    toolNames = new Map();
+}
+/**
+ * SDK tool name → native dsh tool name (2026-09-18). Keys are the Claude
+ * Agent SDK's built-in tool names; values are the dsh vocabulary the WebUI's
+ * typed presenters recognize. Unknown names pass through untouched.
+ */
+const TOOL_NAME_ALIASES = {
+    Bash: "bash",
+    Read: "read",
+    Write: "write",
+    Edit: "edit",
+    Grep: "grep",
+    Glob: "glob",
+    MultiEdit: "edit",
+    NotebookEdit: "edit",
+};
+/** Normalize one SDK tool name onto the dsh vocabulary (verbatim when unknown). */
+export function normalizeToolName(name) {
+    return TOOL_NAME_ALIASES[name] ?? name;
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+function textOf(content) {
+    const result = { text: "", reasoning: "", tool: [] };
+    if (!Array.isArray(content))
+        return result;
+    for (const raw of content) {
+        const block = asRecord(raw);
+        if (block === null)
+            continue;
+        if (block.type === "text" && typeof block.text === "string")
+            result.text += block.text;
+        // Reasoning reaches the wire in two shapes: the Beta API `reasoning`
+        // block (`{type, text}`) and the CLI's `thinking` block (`{type,
+        // thinking}`). Both fold into the same reasoning text.
+        if (block.type === "reasoning" && typeof block.text === "string")
+            result.reasoning += block.text;
+        if (block.type === "thinking" && typeof block.thinking === "string")
+            result.reasoning += block.thinking;
+        if (block.type === "tool_use")
+            result.tool.push(block);
+    }
+    return result;
+}
+/**
+ * Claude `TodoWrite` input → the DSH `todo/write` whole-list snapshot payload
+ * (`TodoItem { content, status }`; upstream packages/todo/tool-todo). The
+ * whole list is replaced on every write (latest-wins). Defensive: rows with
+ * no usable content text are dropped, and an unknown status degrades to
+ * `pending`. Returns undefined when the input carries no todos array at all
+ * (not a todo write), so a malformed call never clears the list.
+ */
+function todoSnapshot(input) {
+    if (input === null || typeof input !== "object" || Array.isArray(input))
+        return undefined;
+    const items = input.todos;
+    if (!Array.isArray(items))
+        return undefined;
+    const todos = [];
+    for (const entry of items) {
+        const record = asRecord(entry);
+        if (record === null)
+            continue;
+        const content = typeof record.content === "string" ? record.content : "";
+        if (content === "")
+            continue;
+        const status = record.status === "completed" || record.status === "in_progress" ? record.status : "pending";
+        todos.push({ content, status });
+    }
+    return todos;
+}
+export function projectClaudeEvent(message) {
+    const msg = asRecord(message);
+    if (msg === null || typeof msg.type !== "string")
+        return null;
+    if (msg.type === "system") {
+        switch (msg.subtype) {
+            case "init":
+                return {
+                    type: "session_init",
+                    sessionId: msg.session_id,
+                    cwd: msg.cwd,
+                    model: msg.model,
+                    permissionMode: msg.permissionMode,
+                    tools: msg.tools,
+                    slashCommands: msg.slash_commands,
+                    skills: msg.skills,
+                    plugins: msg.plugins,
+                    mcpServers: msg.mcp_servers,
+                    cliVersion: msg.claude_code_version,
+                    apiKeySource: msg.apiKeySource,
+                };
+            case "compact_boundary":
+                return { type: "compaction", metadata: msg.compact_metadata };
+            case "permission_denied":
+                return {
+                    type: "permission_denied",
+                    toolName: msg.tool_name,
+                    callId: msg.tool_use_id,
+                    reasonType: msg.decision_reason_type,
+                };
+            case "model_refusal_fallback":
+                return {
+                    type: "refusal_fallback",
+                    direction: msg.direction,
+                    scope: msg.scope ?? "session",
+                    originalModel: msg.original_model,
+                    fallbackModel: msg.fallback_model,
+                    category: msg.api_refusal_category ?? null,
+                    explanation: msg.api_refusal_explanation ?? null,
+                    retractedMessageUuids: msg.retracted_message_uuids ?? [],
+                    refusedUserMessageUuid: msg.refused_user_message_uuid ?? null,
+                    content: msg.content,
+                };
+            case "model_refusal_no_fallback":
+                return {
+                    type: "refusal_no_fallback",
+                    originalModel: msg.original_model,
+                    category: msg.api_refusal_category ?? null,
+                    explanation: msg.api_refusal_explanation ?? null,
+                    refusedUserMessageUuid: msg.refused_user_message_uuid ?? null,
+                    content: msg.content,
+                };
+            case "local_command_output":
+                return { type: "local_command_output", content: msg.content };
+            default:
+                return null;
+        }
+    }
+    if (msg.type === "assistant") {
+        const body = asRecord(msg.message);
+        const parsed = textOf(body?.content);
+        const out = [];
+        // Per-message accounting rides every event projected from THIS message
+        // (RC-6): the agent closes the step's attempt with the usage of the
+        // message that opened it, so a tool_start flush still lands a sample.
+        const usage = asRecord(body?.usage);
+        const model = typeof body?.model === "string" && body.model !== "" ? body.model : undefined;
+        const provenance = {
+            ...(usage === null ? {} : { usage }),
+            ...(model === undefined ? {} : { model }),
+        };
+        if (parsed.reasoning !== "")
+            out.push({ type: "assistant_reasoning", text: parsed.reasoning, parentToolUseId: msg.parent_tool_use_id ?? null, ...provenance });
+        if (parsed.text !== "")
+            out.push({ type: "assistant_text", text: parsed.text, parentToolUseId: msg.parent_tool_use_id ?? null, ...provenance });
+        for (const block of parsed.tool) {
+            const id = String(block.id ?? "");
+            const name = normalizeToolName(String(block.name ?? "tool"));
+            if (id !== "")
+                toolNames.set(id, name);
+            out.push({
+                type: "tool_start",
+                callId: id,
+                name,
+                arguments: block.input ?? {},
+                parentToolUseId: msg.parent_tool_use_id ?? null,
+                ...provenance,
+            });
+            // `TodoWrite` ALSO projects the DSH `todo/write` whole-list snapshot
+            // (log-only, latest-wins) after the tool_start — the tool pair stays.
+            if (String(block.name ?? "") === "TodoWrite") {
+                const todos = todoSnapshot(block.input ?? null);
+                if (todos !== undefined)
+                    out.push({ type: "todo_write", todos });
+            }
+        }
+        if (out.length === 0)
+            out.push({ type: "assistant_message", raw: body ?? null });
+        return out;
+    }
+    if (msg.type === "user") {
+        const body = asRecord(msg.message);
+        const content = Array.isArray(body?.content) ? body.content : [];
+        const out = [];
+        for (const raw of content) {
+            const block = asRecord(raw);
+            if (block?.type !== "tool_result")
+                continue;
+            const callId = String(block.tool_use_id ?? "");
+            const text = typeof block.content === "string"
+                ? block.content
+                : Array.isArray(block.content)
+                    ? block.content.map((part) => String(asRecord(part)?.text ?? "")).join("")
+                    : "";
+            out.push({
+                type: "tool_end",
+                callId,
+                name: toolNames.get(callId) ?? "tool",
+                content: text,
+                isError: block.is_error === true,
+                parentToolUseId: msg.parent_tool_use_id ?? null,
+            });
+        }
+        // One result is the common shape and stays a bare event; only a parallel
+        // tool_result batch needs the array form (mirrors codex-events' toolEnd).
+        return out.length === 0 ? null : out.length === 1 ? out[0] : out;
+    }
+    if (msg.type === "result") {
+        return {
+            type: "turn_end",
+            subtype: msg.subtype,
+            isError: msg.is_error === true,
+            numTurns: msg.num_turns,
+            durationMs: msg.duration_ms,
+            durationApiMs: msg.duration_api_ms,
+            costUsd: msg.total_cost_usd,
+            usage: msg.usage,
+            modelUsage: msg.modelUsage,
+            permissionDenials: msg.permission_denials,
+            result: msg.result,
+            errors: msg.errors,
+            stopReason: msg.stop_reason ?? null,
+        };
+    }
+    return null;
+}

package/agent-claude/dist/claude-home.js

@@ -0,0 +1,29 @@
+/**
+ * Claude Code app-home resolution (native home, user ruling 2026-09-17).
+ *
+ * The installed Claude CLI keeps its own native home (`~/.claude`; an ambient
+ * `CLAUDE_CONFIG_DIR` overrides in tests). The adapter never redirects it at
+ * spawn and never copies config into it — this supersedes the S7 nested-home
+ * layout (`<dshHome>/agents/claude`) and its one-way config valve, matching
+ * the agent-pi precedent.
+ */
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+const PROD_HOMES = [join(homedir(), ".dsh"), join(homedir(), ".superd")];
+/** Refuse any path that resolves into a production DSH home (repo red line). */
+export function assertNotProdHome(path, label) {
+    const p = resolve(path);
+    if (PROD_HOMES.includes(p) || PROD_HOMES.some((prod) => p.startsWith(`${prod}/`))) {
+        throw new Error(`agent-claude: refusing prod home "${p}" for ${label} — set DSH_HOME to the test home`);
+    }
+}
+/**
+ * The Claude app home: the NATIVE `~/.claude`, prod-home guarded. An ambient
+ * `CLAUDE_CONFIG_DIR` wins (tests pin an isolated home that way); the adapter
+ * itself never sets the variable when spawning the CLI.
+ */
+export function resolveClaudeHome() {
+    const claudeHome = resolve(process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), ".claude"));
+    assertNotProdHome(claudeHome, "claudeHome");
+    return claudeHome;
+}