@lucascouts/claude-agent-acp-plus 0.23.6 → 0.25.0

package/dist/permissions/response.js

@@ -1,4 +1,5 @@
 import { applyClaudePermissionSelection, parseClaudePermissionSelection } from "./effects.js";
+import { PERMISSION_OPTION_ID } from "./options/shared.js";
 /** Decode, validate, and interpret an ACP response exactly once. */
 export function decodeClaudePermissionResponse(response, toolName, input, toolUseID, offeredOptions, durableChangeSet) {
     const selection = parseClaudePermissionSelection(response, toolName);
@@ -17,3 +18,21 @@ export function decodeClaudePermissionResponse(response, toolName, input, toolUs
         ...(selection.contextResetMode ? { contextResetMode: selection.contextResetMode } : {}),
     };
 }
+/**
+ * Map the answer to a classifier-denial request. Only the three ids that
+ * request offers are accepted; anything else is an error, never an approval.
+ */
+export function decodeClassifierEscalationResponse(response) {
+    if (response.outcome.outcome === "cancelled")
+        return "cancelled";
+    switch (response.outcome.optionId) {
+        case PERMISSION_OPTION_ID.classifierAllowOnce:
+            return "once";
+        case PERMISSION_OPTION_ID.classifierAllowSession:
+            return "session";
+        case PERMISSION_OPTION_ID.reject:
+            return "reject";
+        default:
+            throw new Error(`Classifier escalation option was not offered: ${response.outcome.optionId}`);
+    }
+}

package/dist/task-feed.d.ts

@@ -0,0 +1,195 @@
+/**
+ * The agent's task feed: background shells, subagents, monitors and workflows,
+ * folded from the SDK's task messages into the `_claude/tasks` snapshot.
+ *
+ * The SDK reports tasks as a stream of bookends (`task_started`,
+ * `task_progress`, `task_updated`, `task_notification`) plus a level
+ * (`background_tasks_changed`). Zeo needs one table it can render, so
+ * `TaskFeed` keeps that table per session and renders it as a snapshot. The
+ * snapshot is a LEVEL, not a stream: every publish carries every live task,
+ * so a lost update is repaired by the next one, and the client replaces its
+ * list instead of merging.
+ *
+ * An ended task appears in exactly one successful snapshot with its final
+ * status, then drops out. `snapshot()` marks nothing; the publisher calls
+ * `markPublished()` only after the send carrying the endings succeeded, so a
+ * failed send never loses an ending.
+ *
+ * `TaskFeedPublisher` decides WHEN to publish: at most once per second during
+ * progress, at once on an ending, and once more after a burst so the latest
+ * values are not lost.
+ *
+ * A foreground shell task (`local_bash`, not backgrounded) is held back for
+ * `FOREGROUND_SHELL_HOLD_MS`: Claude Code registers every shell command as a
+ * task, so only one still running after the hold, or moved to the background,
+ * is published. One that ends while held is dropped without a trace. The feed
+ * stays clock-driven: the publisher's timer calls `promoteDue()`.
+ *
+ * Neither class ever copies a command line (`SDKTaskStartedMessage.prompt`)
+ * into an entry or a log line.
+ */
+import type { SDKTaskNotificationMessage, SDKTaskProgressMessage, SDKTaskStartedMessage, SDKTaskUpdatedMessage } from "@anthropic-ai/claude-agent-sdk";
+/** The `session_info_update._meta` key the snapshot is published under. */
+export declare const TASKS_META_KEY = "_claude/tasks";
+export type TaskStatus = "running" | "completed" | "failed" | "stopped" | "interrupted";
+export type TaskUsage = {
+    tokens: number;
+    toolUses: number;
+    durationMs: number;
+};
+/** One row of the snapshot — design.md's Data Models, field for field. */
+export type TaskEntry = {
+    id: string;
+    toolCallId: string | null;
+    type: string;
+    description: string;
+    background: boolean;
+    depth: number;
+    status: TaskStatus;
+    startedAt: number;
+    endedAt: number | null;
+    usage: TaskUsage | null;
+    lastTool: string | null;
+    summary: string | null;
+};
+export type TasksSnapshot = {
+    tasks: TaskEntry[];
+};
+/** What a message did to the table; the publisher decides timing from it. */
+export type TaskChange = "none" | "progress" | "terminal" | "held";
+/** How long a foreground shell task is held back before it is published. */
+export declare const FOREGROUND_SHELL_HOLD_MS = 5000;
+/** How long a running background task may be missing from the level before
+ *  it is ended as `interrupted`. The level and the bookends race (the level
+ *  may arrive first), so a real ending gets this long to land. */
+export declare const RECONCILE_GRACE_MS = 2000;
+/** Minimum gap between two progress publishes of one session. */
+export declare const PUBLISH_INTERVAL_MS = 1000;
+export type TaskFeedLog = {
+    /** Diagnostics nobody acts on (an unknown task id). Omitted = dropped. */
+    debug?: (message: string) => void;
+    /** Degraded but self-recovered (a task ended by reconciliation). */
+    warn?: (message: string) => void;
+};
+/**
+ * The one place the SDK's ending vocabulary becomes the wire's. The same stop
+ * arrives as `task_updated.patch.status = "killed"` and as
+ * `task_notification.status = "stopped"`; both are `stopped`. Returns null for
+ * a non-terminal status (`pending`, `running`, `paused`).
+ */
+export declare function normaliseStatus(status: string | undefined, reason?: string): Exclude<TaskStatus, "running"> | null;
+export declare class TaskFeed {
+    private readonly clock;
+    private readonly log;
+    private readonly sessionId;
+    private readonly tasks;
+    /** Ended tasks whose final snapshot was sent successfully: never shown again. */
+    private readonly published;
+    /** Ambient task ids: never shown, and their later messages are not news. */
+    private readonly ambient;
+    /** task id → its current life; bumped on every start. */
+    private readonly lives;
+    /** task id → the life the latest snapshot carried as ended. */
+    private readonly snapshotLives;
+    /** task id → time after which a missing bookend means `interrupted`. */
+    private readonly deadlines;
+    /** Foreground shell tasks not published yet: see `promoteDue`. */
+    private readonly held;
+    /** Shell task ids labelled by their tool call: a patch never relabels them. */
+    private readonly toolDescribed;
+    constructor(clock: () => number, log?: TaskFeedLog, sessionId?: string);
+    /**
+     * `toolDescription` is the spawning tool call's own `description` input. A
+     * shell task carries it when it is non-empty; otherwise the SDK's, which
+     * for a shell is the command text. Other task types keep the SDK's.
+     */
+    onStarted(msg: SDKTaskStartedMessage, toolDescription?: string): TaskChange;
+    /** Publishes every held shell task whose hold has run out. */
+    promoteDue(): TaskChange;
+    /** When the earliest held shell task is due for promotion; null if none is held. */
+    nextHoldDue(): number | null;
+    onProgress(msg: SDKTaskProgressMessage): TaskChange;
+    onUpdated(msg: SDKTaskUpdatedMessage): TaskChange;
+    onNotification(msg: SDKTaskNotificationMessage): TaskChange;
+    /**
+     * The SDK's level: every live background task. It never adds or ends a task
+     * by itself — it may precede the `task_started` that names a task, or the
+     * bookend that ends one. A running background task the level omits gets a
+     * reconcile deadline; a level that lists it again clears it.
+     */
+    onLevel(level: {
+        task_id: string;
+    }[]): TaskChange;
+    nextReconcileAt(): number | null;
+    /** Ends as `interrupted` every task whose deadline passed with no bookend. */
+    reconcile(now: number): TaskChange;
+    /** The CLI process restarted: whatever was running did not survive it. A
+     *  held shell task was never shown, so it is dropped rather than ended. */
+    onProcessRestart(): TaskChange;
+    /** True when the feed holds `taskId` as running — the stop request's gate. */
+    isRunning(taskId: string): boolean;
+    /** Running tasks plus ended tasks not yet published, oldest start first.
+     *  Marks nothing: see `markPublished`. */
+    snapshot(): {
+        snapshot: TasksSnapshot;
+        endedIds: string[];
+    };
+    /** Called after the send carrying these endings succeeded. Their entries are
+     *  dropped; the ids are remembered so a late bookend cannot resurrect them. */
+    markPublished(endedIds: string[]): void;
+    private running;
+    /** Puts a running entry into the table. A known id starting again is a new
+     *  life of the same task — a resumed subagent is re-registered under its
+     *  agent id. It replaces the ended entry, published or not: the running
+     *  state supersedes an ending the client has not seen yet, and a published
+     *  id must be shown again. */
+    private admit;
+    /** Applies a `task_updated` patch's label and placement; a label taken from
+     *  the tool call is never replaced. */
+    private patch;
+    private end;
+}
+export type PublisherTimers = {
+    now: () => number;
+    setTimeout: (fn: () => void, ms: number) => unknown;
+    clearTimeout: (handle: any) => void;
+};
+export declare class TaskFeedPublisher {
+    private readonly feed;
+    private readonly send;
+    private readonly timers;
+    private readonly onSendError;
+    private lastSendAt;
+    /** One send at a time: a snapshot taken while another is in flight would
+     *  carry that one's endings again, and both would succeed. */
+    private inFlight;
+    /** A publish requested while a send was in flight; `"terminal"` skips the
+     *  throttle when it runs. */
+    private queued;
+    /** The trailing publish or the retry after a failed send — never both. */
+    private pending;
+    private reconcileTimer;
+    private reconcileAt;
+    /** Promotes held foreground shells: armed at the feed's `nextHoldDue()`. */
+    private holdTimer;
+    private holdAt;
+    private closed;
+    /** Set by `dispose({ flush: true })`: a publish queued behind an in-flight
+     *  send still goes out once — a retirement's `interrupted` endings. */
+    private flushOnSettle;
+    constructor(feed: TaskFeed, send: (snapshot: TasksSnapshot) => Promise<void>, timers?: PublisherTimers, onSendError?: (error: unknown) => void);
+    notify(change: TaskChange): void;
+    dispose(options?: {
+        flush?: boolean;
+    }): void;
+    private publishNow;
+    private settle;
+    private arm;
+    private cancelPending;
+    /** One timer for every held shell, at the earliest due time. A held shell
+     *  that ended early leaves the timer armed: it fires, promotes nothing, and
+     *  re-arms for the next one still held. */
+    private armHold;
+    private armReconcile;
+}
+//# sourceMappingURL=task-feed.d.ts.map

package/dist/task-feed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-feed.d.ts","sourceRoot":"","sources":["../src/task-feed.ts"],"names":[],"mappings":"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"}