@hyperdrive.bot/paseo-server 0.2.6

package/dist/server/server/agent/providers/claude/sidechain-tracker.js

@@ -0,0 +1,232 @@
+import { mapClaudeRunningToolCall } from "./tool-call-mapper.js";
+import { buildToolCallDisplayModel } from "@hyperdrive.bot/paseo-protocol/tool-call-display";
+const MAX_SUB_AGENT_LOG_ENTRIES = 200;
+const MAX_SUB_AGENT_SUMMARY_CHARS = 160;
+function readTrimmedString(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function isClaudeContentChunk(value) {
+    return Boolean(value && typeof value === "object" && typeof value.type === "string");
+}
+export class ClaudeSidechainTracker {
+    constructor(input) {
+        this.activeSidechains = new Map();
+        this.getToolInput = input.getToolInput;
+    }
+    handleMessage(message, parentToolUseId) {
+        const state = this.activeSidechains.get(parentToolUseId) ??
+            {
+                actions: [],
+                actionKeys: [],
+                nextActionIndex: 1,
+                actionIndexByKey: new Map(),
+            };
+        this.activeSidechains.set(parentToolUseId, state);
+        const contextUpdated = this.updateSubAgentContextFromTaskInput(state, parentToolUseId);
+        const actionCandidates = this.extractSubAgentActionCandidates(message);
+        let actionUpdated = false;
+        for (const action of actionCandidates) {
+            if (this.appendSubAgentAction(state, action)) {
+                actionUpdated = true;
+            }
+        }
+        if (!contextUpdated && !actionUpdated) {
+            return [];
+        }
+        const toolCall = mapClaudeRunningToolCall({
+            name: "Task",
+            callId: parentToolUseId,
+            input: null,
+            output: null,
+        });
+        if (!toolCall) {
+            return [];
+        }
+        const detail = {
+            type: "sub_agent",
+            ...(state.subAgentType ? { subAgentType: state.subAgentType } : {}),
+            ...(state.description ? { description: state.description } : {}),
+            log: state.actions
+                .map((action) => action.summary ? `[${action.toolName}] ${action.summary}` : `[${action.toolName}]`)
+                .join("\n"),
+            actions: [],
+        };
+        return [
+            {
+                type: "timeline",
+                item: {
+                    ...toolCall,
+                    detail,
+                },
+                provider: "claude",
+            },
+        ];
+    }
+    delete(toolUseId) {
+        this.activeSidechains.delete(toolUseId);
+    }
+    clear() {
+        this.activeSidechains.clear();
+    }
+    updateSubAgentContextFromTaskInput(state, parentToolUseId) {
+        const taskInput = this.getToolInput(parentToolUseId);
+        const nextSubAgentType = this.normalizeSubAgentText(taskInput?.subagent_type);
+        const nextDescription = this.normalizeSubAgentText(taskInput?.description);
+        let changed = false;
+        if (nextSubAgentType && nextSubAgentType !== state.subAgentType) {
+            state.subAgentType = nextSubAgentType;
+            changed = true;
+        }
+        if (nextDescription && nextDescription !== state.description) {
+            state.description = nextDescription;
+            changed = true;
+        }
+        return changed;
+    }
+    normalizeSubAgentText(value) {
+        const normalized = readTrimmedString(value)?.replace(/\s+/g, " ");
+        if (!normalized) {
+            return undefined;
+        }
+        if (normalized.length <= MAX_SUB_AGENT_SUMMARY_CHARS) {
+            return normalized;
+        }
+        return `${normalized.slice(0, MAX_SUB_AGENT_SUMMARY_CHARS)}...`;
+    }
+    extractAssistantMessageActions(message) {
+        const content = message.message?.content;
+        if (!Array.isArray(content)) {
+            return [];
+        }
+        const actions = [];
+        for (const block of content) {
+            if (!isClaudeContentChunk(block) ||
+                !(block.type === "tool_use" ||
+                    block.type === "mcp_tool_use" ||
+                    block.type === "server_tool_use") ||
+                typeof block.name !== "string") {
+                continue;
+            }
+            const key = readTrimmedString(block.id) ?? `assistant:${block.name}:${actions.length}`;
+            actions.push({
+                key,
+                toolName: block.name,
+                input: block.input ?? null,
+            });
+        }
+        return actions;
+    }
+    extractStreamEventActions(message) {
+        const event = message.event;
+        if (event.type !== "content_block_start") {
+            return [];
+        }
+        const block = isClaudeContentChunk(event.content_block) ? event.content_block : null;
+        if (!block ||
+            !(block.type === "tool_use" ||
+                block.type === "mcp_tool_use" ||
+                block.type === "server_tool_use") ||
+            typeof block.name !== "string") {
+            return [];
+        }
+        const key = readTrimmedString(block.id) ??
+            `stream:${block.name}:${typeof event.index === "number" ? event.index : 0}`;
+        return [
+            {
+                key,
+                toolName: block.name,
+                input: block.input ?? null,
+            },
+        ];
+    }
+    extractSubAgentActionCandidates(message) {
+        if (message.type === "assistant") {
+            return this.extractAssistantMessageActions(message);
+        }
+        if (message.type === "stream_event") {
+            return this.extractStreamEventActions(message);
+        }
+        if (message.type === "tool_progress") {
+            const toolName = readTrimmedString(message.tool_name);
+            if (!toolName) {
+                return [];
+            }
+            const key = readTrimmedString(message.tool_use_id) ?? `progress:${toolName}`;
+            return [{ key, toolName, input: null }];
+        }
+        return [];
+    }
+    appendSubAgentAction(state, candidate) {
+        const normalizedToolName = readTrimmedString(candidate.toolName);
+        if (!normalizedToolName) {
+            return false;
+        }
+        const summary = this.deriveSubAgentActionSummary(normalizedToolName, candidate.input);
+        const existingIndex = state.actionIndexByKey.get(candidate.key);
+        if (existingIndex !== undefined) {
+            const existing = state.actions[existingIndex];
+            if (!existing) {
+                return false;
+            }
+            const nextSummary = existing.summary ?? summary;
+            if (existing.toolName === normalizedToolName && existing.summary === nextSummary) {
+                return false;
+            }
+            state.actions[existingIndex] = {
+                ...existing,
+                toolName: normalizedToolName,
+                ...(nextSummary ? { summary: nextSummary } : {}),
+            };
+            return true;
+        }
+        state.actions.push({
+            index: state.nextActionIndex,
+            toolName: normalizedToolName,
+            ...(summary ? { summary } : {}),
+        });
+        state.nextActionIndex += 1;
+        state.actionKeys.push(candidate.key);
+        this.trimSubAgentTail(state);
+        this.rebuildSubAgentActionIndex(state);
+        return true;
+    }
+    trimSubAgentTail(state) {
+        while (state.actions.length > MAX_SUB_AGENT_LOG_ENTRIES) {
+            state.actions.shift();
+            state.actionKeys.shift();
+        }
+    }
+    rebuildSubAgentActionIndex(state) {
+        state.actionIndexByKey.clear();
+        for (let index = 0; index < state.actionKeys.length; index += 1) {
+            const key = state.actionKeys[index];
+            if (key) {
+                state.actionIndexByKey.set(key, index);
+            }
+        }
+    }
+    deriveSubAgentActionSummary(toolName, input) {
+        const runningToolCall = mapClaudeRunningToolCall({
+            name: toolName,
+            callId: `sub-agent-summary-${toolName}`,
+            input,
+            output: null,
+        });
+        if (!runningToolCall) {
+            return undefined;
+        }
+        const display = buildToolCallDisplayModel({
+            name: runningToolCall.name,
+            status: runningToolCall.status,
+            error: runningToolCall.error,
+            detail: runningToolCall.detail,
+            metadata: runningToolCall.metadata,
+        });
+        return this.normalizeSubAgentText(display.summary);
+    }
+}
+//# sourceMappingURL=sidechain-tracker.js.map

package/dist/server/server/agent/providers/claude/spawn-config-writer.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Maximum byte size for an inline `--append-system-prompt` payload before
+ * spilling to a file via `--append-system-prompt-file`. Conservative — most
+ * terminals buffer 64 KB+ but PTY line-buffer limits vary by OS. See Story 5.2
+ * for rationale.
+ */
+export declare const BOOT_PROMPT_MAX_INLINE_BYTES = 8192;
+/**
+ * Flag name for the file-based system-prompt variant. Centralized so a future
+ * upstream rename is a single edit. Verified at HEAD of `claude` 2.1.119 — the
+ * `--bare` help text lists `--append-system-prompt[-file]` as an exposed flag.
+ */
+export declare const SYSTEM_PROMPT_FILE_FLAG = "--append-system-prompt-file";
+export interface SpawnConfigWriteResult {
+    settingsPath: string;
+    mcpPath: string;
+}
+export declare function resolvePaseoBinary(): string;
+export interface SpawnConfigWriterOptions {
+    /** Override the paseo binary path resolution. Used by tests. */
+    paseoBinaryPath?: string;
+}
+export declare class SpawnConfigWriter {
+    private state;
+    private readonly options;
+    constructor(options?: SpawnConfigWriterOptions);
+    write(cwd: string, daemonPort: number): SpawnConfigWriteResult;
+    restore(cwd: string): void;
+}
+export interface BuildSpawnArgsOptions {
+    /** Stable per-session id — used to name the temp file. */
+    sessionId: string;
+    /** Resolved path to the `claude` binary (used to probe `--help` for flag availability). */
+    claudeBinary: string;
+    /** The appended system prompt payload. Empty/undefined → no flag emitted. */
+    appendSystemPrompt?: string;
+    /** Additional spawn args to append after the system-prompt flag pair. */
+    extraArgs?: string[];
+    /** Override `$PASEO_HOME` (defaults to `process.env.PASEO_HOME` or `~/.paseo`). Test hook. */
+    paseoHome?: string;
+    /**
+     * Test hook — override the `--help` probe. When set, the probe is skipped
+     * and the result is used verbatim. Production callers leave this undefined.
+     */
+    systemPromptFileFlagAvailable?: boolean;
+    /** Test hook — override the warning sink. Defaults to console.warn. */
+    warn?: (message: string) => void;
+}
+export interface BuildSpawnArgsResult {
+    args: string[];
+    /**
+     * Path to the temp file the writer created, if any. The caller (PtyTransport
+     * via AgentTransportSpawnOptions.systemPromptFilePath) is responsible for
+     * unlinking it on kill().
+     */
+    systemPromptFilePath: string | null;
+}
+/** Test-only — reset the `--help` probe cache between cases. */
+export declare function __resetSystemPromptFileFlagCacheForTesting(): void;
+/**
+ * Build the spawn args for the PTY transport, applying the boot-prompt
+ * size mitigation: payloads larger than {@link BOOT_PROMPT_MAX_INLINE_BYTES}
+ * are written to `$PASEO_HOME/tmp/system-prompt-<sessionId>.txt` and passed
+ * via {@link SYSTEM_PROMPT_FILE_FLAG} instead of inline.
+ *
+ * If the installed `claude` binary does not expose the file flag, falls back
+ * to inline (regardless of size) and emits a daemon-log warning.
+ */
+export declare function buildSpawnArgs(options: BuildSpawnArgsOptions): BuildSpawnArgsResult;
+//# sourceMappingURL=spawn-config-writer.d.ts.map

package/dist/server/server/agent/providers/claude/spawn-config-writer.js

@@ -0,0 +1,229 @@
+import { execSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Maximum byte size for an inline `--append-system-prompt` payload before
+ * spilling to a file via `--append-system-prompt-file`. Conservative — most
+ * terminals buffer 64 KB+ but PTY line-buffer limits vary by OS. See Story 5.2
+ * for rationale.
+ */
+export const BOOT_PROMPT_MAX_INLINE_BYTES = 8192;
+/**
+ * Flag name for the file-based system-prompt variant. Centralized so a future
+ * upstream rename is a single edit. Verified at HEAD of `claude` 2.1.119 — the
+ * `--bare` help text lists `--append-system-prompt[-file]` as an exposed flag.
+ */
+export const SYSTEM_PROMPT_FILE_FLAG = "--append-system-prompt-file";
+const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+const PASEO_MANAGED_MARKER = "paseo-managed";
+export function resolvePaseoBinary() {
+    // Walk upward from this module to find a bin/paseo wrapper. If the daemon
+    // was invoked through the CLI, process.argv[0] is `node` and argv[1] is
+    // the daemon JS entry — neither is the paseo wrapper. The wrapper lives
+    // alongside the package root.
+    let dir = moduleDir;
+    for (let i = 0; i < 10; i++) {
+        const candidate = path.join(dir, "bin", "paseo");
+        if (existsSync(candidate))
+            return candidate;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    // Fall back to process.argv[1] resolved against a sibling bin dir.
+    const argv1 = process.argv[1];
+    if (argv1) {
+        const candidate = path.resolve(path.dirname(argv1), "..", "bin", "paseo");
+        if (existsSync(candidate))
+            return candidate;
+    }
+    throw new Error("spawn-config-writer: unable to resolve absolute path to paseo binary (no bin/paseo found)");
+}
+function buildSettings(paseoBinary) {
+    const cmd = (kind) => ({
+        type: "command",
+        command: `${paseoBinary} agent-hook ${kind}`,
+    });
+    return {
+        [PASEO_MANAGED_MARKER]: true,
+        hooks: {
+            PreToolUse: [{ matcher: ".*", hooks: [cmd("pre-tool")] }],
+            PostToolUse: [{ matcher: ".*", hooks: [cmd("post-tool")] }],
+            PermissionRequest: [{ hooks: [cmd("permission")] }],
+            StatusLine: [{ hooks: [cmd("status-line")] }],
+            SessionStart: [{ hooks: [cmd("session-start")] }],
+            SessionEnd: [{ hooks: [cmd("session-end")] }],
+        },
+    };
+}
+function buildMcp(daemonPort) {
+    return {
+        mcpServers: {
+            paseo: {
+                url: `http://127.0.0.1:${daemonPort}/mcp`,
+                transport: "http",
+            },
+        },
+    };
+}
+function snapshot(filePath) {
+    if (!existsSync(filePath))
+        return { existed: false, bytes: null };
+    return { existed: true, bytes: readFileSync(filePath) };
+}
+function mergeWithPaseo(userJson, paseoJson) {
+    const merged = { ...userJson, [PASEO_MANAGED_MARKER]: true };
+    const userHooks = userJson.hooks ?? {};
+    const paseoHooks = paseoJson.hooks ?? {};
+    const mergedHooks = {};
+    const allKeys = new Set([...Object.keys(userHooks), ...Object.keys(paseoHooks)]);
+    for (const k of allKeys) {
+        mergedHooks[k] = [...(userHooks[k] ?? []), ...(paseoHooks[k] ?? [])];
+    }
+    merged.hooks = mergedHooks;
+    return merged;
+}
+export class SpawnConfigWriter {
+    constructor(options = {}) {
+        this.state = null;
+        this.options = options;
+    }
+    write(cwd, daemonPort) {
+        const claudeDir = path.join(cwd, ".claude");
+        const settingsPath = path.join(claudeDir, "settings.json");
+        const mcpPath = path.join(cwd, ".mcp.json");
+        if (!existsSync(claudeDir)) {
+            mkdirSync(claudeDir, { recursive: true });
+        }
+        else if (!statSync(claudeDir).isDirectory()) {
+            throw new Error(`spawn-config-writer: ${claudeDir} exists and is not a directory`);
+        }
+        const settingsSnap = snapshot(settingsPath);
+        const mcpSnap = snapshot(mcpPath);
+        const paseoBinary = this.options.paseoBinaryPath ?? resolvePaseoBinary();
+        const paseoSettings = buildSettings(paseoBinary);
+        let finalSettings;
+        if (settingsSnap.existed && settingsSnap.bytes) {
+            let parsed;
+            try {
+                parsed = JSON.parse(settingsSnap.bytes.toString("utf8"));
+            }
+            catch {
+                throw new Error(`spawn-config-writer: ${settingsPath} exists but is not valid JSON; refusing to overwrite`);
+            }
+            finalSettings = mergeWithPaseo(parsed, paseoSettings);
+        }
+        else {
+            finalSettings = paseoSettings;
+        }
+        writeFileSync(settingsPath, `${JSON.stringify(finalSettings, null, 2)}\n`);
+        writeFileSync(mcpPath, `${JSON.stringify(buildMcp(daemonPort), null, 2)}\n`);
+        this.state = { cwd, settings: settingsSnap, mcp: mcpSnap };
+        return { settingsPath, mcpPath };
+    }
+    restore(cwd) {
+        const state = this.state;
+        if (!state || state.cwd !== cwd)
+            return;
+        this.state = null;
+        const settingsPath = path.join(cwd, ".claude", "settings.json");
+        const mcpPath = path.join(cwd, ".mcp.json");
+        restoreOne(settingsPath, state.settings);
+        restoreOne(mcpPath, state.mcp);
+    }
+}
+let cachedFlagAvailability = null;
+/** Test-only — reset the `--help` probe cache between cases. */
+export function __resetSystemPromptFileFlagCacheForTesting() {
+    cachedFlagAvailability = null;
+}
+function probeSystemPromptFileFlag(claudeBinary) {
+    if (!cachedFlagAvailability)
+        cachedFlagAvailability = new Map();
+    const cached = cachedFlagAvailability.get(claudeBinary);
+    if (typeof cached === "boolean")
+        return cached;
+    let available = false;
+    try {
+        const help = execSync(`${claudeBinary} --help`, {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 5000,
+        });
+        // The flag may appear as `--append-system-prompt-file` directly or in the
+        // shorthand `--append-system-prompt[-file]` form inside the `--bare` help.
+        available =
+            help.includes("append-system-prompt-file") || help.includes("append-system-prompt[-file]");
+    }
+    catch {
+        available = false;
+    }
+    cachedFlagAvailability.set(claudeBinary, available);
+    return available;
+}
+function resolvePaseoHome(override) {
+    if (override)
+        return override;
+    const fromEnv = process.env["PASEO_HOME"];
+    if (fromEnv)
+        return fromEnv;
+    return path.join(os.homedir(), ".paseo");
+}
+/**
+ * Build the spawn args for the PTY transport, applying the boot-prompt
+ * size mitigation: payloads larger than {@link BOOT_PROMPT_MAX_INLINE_BYTES}
+ * are written to `$PASEO_HOME/tmp/system-prompt-<sessionId>.txt` and passed
+ * via {@link SYSTEM_PROMPT_FILE_FLAG} instead of inline.
+ *
+ * If the installed `claude` binary does not expose the file flag, falls back
+ * to inline (regardless of size) and emits a daemon-log warning.
+ */
+export function buildSpawnArgs(options) {
+    const args = [];
+    let systemPromptFilePath = null;
+    const warn = options.warn ?? ((m) => console.warn(m));
+    const payload = options.appendSystemPrompt ?? "";
+    if (payload.length > 0) {
+        const sizeBytes = Buffer.byteLength(payload, "utf8");
+        const flagAvailable = options.systemPromptFileFlagAvailable ?? probeSystemPromptFileFlag(options.claudeBinary);
+        if (sizeBytes <= BOOT_PROMPT_MAX_INLINE_BYTES) {
+            args.push("--append-system-prompt", payload);
+        }
+        else if (!flagAvailable) {
+            warn("[spawn-config-writer] --system-prompt-file flag not available; " +
+                "using inline --append-system-prompt (payload may cause PTY hang)");
+            args.push("--append-system-prompt", payload);
+        }
+        else {
+            const paseoHome = resolvePaseoHome(options.paseoHome);
+            const tmpDir = path.join(paseoHome, "tmp");
+            mkdirSync(tmpDir, { recursive: true });
+            const filePath = path.join(tmpDir, `system-prompt-${options.sessionId}.txt`);
+            writeFileSync(filePath, payload, "utf8");
+            systemPromptFilePath = filePath;
+            args.push(SYSTEM_PROMPT_FILE_FLAG, filePath);
+        }
+    }
+    if (options.extraArgs?.length)
+        args.push(...options.extraArgs);
+    return { args, systemPromptFilePath };
+}
+function restoreOne(filePath, snap) {
+    try {
+        if (snap.existed && snap.bytes) {
+            writeFileSync(filePath, snap.bytes);
+        }
+        else if (existsSync(filePath)) {
+            rmSync(filePath, { force: true });
+        }
+    }
+    catch (err) {
+        // restore() must never throw — log to stderr and move on.
+        // eslint-disable-next-line no-console
+        console.error(`spawn-config-writer: failed to restore ${filePath}:`, err);
+    }
+}
+//# sourceMappingURL=spawn-config-writer.js.map

package/dist/server/server/agent/providers/claude/task-notification-tool-call.d.ts

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import type { AgentTimelineItem } from "../../agent-sdk-types.js";
+declare const TaskNotificationEnvelopeSchema: z.ZodObject<{
+    messageId: z.ZodNullable<z.ZodString>;
+    taskId: z.ZodNullable<z.ZodString>;
+    status: z.ZodNullable<z.ZodString>;
+    summary: z.ZodNullable<z.ZodString>;
+    outputFile: z.ZodNullable<z.ZodString>;
+    rawText: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+declare const MapTaskNotificationUserContentToToolCallInputSchema: z.ZodObject<{
+    content: z.ZodUnknown;
+    messageId: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+}, z.core.$strip>;
+export type TaskNotificationEnvelope = z.infer<typeof TaskNotificationEnvelopeSchema>;
+export type MapTaskNotificationUserContentToToolCallInput = z.infer<typeof MapTaskNotificationUserContentToToolCallInputSchema>;
+export interface TaskNotificationSystemMessageLike {
+    type: "system";
+    subtype: "task_notification";
+    uuid?: string;
+    task_id?: string;
+    status?: "completed" | "failed" | "stopped";
+    summary?: string;
+    output_file?: string;
+    content?: string;
+}
+type TaskNotificationToolCallItem = Extract<AgentTimelineItem, {
+    type: "tool_call";
+}>;
+export interface BackgroundTaskLifecycleSignal {
+    taskId: string;
+    status: string | null;
+}
+/**
+ * Project a system task_notification record down to its background-task
+ * lifecycle ({ taskId, status }) — used to expire a tracked background shell
+ * when its terminal notification arrives. Returns null when there's no task id.
+ */
+export declare function extractTaskNotificationLifecycleFromSystemRecord(record: unknown): BackgroundTaskLifecycleSignal | null;
+/** Same as above for a task_notification that arrives as user-message content. */
+export declare function extractTaskNotificationLifecycleFromUserContent(input: MapTaskNotificationUserContentToToolCallInput): BackgroundTaskLifecycleSignal | null;
+export declare function isTaskNotificationUserContent(content: unknown): boolean;
+export declare function mapTaskNotificationUserContentToToolCall(input: MapTaskNotificationUserContentToToolCallInput): TaskNotificationToolCallItem | null;
+export declare function mapTaskNotificationSystemRecordToToolCall(record: unknown): TaskNotificationToolCallItem | null;
+export declare function coerceTaskNotificationHistoryRecordToSystemMessage(record: unknown): TaskNotificationSystemMessageLike | null;
+export {};
+//# sourceMappingURL=task-notification-tool-call.d.ts.map