apex-code 0.0.4 → 0.0.6

package/dist/core/agent-session.js

@@ -26,6 +26,7 @@ import { createSessionCheckpoints } from "./checkpoints/session-checkpoints.js";
 import { calculateContextTokens, collectEntriesForBranchSummary, compact, estimateContextTokens, estimateTokens, generateBranchSummary, prepareCompaction, shouldCompact, } from "./compaction/index.js";
 import { evictionBudget, installContextPipeline, isDefaultStreamFunction } from "./context/pipeline.js";
 import { DEFAULT_THINKING_LEVEL, THINKING_LEVEL_OPTIONS } from "./defaults.js";
+import { RESUME_CHILD_PROMPT, runDelegation } from "./delegation/runtime.js";
 import { SessionEvidenceSink } from "./evidence.js";
 import { exportSessionToHtml } from "./export-html/index.js";
 import { createToolHtmlRenderer } from "./export-html/tool-renderer.js";
@@ -88,6 +89,12 @@ function estimateMessagesTokens(messages) {
     return tokens;
 }
 export class AgentSession {
+    _lifecycle = "created";
+    _activePrompt = false;
+    /** Lifecycle is deliberately retained after completion/close for protocol callers. */
+    get lifecycle() {
+        return this._lifecycle;
+    }
     agent;
     sessionManager;
     settingsManager;
@@ -159,6 +166,9 @@ export class AgentSession {
     _checkpoints;
     _hookRuntime;
     _backgroundShellRegistry;
+    _childRunRegistry;
+    _delegationRuntime;
+    _aggregateBudgetUsage;
     _permissionResponderFactory;
     /** Worktree checkpoints for this session. Inert unless `checkpoints.enabled` is set. */
     get checkpoints() {
@@ -211,6 +221,21 @@ export class AgentSession {
         });
         this._hookRuntime = config.hookRuntime;
         this._backgroundShellRegistry = config.backgroundShellRegistry;
+        this._childRunRegistry = config.childRunRegistry;
+        this._delegationRuntime = config.delegationRuntime;
+        this._aggregateBudgetUsage = config.aggregateBudgetUsage;
+        if (this._childRunRegistry) {
+            // Install persistence before restoring history. Restoration is normally
+            // passive, but registries may reconcile lifecycle state while loading;
+            // no child transition should be able to observe an unwired registry.
+            this._childRunRegistry.setPersistence((record) => this.sessionManager.appendCustomEntry("child_run", record));
+            const records = this.sessionManager
+                .getEntries()
+                .filter((entry) => entry.type === "custom" && entry.customType === "child_run")
+                .map((entry) => entry.data)
+                .filter((value) => !!value && typeof value === "object");
+            this._childRunRegistry.restore(records);
+        }
         this._permissionResponderFactory = config.permissionResponderFactory;
         this._workspaceComparePending = hasWorkspaceObservationAwaitingComparison(this.sessionManager);
         // Always subscribe to agent events for internal handling
@@ -791,6 +816,196 @@ export class AgentSession {
             }
         };
     }
+    /** Child handles remain available until explicitly closed or this session is disposed. */
+    listChildRuns() {
+        return this._childRunRegistry?.list() ?? [];
+    }
+    /**
+     * A point-in-time snapshot of the root aggregate budget's counters for this
+     * session's whole delegation tree -- {providerRequests, toolCalls,
+     * maintenanceRequests, startedAtMs} (spec 2026-09-09, "Shared budgets").
+     * `undefined` when no aggregate budget is configured for the tree.
+     */
+    aggregateBudgetUsage() {
+        return this._aggregateBudgetUsage?.();
+    }
+    _requireChildRuns() {
+        if (!this._childRunRegistry)
+            throw new Error("Child run registry is unavailable.");
+        return this._childRunRegistry;
+    }
+    waitChildRun(id) {
+        return this._requireChildRuns().wait(id);
+    }
+    retrieveChildRun(id) {
+        return this._requireChildRuns().retrieve(id);
+    }
+    sendChildInput(id, input) {
+        return this._requireChildRuns().sendInput(id, input);
+    }
+    interruptChildRun(id, reason) {
+        this._requireChildRuns().interrupt(id, reason);
+    }
+    closeChildRun(id) {
+        this._requireChildRuns().close(id);
+    }
+    /**
+     * Non-blocking status snapshot for one child run (spec 2026-09-09, pollable
+     * status): `{handleId, agentType, task, status, attempt, attempts, ...}` built
+     * from the record/entry alone -- this never awaits a turn, so a caller can
+     * poll a running child without blocking (`waitChildRun` stays the blocking
+     * form). Unknown ids still error; historical records are served from the
+     * persisted record. Observing the status lazily interrupts a running child
+     * whose wall-clock deadline has passed.
+     */
+    childRunStatus(id) {
+        return this._requireChildRuns().status(id);
+    }
+    /**
+     * The child run's token/cost totals, rolled up from the child's OWN session
+     * transcript (`ChildRunRegistry.usageTotals`). `undefined` -- never a throw,
+     * never a zero-fill -- when nothing is reachable (an in-memory child without
+     * a reachable transcript, or a legacy record without any transcript).
+     */
+    childRunUsageTotals(id) {
+        return this._requireChildRuns().usageTotals(id);
+    }
+    /**
+     * Explicitly verify and reactivate a retained child worktree (spec
+     * 2026-09-09, "Workspace states and explicit recovery"): the thinnest
+     * pass-through over `ChildRunRegistry.recoverWorkspace`. Read-only git
+     * inspection through the workspace owner -- the admin entry, the checked-out
+     * branch, and the owner's layout -- never a recreate, checkout, reset, or
+     * force. On success the workspace state becomes "active" (persisted) and the
+     * child can be resumed in the SAME worktree; `{dirty}` reports preserved
+     * uncommitted work. Every failed check throws an actionable error naming the
+     * failed check and leaving the state unverified.
+     */
+    recoverChildWorkspace(id) {
+        return this._requireChildRuns().recoverWorkspace(id);
+    }
+    /**
+     * Start a background child run through the session's own delegation runtime.
+     * A thin pass-through over `runDelegation` (registry-backed, always
+     * background): admission -- agent resolution, depth bound, capability
+     * ceiling -- is the same projection the `delegate` tool uses, so a spawned
+     * child can never hold authority the parent cannot cover. Foreground
+     * spawning is not offered; protocol clients wait on the returned handle.
+     *
+     * Idempotent spawn: a supplied `idempotencyKey` that already maps to a
+     * handle returns the EXISTING handle with `created: false` and never builds
+     * a second child (no budget slot consumed twice); the key persists on the
+     * record, so a restarted parent dedupes too. `timeoutMs` caps the child's
+     * own run budget at the wall-time gate and records the deadline for lazy
+     * status observation.
+     */
+    async startChildRun(agentType, task, request) {
+        const runtime = this._delegationRuntime;
+        if (!runtime) {
+            throw new Error("No delegation runtime is configured; create the session with a permission gate or options.delegation to spawn agents.");
+        }
+        const existing = request?.idempotencyKey !== undefined
+            ? this._childRunRegistry?.handleForIdempotencyKey(request.idempotencyKey)
+            : undefined;
+        if (existing !== undefined)
+            return { handleId: existing, created: false };
+        const result = await runDelegation(runtime, agentType, task, {
+            background: true,
+            workspace: request?.workspace,
+            idempotencyKey: request?.idempotencyKey,
+            timeoutMs: request?.timeoutMs,
+        });
+        if (!result.handleId) {
+            throw new Error(`Delegation to agent "${agentType}" did not return a background handle.`);
+        }
+        return { handleId: result.handleId, created: true };
+    }
+    /**
+     * Wait for a child run's latest settled turn and return its payload with the
+     * registry status after settlement: `{ status, output, outcome }` plus the
+     * run's additive linkage fields (`artifactDir`, `sessionFile`,
+     * `parentSessionId`, `policy`, `sandboxEnforced`) when the registry snapshot
+     * knows them. A failed settlement surfaces as `outcome: "failed"` with the
+     * error message as the output rather than a rejection, so protocol waiters
+     * get the same payload shape on every settled turn; unknown handles still
+     * throw the registry's actionable error.
+     */
+    async waitChildRunResult(id) {
+        // Linkage comes from the same registry snapshot every status payload is
+        // built from -- never recomputed here. Unknown handles throw through the
+        // status read below only after wait itself has rethrown, so the error
+        // contract is unchanged.
+        const linkageOf = () => {
+            try {
+                const snapshot = this.childRunStatus(id);
+                return {
+                    ...(snapshot.artifactDir !== undefined ? { artifactDir: snapshot.artifactDir } : {}),
+                    ...(snapshot.sessionFile !== undefined ? { sessionFile: snapshot.sessionFile } : {}),
+                    ...(snapshot.parentSessionId !== undefined ? { parentSessionId: snapshot.parentSessionId } : {}),
+                    ...(snapshot.policy ? { policy: snapshot.policy } : {}),
+                    ...(snapshot.sandboxEnforced !== undefined ? { sandboxEnforced: snapshot.sandboxEnforced } : {}),
+                };
+            }
+            catch {
+                return {};
+            }
+        };
+        let output;
+        let outcome;
+        try {
+            const result = await this.waitChildRun(id);
+            output = result.output;
+            outcome = result.outcome ?? "completed";
+        }
+        catch (error) {
+            const status = this.listChildRuns().find((run) => run.handleId === id)?.status;
+            if (status === undefined)
+                throw error;
+            return {
+                status,
+                output: error instanceof Error ? error.message : String(error),
+                outcome: "failed",
+                ...linkageOf(),
+            };
+        }
+        const status = this.listChildRuns().find((run) => run.handleId === id)?.status;
+        return { status: status ?? "closed", output, outcome, ...linkageOf() };
+    }
+    /**
+     * Resume an interrupted child run in its existing child session.
+     *
+     * The thinnest pass-through over the session-owned registry: the child keeps its
+     * identity, policy ceiling, and session linkage, and no second service or registry
+     * is involved. Returns the observed status after the resumed turn settles. The
+     * resumed turn's output becomes the run's stored latest result, so a later
+     * `waitChildRun` retrieves it; this call itself returns only the observed status.
+     *
+     * A handle known only as a persisted record (restored from this session's
+     * `child_run` log, no live entry in this process) is historically reattached
+     * instead: its recorded child session file is reopened through the same
+     * construction seam a live delegation uses, then resumed. Live handles keep
+     * the interrupted-only contract below.
+     */
+    async resumeChildRun(id, input) {
+        const registry = this._requireChildRuns();
+        const current = registry.list().find((run) => run.handleId === id)?.status;
+        if (current === undefined)
+            throw new Error(`Unknown delegation handle "${id}".`);
+        if (registry.isHistorical(id))
+            return registry.resumeHistorical(id, input);
+        if (current !== "interrupted")
+            throw new Error(`Child run "${id}" is not interrupted (status: ${current}).`);
+        // A resume is a new attempt epoch (spec 2026-09-09, "Child lifecycle"):
+        // the interrupted attempt closes with its settled outcome and the resuming
+        // turn opens a new one. Historical resume does the same inside
+        // `resumeHistorical`.
+        registry.beginResumeAttempt(id);
+        await registry.sendInput(id, input ?? RESUME_CHILD_PROMPT);
+        const status = registry.list().find((run) => run.handleId === id)?.status;
+        if (status === undefined)
+            throw new Error(`Child run "${id}" disappeared while resuming.`);
+        return status;
+    }
     /** Disconnect from agent events during disposal. */
     _disconnectFromAgent() {
         if (this._unsubscribeAgent) {
@@ -803,6 +1018,9 @@ export class AgentSession {
      * Call this when completely done with the session.
      */
     dispose() {
+        if (this._lifecycle === "closed")
+            return;
+        this._lifecycle = "closed";
         try {
             this.abortRetry();
             this.abortCompaction();
@@ -812,6 +1030,7 @@ export class AgentSession {
             // Background shell children (spec 2026-08-31-background-shell.md) must
             // never outlive the session that launched them.
             this._backgroundShellRegistry?.dispose();
+            this._childRunRegistry?.dispose();
         }
         catch {
             // Dispose must succeed even if an abort hook throws.
@@ -1061,6 +1280,33 @@ export class AgentSession {
      * @throws Error if no model selected or no API key available (when not streaming)
      */
     async prompt(text, options) {
+        if (this._lifecycle === "closed")
+            throw new Error("Session is closed.");
+        if (this._activePrompt) {
+            if (!this.isStreaming)
+                throw new Error("Session is already running.");
+            return this._prompt(text, options);
+        }
+        this._activePrompt = true;
+        this._lifecycle = "running";
+        try {
+            await this._prompt(text, options);
+            if (this.lifecycle === "running") {
+                const last = [...this.agent.state.messages].reverse().find((message) => message.role === "assistant");
+                this._lifecycle =
+                    last?.stopReason === "error" ? "failed" : last?.stopReason === "aborted" ? "interrupted" : "completed";
+            }
+        }
+        catch (error) {
+            if (this.lifecycle === "running")
+                this._lifecycle = "failed";
+            throw error;
+        }
+        finally {
+            this._activePrompt = false;
+        }
+    }
+    async _prompt(text, options) {
         const expandPromptTemplates = options?.expandPromptTemplates ?? true;
         const preflightResult = options?.preflightResult;
         let messages;
@@ -1190,6 +1436,8 @@ export class AgentSession {
         preflightResult?.(true);
         await this._runWorkspaceComparisonBoundary();
         await this._runAgentPrompt(messages);
+        if (this.lifecycle === "closed" || this.lifecycle === "interrupted")
+            return;
         await this._runVerificationTurnBoundary();
     }
     /**
@@ -1471,6 +1719,8 @@ export class AgentSession {
      * Abort current operation and wait for agent to become idle.
      */
     async abort() {
+        if (this._activePrompt && this._lifecycle !== "closed")
+            this._lifecycle = "interrupted";
         this.abortRetry();
         this.agent.abort();
         await this.waitForIdle();
@@ -1859,6 +2109,21 @@ export class AgentSession {
     verificationStatus() {
         return this._verificationTracker?.completionStatus() ?? "unavailable";
     }
+    /** The configured verification boundary, for execution owners enforcing it. */
+    verificationBoundary() {
+        return this._verificationTracker?.boundary ?? "explicit";
+    }
+    /**
+     * The configured verification policy ids, read through the canonical
+     * tracker (refreshed from settings on each call, like requestVerification).
+     * Execution owners such as the delegation child gate use the count to tell
+     * "no policies configured" (turn proceeds unchanged) from "configured and
+     * not verified" (turn fails) -- the completion status alone cannot express
+     * that difference, because it reports "unavailable" for both.
+     */
+    verificationPolicyIds() {
+        return this._ensureVerificationTracker().policyIds();
+    }
     /** The live verification record with its bounded evidence, if any. */
     verificationRecord() {
         return this._verificationTracker?.latest();