@zhivex-ai/core 0.19.0 → 1.0.0

package/dist/types.d.ts

@@ -152,6 +152,119 @@ export interface ToolExecutionOptions {
     timeoutMs?: number;
     stopOnError?: boolean;
 }
+export type ToolApprovalMode = "policy" | "interrupt";
+export interface ToolApprovalSigner {
+    sign(payload: string): string | Promise<string>;
+    verify?(payload: string, signature: string): boolean | Promise<boolean>;
+}
+export interface ToolGuardrailTrigger {
+    triggered: true;
+    reason?: string;
+    metadata?: Record<string, JsonValue>;
+}
+export interface ToolRuntimeContext<TContext = any> {
+    context?: TContext;
+    /** Durable run that owns this execution, when invoked by the agent runtime. */
+    runId?: string;
+    agentId?: string;
+    scope?: AgentStoreScope;
+    metadata?: Record<string, JsonValue>;
+    /** Acquired execution boundary for this run. Callbacks and secrets are never persisted. */
+    executionEnvironment?: AgentExecutionEnvironmentSession<TContext>;
+}
+export type AgentExecutionEnvironmentBackend = "host" | "process" | "container" | "microvm" | "remote" | "custom";
+export interface AgentExecutionEnvironmentManifest {
+    schemaVersion: 1;
+    id: string;
+    version?: string;
+    backend: AgentExecutionEnvironmentBackend;
+    assurance: "best-effort" | "enforced";
+    isolation: "shared" | "per-run" | "per-tool-call";
+    workspace?: {
+        id?: string;
+        root: string;
+        cwd?: string;
+        access: "read-only" | "read-write";
+        followSymlinks?: boolean;
+        readablePaths?: string[];
+        writablePaths?: string[];
+    };
+    permissions?: {
+        undeclaredTools?: "allow" | "deny";
+        filesystem?: "deny" | "read-only" | "read-write";
+        network?: {
+            mode: "deny" | "allowlist";
+            allowedDomains?: string[];
+            allowedPorts?: number[];
+            allowPrivateNetworks?: boolean;
+        };
+        process?: {
+            shell: "deny" | "allowlist" | "allow";
+            allowedCommands?: string[];
+        };
+        environment?: {
+            inheritedVariables?: string[];
+        };
+    };
+    limits?: {
+        maxProcessRuntimeMs?: number;
+        maxProcessOutputBytes?: number;
+        maxConcurrentProcesses?: number;
+        maxMemoryMb?: number;
+        maxWorkspaceBytes?: number;
+        maxFileWriteBytes?: number;
+        maxNetworkRequests?: number;
+        maxNetworkBytes?: number;
+    };
+    metadata?: Record<string, JsonValue>;
+}
+export interface AgentExecutionEnvironmentBinding {
+    environmentId: string;
+    environmentVersion?: string;
+    fingerprint: string;
+    workspaceId?: string;
+}
+export interface AgentExecutionEnvironmentAcquireRequest<TContext = any> {
+    runId: string;
+    agentId?: string;
+    scope?: AgentStoreScope;
+    context?: TContext;
+    metadata?: Record<string, JsonValue>;
+    abortSignal?: AbortSignal;
+}
+export interface AgentExecutionAuthorizationRequest<TContext = any> {
+    manifest: AgentExecutionEnvironmentManifest;
+    binding: AgentExecutionEnvironmentBinding;
+    tool: ToolDefinition;
+    toolCall: ToolCall;
+    input: unknown;
+    context: ToolExecutionContext<TContext>;
+    phase: "preflight" | "execute";
+}
+export type AgentExecutionAuthorizationDecision = {
+    decision: "allow";
+    metadata?: Record<string, JsonValue>;
+} | {
+    decision: "deny";
+    reason: string;
+    metadata?: Record<string, JsonValue>;
+};
+export interface AgentExecutionEnvironmentSession<TContext = any> {
+    readonly manifest: AgentExecutionEnvironmentManifest;
+    readonly binding: AgentExecutionEnvironmentBinding;
+    authorize(request: AgentExecutionAuthorizationRequest<TContext>): AgentExecutionAuthorizationDecision | Promise<AgentExecutionAuthorizationDecision>;
+    execute<TResult>(request: AgentExecutionAuthorizationRequest<TContext>, operation: () => TResult | Promise<TResult>): TResult | Promise<TResult>;
+    release?(result: {
+        status: AgentStatus;
+        error?: {
+            message: string;
+        };
+    }): void | Promise<void>;
+}
+export interface AgentExecutionEnvironment<TContext = any> {
+    readonly manifest: AgentExecutionEnvironmentManifest;
+    acquire(request: AgentExecutionEnvironmentAcquireRequest<TContext>): AgentExecutionEnvironmentSession<TContext> | Promise<AgentExecutionEnvironmentSession<TContext>>;
+}
 export interface StructuredOutputConfig<TSchema extends ZodTypeAny = ZodTypeAny> {
     schema: TSchema;
     mode: StructuredOutputMode;
@@ -177,6 +290,10 @@ export interface StreamToolResultEvent {
     type: "tool-result";
     toolResult: ToolExecutionResult;
 }
+export interface StreamToolApprovalRequestEvent {
+    type: "tool-approval-request";
+    approval: AgentApprovalRequest;
+}
 export interface StreamProviderDataEvent {
     type: "provider-data";
     provider: string;
@@ -201,7 +318,7 @@ export interface StreamErrorEvent {
     type: "error";
     error: Error;
 }
-export type StreamEvent = StreamTextDeltaEvent | StreamToolCallEvent | StreamToolResultEvent | StreamProviderDataEvent | StreamImageGenerationEvent | StreamFinishEvent | StreamErrorEvent;
+export type StreamEvent = StreamTextDeltaEvent | StreamToolCallEvent | StreamToolResultEvent | StreamToolApprovalRequestEvent | StreamProviderDataEvent | StreamImageGenerationEvent | StreamFinishEvent | StreamErrorEvent;
 export interface AgentRunStartEvent {
     type: "agent-run-start";
     currentStep: number;
@@ -223,12 +340,16 @@ export interface AgentApprovalResolvedEvent {
     type: "agent-approval-resolved";
     approval: AgentApprovalResponse;
 }
+export interface AgentCompactionEvent {
+    type: "agent-compaction";
+    compaction: AgentCompactionRecord;
+}
 export interface AgentRunFinishEvent {
     type: "agent-run-finish";
     status: AgentStatus;
     state: AgentRunState;
 }
-export type AgentStreamEvent = StreamEvent | AgentRunStartEvent | AgentStepStartEvent | AgentStepFinishEvent | AgentApprovalRequestEvent | AgentApprovalResolvedEvent | AgentRunFinishEvent;
+export type AgentStreamEvent = StreamEvent | AgentRunStartEvent | AgentStepStartEvent | AgentStepFinishEvent | AgentApprovalRequestEvent | AgentApprovalResolvedEvent | AgentCompactionEvent | AgentRunFinishEvent;
 export interface StreamObjectDeltaEvent {
     type: "object-delta";
     textDelta: string;
@@ -896,26 +1017,46 @@ export interface ProviderAdapter {
     predictionModel?: (modelId: string) => PredictionModel;
 }
 export type CallableProviderAdapter = ProviderAdapter & ((modelId: string) => LanguageModel);
-export interface ToolDefinition<TSchema extends ZodTypeAny = ZodTypeAny, TResult = JsonValue> {
+export interface ToolDefinition<TSchema extends ZodTypeAny = any, TResult = JsonValue, TContext = any> {
     name: string;
     description?: string;
     schema: TSchema;
     metadata?: Record<string, JsonValue>;
     requiresApproval?: boolean;
-    execute: (input: z.infer<TSchema>, context?: ToolExecutionContext) => Promise<TResult> | TResult;
-}
-export interface ToolExecutionContext {
+    /**
+     * "policy" preserves the immediate allow/deny policy behavior. "interrupt"
+     * creates a resumable local approval request before any tool side effect.
+     */
+    approvalMode?: ToolApprovalMode;
+    /** Bump when approval-relevant tool behavior changes so stale approvals cannot be replayed. */
+    approvalVersion?: string;
+    isEnabled?: (input: z.infer<TSchema>, context: ToolExecutionContext<TContext>) => boolean | Promise<boolean>;
+    inputGuardrails?: ToolInputGuardrail<TSchema, TContext>[];
+    outputGuardrails?: ToolOutputGuardrail<TSchema, TResult, TContext>[];
+    onError?: ToolErrorHandler<TSchema, TResult, TContext>;
+    execute: (input: z.infer<TSchema>, context?: ToolExecutionContext<TContext>) => Promise<TResult> | TResult;
+}
+export interface ToolExecutionContext<TContext = any> extends ToolRuntimeContext<TContext> {
     abortSignal?: AbortSignal;
     toolCall: ToolCall;
     step: number;
     model: LanguageModel | RealtimeModel;
-    /** Durable run that owns this execution, when invoked by the agent runtime. */
-    runId?: string;
     /** Forward this key to side-effecting APIs to make retries externally idempotent. */
     idempotencyKey?: string;
     request?: ModelGenerateInput;
     realtimeConfig?: RealtimeSessionConfig;
 }
+export interface ToolInputGuardrailRequest<TSchema extends ZodTypeAny = any, TContext = any> {
+    tool: ToolDefinition;
+    input: z.infer<TSchema>;
+    context: ToolExecutionContext<TContext>;
+}
+export interface ToolOutputGuardrailRequest<TSchema extends ZodTypeAny = any, TResult = JsonValue, TContext = any> extends ToolInputGuardrailRequest<TSchema, TContext> {
+    output: TResult;
+}
+export type ToolInputGuardrail<TSchema extends ZodTypeAny = any, TContext = any> = (request: ToolInputGuardrailRequest<TSchema, TContext>) => ToolGuardrailTrigger | void | Promise<ToolGuardrailTrigger | void>;
+export type ToolOutputGuardrail<TSchema extends ZodTypeAny = any, TResult = JsonValue, TContext = any> = (request: ToolOutputGuardrailRequest<TSchema, TResult, TContext>) => ToolGuardrailTrigger | void | Promise<ToolGuardrailTrigger | void>;
+export type ToolErrorHandler<TSchema extends ZodTypeAny = any, TResult = JsonValue, TContext = any> = (error: Error, request: ToolInputGuardrailRequest<TSchema, TContext>) => TResult | void | Promise<TResult | void>;
 export type HostedToolClass = "web-search" | "file-search" | "remote-mcp" | "computer-use" | "code-execution" | "shell" | "apply-patch" | "tool-search" | "web-extraction" | "skill" | "toolset" | "custom";
 export interface HostedToolDefinition<TConfig extends JsonValue = JsonValue> {
     kind: "hosted";
@@ -927,7 +1068,7 @@ export interface HostedToolDefinition<TConfig extends JsonValue = JsonValue> {
     requiresApproval?: boolean;
     metadata?: Record<string, JsonValue>;
 }
-export type AnyToolDefinition = ToolDefinition | HostedToolDefinition;
+export type AnyToolDefinition = ToolDefinition<any, any, any> | HostedToolDefinition;
 export type ToolSet = Record<string, AnyToolDefinition>;
 export interface ToolRegistryLike {
     get(name: string): AnyToolDefinition | undefined;
@@ -936,17 +1077,20 @@ export interface ToolRegistryLike {
     toToolSet(): ToolSet;
 }
 export type ToolCollection = ToolSet | ToolRegistryLike;
-export interface ToolApprovalRequest {
+export interface ToolApprovalRequest<TContext = any> {
     toolCall: ToolCall;
     tool: ToolDefinition;
     input: JsonValue;
     step: number;
     model: LanguageModel | RealtimeModel;
     request?: ModelGenerateInput;
+    executionContext?: ToolExecutionContext<TContext>;
     realtimeConfig?: RealtimeSessionConfig;
 }
 export interface ToolApprovalDecision {
     approved: boolean;
+    /** Requests resumable human approval instead of treating approved:false as a final denial. */
+    approvalRequired?: boolean;
     reason?: string;
     metadata?: Record<string, JsonValue>;
 }
@@ -954,17 +1098,26 @@ export interface ToolApprovalEvent {
     request: ToolApprovalRequest;
     decision: ToolApprovalDecision;
 }
-export type ToolApprovalPolicy = (request: ToolApprovalRequest) => ToolApprovalDecision | boolean | Promise<ToolApprovalDecision | boolean>;
+export type ToolApprovalPolicy<TContext = any> = (request: ToolApprovalRequest<TContext>) => ToolApprovalDecision | boolean | Promise<ToolApprovalDecision | boolean>;
 export type ToolApprovalObserver = (event: ToolApprovalEvent) => void | Promise<void>;
 export type ProviderOptionsOf<TModel extends LanguageModel> = TModel extends LanguageModel<infer TProviderOptions> ? TProviderOptions : ProviderOptions;
-export type GenerateTextOptions<TModel extends LanguageModel = LanguageModel> = RetryOptions & GenerateInputSource & {
+export type GenerateTextOptions<TModel extends LanguageModel = LanguageModel, TContext = unknown> = RetryOptions & GenerateInputSource & {
     model: TModel;
     system?: string;
     tools?: ToolCollection;
     toolChoice?: ToolChoice;
     toolExecution?: ToolExecutionOptions;
-    toolApprovalPolicy?: ToolApprovalPolicy;
+    toolApprovalPolicy?: ToolApprovalPolicy<TContext>;
+    toolApprovalSigner?: ToolApprovalSigner;
+    /** Resolved local approvals supplied by a durable agent runtime. */
+    toolApprovalResolutions?: AgentApprovalResolution[];
+    toolContext?: ToolRuntimeContext<TContext>;
     onToolApprovalDecision?: ToolApprovalObserver;
+    /** Durable runtimes may replace the active context before each provider request. */
+    prepareModelMessages?: (context: {
+        messages: readonly ModelMessage[];
+        step: number;
+    }) => ModelMessage[] | undefined | Promise<ModelMessage[] | undefined>;
     /** Called immediately before each model request. Throw to stop the loop. */
     onBeforeModelStep?: (context: {
         request: ModelGenerateInput;
@@ -982,6 +1135,7 @@ export type GenerateTextOptions<TModel extends LanguageModel = LanguageModel> =
         response: GenerateResult;
         step: number;
         toolCalls: ToolCall[];
+        approvalRequests: AgentApprovalRequest[];
     }) => void | Promise<void>;
     /** Durable runtimes use this hook to checkpoint tool results before the next model request. */
     onToolExecutionComplete?: (context: {
@@ -1010,6 +1164,8 @@ export interface GenerateTextOutput {
     steps: GenerateTextStep[];
     messages: ModelMessage[];
     toolResults: ToolExecutionResult[];
+    /** Local resumable approval requests produced before any tool in the batch executes. */
+    approvalRequests?: AgentApprovalRequest[];
 }
 export type AgentStatus = "queued" | "running" | "completed"
 /**
@@ -1020,6 +1176,10 @@ export type AgentStepStatus = "running" | "completed" | "suspended" | "waiting_a
 export interface AgentRunPolicy {
     timeoutMs?: number;
     onTimeout?: "fail" | "cancel-requested";
+    /** Explicit migration escape hatch for pre-fingerprint durable states. */
+    allowLegacyHarnessResume?: boolean;
+    /** Explicit migration escape hatch for states created before environment binding. */
+    allowLegacyExecutionEnvironmentResume?: boolean;
     /** Disable only for stores that intentionally provide CAS without worker leases. */
     leaseMode?: "required" | "disabled";
     /** Duration of the exclusive worker lease. Defaults to 30 seconds. */
@@ -1043,6 +1203,57 @@ export interface AgentRunPolicy {
         includeChildRuns?: boolean;
     };
 }
+export type AgentCompactionReason = "message-count" | "estimated-input-tokens";
+export interface AgentCompactionRequest<TContext = any> {
+    runId: string;
+    agentId?: string;
+    scope?: AgentStoreScope;
+    beforeStep: number;
+    context?: TContext;
+    /** Historical prefix being summarized. System messages are never included. */
+    messages: ModelMessage[];
+    /** Literal tail preserved after the summary. */
+    retainedMessages: ModelMessage[];
+    reasons: AgentCompactionReason[];
+    estimatedTokensBefore: number;
+    sourceDigest: string;
+    idempotencyKey: string;
+    metadata?: Record<string, JsonValue>;
+    abortSignal?: AbortSignal;
+}
+export interface AgentCompactionResult {
+    summary: string;
+    usage?: TokenUsage;
+    metadata?: Record<string, JsonValue>;
+}
+export type AgentCompactor<TContext = any> = (request: AgentCompactionRequest<TContext>) => AgentCompactionResult | Promise<AgentCompactionResult>;
+export interface AgentCompactionOptions<TContext = any> {
+    /** Compaction runs when either configured threshold is exceeded. */
+    maxMessages?: number;
+    maxEstimatedInputTokens?: number;
+    /** Literal non-system tail retained after compaction. Defaults to 8 messages. */
+    keepRecentMessages?: number;
+    estimateTokens?: (messages: readonly ModelMessage[]) => number;
+    compactor: AgentCompactor<TContext>;
+}
+export interface AgentCompactionRecord {
+    id: string;
+    beforeStep: number;
+    createdAt: number;
+    reasons: AgentCompactionReason[];
+    sourceDigest: string;
+    resultDigest: string;
+    summaryDigest: string;
+    summary: string;
+    messageCountBefore: number;
+    messageCountAfter: number;
+    compactedMessageCount: number;
+    retainedMessageCount: number;
+    estimatedTokensBefore: number;
+    estimatedTokensAfter: number;
+    usage?: TokenUsage;
+    metadata?: Record<string, JsonValue>;
+}
 export interface AgentStepRequest {
     /** Index in the full conversation where this incremental snapshot begins. */
     messageOffset?: number;
@@ -1081,6 +1292,7 @@ export interface AgentChildRun {
     agentId?: string;
     parentRunId?: string;
     toolName?: string;
+    toolCallId?: string;
     status: AgentStatus;
     outputText: string;
     steps: number;
@@ -1093,6 +1305,15 @@ export interface AgentChildRun {
         message: string;
     };
     metadata?: Record<string, JsonValue>;
+    /** Durable child state retained only while the parent must resume a child approval. */
+    resumeState?: AgentRunState;
+}
+export interface AgentHarnessBinding {
+    schemaVersion: 1;
+    id: string;
+    version: string;
+    fingerprint: string;
+    algorithm: "sha256";
 }
 export interface AgentRunState {
     schemaVersion: 1;
@@ -1109,6 +1330,8 @@ export interface AgentRunState {
     parentRunId?: string;
     provider: string;
     modelId: string;
+    harness?: AgentHarnessBinding;
+    executionEnvironment?: AgentExecutionEnvironmentBinding;
     status: AgentStatus;
     messages: ModelMessage[];
     steps: AgentStep[];
@@ -1116,11 +1339,15 @@ export interface AgentRunState {
     currentStep: number;
     maxSteps: number;
     outputText: string;
+    finalOutput?: JsonValue;
+    outputMode?: Exclude<StructuredOutputMode, "auto">;
     finishReason?: FinishReason;
     providerFinishReason?: string;
     usage?: TokenUsage;
     pendingApprovals: AgentApprovalRequest[];
+    approvalHistory?: AgentApprovalResolution[];
     childRuns?: AgentChildRun[];
+    compactions?: AgentCompactionRecord[];
     metadata?: Record<string, JsonValue>;
     handoff?: AgentHandoff;
     startedAt?: number;
@@ -1360,22 +1587,24 @@ export interface AgentGuardrailTrigger {
     reason?: string;
     metadata?: Record<string, JsonValue>;
 }
-export interface AgentInputGuardrailRequest {
+export interface AgentInputGuardrailRequest<TContext = any> {
     runId: string;
     agentId?: string;
+    context?: TContext;
     state: AgentRunState;
     messages: ModelMessage[];
     metadata?: Record<string, JsonValue>;
 }
-export interface AgentOutputGuardrailRequest {
+export interface AgentOutputGuardrailRequest<TContext = any, TOutput = any> {
     runId: string;
     agentId?: string;
+    context?: TContext;
     state: AgentRunState;
-    output: AgentRunOutput | LiveAgentRunOutput;
+    output: AgentRunOutput<TOutput> | LiveAgentRunOutput;
     metadata?: Record<string, JsonValue>;
 }
-export type AgentInputGuardrail = (request: AgentInputGuardrailRequest) => AgentGuardrailTrigger | void | Promise<AgentGuardrailTrigger | void>;
-export type AgentOutputGuardrail = (request: AgentOutputGuardrailRequest) => AgentGuardrailTrigger | void | Promise<AgentGuardrailTrigger | void>;
+export type AgentInputGuardrail<TContext = any> = (request: AgentInputGuardrailRequest<TContext>) => AgentGuardrailTrigger | void | Promise<AgentGuardrailTrigger | void>;
+export type AgentOutputGuardrail<TContext = any, TOutput = any> = (request: AgentOutputGuardrailRequest<TContext, TOutput>) => AgentGuardrailTrigger | void | Promise<AgentGuardrailTrigger | void>;
 export interface AgentTelemetryGuardrailTriggeredEvent {
     type: "guardrail-triggered";
     runId: string;
@@ -1432,21 +1661,31 @@ export interface AgentHookFailurePolicy {
     memory?: AgentHookFailureMode;
     onError?: (event: AgentOperationalError) => void | Promise<void>;
 }
-export interface AgentDefinition<TModel extends LanguageModel = LanguageModel> {
+export interface AgentDefinition<TModel extends LanguageModel = LanguageModel, TContext = any, TOutput = any> {
     id?: string;
     model: TModel;
     instructions?: string;
+    contextSchema?: z.ZodType<TContext>;
     tools?: ToolCollection;
     maxSteps?: number;
     temperature?: number;
     maxTokens?: number;
     reasoning?: ReasoningConfig;
+    outputSchema?: z.ZodType<TOutput>;
+    outputMode?: StructuredOutputMode;
+    outputName?: string;
+    outputDescription?: string;
     toolExecution?: ToolExecutionOptions;
-    toolApprovalPolicy?: ToolApprovalPolicy;
-    inputGuardrails?: AgentInputGuardrail[];
-    outputGuardrails?: AgentOutputGuardrail[];
+    toolApprovalPolicy?: ToolApprovalPolicy<TContext>;
+    toolApprovalSigner?: ToolApprovalSigner;
+    inputGuardrails?: AgentInputGuardrail<TContext>[];
+    outputGuardrails?: AgentOutputGuardrail<TContext, TOutput>[];
     providerOptions?: ProviderOptionsOf<TModel>;
     subagents?: AgentSubAgentDefinition[];
+    /** Immutable identity of the capsule/spec that owns durable resume semantics. */
+    harness?: AgentHarnessBinding;
+    executionEnvironment?: AgentExecutionEnvironment<TContext>;
+    compaction?: AgentCompactionOptions<TContext>;
     policy?: AgentRunPolicy;
     metadata?: Record<string, JsonValue>;
     store?: AgentRunStore;
@@ -1471,11 +1710,21 @@ export interface LiveAgentDefinition<TModel extends RealtimeModel = RealtimeMode
     onTelemetryEvent?: AgentTelemetryObserver;
 }
 export interface AgentApprovalRequest {
+    /** Absent on legacy persisted states and treated as "provider". */
+    kind?: "provider" | "local-tool" | "subagent";
     provider: string;
     id: string;
     name: string;
     arguments: string;
     serverLabel?: string;
+    toolCallId?: string;
+    step?: number;
+    inputDigest?: string;
+    toolVersion?: string;
+    signature?: string;
+    childRunId?: string;
+    childAgentId?: string;
+    childApprovalRequestId?: string;
     rawData: JsonValue;
 }
 export interface AgentApprovalResponse {
@@ -1485,11 +1734,29 @@ export interface AgentApprovalResponse {
     id?: string;
     reason?: string;
 }
-export type AgentRunInput<TModel extends LanguageModel = LanguageModel> = RetryOptions & GenerateInputSource & {
+export interface AgentApprovalResolution {
+    requestId: string;
+    kind: "provider" | "local-tool" | "subagent";
+    provider: string;
+    approve: boolean;
+    reason?: string;
+    toolCallId?: string;
+    step?: number;
+    inputDigest?: string;
+    toolVersion?: string;
+    signature?: string;
+    childRunId?: string;
+    childAgentId?: string;
+    childApprovalRequestId?: string;
+    resolvedAt: number;
+}
+export type AgentRunInput<TModel extends LanguageModel = LanguageModel, TContext = any> = RetryOptions & GenerateInputSource & {
     runId?: string;
     /** Required isolation boundary for shared durable stores and memory. */
     scope?: AgentStoreScope;
     idempotencyKey?: string;
+    /** Ephemeral application context. Callers must provide it again when resuming a run. */
+    context?: TContext;
     state?: AgentRunState;
     approvals?: AgentApprovalResponse[];
     handoff?: AgentHandoff;
@@ -1498,7 +1765,10 @@ export type AgentRunInput<TModel extends LanguageModel = LanguageModel> = RetryO
     tools?: ToolCollection;
     toolChoice?: ToolChoice;
     toolExecution?: ToolExecutionOptions;
-    toolApprovalPolicy?: ToolApprovalPolicy;
+    toolApprovalPolicy?: ToolApprovalPolicy<TContext>;
+    executionEnvironment?: AgentExecutionEnvironment<TContext>;
+    /** Pass false to disable the agent default for this invocation. */
+    compaction?: AgentCompactionOptions<TContext> | false;
     maxSteps?: number;
     temperature?: number;
     maxTokens?: number;
@@ -1507,9 +1777,10 @@ export type AgentRunInput<TModel extends LanguageModel = LanguageModel> = RetryO
     policy?: AgentRunPolicy;
     metadata?: Record<string, JsonValue>;
 };
-export interface AgentRunOutput {
+export interface AgentRunOutput<TOutput = unknown> {
     status: AgentStatus;
     outputText: string;
+    finalOutput?: TOutput;
     finishReason?: FinishReason;
     providerFinishReason?: string;
     usage?: TokenUsage;
@@ -1575,6 +1846,8 @@ export interface PrepareSubagentsForAgentOptions {
     onTelemetryEvent?: AgentTelemetryObserver;
     toolApprovalPolicy?: ToolApprovalPolicy;
     toolExecution?: ToolExecutionOptions;
+    executionEnvironment?: AgentExecutionEnvironment;
+    compaction?: AgentCompactionOptions;
     metadata?: Record<string, JsonValue>;
 }
 export type LiveAgentRunInput = GenerateInputSource & RetryOptions & {
@@ -1599,10 +1872,10 @@ export interface LiveAgentRunOutput {
         message: string;
     };
 }
-export interface AgentStreamResult {
+export interface AgentStreamResult<TOutput = unknown> {
     eventStream: AsyncIterable<AgentStreamEvent>;
     textStream: AsyncIterable<string>;
-    collect: () => Promise<AgentRunOutput>;
+    collect: () => Promise<AgentRunOutput<TOutput>>;
 }
 export type AgentLiveEvent = AgentStreamEvent | RealtimeEvent;
 export interface AgentLiveStreamResult {
@@ -1930,6 +2203,12 @@ export interface UIMessageToolResultChunk {
     role: "tool";
     toolResult: ToolExecutionResult;
 }
+export interface UIMessageToolApprovalRequestChunk {
+    type: "tool-approval-request";
+    messageId: string;
+    role: "assistant";
+    approval: AgentApprovalRequest;
+}
 export interface UIMessageProviderDataChunk {
     type: "provider-data";
     messageId: string;
@@ -1937,6 +2216,25 @@ export interface UIMessageProviderDataChunk {
     provider: string;
     data: JsonValue;
 }
+export interface UIMessageGeneratedMedia {
+    data?: string;
+    encoding?: "base64";
+    uri?: string;
+    mediaType: string;
+    text?: string;
+    providerMetadata?: Record<string, JsonValue>;
+}
+export interface UIMessageImageGenerationChunk {
+    type: "image-generation";
+    messageId: string;
+    role: "assistant";
+    provider: string;
+    image: UIMessageGeneratedMedia;
+    partial: boolean;
+    id?: string;
+    index?: number;
+    providerMetadata?: Record<string, JsonValue>;
+}
 export interface UIMessageFinishChunk {
     type: "finish";
     messageId: string;
@@ -1972,12 +2270,21 @@ export interface UIAgentApprovalResolvedChunk {
     type: "agent-approval-resolved";
     approval: AgentApprovalResponse;
 }
+export interface UIAgentCompactionChunk {
+    type: "agent-compaction";
+    compaction: AgentCompactionRecord;
+}
 export interface UIAgentRunFinishChunk {
     type: "agent-run-finish";
     status: AgentStatus;
     state: AgentRunState;
 }
-export type UIMessageChunk = UIMessageTextChunk | UIMessageToolCallChunk | UIMessageToolResultChunk | UIMessageProviderDataChunk | UIMessageFinishChunk | UIMessageErrorChunk | UIAgentRunStartChunk | UIAgentStepStartChunk | UIAgentStepFinishChunk | UIAgentApprovalRequestChunk | UIAgentApprovalResolvedChunk | UIAgentRunFinishChunk;
+export interface UISessionFinishChunk {
+    type: "session-finish";
+    sessionId: string;
+    status: AgentStatus;
+}
+export type UIMessageChunk = UIMessageTextChunk | UIMessageToolCallChunk | UIMessageToolResultChunk | UIMessageToolApprovalRequestChunk | UIMessageProviderDataChunk | UIMessageImageGenerationChunk | UIMessageFinishChunk | UIMessageErrorChunk | UIAgentRunStartChunk | UIAgentStepStartChunk | UIAgentStepFinishChunk | UIAgentApprovalRequestChunk | UIAgentApprovalResolvedChunk | UIAgentCompactionChunk | UIAgentRunFinishChunk | UISessionFinishChunk;
 export interface EmbedInput {
     values: EmbedValue[];
 }