@zhivex-ai/core 0.17.0 → 0.19.0

package/dist/types.d.ts

@@ -182,6 +182,15 @@ export interface StreamProviderDataEvent {
     provider: string;
     data: JsonValue;
 }
+export interface StreamImageGenerationEvent {
+    type: "image-generation";
+    provider: string;
+    image: GeneratedMedia;
+    partial: boolean;
+    id?: string;
+    index?: number;
+    providerMetadata?: Record<string, JsonValue>;
+}
 export interface StreamFinishEvent {
     type: "finish";
     finishReason?: FinishReason;
@@ -192,7 +201,7 @@ export interface StreamErrorEvent {
     type: "error";
     error: Error;
 }
-export type StreamEvent = StreamTextDeltaEvent | StreamToolCallEvent | StreamToolResultEvent | StreamProviderDataEvent | StreamFinishEvent | StreamErrorEvent;
+export type StreamEvent = StreamTextDeltaEvent | StreamToolCallEvent | StreamToolResultEvent | StreamProviderDataEvent | StreamImageGenerationEvent | StreamFinishEvent | StreamErrorEvent;
 export interface AgentRunStartEvent {
     type: "agent-run-start";
     currentStep: number;
@@ -239,6 +248,7 @@ export interface GenerateResult {
     messages?: ModelMessage[];
     text?: string;
     audio?: GeneratedMedia[];
+    images?: GeneratedMedia[];
     finishReason?: FinishReason;
     providerFinishReason?: string;
     usage?: TokenUsage;
@@ -332,12 +342,58 @@ export interface BatchJob {
     rawResponse?: unknown;
     providerMetadata?: Record<string, unknown>;
 }
+export type InteractionStatus = "in_progress" | "requires_action" | "completed" | "failed" | "cancelled" | "incomplete" | "budget_exceeded" | (string & {});
+/**
+ * A raw content block returned by an interaction step.
+ *
+ * Provider field names are intentionally preserved so steps can be sent back
+ * unchanged when callers manage stateless interaction history.
+ */
+export interface InteractionContent {
+    type: string;
+    text?: string;
+    data?: string;
+    uri?: string;
+    mime_type?: string;
+    [key: string]: unknown;
+}
+/** A chronological step returned by the Interactions API. */
+export interface InteractionStep {
+    type: string;
+    id?: string;
+    name?: string;
+    arguments?: JsonValue;
+    call_id?: string;
+    content?: InteractionContent[];
+    result?: InteractionContent[] | JsonValue;
+    signature?: string;
+    summary?: InteractionContent[];
+    status?: string;
+    [key: string]: unknown;
+}
 export interface Interaction {
     id: string;
     name?: string;
     model?: string;
-    status?: string;
+    agent?: string;
+    status?: InteractionStatus;
+    object?: string;
+    createTime?: string;
+    updateTime?: string;
+    previousInteractionId?: string;
+    environmentId?: string;
+    steps?: InteractionStep[];
+    /**
+     * Backward-compatible output blocks. Current responses are normalized from
+     * the latest model output step when the provider no longer returns outputs.
+     */
     outputs?: unknown[];
+    outputText?: string;
+    outputImage?: InteractionContent;
+    outputAudio?: InteractionContent;
+    outputVideo?: InteractionContent;
+    usage?: TokenUsage;
+    error?: unknown;
     rawResponse?: unknown;
     providerMetadata?: Record<string, unknown>;
 }
@@ -428,6 +484,7 @@ export interface SpeechModel<TProviderOptions extends ProviderOptions = Provider
     readonly modelId: string;
     readonly capabilities: ModelCapabilities;
     generateSpeech(input: SpeechModelInput<TProviderOptions>): Promise<SpeechResult>;
+    streamSpeech?(input: SpeechModelInput<TProviderOptions>): Promise<AsyncIterable<SpeechResult>>;
 }
 export interface ImageGenerationModel<TProviderOptions extends ProviderOptions = ProviderOptions> {
     readonly provider: string;
@@ -611,6 +668,12 @@ export interface InteractionCreateInput<TProviderOptions extends ProviderOptions
     input: unknown;
     previousInteractionId?: string;
     tools?: ToolCollection;
+    systemInstruction?: string;
+    responseFormat?: JsonValue | JsonValue[];
+    generationConfig?: JsonValue;
+    agentConfig?: JsonValue;
+    environment?: string | JsonValue;
+    labels?: Record<string, string>;
     background?: boolean;
     store?: boolean;
     providerOptions?: TProviderOptions;
@@ -619,9 +682,28 @@ export interface InteractionGetInput<TProviderOptions extends ProviderOptions =
     id: string;
     providerOptions?: TProviderOptions;
 }
+export interface InteractionCancelInput<TProviderOptions extends ProviderOptions = ProviderOptions> extends RetryOptions {
+    id: string;
+    providerOptions?: TProviderOptions;
+}
+export interface InteractionDeleteInput<TProviderOptions extends ProviderOptions = ProviderOptions> extends RetryOptions {
+    id: string;
+    providerOptions?: TProviderOptions;
+}
+export interface InteractionResumeInput<TProviderOptions extends ProviderOptions = ProviderOptions> extends RetryOptions {
+    id: string;
+    lastEventId?: string;
+    providerOptions?: TProviderOptions;
+}
 export interface InteractionsClient<TProviderOptions extends ProviderOptions = ProviderOptions> {
     create(input: InteractionCreateInput<TProviderOptions>): Promise<Interaction>;
     get(input: InteractionGetInput<TProviderOptions>): Promise<Interaction>;
+    cancel(input: InteractionCancelInput<TProviderOptions>): Promise<Interaction>;
+    delete(input: InteractionDeleteInput<TProviderOptions>): Promise<{
+        id: string;
+        rawResponse?: unknown;
+    }>;
+    resume(input: InteractionResumeInput<TProviderOptions>): Promise<AsyncIterable<StreamEvent>>;
     stream(input: InteractionCreateInput<TProviderOptions>): Promise<AsyncIterable<StreamEvent>>;
 }
 export interface PredictionModel<TProviderOptions extends ProviderOptions = ProviderOptions> {
@@ -730,6 +812,11 @@ export interface RealtimeToolResultEvent {
     type: "realtime-tool-result";
     toolResult: ToolExecutionResult;
 }
+export interface RealtimeProviderDataEvent {
+    type: "realtime-provider-data";
+    provider: string;
+    data: JsonValue;
+}
 export interface RealtimeResponseCompleteEvent {
     type: "realtime-response-complete";
     reason?: string;
@@ -757,7 +844,7 @@ export interface RealtimeErrorEvent {
     message?: string;
     providerMetadata?: Record<string, JsonValue>;
 }
-export type RealtimeEvent = RealtimeSessionStartedEvent | RealtimeTextDeltaEvent | RealtimeAudioOutputEvent | RealtimeTranscriptEvent | RealtimeToolCallEvent | RealtimeToolResultEvent | RealtimeResponseCompleteEvent | RealtimeSessionResumptionEvent | RealtimeGoAwayEvent | RealtimeSessionEndedEvent | RealtimeErrorEvent;
+export type RealtimeEvent = RealtimeSessionStartedEvent | RealtimeTextDeltaEvent | RealtimeAudioOutputEvent | RealtimeTranscriptEvent | RealtimeToolCallEvent | RealtimeToolResultEvent | RealtimeProviderDataEvent | RealtimeResponseCompleteEvent | RealtimeSessionResumptionEvent | RealtimeGoAwayEvent | RealtimeSessionEndedEvent | RealtimeErrorEvent;
 export interface RealtimeSession {
     readonly provider: string;
     readonly modelId: string;
@@ -822,6 +909,10 @@ export interface ToolExecutionContext {
     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;
 }
@@ -874,6 +965,32 @@ export type GenerateTextOptions<TModel extends LanguageModel = LanguageModel> =
     toolExecution?: ToolExecutionOptions;
     toolApprovalPolicy?: ToolApprovalPolicy;
     onToolApprovalDecision?: ToolApprovalObserver;
+    /** Called immediately before each model request. Throw to stop the loop. */
+    onBeforeModelStep?: (context: {
+        request: ModelGenerateInput;
+        step: number;
+    }) => void | Promise<void>;
+    /** Called before a batch of approved local tool calls is executed. */
+    onBeforeToolExecution?: (context: {
+        request: ModelGenerateInput;
+        step: number;
+        toolCalls: ToolCall[];
+    }) => void | Promise<void>;
+    /** Durable runtimes use this hook to checkpoint a model response before tools run. */
+    onModelStep?: (context: {
+        request: ModelGenerateInput;
+        response: GenerateResult;
+        step: number;
+        toolCalls: ToolCall[];
+    }) => void | Promise<void>;
+    /** Durable runtimes use this hook to checkpoint tool results before the next model request. */
+    onToolExecutionComplete?: (context: {
+        request: ModelGenerateInput;
+        step: number;
+        toolResults: ToolExecutionResult[];
+    }) => void | Promise<void>;
+    /** Existing completed steps preceding this invocation. */
+    stepOffset?: number;
     maxSteps?: number;
     temperature?: number;
     maxTokens?: number;
@@ -903,8 +1020,32 @@ export type AgentStepStatus = "running" | "completed" | "suspended" | "waiting_a
 export interface AgentRunPolicy {
     timeoutMs?: number;
     onTimeout?: "fail" | "cancel-requested";
+    /** Disable only for stores that intentionally provide CAS without worker leases. */
+    leaseMode?: "required" | "disabled";
+    /** Duration of the exclusive worker lease. Defaults to 30 seconds. */
+    leaseTtlMs?: number;
+    /** Lease renewal interval. Defaults to one third of leaseTtlMs. */
+    heartbeatMs?: number;
+    /** How often an active worker checks durable cancellation. Defaults to 1 second. */
+    cancellationPollMs?: number;
+    /** Maximum retained events for agent stream replay. Defaults to 4096. */
+    maxStreamEvents?: number;
+    /** Maximum serialized durable state size. Defaults to 4 MiB. */
+    maxStateBytes?: number;
+    /** Optional preflight limits enforced before model and tool operations. */
+    budget?: {
+        maxSteps?: number;
+        maxToolCalls?: number;
+        maxToolErrors?: number;
+        maxInputTokens?: number;
+        maxOutputTokens?: number;
+        maxTotalTokens?: number;
+        includeChildRuns?: boolean;
+    };
 }
 export interface AgentStepRequest {
+    /** Index in the full conversation where this incremental snapshot begins. */
+    messageOffset?: number;
     messages: ModelMessage[];
     toolChoice?: ToolChoice;
     toolExecution?: ToolExecutionOptions;
@@ -955,6 +1096,13 @@ export interface AgentChildRun {
 }
 export interface AgentRunState {
     schemaVersion: 1;
+    /**
+     * Monotonic durable-store revision. Legacy states without a revision are
+     * normalized to revision 0 before their next write.
+     */
+    revision?: number;
+    /** Tenant/user isolation boundary propagated by the runtime. */
+    scope?: AgentStoreScope;
     runId: string;
     idempotencyKey?: string;
     agentId?: string;
@@ -983,17 +1131,115 @@ export interface AgentRunState {
         message: string;
     };
 }
+/**
+ * Logical isolation boundary for durable agent data. Applications should use
+ * one scope per tenant and, when memory must be private, per end user.
+ */
+export interface AgentStoreScope {
+    tenantId: string;
+    userId?: string;
+    namespace?: string;
+}
+export interface AgentRunStoreScopeOptions {
+    /** Fixed scope applied to every key handled by this store instance. */
+    scope?: AgentStoreScope;
+}
+export interface AgentRunLease {
+    runId: string;
+    ownerId: string;
+    expiresAt: number;
+}
+export interface AgentRunLeaseOptions {
+    ownerId: string;
+    ttlMs: number;
+    /** Injectable clock used by deterministic workers and tests. */
+    now?: number;
+}
+export type AgentToolCallJournalStatus = "pending" | "running" | "completed" | "failed";
+export interface AgentToolCallJournalEntry {
+    runId: string;
+    scope?: AgentStoreScope;
+    toolCallId: string;
+    toolName: string;
+    status: AgentToolCallJournalStatus;
+    /** Stable key that must also be forwarded to side-effecting integrations. */
+    idempotencyKey: string;
+    revision: number;
+    input?: JsonValue;
+    output?: JsonValue;
+    error?: {
+        message: string;
+    };
+    startedAt?: number;
+    completedAt?: number;
+    updatedAt: number;
+}
+export interface AgentToolCallJournalSaveOptions {
+    expectedRevision?: number;
+}
+export interface AgentToolExecutionClaimResult {
+    claimed: boolean;
+    entry: AgentToolCallJournalEntry;
+}
+export interface AgentRunListOptions {
+    agentId?: string;
+    parentRunId?: string;
+    statuses?: AgentStatus[];
+    updatedAfter?: number;
+    updatedBefore?: number;
+    limit?: number;
+    /** Opaque cursor returned by the previous page. */
+    cursor?: string;
+}
+export interface AgentRunPage {
+    items: AgentRunState[];
+    nextCursor?: string;
+}
+export interface AgentRunRetentionOptions {
+    before: number;
+    statuses?: AgentStatus[];
+    limit?: number;
+}
+export interface AgentRunSaveOptions {
+    expectedRevision?: number;
+}
+export interface AgentRunClaimResult {
+    claimed: boolean;
+    state: AgentRunState;
+}
 export interface AgentRunStore {
-    load(runId: string): Promise<AgentRunState | undefined> | AgentRunState | undefined;
-    findByIdempotencyKey?(idempotencyKey: string): Promise<AgentRunState | undefined> | AgentRunState | undefined;
-    findByParentRunId?(parentRunId: string): Promise<AgentRunState[]> | AgentRunState[];
-    save(state: AgentRunState): Promise<void> | void;
-    delete?(runId: string): Promise<void> | void;
+    load(runId: string, scope?: AgentStoreScope): Promise<AgentRunState | undefined> | AgentRunState | undefined;
+    findByIdempotencyKey?(idempotencyKey: string, scope?: AgentStoreScope): Promise<AgentRunState | undefined> | AgentRunState | undefined;
+    findByParentRunId?(parentRunId: string, scope?: AgentStoreScope): Promise<AgentRunState[]> | AgentRunState[];
+    /**
+     * Atomically reserves an idempotency key for a fresh run. Returns the
+     * caller's state when the reservation succeeds, or the already-reserved
+     * state when another caller owns the key.
+     */
+    claimIdempotencyKey?(state: AgentRunState & {
+        idempotencyKey: string;
+    }): Promise<AgentRunClaimResult> | AgentRunClaimResult;
+    save(state: AgentRunState, options?: AgentRunSaveOptions): Promise<void> | void;
+    delete?(runId: string, scope?: AgentStoreScope): Promise<void> | void;
+    list?(options?: AgentRunListOptions, scope?: AgentStoreScope): Promise<AgentRunPage> | AgentRunPage;
+    deleteExpired?(options: AgentRunRetentionOptions, scope?: AgentStoreScope): Promise<number> | number;
+    acquireLease?(runId: string, options: AgentRunLeaseOptions, scope?: AgentStoreScope): Promise<AgentRunLease | undefined> | AgentRunLease | undefined;
+    renewLease?(runId: string, options: AgentRunLeaseOptions, scope?: AgentStoreScope): Promise<AgentRunLease | undefined> | AgentRunLease | undefined;
+    releaseLease?(runId: string, ownerId: string, scope?: AgentStoreScope): Promise<boolean> | boolean;
+    loadToolCall?(runId: string, toolCallId: string, scope?: AgentStoreScope): Promise<AgentToolCallJournalEntry | undefined> | AgentToolCallJournalEntry | undefined;
+    loadToolExecution?(runId: string, toolCallId: string, scope?: AgentStoreScope): Promise<AgentToolCallJournalEntry | undefined> | AgentToolCallJournalEntry | undefined;
+    listToolCalls?(runId: string, scope?: AgentStoreScope): Promise<AgentToolCallJournalEntry[]> | AgentToolCallJournalEntry[];
+    saveToolCall?(entry: AgentToolCallJournalEntry, options?: AgentToolCallJournalSaveOptions): Promise<AgentToolCallJournalEntry> | AgentToolCallJournalEntry;
+    claimToolExecution?(entry: AgentToolCallJournalEntry): Promise<AgentToolExecutionClaimResult> | AgentToolExecutionClaimResult;
+    completeToolExecution?(entry: AgentToolCallJournalEntry, options: AgentToolCallJournalSaveOptions & {
+        expectedRevision: number;
+    }): Promise<AgentToolCallJournalEntry> | AgentToolCallJournalEntry;
 }
 export interface AgentRunCancellationOptions {
     reason?: string;
     cascade?: boolean;
     mode?: "request" | "final";
+    scope?: AgentStoreScope;
 }
 export interface AgentRunTreeCancellationResult {
     parent?: AgentRunState;
@@ -1002,6 +1248,7 @@ export interface AgentRunTreeCancellationResult {
 export interface AgentMemoryContext {
     runId: string;
     agentId?: string;
+    scope?: AgentStoreScope;
     state?: AgentRunState;
     metadata?: Record<string, JsonValue>;
 }
@@ -1024,12 +1271,14 @@ export interface SqliteDatabaseLike {
 export interface SqliteAgentRunStoreOptions {
     db: SqliteDatabaseLike;
     tableName?: string;
+    scope?: AgentStoreScope;
 }
 export interface SqliteAgentMemoryStoreOptions {
     db: SqliteDatabaseLike;
     tableName?: string;
     key?: (context: AgentMemoryContext) => string;
     selectMessages?: (state: AgentRunState) => ModelMessage[];
+    scope?: AgentStoreScope;
 }
 export interface PostgresQueryResultLike<TResult extends Record<string, unknown> = Record<string, unknown>> {
     rows: TResult[];
@@ -1040,16 +1289,19 @@ export interface PostgresClientLike {
 export interface PostgresAgentRunStoreOptions {
     client: PostgresClientLike;
     tableName?: string;
+    scope?: AgentStoreScope;
 }
 export interface PostgresAgentMemoryStoreOptions {
     client: PostgresClientLike;
     tableName?: string;
     key?: (context: AgentMemoryContext) => string;
     selectMessages?: (state: AgentRunState) => ModelMessage[];
+    scope?: AgentStoreScope;
 }
 export interface AgentHandoff {
     id: string;
     fromRunId: string;
+    scope?: AgentStoreScope;
     fromAgentId?: string;
     toAgentId?: string;
     summary: string;
@@ -1111,6 +1363,7 @@ export interface AgentGuardrailTrigger {
 export interface AgentInputGuardrailRequest {
     runId: string;
     agentId?: string;
+    state: AgentRunState;
     messages: ModelMessage[];
     metadata?: Record<string, JsonValue>;
 }
@@ -1165,6 +1418,20 @@ export interface AgentTelemetryRunFinishEvent {
 }
 export type AgentTelemetryEvent = AgentTelemetryRunStartEvent | AgentTelemetryStepStartEvent | AgentTelemetryStepFinishEvent | AgentTelemetryApprovalRequestEvent | AgentTelemetryApprovalResolvedEvent | AgentTelemetryToolApprovalEvent | AgentTelemetryMemoryLoadedEvent | AgentTelemetryGuardrailTriggeredEvent | AgentTelemetryStateSavedEvent | AgentTelemetryHandoffEvent | AgentTelemetrySubAgentStartEvent | AgentTelemetrySubAgentFinishEvent | AgentTelemetryRunFinishEvent;
 export type AgentTelemetryObserver = (event: AgentTelemetryEvent) => void | Promise<void>;
+export type AgentHookFailureMode = "ignore" | "fail";
+export interface AgentOperationalError {
+    source: "telemetry" | "memory";
+    operation: string;
+    runId?: string;
+    error: Error;
+}
+export interface AgentHookFailurePolicy {
+    /** Telemetry is best-effort by default and cannot fail a run. */
+    telemetry?: AgentHookFailureMode;
+    /** Memory hooks are best-effort by default and cannot fail durable execution. */
+    memory?: AgentHookFailureMode;
+    onError?: (event: AgentOperationalError) => void | Promise<void>;
+}
 export interface AgentDefinition<TModel extends LanguageModel = LanguageModel> {
     id?: string;
     model: TModel;
@@ -1185,6 +1452,7 @@ export interface AgentDefinition<TModel extends LanguageModel = LanguageModel> {
     store?: AgentRunStore;
     memory?: AgentMemoryStore;
     onTelemetryEvent?: AgentTelemetryObserver;
+    hookFailurePolicy?: AgentHookFailurePolicy;
 }
 export interface LiveAgentDefinition<TModel extends RealtimeModel = RealtimeModel> {
     id?: string;
@@ -1219,6 +1487,8 @@ export interface AgentApprovalResponse {
 }
 export type AgentRunInput<TModel extends LanguageModel = LanguageModel> = RetryOptions & GenerateInputSource & {
     runId?: string;
+    /** Required isolation boundary for shared durable stores and memory. */
+    scope?: AgentStoreScope;
     idempotencyKey?: string;
     state?: AgentRunState;
     approvals?: AgentApprovalResponse[];
@@ -1268,6 +1538,7 @@ export type SubAgentToolOutput = Record<string, JsonValue>;
 export interface CreateSubAgentToolOptions<TModel extends LanguageModel = LanguageModel> extends AgentSubAgentDefinition<TModel> {
     parentRunId?: string;
     parentAgentId?: string;
+    scope?: AgentStoreScope;
     toolName?: string;
     onStart?: (request: {
         toolName: string;
@@ -1356,6 +1627,7 @@ export type GenerateSpeechOptions<TModel extends SpeechModel = SpeechModel> = Re
     voice?: string;
     providerOptions?: TModel extends SpeechModel<infer TProviderOptions> ? TProviderOptions : ProviderOptions;
 };
+export type StreamSpeechOptions<TModel extends SpeechModel = SpeechModel> = GenerateSpeechOptions<TModel>;
 export interface SpeechOutput extends SpeechResult {
     input: string;
 }
@@ -1468,6 +1740,15 @@ export type CreateInteractionOptions<TProvider extends ProviderAdapter = Provide
 export type GetInteractionOptions<TProvider extends ProviderAdapter = ProviderAdapter> = InteractionGetInput & {
     provider: TProvider;
 };
+export type CancelInteractionOptions<TProvider extends ProviderAdapter = ProviderAdapter> = InteractionCancelInput & {
+    provider: TProvider;
+};
+export type DeleteInteractionOptions<TProvider extends ProviderAdapter = ProviderAdapter> = InteractionDeleteInput & {
+    provider: TProvider;
+};
+export type ResumeInteractionOptions<TProvider extends ProviderAdapter = ProviderAdapter> = InteractionResumeInput & {
+    provider: TProvider;
+};
 export type StreamInteractionOptions<TProvider extends ProviderAdapter = ProviderAdapter> = InteractionCreateInput & {
     provider: TProvider;
 };