apex-code 0.0.5 → 0.1.0

package/dist/core/agent-session.d.ts

@@ -18,6 +18,7 @@ import { type BashResult } from "./bash-executor.ts";
 import type { CheckpointSettings } from "./checkpoints/git-checkpoints.ts";
 import { type SessionCheckpoints } from "./checkpoints/session-checkpoints.ts";
 import { type CompactionResult } from "./compaction/index.ts";
+import type { ChildRunPolicySnapshot, ChildRunRegistry, ChildRunStatus, ChildRunUsageTotals, ChildSessionStatus, ChildTurnOutcome, ChildWorkspaceRecoveryResult, ChildWorkspaceRequest, DelegationRuntimeOptions } from "./delegation/runtime.ts";
 import { type ContextUsage, type ExtensionCommandContextActions, type ExtensionErrorListener, type ExtensionMode, ExtensionRunner, type ExtensionUIContext, type InputSource, type ReplacedSessionContext, type SessionStartEvent, type ShutdownHandler, type ToolDefinition, type ToolInfo } from "./extensions/index.ts";
 import { type FormatterRunOutcome } from "./formatter-lifecycle.ts";
 import type { HookRuntime } from "./hooks/types.ts";
@@ -39,6 +40,7 @@ import { type ToolContractSnapshotEntry } from "./tools/contract-snapshot.ts";
 import type { DiagnosticsOperations } from "./tools/diagnostics.ts";
 import type { LspOperations } from "./tools/lsp.ts";
 import type { WebSearchOperations } from "./tools/web-search.ts";
+import type { VerificationBoundary } from "./verification-lifecycle.ts";
 import { type VerificationCompletionStatus, type VerificationRecord } from "./verification-lifecycle.ts";
 import { type GitObserveOptions } from "./workspace/git-observer.ts";
 import { type WorkspaceStateRecord } from "./workspace/state.ts";
@@ -126,7 +128,35 @@ export type AgentSessionEvent = Exclude<AgentEvent, {
 };
 /** Listener function for agent session events */
 export type AgentSessionEventListener = (event: AgentSessionEvent) => void;
+/**
+ * Point-in-time snapshot of the root aggregate budget's counters for this
+ * session's whole delegation tree (spec 2026-09-09, "Shared budgets"). Reported
+ * by `AgentSession.aggregateBudgetUsage()`; `undefined` there when no aggregate
+ * budget is configured.
+ */
+export interface AggregateBudgetUsageSnapshot {
+    providerRequests: number;
+    toolCalls: number;
+    maintenanceRequests: number;
+    startedAtMs: number;
+}
 export interface AgentSessionConfig {
+    childRunRegistry?: ChildRunRegistry;
+    /**
+     * The session's delegation runtime options when delegation is configured.
+     * Required for `startChildRun`: without it (no permission gate or explicit
+     * `delegation` option), spawning children from the protocol surfaces refuses
+     * with an actionable error instead of silently fabricating authority.
+     */
+    delegationRuntime?: DelegationRuntimeOptions;
+    /**
+     * Reads the root aggregate budget's counters for this session's delegation
+     * tree (spec 2026-09-09, "Shared budgets"). Wired by `createAgentSession`
+     * when the tree has an aggregate budget (an explicit `aggregateBudget` on
+     * the root, or an inherited root aggregate via `sharedBudgetController` on a
+     * delegated child); absent means the session has no shared ceiling.
+     */
+    aggregateBudgetUsage?: () => AggregateBudgetUsageSnapshot;
     agent: Agent;
     sessionManager: SessionManager;
     settingsManager: SettingsManager;
@@ -239,6 +269,8 @@ export interface PromptOptions {
     /** Internal hook used by RPC mode to observe prompt preflight acceptance or rejection. */
     preflightResult?: (success: boolean) => void;
 }
+/** Stable lifecycle of an AgentSession. Terminal states remain queryable. */
+export type AgentSessionLifecycle = "created" | "running" | "waiting" | "completed" | "failed" | "interrupted" | "closed";
 /** Options for model/thinking mutations. */
 export interface ModelMutationOptions {
     /** Persist the new value to global defaults. Defaults to session-only. */
@@ -291,6 +323,10 @@ export interface TreeNavigationResult {
     workspace?: TreeWorkspaceOutcome;
 }
 export declare class AgentSession {
+    private _lifecycle;
+    private _activePrompt;
+    /** Lifecycle is deliberately retained after completion/close for protocol callers. */
+    get lifecycle(): AgentSessionLifecycle;
     readonly agent: Agent;
     readonly sessionManager: SessionManager;
     readonly settingsManager: SettingsManager;
@@ -354,6 +390,9 @@ export declare class AgentSession {
     private readonly _checkpoints;
     private readonly _hookRuntime;
     private readonly _backgroundShellRegistry;
+    private readonly _childRunRegistry;
+    private readonly _delegationRuntime;
+    private readonly _aggregateBudgetUsage;
     private readonly _permissionResponderFactory;
     /** Worktree checkpoints for this session. Inert unless `checkpoints.enabled` is set. */
     get checkpoints(): SessionCheckpoints;
@@ -443,6 +482,115 @@ export declare class AgentSession {
      * Multiple listeners can be added. Returns unsubscribe function for this listener.
      */
     subscribe(listener: AgentSessionEventListener): () => void;
+    /** Child handles remain available until explicitly closed or this session is disposed. */
+    listChildRuns(): {
+        handleId: string;
+        agentType: string;
+        task: string;
+        status: ChildSessionStatus;
+        attemptCount: number;
+    }[];
+    /**
+     * 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(): AggregateBudgetUsageSnapshot | undefined;
+    private _requireChildRuns;
+    waitChildRun(id: string): Promise<import("./delegation/runtime.ts").DelegationResult>;
+    retrieveChildRun(id: string): Promise<import("./delegation/runtime.ts").DelegationResult>;
+    sendChildInput(id: string, input: string): Promise<void>;
+    interruptChildRun(id: string, reason?: string): void;
+    closeChildRun(id: string): void;
+    /**
+     * 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: string): ChildRunStatus;
+    /**
+     * 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: string): ChildRunUsageTotals | undefined;
+    /**
+     * 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: string): Promise<ChildWorkspaceRecoveryResult>;
+    /**
+     * 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.
+     */
+    startChildRun(agentType: string, task: string, request?: {
+        workspace?: ChildWorkspaceRequest;
+        idempotencyKey?: string;
+        timeoutMs?: number;
+    }): Promise<{
+        handleId: string;
+        created: boolean;
+    }>;
+    /**
+     * 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.
+     */
+    waitChildRunResult(id: string): Promise<{
+        status: ChildSessionStatus;
+        output: string;
+        outcome: ChildTurnOutcome;
+        artifactDir?: string;
+        sessionFile?: string;
+        parentSessionId?: string;
+        policy?: ChildRunPolicySnapshot;
+        sandboxEnforced?: boolean;
+    }>;
+    /**
+     * 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.
+     */
+    resumeChildRun(id: string, input?: string): Promise<ChildSessionStatus>;
     /** Disconnect from agent events during disposal. */
     private _disconnectFromAgent;
     /**
@@ -527,6 +675,7 @@ export declare class AgentSession {
      * @throws Error if no model selected or no API key available (when not streaming)
      */
     prompt(text: string, options?: PromptOptions): Promise<void>;
+    private _prompt;
     private _tryExecuteExtensionCommand;
     /**
      * Expand skill commands (/skill:name args) to their full content.
@@ -723,6 +872,17 @@ export declare class AgentSession {
     }): Promise<FormatterRunOutcome | undefined>;
     /** The current completion status: verified, failed, unavailable, interrupted, or continued-unverified. */
     verificationStatus(): VerificationCompletionStatus;
+    /** The configured verification boundary, for execution owners enforcing it. */
+    verificationBoundary(): VerificationBoundary;
+    /**
+     * 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(): string[];
     /** The live verification record with its bounded evidence, if any. */
     verificationRecord(): VerificationRecord | undefined;
     /** Record that the user chose to finish without verification. */