@agentex/agent 0.0.31 → 0.0.33

package/src/types.ts

@@ -63,6 +63,13 @@ export interface ProviderCapabilities {
    * process — the model is not involved.
    */
   stopTask: boolean;
+  /**
+   * Provider emits first-class `background_task` StreamEvents for work that
+   * can outlive the root turn, such as async subagents and backgrounded
+   * processes. Absent/false means callers must not infer task lifecycle from
+   * provider-specific `unknown` events.
+   */
+  backgroundTaskEvents?: boolean;
   /**
    * Provider exposes selectable operating modes via `listModes()` — e.g. Codex
    * collaboration modes, Copilot's allow-all/agent/plan. When `false`,
@@ -985,6 +992,21 @@ export interface BaseStreamEventFields {
   raw: Record<string, unknown>;
 }
 
+/** Provider-neutral category for work that may outlive its launching turn. */
+export type BackgroundTaskType = "subagent" | "process" | "unknown";
+
+/** Lifecycle edge represented by one `background_task` StreamEvent. */
+export type BackgroundTaskPhase = "started" | "progress" | "completed";
+
+/** Current normalized state carried by a `background_task` event. */
+export type BackgroundTaskStatus =
+  | "pending"
+  | "running"
+  | "paused"
+  | "completed"
+  | "failed"
+  | "stopped";
+
 /**
  * Categorical reason for an `auth_required` event. Derived from the
  * provider's user-facing error text. Stable across providers — new
@@ -1037,7 +1059,12 @@ export type StreamEvent =
       slashCommands?: string[];
       skills?: string[];
     } & BaseStreamEventFields)
-  | ({ type: "assistant"; text: string } & BaseStreamEventFields)
+  | ({
+      type: "assistant";
+      text: string;
+      /** Codex message role within a turn. Omitted by other providers and older wire formats. */
+      phase?: "commentary" | "final_answer";
+    } & BaseStreamEventFields)
   | ({
       /**
        * Incremental assistant text (typewriter). Only emitted when
@@ -1171,6 +1198,26 @@ export type StreamEvent =
       tokenBudget?: number;
       iterations?: number;
     } & BaseStreamEventFields)
+  /**
+   * Lifecycle for work that is independent from the root turn. In particular,
+   * `phase: "completed"` settles only this task. It is never a root turn
+   * result and must not be used to resolve `SendHandle.result`.
+   *
+   * Events are reducer-friendly snapshots. `status` is always populated,
+   * while description/summary may be null when the provider did not report
+   * them. `parentTaskId` identifies a nested background task when that lineage
+   * is available.
+   */
+  | ({
+      type: "background_task";
+      taskId: string;
+      taskType: BackgroundTaskType;
+      phase: BackgroundTaskPhase;
+      status: BackgroundTaskStatus;
+      description: string | null;
+      summary: string | null;
+      parentTaskId: string | null;
+    } & BaseStreamEventFields)
   | ({
       type: "result";
       text: string;