@robota-sdk/agent-interface-execution 3.0.0-beta.81

package/dist/node/index.d.cts

@@ -0,0 +1,585 @@
+import { IHistoryEntry, ITokenUsage, TBackgroundPermissionPolicy, TModelEffort, TUniversalValue } from "@robota-sdk/agent-core";
+//#region src/background-task-contracts.d.ts
+type TBackgroundTaskKind = 'agent' | 'process' | 'scheduled' | 'tool-invocation';
+type TBackgroundTaskMode = 'foreground' | 'background';
+type TBackgroundTaskIsolation = 'none' | 'worktree';
+type TBackgroundTaskStatus = 'queued' | 'running' | 'waiting_permission' | 'sleeping' | 'paused' | 'completed' | 'failed' | 'cancelled';
+type TBackgroundTaskTimeoutReason = 'idle' | 'max_runtime' | 'output_limit' | 'repetition' | 'stale_worker';
+type TBackgroundTaskErrorCategory = 'validation' | 'capacity' | 'permission' | 'timeout' | 'runner' | 'crash' | 'provider' | 'process';
+type TBackgroundPrimitive = string | number | boolean;
+interface IBackgroundTaskError {
+  category: TBackgroundTaskErrorCategory;
+  message: string;
+  recoverable: boolean;
+}
+interface ISerializableProviderProfile {
+  profileName?: string;
+  type: string;
+  model: string;
+  apiKey?: string;
+  apiKeyEnv?: string;
+  baseURL?: string;
+  timeout?: number;
+  options?: Record<string, TUniversalValue>;
+}
+interface IBaseBackgroundTaskRequest {
+  kind: TBackgroundTaskKind;
+  label: string;
+  mode: TBackgroundTaskMode;
+  parentSessionId: string;
+  parentTaskId?: string;
+  depth: number;
+  cwd: string;
+  timeoutMs?: number;
+  idleTimeoutMs?: number;
+  maxRuntimeMs?: number;
+  metadata?: Record<string, TBackgroundPrimitive>;
+}
+interface IAgentBackgroundTaskRequest extends IBaseBackgroundTaskRequest {
+  kind: 'agent';
+  agentType: string;
+  prompt: string;
+  model?: string;
+  effort?: TModelEffort;
+  isolation?: TBackgroundTaskIsolation;
+  /**
+   * CLI-1994: the persisted session record the child RESTORES before its first turn — a fork of the
+   * parent conversation written under a fresh id by `/fork`. Only the id crosses: the conversation
+   * itself never rides on the request, so the child-process wire stays as narrow as ARCH-044 left it
+   * (the child reads the record from the session store, exactly as `--fork-session` does). Absent ⇒
+   * the child starts with an empty conversation, unchanged.
+   */
+  resumeSessionId?: string;
+  allowedTools?: string[];
+  disallowedTools?: string[];
+  permissionPolicy: TBackgroundPermissionPolicy;
+  providerProfile?: ISerializableProviderProfile;
+  outputLimitBytes?: number;
+  maxTextDeltas?: number;
+  repetitionWindow?: number;
+  repetitionThreshold?: number;
+}
+interface IProcessBackgroundTaskRequest extends IBaseBackgroundTaskRequest {
+  kind: 'process';
+  command: string;
+  shell?: string;
+  env?: Record<string, string>;
+  stdin?: string;
+  outputLimitBytes?: number;
+  /**
+   * FLOW-004 (monitor): a regular-expression source. Output lines matching it fire a
+   * `background_task_waking` carrying `agentInstruction` + the matched line, so the agent
+   * reacts to "something happened in this process's output".
+   */
+  matchPattern?: string;
+  /** FLOW-004: the instruction injected on a monitor match (paired with `matchPattern`). */
+  agentInstruction?: string;
+}
+/**
+ * A scheduled task carries NO `permissionPolicy`, by decision (issue #2354).
+ *
+ * A `kind: 'agent'` task spawns a SEPARATE agent, so it declares its own policy and CORE-025
+ * enforces it. A schedule with `agentInstruction` does not spawn anything: it WAKES the host
+ * session (`background_task_waking` → `requestWakeup` → an `agent-wakeup` turn), and that turn runs
+ * under the host session's own permission configuration — mode, allow/deny rules, hooks, session
+ * consent — exactly as a turn the user typed would. Inheritance is the contract, not an omission:
+ * a policy field here would either duplicate the session's or silently disagree with it. The
+ * `contracts.test.ts` type assertion fails if one is added without that wiring being designed.
+ */
+interface IScheduledBackgroundTaskRequest extends IBaseBackgroundTaskRequest {
+  kind: 'scheduled';
+  cronExpression: string;
+  /**
+   * Shell command to run on each fire. Optional when `agentInstruction` is set —
+   * an agent-wake schedule may fire the agent loop instead of (or in addition to) a shell command.
+   */
+  command?: string;
+  /**
+   * FLOW-001: when set, each fire carries this instruction on the `background_task_waking`
+   * event so an upper layer (FLOW-002) can wake the agent loop with a non-user turn.
+   */
+  agentInstruction?: string;
+  shell?: string;
+  env?: Record<string, string>;
+  outputLimitBytes?: number;
+}
+/**
+ * MCP-004 §S1: an in-flight MCP tool call handed off to the background-task manager. Data only —
+ * the naming split is deliberate: the KIND is `'tool-invocation'` (INFRA-025's closed vocabulary
+ * names the thing that runs), while the feature, its files and its tests keep the name "tool-call
+ * handoff" (what a user does with it). Provenance is flattened into primitive fields rather than a
+ * nested object so the request stays data-only and the executor helpers can project the same
+ * fields into `metadata` for `/tasks` to read (agent-executor, not this package, owns that
+ * projection). The remaining budget rides the base request's `maxRuntimeMs` — no dedicated field.
+ */
+interface IToolInvocationBackgroundTaskRequest extends IBaseBackgroundTaskRequest {
+  kind: 'tool-invocation';
+  toolName: string;
+  /** Looked up by the runner's adoption registry (`agent-executor`) to find the already-running call. */
+  adoptionToken: string;
+  /** MCP-004 provenance: the only owner today. A closed union of one, matching the request's origin. */
+  provenanceOwner: 'mcp';
+  serverId: string;
+  sourceName: string;
+  securityIdentity?: string;
+  /** Provenance metadata for `/tasks` and the notification — not an enforcement carrier (§ Decision). */
+  permissionMode: string;
+}
+type TBackgroundTaskRequest = IAgentBackgroundTaskRequest | IProcessBackgroundTaskRequest | IScheduledBackgroundTaskRequest | IToolInvocationBackgroundTaskRequest;
+/**
+ * ANALYTICS-001 (Phase 2): token usage a completed task/subagent consumed, for source attribution.
+ * TYPE-003: alias of the `agent-core` usage-triple SSOT (`ITokenUsage`) — derived, not re-declared.
+ */
+type IBackgroundTaskUsage = ITokenUsage;
+interface IBaseBackgroundTaskResult {
+  taskId: string;
+  output: string;
+  metadata?: Record<string, TBackgroundPrimitive>;
+}
+interface IAgentBackgroundTaskResult extends IBaseBackgroundTaskResult {
+  kind: 'agent';
+  /** ANALYTICS-001 (Phase 2): total token usage of an agent task, attributed to it in the parent log. */
+  usage?: IBackgroundTaskUsage;
+}
+interface IProcessBackgroundTaskResult extends IBaseBackgroundTaskResult {
+  kind: 'process';
+  exitCode?: number;
+  signalCode?: string;
+}
+interface IScheduledBackgroundTaskResult extends IBaseBackgroundTaskResult {
+  kind: 'scheduled';
+}
+interface IToolInvocationBackgroundTaskResult extends IBaseBackgroundTaskResult {
+  kind: 'tool-invocation';
+}
+/**
+ * #2079: the outcome hop discriminates by kind exactly as the request hop
+ * (`TBackgroundTaskRequest`) does — `exitCode`/`signalCode` are producible only by the process
+ * runner and `usage` only by the agent runner (`ISubagentJobResult` is now
+ * `Omit<IBackgroundTaskResult<'agent'>, 'kind'>`, not a hand-maintained `Omit` off the flat shape).
+ * `IBackgroundTaskResult<K>` narrows to the kind-specific member for a caller that knows `K`
+ * statically (a runner's `start()`, the decoder once it has
+ * checked `kind`); called with no type argument it stays the full union. `IBackgroundTaskState<K>`
+ * is discriminated the same way, and its `result` field is `IBackgroundTaskResult<K>` — correlated
+ * with `state.kind`, not the free-standing full union.
+ */
+type TBackgroundTaskResult = IAgentBackgroundTaskResult | IProcessBackgroundTaskResult | IScheduledBackgroundTaskResult | IToolInvocationBackgroundTaskResult;
+type IBackgroundTaskResult<K extends TBackgroundTaskKind = TBackgroundTaskKind> = Extract<TBackgroundTaskResult, {
+  kind: K;
+}>;
+/**
+ * #2079: the persisted/live state hop discriminates by kind exactly as the request and result hops
+ * do. Fields a single runner alone can produce — `agentType`/`isolation`/`resumeSessionId`/
+ * `promptPreview`/the worktree-isolation fields (agent), `schedule`/`nextFireAt` (scheduled) — live
+ * only on that kind's member. `commandPreview` is produced by every runner except the agent one (a
+ * process command, a tool-invocation summary, or a schedule's shell command / wake instruction), so
+ * it stays on the three non-agent members, not the base. `pid`/`logPath`/`transcriptPath` stay on
+ * the shared base: the handle SPI (`IBackgroundTaskHandle`) already reports them generically for
+ * whichever runner's process happens to produce them, and a subagent run as a child process (the
+ * worktree-isolation runner) carries a `pid` exactly as a `process`-kind task does — an audit of
+ * every producer (`background-task-manager-helpers.ts`, `subagent-manager.ts`,
+ * `worktree-subagent-runner.ts`) found no case of an agent/process pid being kind-exclusive.
+ * `timeoutReason` is likewise base: `interactive-session-restore.ts` sets `'stale_worker'` on ANY
+ * non-terminal, non-rearmable task regardless of kind, not only on agent tasks.
+ */
+interface IBaseBackgroundTaskState<K extends TBackgroundTaskKind> {
+  id: string;
+  kind: K;
+  label: string;
+  status: TBackgroundTaskStatus;
+  mode: TBackgroundTaskMode;
+  parentSessionId: string;
+  parentTaskId?: string;
+  depth: number;
+  cwd: string;
+  pid?: number;
+  startedAt?: string;
+  updatedAt: string;
+  lastActivityAt?: string;
+  completedAt?: string;
+  currentAction?: string;
+  unread: boolean;
+  result?: IBackgroundTaskResult<K>;
+  error?: IBackgroundTaskError;
+  logPath?: string;
+  transcriptPath?: string;
+  timeoutReason?: TBackgroundTaskTimeoutReason;
+  metadata?: Record<string, TBackgroundPrimitive>;
+}
+interface IAgentBackgroundTaskState extends IBaseBackgroundTaskState<'agent'> {
+  agentType?: string;
+  promptPreview?: string;
+  isolation?: TBackgroundTaskIsolation;
+  /**
+   * CLI-1994: carried from `IAgentBackgroundTaskRequest.resumeSessionId` so a surface can offer to
+   * ATTACH to the forked session — a view switch onto that record, never a merge with the parent.
+   */
+  resumeSessionId?: string;
+  worktreePath?: string;
+  branchName?: string;
+  worktreeStatus?: string;
+  worktreeNextAction?: string;
+  worktreeBaseRevision?: string;
+  parentWorktreeStatus?: string;
+}
+interface IProcessBackgroundTaskState extends IBaseBackgroundTaskState<'process'> {
+  commandPreview?: string;
+}
+interface IScheduledBackgroundTaskState extends IBaseBackgroundTaskState<'scheduled'> {
+  commandPreview?: string;
+  nextFireAt?: string;
+  /**
+   * FLOW-003: for `kind: 'scheduled'` tasks, the reconstructable schedule definition.
+   * Persisted with the task so a resumed session can re-arm the croner job.
+   */
+  schedule?: IBackgroundTaskSchedule;
+}
+interface IToolInvocationBackgroundTaskState extends IBaseBackgroundTaskState<'tool-invocation'> {
+  commandPreview?: string;
+}
+type TBackgroundTaskState = IAgentBackgroundTaskState | IProcessBackgroundTaskState | IScheduledBackgroundTaskState | IToolInvocationBackgroundTaskState;
+type IBackgroundTaskState<K extends TBackgroundTaskKind = TBackgroundTaskKind> = Extract<TBackgroundTaskState, {
+  kind: K;
+}>;
+/** FLOW-003: the persisted, reconstructable definition of a scheduled wake. */
+interface IBackgroundTaskSchedule {
+  cronExpression: string;
+  agentInstruction?: string;
+  command?: string;
+  shell?: string;
+  env?: Record<string, string>;
+}
+interface IBackgroundTaskInput {
+  prompt?: string;
+  stdin?: string;
+}
+interface IBackgroundTaskLogCursor {
+  offset: number;
+}
+interface IBackgroundTaskLogPage {
+  taskId: string;
+  cursor?: IBackgroundTaskLogCursor;
+  nextCursor?: IBackgroundTaskLogCursor;
+  lines: string[];
+}
+interface IBackgroundTaskListFilter {
+  kind?: TBackgroundTaskKind;
+  status?: TBackgroundTaskStatus;
+  mode?: TBackgroundTaskMode;
+  includeClosed?: boolean;
+}
+type TBackgroundTaskEvent = {
+  type: 'background_task_created';
+  task: IBackgroundTaskState;
+} | {
+  type: 'background_task_started';
+  task: IBackgroundTaskState;
+} | {
+  type: 'background_task_updated';
+  task: IBackgroundTaskState;
+} | {
+  type: 'background_task_text_delta';
+  taskId: string;
+  delta: string;
+} | {
+  type: 'background_task_tool_start';
+  taskId: string;
+  toolName: string;
+  firstArg?: string;
+} | {
+  type: 'background_task_tool_end';
+  taskId: string;
+  toolName: string;
+  success: boolean;
+  error?: string;
+} | {
+  type: 'background_task_permission_request';
+  taskId: string;
+  requestId: string;
+  toolName: string;
+  toolArgs: Record<string, TBackgroundPrimitive>;
+} | {
+  type: 'background_task_completed';
+  task: IBackgroundTaskState;
+} | {
+  type: 'background_task_failed';
+  task: IBackgroundTaskState;
+} | {
+  type: 'background_task_cancelled';
+  task: IBackgroundTaskState;
+} | {
+  type: 'background_task_closed';
+  taskId: string;
+} | {
+  type: 'background_task_waking';
+  taskId: string;
+  instruction?: string;
+};
+type TBackgroundTaskEventListener = (event: TBackgroundTaskEvent) => void;
+//#endregion
+//#region src/background-group-contracts.d.ts
+type TBackgroundJobWaitPolicy = 'detached' | 'wait_all' | 'wait_any' | 'manual';
+type TBackgroundJobGroupStatus = 'running' | 'completed';
+interface IBackgroundJobResultEnvelope {
+  taskId: string;
+  label: string;
+  status: TBackgroundTaskStatus;
+  summary?: string;
+  outputRef?: string;
+  error?: IBackgroundTaskError;
+  startedAt?: string;
+  completedAt?: string;
+}
+interface IBackgroundJobGroupState {
+  id: string;
+  parentSessionId: string;
+  waitPolicy: TBackgroundJobWaitPolicy;
+  taskIds: string[];
+  status: TBackgroundJobGroupStatus;
+  createdAt: string;
+  updatedAt: string;
+  label?: string;
+  completedAt?: string;
+  results: IBackgroundJobResultEnvelope[];
+}
+interface IBackgroundJobGroupSummary {
+  groupId: string;
+  status: TBackgroundJobGroupStatus;
+  total: number;
+  completed: number;
+  failed: number;
+  cancelled: number;
+  pending: number;
+  lines: string[];
+}
+interface IBackgroundJobGroupCreateRequest {
+  parentSessionId: string;
+  waitPolicy: TBackgroundJobWaitPolicy;
+  taskIds: string[];
+  label?: string;
+}
+type TBackgroundJobGroupEvent = {
+  type: 'background_job_group_created';
+  group: IBackgroundJobGroupState;
+} | {
+  type: 'background_job_group_updated';
+  group: IBackgroundJobGroupState;
+} | {
+  type: 'background_job_group_completed';
+  group: IBackgroundJobGroupState;
+};
+type TBackgroundJobGroupEventListener = (event: TBackgroundJobGroupEvent) => void;
+type TBackgroundJobGroupIdFactory = (request: IBackgroundJobGroupCreateRequest) => string;
+//#endregion
+//#region src/subagent-contracts.d.ts
+/**
+ * TYPE-003: derived from the background-task status SSOT ({@link TBackgroundTaskStatus}) instead of
+ * a second hand-maintained union — a status added to the SSOT now flows here mechanically (the
+ * prior manual copy silently missed `paused` when SELFHOST-012 added it). `paused` is excluded on
+ * purpose: it is a scheduled-task-only status and a subagent is never a scheduled task
+ * (`SubagentManager.toSubagentState` maps it to `sleeping`).
+ */
+type TSubagentJobStatus = Exclude<TBackgroundTaskStatus, 'paused'>;
+/** TYPE-003: alias of the background-task mode SSOT — the job mode is the same foreground/background pair. */
+type TSubagentJobMode = TBackgroundTaskMode;
+/**
+ * Subagent-job projection of {@link IBackgroundTaskState}.
+ *
+ * TYPE-003: every field a subagent job shares with the background-task SSOT is derived via `Pick`
+ * (previously a ~20-field manual mirror that could drift silently). Only the genuinely
+ * subagent-specific fields are declared here:
+ * - `type` — the agent-definition type (the task-side counterpart is the optional `agentType`);
+ * - `status` — the derived {@link TSubagentJobStatus} (no `paused`);
+ * - `promptPreview` — required here (every subagent job is created from a prompt; optional on tasks);
+ * - `currentTool` — the job-level projection of the task's free-form `currentAction`;
+ * - `result`/`error` — flattened display strings (the task carries structured
+ *   `IBackgroundTaskResult`/`IBackgroundTaskError` objects).
+ */
+interface ISubagentJobState extends Pick<IBackgroundTaskState<'agent'>, 'id' | 'label' | 'parentSessionId' | 'mode' | 'depth' | 'pid' | 'cwd' | 'isolation' | 'resumeSessionId' | 'worktreePath' | 'branchName' | 'worktreeStatus' | 'worktreeNextAction' | 'worktreeBaseRevision' | 'parentWorktreeStatus' | 'logPath' | 'transcriptPath' | 'startedAt' | 'updatedAt' | 'completedAt' | 'timeoutReason' | 'metadata'> {
+  type: string;
+  status: TSubagentJobStatus;
+  promptPreview: string;
+  currentTool?: string;
+  result?: string;
+  error?: string;
+}
+/**
+ * A subagent spawn request IS an agent background-task request (ARCH-031).
+ *
+ * `kind` is fixed by the seam — a subagent is never a process task — so omitting it both removes a
+ * field every caller would have to set identically and structurally prevents `kind: 'process'` from
+ * reaching `SubagentManager.spawn`. Everything else is carried by derivation rather than by a
+ * hand-written projection remembering it, which is the whole point: `parentTaskId` and
+ * `providerProfile` reach the runner because they exist on the source, not because someone recalled
+ * them.
+ *
+ * Nothing is added here. The worktree identity a runner produces (`worktreePath`, and formerly a
+ * write-only `branchName`) belongs on the runner envelope `ISubagentJobStart`, not on a request that
+ * models what the CALLER asked for.
+ */
+type ISubagentSpawnRequest = Omit<IAgentBackgroundTaskRequest, 'kind'>;
+/**
+ * A subagent job result IS a background-task result, for the `'agent'` kind, minus the discriminant
+ * (ARCH-031, #2079). `kind` is fixed by the seam the same way `ISubagentSpawnRequest` fixes it on the
+ * request side — a subagent job is never a process/scheduled/tool-invocation task, so a caller of
+ * `ISubagentManager.wait` has no use for a field that can only ever read `'agent'` — so `wait()`
+ * strips it (`subagent-manager.ts`) rather than this alias ever carrying it.
+ *
+ * `IBackgroundTaskResult` is now discriminated by kind, so `IBackgroundTaskResult<'agent'>` is the
+ * exact agent-kind member: `exitCode`/`signalCode` (process-only; their sole producer is the shell
+ * runner, `agent-executor/src/background-tasks/runners/managed-shell-process-runner.ts`) are
+ * structurally absent rather than omitted by hand, and `usage` (agent-only) is carried without a
+ * separate key list to forget it from.
+ *
+ * `IBackgroundTaskState<'agent'>.result` is `IBackgroundTaskResult<'agent'>` too (#2079 discriminated
+ * the state hop the same way), so `state.kind === 'agent'` now narrows `state.result` there as well.
+ * This alias narrows at a seam where the kind is statically known instead — a subagent job never
+ * becomes a process task — which is why `ISubagentJobResult` exists as its own name rather than just
+ * reading `state.result` after a kind check everywhere a job result is needed.
+ */
+type ISubagentJobResult = Omit<IBackgroundTaskResult<'agent'>, 'kind'>;
+//#endregion
+//#region src/workspace-contracts.d.ts
+type TExecutionEntryKind = 'main_thread' | 'background_task' | 'background_group';
+type TExecutionWorkspaceStatus = 'active' | 'idle' | TBackgroundTaskStatus;
+type TExecutionAttention = 'none' | 'unread' | 'failed' | 'permission' | 'completed';
+type TExecutionWorkspaceVisibility = 'default' | 'collapsed';
+/**
+ * `attach` (CLI-1994) is offered on a `background_task` entry whose request carried a
+ * `resumeSessionId` — a forked conversation. Selecting it is a VIEW SWITCH onto that session record,
+ * not a merge: the parent and the fork stay separate records.
+ */
+type TExecutionControl = 'select' | 'cancel' | 'close' | 'send' | 'read_log' | 'wait' | 'attach';
+type TExecutionOriginKind = 'user_prompt' | 'slash_command' | 'model_command' | 'tool_call' | 'skill' | 'transport' | 'system';
+type TExecutionDetailRecordKind = 'message' | 'tool_activity' | 'process_output' | 'progress' | 'result' | 'error' | 'group_summary';
+type TExecutionWorkspaceUpdateCause = 'main_thread' | 'background_task' | 'background_group';
+/**
+ * SCREEN-1992 — the five-word normalization every surface renders beside the detailed `status`:
+ * `working` (queued/running/sleeping/active), `needs-input` (a parked prompt or a task waiting for
+ * permission), `completed`, `failed`, `stopped` (cancelled or paused — never reported as completed).
+ * Total over every `TExecutionWorkspaceStatus`; derived once by the projection, never re-derived.
+ */
+type TExecutionNormalizedState = 'working' | 'needs-input' | 'completed' | 'failed' | 'stopped';
+/** SCREEN-1992 — the row's one-line text: what it is doing, the question it is asking, or its result. */
+type TExecutionHeadlineKind = 'activity' | 'question' | 'result';
+interface IExecutionHeadline {
+  readonly kind: TExecutionHeadlineKind;
+  readonly text: string;
+}
+/** SCREEN-1992 — the prompt the main thread is parked on, so a surface can say what it is waiting for. */
+interface IExecutionPendingRequest {
+  readonly kind: 'permission' | 'ask';
+  readonly text: string;
+}
+interface IExecutionOrigin {
+  readonly kind: TExecutionOriginKind;
+  readonly sessionId: string;
+  readonly turnId?: string;
+  readonly commandName?: string;
+  readonly toolCallId?: string;
+  readonly skillId?: string;
+  readonly label?: string;
+}
+interface IExecutionWorkspaceEntry {
+  readonly id: string;
+  readonly sourceId: string;
+  readonly kind: TExecutionEntryKind;
+  readonly parentId?: string;
+  readonly groupId?: string;
+  readonly origin: IExecutionOrigin;
+  readonly taskKind?: TBackgroundTaskKind;
+  readonly status: TExecutionWorkspaceStatus;
+  readonly title: string;
+  readonly subtitle?: string;
+  readonly preview?: string;
+  readonly currentAction?: string;
+  readonly unread: boolean;
+  readonly attention: TExecutionAttention;
+  readonly visibility: TExecutionWorkspaceVisibility;
+  readonly updatedAt: string;
+  readonly controls: readonly TExecutionControl[];
+  /** CLI-1994: the forked session record an `attach` control switches the view onto. */
+  readonly resumeSessionId?: string;
+  /** SCREEN-1992: the normalized state word (see `TExecutionNormalizedState`). */
+  readonly state: TExecutionNormalizedState;
+  /** SCREEN-1992: the row's one-line text SSOT; `preview` stays the raw last output. */
+  readonly headline?: IExecutionHeadline;
+  /** SCREEN-1992: ISO time of a sleeping schedule's next fire, for a surface-side countdown. */
+  readonly nextFireAt?: string;
+}
+interface IExecutionWorkspaceFilter {
+  readonly includeMainThread?: boolean;
+  readonly kinds?: readonly TExecutionEntryKind[];
+  readonly visibility?: readonly TExecutionWorkspaceVisibility[];
+}
+interface IExecutionWorkspaceSnapshot {
+  readonly sessionId: string;
+  readonly selectedEntryId?: string;
+  readonly updatedAt: string;
+  readonly entries: readonly IExecutionWorkspaceEntry[];
+}
+interface IExecutionWorkspaceSnapshotOptions {
+  readonly selectedEntryId?: string;
+  readonly filter?: IExecutionWorkspaceFilter;
+}
+interface IExecutionWorkspaceEvent {
+  readonly type: 'execution_workspace_updated';
+  readonly cause: TExecutionWorkspaceUpdateCause;
+  readonly entryId?: string;
+  readonly snapshot: IExecutionWorkspaceSnapshot;
+}
+interface IExecutionDetailCursor {
+  readonly offset: number;
+}
+interface IExecutionDetailRecord {
+  readonly id: string;
+  readonly kind: TExecutionDetailRecordKind;
+  readonly text: string;
+  readonly timestamp?: string;
+  readonly sourceId?: string;
+}
+interface IExecutionDetailPage {
+  readonly entryId: string;
+  readonly cursor?: IExecutionDetailCursor;
+  readonly nextCursor?: IExecutionDetailCursor;
+  readonly records: readonly IExecutionDetailRecord[];
+}
+interface ICreateMainThreadEntryInput {
+  readonly sessionId: string;
+  readonly isExecuting: boolean;
+  readonly hasPendingPrompt: boolean;
+  readonly historyLength: number;
+  readonly updatedAt: string;
+  readonly preview?: string;
+  /** SCREEN-1992: the parked permission/ask the main thread is waiting on, when there is one. */
+  readonly pendingRequest?: IExecutionPendingRequest;
+}
+interface ICreateExecutionWorkspaceSnapshotInput {
+  readonly sessionId: string;
+  readonly mainThread: ICreateMainThreadEntryInput;
+  readonly tasks: readonly IBackgroundTaskState[];
+  readonly groups: readonly IBackgroundJobGroupState[];
+  readonly selectedEntryId?: string;
+  readonly filter?: IExecutionWorkspaceFilter;
+}
+interface IExecutionWorkspaceEntryRef {
+  readonly kind: TExecutionEntryKind;
+  readonly sourceId: string;
+}
+interface ICreateMainThreadDetailPageInput {
+  readonly entryId: string;
+  readonly history: readonly IHistoryEntry[];
+  readonly cursor?: IExecutionDetailCursor;
+  /** SCREEN-1992: a parked prompt leads the page so a peek shows the blocking question first. */
+  readonly pendingRequest?: IExecutionPendingRequest;
+}
+interface ICreateLineDetailPageInput {
+  readonly entryId: string;
+  readonly lines: readonly string[];
+  readonly cursor?: IBackgroundTaskLogCursor;
+  readonly nextCursor?: IBackgroundTaskLogCursor;
+  readonly kind?: TExecutionDetailRecordKind;
+}
+//#endregion
+export type { IAgentBackgroundTaskRequest, IAgentBackgroundTaskResult, IAgentBackgroundTaskState, IBackgroundJobGroupCreateRequest, IBackgroundJobGroupState, IBackgroundJobGroupSummary, IBackgroundJobResultEnvelope, IBackgroundTaskError, IBackgroundTaskInput, IBackgroundTaskListFilter, IBackgroundTaskLogCursor, IBackgroundTaskLogPage, IBackgroundTaskResult, IBackgroundTaskSchedule, IBackgroundTaskState, IBackgroundTaskUsage, IBaseBackgroundTaskRequest, ICreateExecutionWorkspaceSnapshotInput, ICreateLineDetailPageInput, ICreateMainThreadDetailPageInput, ICreateMainThreadEntryInput, IExecutionDetailCursor, IExecutionDetailPage, IExecutionDetailRecord, IExecutionHeadline, IExecutionOrigin, IExecutionPendingRequest, IExecutionWorkspaceEntry, IExecutionWorkspaceEntryRef, IExecutionWorkspaceEvent, IExecutionWorkspaceFilter, IExecutionWorkspaceSnapshot, IExecutionWorkspaceSnapshotOptions, IProcessBackgroundTaskRequest, IProcessBackgroundTaskResult, IProcessBackgroundTaskState, IScheduledBackgroundTaskRequest, IScheduledBackgroundTaskResult, IScheduledBackgroundTaskState, ISerializableProviderProfile, ISubagentJobResult, ISubagentJobState, ISubagentSpawnRequest, IToolInvocationBackgroundTaskRequest, IToolInvocationBackgroundTaskResult, IToolInvocationBackgroundTaskState, TBackgroundJobGroupEvent, TBackgroundJobGroupEventListener, TBackgroundJobGroupIdFactory, TBackgroundJobGroupStatus, TBackgroundJobWaitPolicy, TBackgroundPrimitive, TBackgroundTaskErrorCategory, TBackgroundTaskEvent, TBackgroundTaskEventListener, TBackgroundTaskIsolation, TBackgroundTaskKind, TBackgroundTaskMode, TBackgroundTaskRequest, TBackgroundTaskResult, TBackgroundTaskState, TBackgroundTaskStatus, TBackgroundTaskTimeoutReason, TExecutionAttention, TExecutionControl, TExecutionDetailRecordKind, TExecutionEntryKind, TExecutionHeadlineKind, TExecutionNormalizedState, TExecutionOriginKind, TExecutionWorkspaceStatus, TExecutionWorkspaceUpdateCause, TExecutionWorkspaceVisibility, TSubagentJobMode, TSubagentJobStatus };
+//# sourceMappingURL=index.d.cts.map

package/dist/node/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/background-task-contracts.ts","../../src/background-group-contracts.ts","../../src/subagent-contracts.ts","../../src/workspace-contracts.ts"],"mappings":"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"}