@hyperdrive.bot/paseo-server 0.2.6

package/dist/server/server/agent/providers/claude/background-shell-kill-keys.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Keystrokes that drive Claude Code's *own* CLI TUI (over the PTY) to stop its
+ * background work — i.e. kill a background shell from inside Claude Code, the
+ * same keys a human presses, NOT an external OS process kill.
+ *
+ * Source of truth: the Claude Code binary binds `chat:killAgents` to the chord
+ * `ctrl+x ctrl+k`, which arms a confirm ("Press ctrl+x ctrl+k again to stop
+ * background agents"); the second identical chord confirms. We replay that.
+ *
+ * Control bytes: Ctrl+X = 0x18 (CAN), Ctrl+K = 0x0B (VT).
+ *
+ * NOTE (scope): this is Claude Code's *global* stop-background-work chord — it
+ * stops the session's background work rather than one shell selected by id. The
+ * binary exposes no per-shell-selective interactive kill binding, so paseo
+ * clears its whole background-shell set for the agent after sending it.
+ *
+ * MAINTENANCE: these bytes are coupled to Claude Code's keybindings. If a
+ * future Claude Code release rebinds `chat:killAgents`, update this module
+ * (re-derive from the binary's keybinding strings).
+ */
+export declare const CTRL_X = "\u0018";
+export declare const CTRL_K = "\v";
+/** One `ctrl+x ctrl+k` chord press. */
+export declare const KILL_BACKGROUND_CHORD = "\u0018\v";
+/**
+ * The discrete key presses to send, in order, to stop Claude Code's background
+ * work: the chord, then the chord again to confirm. Returned as separate
+ * entries so the caller delivers them as distinct PTY input events (the TUI
+ * renders the confirm prompt between them).
+ */
+export declare function buildBackgroundKillPresses(): readonly string[];
+//# sourceMappingURL=background-shell-kill-keys.d.ts.map

package/dist/server/server/agent/providers/claude/background-shell-kill-keys.js

@@ -0,0 +1,34 @@
+/**
+ * Keystrokes that drive Claude Code's *own* CLI TUI (over the PTY) to stop its
+ * background work — i.e. kill a background shell from inside Claude Code, the
+ * same keys a human presses, NOT an external OS process kill.
+ *
+ * Source of truth: the Claude Code binary binds `chat:killAgents` to the chord
+ * `ctrl+x ctrl+k`, which arms a confirm ("Press ctrl+x ctrl+k again to stop
+ * background agents"); the second identical chord confirms. We replay that.
+ *
+ * Control bytes: Ctrl+X = 0x18 (CAN), Ctrl+K = 0x0B (VT).
+ *
+ * NOTE (scope): this is Claude Code's *global* stop-background-work chord — it
+ * stops the session's background work rather than one shell selected by id. The
+ * binary exposes no per-shell-selective interactive kill binding, so paseo
+ * clears its whole background-shell set for the agent after sending it.
+ *
+ * MAINTENANCE: these bytes are coupled to Claude Code's keybindings. If a
+ * future Claude Code release rebinds `chat:killAgents`, update this module
+ * (re-derive from the binary's keybinding strings).
+ */
+export const CTRL_X = "\x18";
+export const CTRL_K = "\x0b";
+/** One `ctrl+x ctrl+k` chord press. */
+export const KILL_BACKGROUND_CHORD = `${CTRL_X}${CTRL_K}`;
+/**
+ * The discrete key presses to send, in order, to stop Claude Code's background
+ * work: the chord, then the chord again to confirm. Returned as separate
+ * entries so the caller delivers them as distinct PTY input events (the TUI
+ * renders the confirm prompt between them).
+ */
+export function buildBackgroundKillPresses() {
+    return [KILL_BACKGROUND_CHORD, KILL_BACKGROUND_CHORD];
+}
+//# sourceMappingURL=background-shell-kill-keys.js.map

package/dist/server/server/agent/providers/claude/background-task-tracker.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Tracks an agent's live Claude Code **background shells** (`Bash` invoked with
+ * `run_in_background: true`) so paseo can keep surfacing the agent as "Running"
+ * — and offer a dismiss — while those shells outlive the turn.
+ *
+ * Why this exists: a backgrounded `Bash` returns its handle immediately, so the
+ * tool-call completes and the agent's lifecycle status settles to `idle` even
+ * though the shell is still alive. The liveness only shows up as two text
+ * signals in the (transport-agnostic) message stream paseo already ingests —
+ * the PTY transport feeds these by tailing Claude Code's transcript JSONL, the
+ * SDK transport by its message events, both converging on the same handler:
+ *
+ *   start → the Bash tool_result text: "Command running in background with ID: <id>"
+ *   end   → a <task-notification> envelope carrying that same <id> + a terminal status
+ *
+ * Both carry the SAME id (e.g. `bjuk0pif4`), so we key the live set by it.
+ * This module is pure (no SDK/PTY types) so it unit-tests cleanly and works
+ * regardless of transport.
+ */
+export declare function isTerminalTaskStatus(status: string | null | undefined): boolean;
+/** Extract every background-task id announced in a Bash tool_result's text. */
+export declare function extractBackgroundTaskIds(text: string | null | undefined): string[];
+export declare class ClaudeBackgroundTaskTracker {
+    private readonly liveTaskIds;
+    /**
+     * Scan a Bash tool_result's text for background-shell launches and mark each
+     * id alive. Returns the ids newly added (idempotent — re-seeing an id is a
+     * no-op). Safe to call on any tool_result text; non-matching text adds none.
+     */
+    noteToolResultText(text: string | null | undefined): string[];
+    /**
+     * A `<task-notification>` arrived. If it carries a terminal status for a task
+     * we're tracking, drop it from the live set. Returns true iff the live set
+     * changed. Unknown ids and non-terminal statuses are no-ops.
+     */
+    noteTaskNotification(input: {
+        taskId?: string | null;
+        status?: string | null;
+    }): boolean;
+    /** Explicit removal — e.g. the user dismissed/killed the shell from the UI. */
+    remove(taskId: string): boolean;
+    has(taskId: string): boolean;
+    /** Count of still-alive background shells owned by this agent. */
+    get count(): number;
+    /** Snapshot of the live ids (insertion order), for surfacing a dismissable list. */
+    list(): string[];
+    clear(): void;
+}
+//# sourceMappingURL=background-task-tracker.d.ts.map

package/dist/server/server/agent/providers/claude/background-task-tracker.js

@@ -0,0 +1,119 @@
+/**
+ * Tracks an agent's live Claude Code **background shells** (`Bash` invoked with
+ * `run_in_background: true`) so paseo can keep surfacing the agent as "Running"
+ * — and offer a dismiss — while those shells outlive the turn.
+ *
+ * Why this exists: a backgrounded `Bash` returns its handle immediately, so the
+ * tool-call completes and the agent's lifecycle status settles to `idle` even
+ * though the shell is still alive. The liveness only shows up as two text
+ * signals in the (transport-agnostic) message stream paseo already ingests —
+ * the PTY transport feeds these by tailing Claude Code's transcript JSONL, the
+ * SDK transport by its message events, both converging on the same handler:
+ *
+ *   start → the Bash tool_result text: "Command running in background with ID: <id>"
+ *   end   → a <task-notification> envelope carrying that same <id> + a terminal status
+ *
+ * Both carry the SAME id (e.g. `bjuk0pif4`), so we key the live set by it.
+ * This module is pure (no SDK/PTY types) so it unit-tests cleanly and works
+ * regardless of transport.
+ */
+/** Matches the harness line emitted in a backgrounded Bash tool_result. */
+const BACKGROUND_ID_PATTERN = /Command running in background with ID:\s*([A-Za-z0-9._-]+)/g;
+/**
+ * Task-notification statuses that mean the background shell is no longer alive.
+ * Compared case-insensitively; anything else (e.g. "running", "in_progress",
+ * "progress") is treated as still-alive and leaves the task in the set.
+ */
+const TERMINAL_STATUSES = new Set([
+    "completed",
+    "complete",
+    "failed",
+    "failure",
+    "error",
+    "killed",
+    "stopped",
+    "canceled",
+    "cancelled",
+    "timeout",
+    "timed_out",
+    "done",
+]);
+export function isTerminalTaskStatus(status) {
+    if (typeof status !== "string") {
+        return false;
+    }
+    return TERMINAL_STATUSES.has(status.trim().toLowerCase());
+}
+/** Extract every background-task id announced in a Bash tool_result's text. */
+export function extractBackgroundTaskIds(text) {
+    if (typeof text !== "string" || text.length === 0) {
+        return [];
+    }
+    const ids = [];
+    // Reset lastIndex defensively — the regex is module-scoped and global.
+    BACKGROUND_ID_PATTERN.lastIndex = 0;
+    let match = BACKGROUND_ID_PATTERN.exec(text);
+    while (match !== null) {
+        const id = match[1];
+        if (id) {
+            ids.push(id);
+        }
+        match = BACKGROUND_ID_PATTERN.exec(text);
+    }
+    return ids;
+}
+export class ClaudeBackgroundTaskTracker {
+    constructor() {
+        this.liveTaskIds = new Set();
+    }
+    /**
+     * Scan a Bash tool_result's text for background-shell launches and mark each
+     * id alive. Returns the ids newly added (idempotent — re-seeing an id is a
+     * no-op). Safe to call on any tool_result text; non-matching text adds none.
+     */
+    noteToolResultText(text) {
+        const added = [];
+        for (const id of extractBackgroundTaskIds(text)) {
+            if (!this.liveTaskIds.has(id)) {
+                this.liveTaskIds.add(id);
+                added.push(id);
+            }
+        }
+        return added;
+    }
+    /**
+     * A `<task-notification>` arrived. If it carries a terminal status for a task
+     * we're tracking, drop it from the live set. Returns true iff the live set
+     * changed. Unknown ids and non-terminal statuses are no-ops.
+     */
+    noteTaskNotification(input) {
+        const taskId = typeof input.taskId === "string" ? input.taskId.trim() : "";
+        if (!taskId || !this.liveTaskIds.has(taskId)) {
+            return false;
+        }
+        if (!isTerminalTaskStatus(input.status)) {
+            return false;
+        }
+        this.liveTaskIds.delete(taskId);
+        return true;
+    }
+    /** Explicit removal — e.g. the user dismissed/killed the shell from the UI. */
+    remove(taskId) {
+        return this.liveTaskIds.delete(taskId);
+    }
+    has(taskId) {
+        return this.liveTaskIds.has(taskId);
+    }
+    /** Count of still-alive background shells owned by this agent. */
+    get count() {
+        return this.liveTaskIds.size;
+    }
+    /** Snapshot of the live ids (insertion order), for surfacing a dismissable list. */
+    list() {
+        return [...this.liveTaskIds];
+    }
+    clear() {
+        this.liveTaskIds.clear();
+    }
+}
+//# sourceMappingURL=background-task-tracker.js.map

package/dist/server/server/agent/providers/claude/feature-definitions.d.ts

@@ -0,0 +1,8 @@
+import type { AgentFeature, AgentFeatureToggle } from "../../agent-sdk-types.js";
+export declare const CLAUDE_FAST_MODE_FEATURE: Omit<AgentFeatureToggle, "value">;
+export declare function claudeModelSupportsFastMode(modelId: string | null | undefined): boolean;
+export declare function buildClaudeFeatures(input: {
+    modelId: string | null | undefined;
+    fastModeEnabled: boolean;
+}): AgentFeature[];
+//# sourceMappingURL=feature-definitions.d.ts.map

package/dist/server/server/agent/providers/claude/feature-definitions.js

@@ -0,0 +1,24 @@
+import { claudeManifestModelSupportsFastMode } from "./model-manifest.js";
+export const CLAUDE_FAST_MODE_FEATURE = {
+    type: "toggle",
+    id: "fast_mode",
+    label: "Fast",
+    description: "Lower latency Opus responses at higher token cost",
+    tooltip: "Toggle fast mode",
+    icon: "zap",
+};
+export function claudeModelSupportsFastMode(modelId) {
+    return claudeManifestModelSupportsFastMode(modelId);
+}
+export function buildClaudeFeatures(input) {
+    if (!claudeModelSupportsFastMode(input.modelId)) {
+        return [];
+    }
+    return [
+        {
+            ...CLAUDE_FAST_MODE_FEATURE,
+            value: input.fastModeEnabled,
+        },
+    ];
+}
+//# sourceMappingURL=feature-definitions.js.map

package/dist/server/server/agent/providers/claude/hook-handler.d.ts

@@ -0,0 +1,37 @@
+import type { Logger } from "pino";
+import { type HookEvent, type PermissionHookEvent } from "@hyperdrive.bot/paseo-protocol/messages";
+export interface PermissionDecision {
+    behavior: "allow" | "deny";
+    message?: string;
+}
+export interface PermissionRequest {
+    event: PermissionHookEvent;
+    requestId: string;
+    resolve: (decision: PermissionDecision) => void;
+}
+export type HookEventHandler = (event: HookEvent, permissionRequestId?: string) => void | Promise<void>;
+export declare class HookHandlerServer {
+    private server;
+    private socketPath;
+    private httpPort;
+    private agentId;
+    private handler;
+    private readonly pendingPermissions;
+    private readonly logger;
+    private requestCounter;
+    constructor(logger: Logger);
+    registerHandler(handler: HookEventHandler): void;
+    unregisterHandler(): void;
+    start(agentId: string): Promise<void>;
+    stop(): Promise<void>;
+    getAddress(): string;
+    /**
+     * Called by ClaudeAgentSession when the WebSocket permission decision arrives.
+     * Returns true if the request was found and resolved.
+     */
+    resolvePermission(requestId: string, decision: PermissionDecision): boolean;
+    private handleRequest;
+    private handlePermissionEvent;
+    private dispatchEvent;
+}
+//# sourceMappingURL=hook-handler.d.ts.map

package/dist/server/server/agent/providers/claude/hook-handler.js

@@ -0,0 +1,193 @@
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import { HookEventSchema, } from "@hyperdrive.bot/paseo-protocol/messages";
+import { resolvePaseoHome } from "../../../paseo-home.js";
+function readRequestBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (chunk) => chunks.push(chunk));
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        req.on("error", reject);
+    });
+}
+function sendJson(res, statusCode, body) {
+    const json = JSON.stringify(body);
+    res.writeHead(statusCode, {
+        "Content-Type": "application/json",
+        "Content-Length": Buffer.byteLength(json),
+    });
+    res.end(json);
+}
+export class HookHandlerServer {
+    constructor(logger) {
+        this.server = null;
+        this.socketPath = null;
+        this.httpPort = null;
+        this.agentId = null;
+        this.handler = null;
+        this.pendingPermissions = new Map();
+        this.requestCounter = 0;
+        this.logger = logger;
+    }
+    registerHandler(handler) {
+        this.handler = handler;
+    }
+    unregisterHandler() {
+        this.handler = null;
+    }
+    async start(agentId) {
+        this.agentId = agentId;
+        const server = http.createServer((req, res) => {
+            this.handleRequest(req, res).catch((err) => {
+                this.logger.error({ err }, "hook-handler: unhandled request error");
+                if (!res.headersSent) {
+                    sendJson(res, 500, { error: "internal server error" });
+                }
+            });
+        });
+        this.server = server;
+        await new Promise((resolve, reject) => {
+            server.on("error", reject);
+            if (process.platform === "win32") {
+                server.listen({ host: "127.0.0.1", port: 0 }, () => {
+                    const addr = server.address();
+                    this.httpPort = addr.port;
+                    resolve();
+                });
+            }
+            else {
+                const sockDir = path.join(resolvePaseoHome(), "sockets");
+                fs.mkdirSync(sockDir, { recursive: true });
+                const sockPath = path.join(sockDir, `agent-hook-${agentId}.sock`);
+                // Remove stale socket file from a prior unclean exit
+                try {
+                    fs.unlinkSync(sockPath);
+                }
+                catch {
+                    // file didn't exist — that's fine
+                }
+                this.socketPath = sockPath;
+                server.listen(sockPath, () => {
+                    resolve();
+                });
+            }
+        });
+        this.logger.debug({ address: this.getAddress(), agentId }, "hook-handler: server started");
+    }
+    async stop() {
+        // Resolve all pending permissions with deny before shutting down
+        for (const [, resolve] of this.pendingPermissions) {
+            resolve({ behavior: "deny", message: "daemon shutting down" });
+        }
+        this.pendingPermissions.clear();
+        if (this.server) {
+            await new Promise((resolve, reject) => {
+                this.server.close((err) => {
+                    if (err) {
+                        reject(err);
+                        return;
+                    }
+                    resolve();
+                });
+            });
+            this.server = null;
+        }
+        if (this.socketPath) {
+            try {
+                fs.unlinkSync(this.socketPath);
+            }
+            catch {
+                // already gone
+            }
+            this.socketPath = null;
+        }
+        this.logger.debug({ agentId: this.agentId }, "hook-handler: server stopped");
+    }
+    getAddress() {
+        if (process.platform === "win32" && this.httpPort !== null) {
+            return `http://127.0.0.1:${this.httpPort}`;
+        }
+        if (this.socketPath) {
+            return this.socketPath;
+        }
+        throw new Error("HookHandlerServer has not been started");
+    }
+    /**
+     * Called by ClaudeAgentSession when the WebSocket permission decision arrives.
+     * Returns true if the request was found and resolved.
+     */
+    resolvePermission(requestId, decision) {
+        const resolver = this.pendingPermissions.get(requestId);
+        if (!resolver) {
+            return false;
+        }
+        this.pendingPermissions.delete(requestId);
+        resolver(decision);
+        return true;
+    }
+    async handleRequest(req, res) {
+        let body;
+        try {
+            body = await readRequestBody(req);
+        }
+        catch (err) {
+            this.logger.warn({ err }, "hook-handler: failed to read request body");
+            sendJson(res, 400, { error: "failed to read body" });
+            return;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch {
+            sendJson(res, 400, { error: "invalid JSON" });
+            return;
+        }
+        const result = HookEventSchema.safeParse(parsed);
+        if (!result.success) {
+            this.logger.warn({ issues: result.error.issues }, "hook-handler: invalid HookEvent payload");
+            sendJson(res, 400, { error: "invalid payload", detail: result.error.issues });
+            return;
+        }
+        const event = result.data;
+        this.logger.debug({ kind: event.kind, agentId: "agent_id" in event ? event.agent_id : undefined }, "hook-handler: received event");
+        if (event.kind === "permission") {
+            await this.handlePermissionEvent(event, res);
+        }
+        else {
+            // Fire-and-forget: respond immediately, then dispatch async
+            sendJson(res, 200, {});
+            Promise.resolve()
+                .then(() => this.dispatchEvent(event))
+                .catch((err) => {
+                this.logger.error({ err, kind: event.kind }, "hook-handler: observation handler error");
+            });
+        }
+    }
+    async handlePermissionEvent(event, res) {
+        const requestId = `hook-perm-${this.agentId}-${++this.requestCounter}`;
+        const decision = await new Promise((resolve) => {
+            this.pendingPermissions.set(requestId, resolve);
+            Promise.resolve()
+                .then(() => this.dispatchEvent(event, requestId))
+                .catch((err) => {
+                this.logger.error({ err }, "hook-handler: permission dispatch error");
+                const existing = this.pendingPermissions.get(requestId);
+                if (existing) {
+                    this.pendingPermissions.delete(requestId);
+                    resolve({ behavior: "deny", message: "handler dispatch failed" });
+                }
+            });
+        });
+        sendJson(res, 200, decision);
+    }
+    dispatchEvent(event, permissionRequestId) {
+        if (!this.handler) {
+            this.logger.debug({ kind: event.kind }, "hook-handler: no handler registered, ignoring event");
+            return;
+        }
+        return this.handler(event, permissionRequestId);
+    }
+}
+//# sourceMappingURL=hook-handler.js.map

package/dist/server/server/agent/providers/claude/hooks/event-translator.d.ts

@@ -0,0 +1,49 @@
+import type { AgentProvider, AgentStreamEvent, AgentPermissionRequest } from "../../../agent-sdk-types.js";
+import type { HookEvent, PermissionHookEvent, SessionStartHookEvent } from "@hyperdrive.bot/paseo-protocol/messages";
+/**
+ * Translator context — minimal surface the pump must expose so the translator
+ * can route side-effects (permission requests, session-start capture) without
+ * importing the full ClaudeAgentSession (would create a circular import).
+ *
+ * The pump owns: pendingPermissions map, claudeSessionId capture, transcript
+ * tailer startup, turnId allocation. The translator only converts wire shapes
+ * and asks the pump to do the side-effecting work via these callbacks.
+ */
+export interface TranslatorContext {
+    readonly provider: AgentProvider;
+    readonly turnId?: string;
+    /**
+     * Called when a permission-request HookEvent arrives. The pump should:
+     *  1. Register a pending waiter keyed on agent_id + a generated request id
+     *  2. Wire the waiter so the hook subprocess receives the eventual decision
+     *  3. Return the AgentPermissionRequest shape so the translator can emit it
+     *     in the permission_requested stream event
+     *
+     * Returning null suppresses the stream event (e.g. caller chose to handle
+     * the permission flow outside the normal event channel).
+     */
+    registerPermissionRequest(event: PermissionHookEvent): AgentPermissionRequest | null;
+    /**
+     * Called once when the SessionStart hook arrives. The pump should capture
+     * `session_id` into `claudeSessionId` and start the TranscriptTailer for
+     * `transcript_path`. This replaces today's `system.init` parse at
+     * agent.ts:3107-3118 for the PTY path.
+     */
+    onSessionStart?(event: SessionStartHookEvent): void;
+}
+/**
+ * Translate a daemon-internal HookEvent into zero-or-more AgentStreamEvent(s)
+ * that the pump can emit verbatim via its existing emitStreamEvent path.
+ *
+ * Returns:
+ *   - `[]` when the event was handled entirely via side-effect callbacks
+ *     (session-start, permission registered without an emit, etc.)
+ *   - One or more AgentStreamEvent shapes that the pump should emit
+ *   - `null` if the event could not be translated (caller may log/skip)
+ *
+ * The translator is pure (modulo `ctx.*` callbacks): no global state, no I/O.
+ * Tool-call mapping is delegated to `tool-call-mapper.ts` so the shapes stay
+ * identical across SDK and PTY transports.
+ */
+export declare function translateHookEvent(event: HookEvent, ctx: TranslatorContext): AgentStreamEvent[] | null;
+//# sourceMappingURL=event-translator.d.ts.map