@tangle-network/sandbox 0.8.3-develop.20260623071657.8f265f2 → 0.8.3-develop.20260623083050.fc79e13

package/dist/{sandbox-BaK5AyL2.d.ts → sandbox-D4JNrUuc.d.ts}

@@ -937,13 +937,77 @@ interface InstalledTool {
 /**
  * Result of an agent prompt.
  */
+/**
+ * Granular outcome of an agent run.
+ * - `success` — reached a terminal event with no run-level error and no failed
+ *   tool. A tool-only turn (no text) succeeds.
+ * - `failed` — a run-level error event, or any failed (`isError`) tool, or the
+ *   stream ended with no terminal event.
+ * - `blocked_on_approval` — a tool hit a hub approval gate; resolve it, then
+ *   re-run. See {@link AgentApprovalRequirement}.
+ * - `awaiting_question` — the agent asked a question and the turn ended without
+ *   an answer. See {@link AgentQuestionRequest}.
+ */
+type AgentRunStatus = "success" | "failed" | "blocked_on_approval" | "awaiting_question";
+/**
+ * A tool the agent invoked during a run. `isError` flags a failed call
+ * (errored, timed out, or rejected — e.g. a hub approval gate). Failed tools
+ * are recorded, not dropped, so callers can inspect what the agent attempted.
+ */
+interface AgentToolInvocation {
+  toolName: string;
+  input?: unknown;
+  result?: unknown;
+  isError?: boolean;
+}
+/**
+ * A hub approval gate the agent hit mid-run. Present on a result when
+ * `status === "blocked_on_approval"`. Approve with the CLI
+ * (`tangle hub approvals approve <approvalId>`) or the hub SDK, then re-run.
+ */
+interface AgentApprovalRequirement {
+  /**
+   * Approval id to act on. `undefined` when the in-sandbox hub bridge did not
+   * preserve the structured approval object — surfaced honestly rather than
+   * invented; inspect `message` in that case.
+   */
+  approvalId?: string;
+  /** Hub connection the gated tool belongs to, when known. */
+  connectionId?: string;
+  /** The tool error message that surfaced the gate. */
+  message?: string;
+}
+/**
+ * A question the agent asked mid-run. Present on a result when
+ * `status === "awaiting_question"`. Answer via
+ * `box.session(id).answer({ [questionId]: [...selected] })`, then re-run.
+ */
+interface AgentQuestionRequest {
+  /** Question id to pass to `session.answer`. */
+  questionId: string;
+  /** The questions payload the agent emitted (prompt + options per entry). */
+  questions: unknown;
+}
 interface PromptResult {
-  /** Whether the prompt completed successfully */
+  /**
+   * Whether the run succeeded. Shorthand for `status === "success"`: true only
+   * when the run reached a terminal event with no run-level error and no failed
+   * tool. (Text presence is no longer part of this — a tool-only turn
+   * succeeds.)
+   */
   success: boolean;
+  /** Granular run outcome. */
+  status: AgentRunStatus;
   /** Agent's response text */
   response?: string;
-  /** Error message if failed */
+  /** Error message when the run did not succeed */
   error?: string;
+  /** Tool calls the agent made this run, including failures (`isError`). */
+  toolInvocations?: AgentToolInvocation[];
+  /** Set when `status === "blocked_on_approval"`. */
+  approval?: AgentApprovalRequirement;
+  /** Set when `status === "awaiting_question"`. */
+  question?: AgentQuestionRequest;
   /** Trace ID for debugging */
   traceId?: string;
   /** Duration in milliseconds */
@@ -1251,6 +1315,15 @@ interface WaitForOptions {
    */
   onProgress?: (event: ProvisionEvent) => void;
 }
+/**
+ * Options for resuming a stopped sandbox.
+ */
+interface ResumeOptions {
+  /** Timeout in milliseconds for the resume request */
+  timeoutMs?: number;
+  /** AbortSignal for cancellation */
+  signal?: AbortSignal;
+}
 /**
  * Usage information for the account.
  */
@@ -4577,12 +4650,26 @@ declare class SandboxInstance {
    * Stream events from an agent prompt.
    * Use this for real-time updates during agent execution.
    *
+   * Guarantees a terminal event on every non-cancelled path: a clean run
+   * ends with the runtime's `result`/`done`; a failure (pre-stream HTTP
+   * error, mid-stream network drop, timeout, or reconnect exhaustion) is
+   * surfaced as an in-band `error` event followed by a synthetic `done`,
+   * never a thrown generator. Caller-initiated cancellation (aborting
+   * `options.signal`) ends the stream silently with no synthetic terminal.
+   *
    * Automatically reconnects via the runtime event replay endpoint if the
-   * SSE stream drops before a terminal event (`result` or `done`) is received.
-   * Reconnection is transparent — replayed events that were already yielded
-   * (based on event ID tracking) are deduplicated.
+   * SSE stream drops before a terminal event (`result` or `done`) is
+   * received. Reconnection is transparent — replayed events that were
+   * already yielded (based on event ID tracking) are deduplicated.
    */
   streamPrompt(message: string | PromptInputPart[], options?: PromptOptions): AsyncGenerator<SandboxEvent>;
+  /**
+   * Inner prompt stream: opens the SSE connection and reconnects on silent
+   * drops. May throw (pre-stream HTTP error, timeout, reconnect exhausted);
+   * the public `streamPrompt` wrapper converts those throws into a terminal
+   * `error` + `done` so callers never see a thrown generator.
+   */
+  private streamPromptInner;
   /**
    * Stream sandbox lifecycle and activity events.
    */
@@ -5133,7 +5220,7 @@ declare class SandboxInstance {
   /**
    * Resume a stopped sandbox.
    */
-  resume(): Promise<void>;
+  resume(options?: ResumeOptions): Promise<void>;
   /**
    * Delete the sandbox permanently.
    */