@pentoshi/clai 3.9.2 → 3.9.4

package/dist/tools/interactive-session-tools.js

@@ -0,0 +1,261 @@
+/**
+ * Tool adapter for the seven additive `terminal.*` operations.
+ *
+ * Existing shell and job tools are untouched. Every handler requires an owning
+ * conversation id, projects a concise ANSI-free `output` for providers and
+ * transcripts, and returns the structured result under `interactiveSession`.
+ */
+import { isScopeActive, loadScope } from "../store/scope.js";
+import { interactiveSessionManager, } from "../interactive-session/manager.js";
+import { isInteractiveSessionsEnabled, resolveInteractiveSessionConfig, } from "../interactive-session/config.js";
+import { asStableError, } from "../interactive-session/types.js";
+import { CONTROL_INPUTS } from "../interactive-session/types.js";
+export const INTERACTIVE_SESSION_TOOL_NAMES = [
+    "terminal.start",
+    "terminal.send",
+    "terminal.read",
+    "terminal.status",
+    "terminal.list",
+    "terminal.resize",
+    "terminal.close",
+];
+function requireString(args, key) {
+    const value = args[key];
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`${key} must be a non-empty string`);
+    }
+    return value;
+}
+function optionalString(args, key) {
+    const value = args[key];
+    return typeof value === "string" ? value : undefined;
+}
+function optionalNumber(args, key) {
+    const value = args[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function optionalView(args) {
+    const value = optionalString(args, "view");
+    if (value === undefined)
+        return undefined;
+    if (value !== "plain" && value !== "encoded") {
+        throw new Error("view must be plain or encoded");
+    }
+    return value;
+}
+/** Strict validation of the dependent send fields before the manager sees them. */
+function parseInput(args) {
+    const kind = requireString(args, "kind");
+    if (kind === "text") {
+        const text = args.text;
+        if (typeof text !== "string")
+            throw new Error("text is required when kind is text");
+        if (args.control !== undefined)
+            throw new Error("control is not allowed when kind is text");
+        const submit = optionalString(args, "submit") ?? "enter";
+        if (submit !== "enter" && submit !== "none") {
+            throw new Error("submit must be enter or none");
+        }
+        return { kind: "text", text, submit };
+    }
+    if (kind === "control") {
+        const control = requireString(args, "control");
+        if (args.text !== undefined)
+            throw new Error("text is not allowed when kind is control");
+        if (!CONTROL_INPUTS.includes(control)) {
+            throw new Error(`control must be one of: ${CONTROL_INPUTS.join(", ")}`);
+        }
+        return { kind: "control", control: control };
+    }
+    if (kind === "eof") {
+        if (args.text !== undefined || args.control !== undefined) {
+            throw new Error("text and control are not allowed when kind is eof");
+        }
+        return { kind: "eof" };
+    }
+    throw new Error("kind must be text, control, or eof");
+}
+/** Active engagement scope, so interactive risk matches the shell boundary. */
+async function activeScope() {
+    const scope = await loadScope();
+    return isScopeActive(scope) ? scope : undefined;
+}
+function requireOwner(options, operation) {
+    const ownerId = options?.sessionId;
+    if (typeof ownerId === "string" && ownerId.length > 0)
+        return ownerId;
+    throw new Error(`terminal.${operation} requires an active clai session that owns the interactive session`);
+}
+/**
+ * Interactive confirmation. The runner already prompted when it marked the call
+ * confirmed; otherwise the managed secret/confirm path is unavailable and a
+ * `confirm`-level action is refused rather than silently delivered.
+ */
+function confirmPort(options) {
+    return async () => options?.confirmed === true;
+}
+function summarizePage(page) {
+    if (!page)
+        return [];
+    const lines = [];
+    const body = page.events.map((event) => event.content).join("");
+    if (body.length > 0)
+        lines.push(body.replace(/\s+$/, ""));
+    lines.push(`[cursor ${page.requestedCursor}→${page.nextCursor}${page.hasMore ? " more" : ""}${page.decodingLoss ? " lossy" : ""}${page.omittedBytes ? ` omitted=${page.omittedBytes}B` : ""}]`);
+    return lines;
+}
+function describeError(error) {
+    return `[${error.code}] ${error.message} (retryable=${error.retryable})`;
+}
+function project(result) {
+    const lines = [];
+    let ok = true;
+    switch (result.operation) {
+        case "start":
+            lines.push(`session ${result.sessionId} ${result.state} transport=${result.transport}` +
+                (result.dimensions
+                    ? ` ${result.dimensions.columns}x${result.dimensions.rows}`
+                    : "") +
+                (result.degradedReason ? ` degraded=${result.degradedReason}` : ""), `artifact=${result.artifact.path}`);
+            break;
+        case "send":
+            lines.push(`seq=${result.inputSequence} delivery=${result.delivery} bytes=${result.deliveredBytes} state=${result.state}`, ...summarizePage(result.page));
+            if (result.error) {
+                ok = false;
+                lines.push(describeError(result.error));
+            }
+            break;
+        case "read":
+            lines.push(`state=${result.state}`, ...summarizePage(result.page));
+            if (result.error) {
+                ok = false;
+                lines.push(describeError(result.error));
+            }
+            break;
+        case "status": {
+            const session = result.session;
+            lines.push(`${session.id} ${session.state} transport=${session.transport} cursor=${session.earliestCursor}..${session.latestCursor}` +
+                (session.inputClosed ? " input=closed" : "") +
+                (session.terminationReason ? ` reason=${session.terminationReason}` : ""));
+            break;
+        }
+        case "list":
+            lines.push(result.sessions.length === 0
+                ? "No interactive sessions for this conversation."
+                : result.sessions
+                    .map((session) => `${session.id} ${session.state} transport=${session.transport} latestCursor=${session.latestCursor}`)
+                    .join("\n"));
+            break;
+        case "resize":
+            lines.push(`${result.sessionId} resized to ${result.dimensions.columns}x${result.dimensions.rows} (${result.state})`);
+            break;
+        case "close":
+            lines.push(`${result.sessionId} ${result.state}` +
+                (result.terminationReason ? ` reason=${result.terminationReason}` : "") +
+                ` cleanupVerified=${result.cleanupVerified}`);
+            if (result.error) {
+                ok = false;
+                lines.push(describeError(result.error));
+            }
+            break;
+    }
+    return { ok, output: lines.filter((line) => line.length > 0).join("\n"), interactiveSession: result };
+}
+function failure(error, operation) {
+    const stable = asStableError(error, {
+        code: "INVALID_REQUEST",
+        operation,
+        message: error instanceof Error ? error.message : "Invalid interactive session request.",
+    });
+    return { ok: false, output: describeError(stable), exitCode: 1 };
+}
+async function guarded(operation, run) {
+    try {
+        if (!isInteractiveSessionsEnabled(resolveInteractiveSessionConfig())) {
+            return {
+                ok: false,
+                output: "Interactive terminal sessions are disabled. Use shell.exec or shell.start instead.",
+                exitCode: 1,
+            };
+        }
+        return project(await run());
+    }
+    catch (error) {
+        return failure(error, operation);
+    }
+}
+export function createInteractiveSessionHandlers(manager = interactiveSessionManager) {
+    return {
+        "terminal.start": async (args, options) => guarded("start", async () => {
+            const ownerId = requireOwner(options, "start");
+            const mode = optionalString(args, "terminalMode");
+            return await manager.start({
+                ownerId,
+                command: requireString(args, "command"),
+                cwd: optionalString(args, "cwd"),
+                terminalMode: mode,
+                columns: optionalNumber(args, "columns"),
+                rows: optionalNumber(args, "rows"),
+                idleTimeoutMs: optionalNumber(args, "idleTimeoutMs"),
+                lifetimeTimeoutMs: optionalNumber(args, "lifetimeTimeoutMs"),
+                deadlineMs: optionalNumber(args, "deadlineMs"),
+                signal: options?.signal,
+                confirm: confirmPort(options),
+                scope: await activeScope(),
+            });
+        }),
+        "terminal.send": async (args, options) => guarded("send", async () => {
+            const ownerId = requireOwner(options, "send");
+            return await manager.send({
+                ownerId,
+                id: requireString(args, "id"),
+                input: parseInput(args),
+                cursor: optionalNumber(args, "cursor"),
+                quietMs: optionalNumber(args, "quietMs"),
+                deadlineMs: optionalNumber(args, "deadlineMs"),
+                view: optionalView(args),
+                signal: options?.signal,
+                confirm: confirmPort(options),
+                scope: await activeScope(),
+            });
+        }),
+        "terminal.read": async (args, options) => guarded("read", async () => {
+            const ownerId = requireOwner(options, "read");
+            const cursor = optionalNumber(args, "cursor");
+            if (cursor === undefined)
+                throw new Error("cursor is required");
+            return await manager.read({
+                ownerId,
+                id: requireString(args, "id"),
+                cursor,
+                waitMs: optionalNumber(args, "waitMs"),
+                view: optionalView(args),
+                signal: options?.signal,
+            });
+        }),
+        "terminal.status": async (args, options) => guarded("status", () => manager.status({
+            ownerId: requireOwner(options, "status"),
+            id: requireString(args, "id"),
+        })),
+        "terminal.list": async (_args, options) => guarded("list", () => manager.list({ ownerId: requireOwner(options, "list") })),
+        "terminal.resize": async (args, options) => guarded("resize", async () => {
+            const columns = optionalNumber(args, "columns");
+            const rows = optionalNumber(args, "rows");
+            if (columns === undefined || rows === undefined) {
+                throw new Error("columns and rows are required");
+            }
+            return await manager.resize({
+                ownerId: requireOwner(options, "resize"),
+                id: requireString(args, "id"),
+                columns,
+                rows,
+            });
+        }),
+        "terminal.close": async (args, options) => guarded("close", async () => await manager.close({
+            ownerId: requireOwner(options, "close"),
+            id: requireString(args, "id"),
+            deadlineMs: optionalNumber(args, "deadlineMs"),
+        })),
+    };
+}
+//# sourceMappingURL=interactive-session-tools.js.map

package/dist/tools/interactive-session-tools.js.map

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

package/dist/tools/jobs.d.ts

@@ -14,6 +14,12 @@ export type JobMonitorMetadata = Record<string, unknown>;
 export interface JobLinkMetadata {
     taskId?: string | undefined;
     parentTaskId?: string | undefined;
+    /**
+     * Stable delegation identity minted before launch. It is the
+     * reconciliation key between a job and its responder child task, so a fast
+     * exit or a failed link cannot orphan the child.
+     */
+    delegationId?: string | undefined;
     wakeOnCompletion?: boolean | undefined;
     monitor?: JobMonitorMetadata | undefined;
     /** Runtime listening lease that authorized this responder delegation. */
@@ -65,6 +71,19 @@ export interface BackgroundJob extends JobLinkMetadata {
     timeoutAt?: string | undefined;
 }
 export declare function formatJobElapsed(job: Pick<BackgroundJob, "startedAt" | "endedAt">, now?: number): string;
+export interface SupersededResultRevision {
+    resultRevision: number;
+    resultHash: string;
+    status: JobTerminalStatus;
+    endedAt: string;
+    exitCode?: number | undefined;
+    signal?: string | undefined;
+    deliveredAt?: string | undefined;
+    readAt?: string | undefined;
+    analyzedAt?: string | undefined;
+    acknowledgedAt?: string | undefined;
+    settledAt?: string | undefined;
+}
 export interface ResponderNotification {
     id: string;
     ownerSessionId: string;
@@ -84,10 +103,21 @@ export interface ResponderNotification {
     responder: boolean;
     monitor?: JobMonitorMetadata | undefined;
     responderLeaseId?: string | undefined;
+    /** A delivery attempt began; not durable consumption. Cleared claims may retry. */
+    deliveryStartedAt?: string | undefined;
     deliveredAt?: string | undefined;
     readAt?: string | undefined;
     analyzedAt?: string | undefined;
     acknowledgedAt?: string | undefined;
+    /** User discarded this receipt (cancel/new session); never model analysis. */
+    discardedAt?: string | undefined;
+    discardReason?: "session-cancelled" | undefined;
+    /** Monotonic revision of the authoritative result this receipt carries. */
+    resultRevision?: number | undefined;
+    /** Content hash of the authoritative result, used to detect a correction. */
+    resultHash?: string | undefined;
+    /** Bounded audit trail of revisions this receipt superseded. */
+    supersededRevisions?: readonly SupersededResultRevision[] | undefined;
     archivedAt?: string | undefined;
     settledAt?: string | undefined;
 }
@@ -100,6 +130,16 @@ export type JobManagerChange = {
     notificationId: string;
 };
 export type JobManagerListener = (change: JobManagerChange) => void;
+/** Durable projection marker for a terminal result whose plan child is unsettled. */
+export interface PendingSettlement {
+    jobId: string;
+    resultRevision: number;
+    attempts: number;
+    firstAttemptAt: string;
+    lastAttemptAt: string;
+    lastReason: string;
+    deadLetteredAt?: string | undefined;
+}
 interface TailCursor {
     stream?: "stdout" | "stderr" | "combined";
     offset?: number;
@@ -137,7 +177,9 @@ export declare class JobManager {
     private authorizationTimers;
     private responderLeases;
     private settlementTimers;
-    private settlementAttempts;
+    private pendingSettlements;
+    private consumedResponderResults;
+    private livenessWatchTimer;
     private finalizations;
     private listeners;
     /**
@@ -147,11 +189,19 @@ export declare class JobManager {
      * observed alive again or finalized.
      */
     private livenessMisses;
+    private livenessCheckedAt;
     private registryRetryTimer;
     private readonly registryPath;
     private readonly transientV2RegistryPath;
     constructor(jobsDir?: string);
     private isDurable;
+    private artifactPathsOf;
+    /** Delete a dropped job's artifact chunks, never one still referenced. */
+    private removeJobArtifacts;
+    /** Drop a job row plus its per-job caches and artifacts. */
+    private forgetJob;
+    /** Remove artifact files whose job row no longer exists. */
+    private sweepOrphanArtifacts;
     private isLive;
     private isTerminalStatus;
     private emit;
@@ -170,6 +220,25 @@ export declare class JobManager {
     /** Reconcile a restored process that no longer has a ChildProcess close event. */
     private refreshJobLiveness;
     private scheduleTaskSettlement;
+    private completeSettlement;
+    /**
+     * Retry until the projection lands. The marker is durable, so a crash or a
+     * long-lived plan-write conflict cannot silently strand a green child, and an
+     * unrecoverable case is dead-lettered with a visible reason.
+     */
+    private retrySettlement;
+    /**
+     * One coalesced, unref'd watcher that reconciles restored live jobs without a
+     * UI read. Without it a headless session can leave a finished responder job
+     * "running" forever, because liveness was only refreshed by list/get calls.
+     */
+    private scheduleLivenessWatch;
+    /** Ownership guard: a receipt may only be mutated by its owning session. */
+    private ownsNotification;
+    /** Receipt for a launch that was deduplicated by its delegation key. */
+    private startJobReceipt;
+    /** Terminal results whose plan child could not be settled yet. */
+    getPendingSettlements(): PendingSettlement[];
     /**
      * Register an in-flight tool for stall tracking only.
      * Never appears in shell.jobs and never touches the durable registry.
@@ -188,10 +257,15 @@ export declare class JobManager {
     pendingNotifications(sessionId?: string): ResponderNotification[];
     claimNextResponderNotification(sessionId: string, leaseId: string): ResponderNotification | undefined;
     releaseResponderNotificationClaim(notificationId: string): void;
-    markDelivered(notificationId: string): boolean;
+    /**
+     * Record that a delivery attempt started. This is deliberately weaker than
+     * `markDelivered`: an aborted or failed analysis turn must remain deliverable.
+     */
+    markDeliveryStarted(notificationId: string, sessionId?: string): boolean;
+    markDelivered(notificationId: string, sessionId?: string): boolean;
     markRead(notificationId: string, sessionId: string): boolean;
-    markAnalyzed(notificationId: string): boolean;
-    acknowledge(notificationId: string): boolean;
+    markAnalyzed(notificationId: string, sessionId?: string): boolean;
+    acknowledge(notificationId: string, sessionId?: string): boolean;
     linkJob(jobId: string, metadata: JobLinkMetadata): BackgroundJob | undefined;
     tailJob(id: string, bytesOrCursor?: number | TailCursor): Promise<ToolResult>;
     stopJob(id: string, options?: {