@aexhq/sdk 0.31.0 → 0.33.0

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { HttpClient, SecretString, type AexEvent, type AgentsMdRecord, type DebugSink, type FetchLike, type FileRecord, type Output, type OutputFileType, type OutputLink, type OutputLinkOptions, type OutputQuery, type OutputText, type OutputMode, type ReadOutputTextOptions, type RunListPage, type RunListQuery, type OutputSearchQuery, type OutputSearchPage, type PlatformEnvironmentInput, type PlatformSubmission, type PlatformInlineSecrets, type PlatformProxyEndpoint, type PlatformProxyEndpointAuth, type PlatformPostHookInput, type Run, type RunModel, type RunEvent, type RunTrace, type UsageSummary, type RunLimits, type RunWebhookDelivery, type RunProvider, type SecretRecord, type SecretReveal, type RunUnit, type BuiltinToolName, type RuntimeSize, type Skill as SkillRecord, type WhoAmI } from "./_contracts/index.js";
+import { HttpClient, SecretString, type AexEvent, type AgentsMdRecord, type DebugSink, type FetchLike, type FileRecord, type Output, type OutputFileType, type OutputLink, type OutputLinkOptions, type OutputQuery, type OutputText, type OutputMode, type ReadOutputTextOptions, type RunListPage, type RunListQuery, type OutputSearchQuery, type OutputSearchPage, type Session, type SessionCreateRequest, type SessionEvent, type SessionListPage, type SessionListQuery, type SessionStateChangeAccepted, type SessionTurn, type PlatformEnvironmentInput, type PlatformSubmission, type PlatformInlineSecrets, type PlatformProxyEndpoint, type PlatformProxyEndpointAuth, type Run, type RunModel, type RunEvent, type RunTrace, type UsageSummary, type RunLimits, type RunWebhookDelivery, type RunProvider, type SecretRecord, type SecretReveal, type RunUnit, type BuiltinToolName, type RuntimeSize, type Skill as SkillRecord, type WebSocketFactory, type WhoAmI } from "./_contracts/index.js";
 import { AgentsMd } from "./agents-md.js";
 import { type UploadedAsset } from "./asset-upload.js";
 import { File } from "./file.js";
@@ -110,12 +110,6 @@ export interface SubmitOptions {
      * [1m, 6h]; omit for the 1h default. Applies to both runtimes.
      */
     readonly timeout?: string;
-    /**
-     * Command to run after the agent process exits successfully. A non-zero exit
-     * or timeout is sent back to the model as a repair prompt until `maxTurns`
-     * is exhausted. Empty commands are treated as omitted.
-     */
-    readonly postHook?: PlatformPostHookInput;
     readonly proxyEndpoints?: readonly ProxyEndpoint[];
     /**
      * Output capture policy for the run's output files.
@@ -186,24 +180,29 @@ export interface SubmitOptions {
      * shape + positivity are validated client-side.
      */
     readonly limits?: RunLimits;
-    readonly signal?: AbortSignal;
 }
 /**
  * The settle-consistent result of {@link AgentExecutor.run} / `runAndCollect`:
- * the terminal run record plus its settle-bracketed events, decoded trace,
- * assistant text, and captured outputs — everything a "do it and give me the
- * result" caller needs without hand-rolling a poll loop.
+ * the one-shot session record plus its events, decoded trace, assistant text,
+ * and captured outputs — everything a "do it and give me the result" caller
+ * needs without hand-rolling a session/message/stream loop.
  */
 export interface RunResult {
     readonly runId: string;
-    /** The full terminal run record (status, costTelemetry, timings). */
+    /** The session id used as the run-compatible handle. */
+    readonly sessionId?: string;
+    /** Run-compatible view of the underlying session record. */
     readonly run: Run;
+    /** The underlying resumable session record. */
+    readonly session?: Session;
+    /** The turn accepted for this one-shot run. */
+    readonly turn?: SessionTurn;
     readonly status: string;
-    /** `true` when `status === "succeeded"`. */
+    /** `true` when the one-shot turn parked the session cleanly (`idle` or `suspended`). */
     readonly ok: boolean;
-    /** The assistant's final text (decoded over the settled events). */
+    /** The assistant's final text. */
     readonly text: string;
-    /** The settle-bracketed event stream (RUN_STARTED … terminal). */
+    /** The session turn event stream. */
     readonly events: readonly RunEvent[];
     /** Decoded view of the events: tool calls + usage + assistant text. */
     readonly trace: RunTrace;
@@ -218,12 +217,96 @@ export interface RunResult {
 }
 /** Options for {@link AgentExecutor.run} / `runAndCollect`. */
 export interface RunCollectOptions {
-    /** Overall wait budget (ms) for the run to reach a terminal record. */
+    /** Overall wait budget (ms) for the one-shot session turn to park. */
     readonly timeoutMs?: number;
-    readonly signal?: AbortSignal;
+    readonly webSocketFactory?: WebSocketFactory;
+    readonly idleTimeoutMs?: number;
+    readonly pingIntervalMs?: number;
     /** Throw a {@link RunStateError} when the run does not succeed. Default false. */
     readonly throwOnFailure?: boolean;
 }
+export type SessionInput = string | readonly string[];
+export type ChatInput = SessionInput;
+export interface SessionEnvironmentOptions extends Omit<PlatformEnvironmentInput, "envVars"> {
+    readonly variables?: Readonly<Record<string, string>>;
+    readonly secrets?: Readonly<Record<string, Secret>>;
+}
+export interface SessionOverrides {
+    readonly idleTtl?: string;
+    readonly timeout?: string;
+    readonly maxSpendUsd?: number;
+}
+export interface SessionCreateOptions extends Omit<SubmitOptions, "prompt" | "webhook" | "environment" | "secretEnv" | "secrets" | "runtimeSize" | "parentRunId" | "limits" | "timeout"> {
+    readonly apiKeys?: Partial<Record<RunProvider, string>>;
+    readonly environment?: SessionEnvironmentOptions;
+    readonly runtime?: RuntimeSize;
+    readonly overrides?: SessionOverrides;
+}
+export type ChatCreateOptions = SessionCreateOptions;
+export interface SessionSendOptions {
+    readonly idempotencyKey?: string;
+    readonly from?: number;
+    readonly webSocketFactory?: WebSocketFactory;
+    readonly idleTimeoutMs?: number;
+    readonly pingIntervalMs?: number;
+}
+export type ChatSendOptions = SessionSendOptions;
+export interface SessionRunOptions extends SessionCreateOptions {
+    readonly message: SessionInput;
+    readonly deleteAfter?: boolean;
+    readonly messageIdempotencyKey?: string;
+    readonly stream?: Omit<SessionSendOptions, "idempotencyKey">;
+}
+export type ChatRunOptions = SessionRunOptions;
+export interface SessionTurnResult {
+    readonly sessionId: string;
+    readonly session: Session;
+    readonly turn: SessionTurn;
+    readonly status: string;
+    readonly text: string;
+    readonly events: readonly SessionEvent[];
+    readonly outputs: readonly Output[];
+}
+export interface ChatTurnResult extends SessionTurnResult {
+}
+export interface SessionRunResult extends SessionTurnResult {
+}
+export interface ChatRunResult extends SessionRunResult {
+}
+export declare class SessionTurnStream implements AsyncIterable<SessionEvent> {
+    #private;
+    constructor(run: () => AsyncGenerator<SessionEvent, SessionTurnResult, void>);
+    [Symbol.asyncIterator](): AsyncIterator<SessionEvent>;
+    done(): Promise<SessionTurnResult>;
+}
+export declare const ChatTurnStream: typeof SessionTurnStream;
+export type ChatTurnStream = SessionTurnStream;
+export declare class SessionHandle {
+    #private;
+    constructor(http: HttpClient, session: Session);
+    get id(): string;
+    get record(): Session;
+    send(input: SessionInput, options?: SessionSendOptions): SessionTurnStream;
+    suspend(options?: Pick<SessionSendOptions, "idempotencyKey">): Promise<SessionStateChangeAccepted>;
+    cancel(options?: Pick<SessionSendOptions, "idempotencyKey">): Promise<SessionStateChangeAccepted>;
+    resume(options?: Pick<SessionSendOptions, "idempotencyKey">): Promise<SessionStateChangeAccepted>;
+    delete(options?: Pick<SessionSendOptions, "idempotencyKey">): Promise<void>;
+    listEvents(): Promise<readonly SessionEvent[]>;
+    listOutputs(query?: OutputQuery): Promise<readonly Output[]>;
+}
+export declare const ChatSession: typeof SessionHandle;
+export type ChatSession = SessionHandle;
+export declare class SessionClient {
+    #private;
+    constructor(http: HttpClient, buildCreateRequest: (options: SessionCreateOptions) => Promise<SessionCreateRequest>);
+    create(options: SessionCreateOptions): Promise<SessionHandle>;
+    open(sessionId: string): Promise<SessionHandle>;
+    get(sessionId: string): Promise<Session>;
+    list(query?: SessionListQuery): Promise<SessionListPage>;
+    run(options: SessionRunOptions): Promise<SessionRunResult>;
+}
+export declare const ChatClient: typeof SessionClient;
+export type ChatClient = SessionClient;
 export interface StreamEventsOptions {
     /** Poll interval in ms for the `RunEvent` snapshot loop. Default 1000. */
     readonly intervalMs?: number;
@@ -310,8 +393,7 @@ export declare class SkillsClient {
  * New run submissions usually use `AgentsMd.fromContent(...)` or
  * `AgentsMd.fromPath(...)` directly inside `submit`; the SDK
  * materializes those bytes to the hosted asset store before the run lands. This namespace is
- * the read/delete surface for persisted AgentsMd records plus an internal
- * upload transport retained for legacy callers.
+ * the read/delete surface for persisted AgentsMd records.
  */
 export declare class AgentsMdClient {
     #private;
@@ -319,14 +401,6 @@ export declare class AgentsMdClient {
     list(): Promise<readonly AgentsMdRecord[]>;
     get(agentsMdId: string): Promise<AgentsMdRecord>;
     delete(agentsMdId: string): Promise<void>;
-    /**
-     * Internal: post an AgentsMd markdown string to the BFF.
-     * NOT part of the public API.
-     */
-    _uploadAgentsMd(args: {
-        readonly name: string;
-        readonly content: string;
-    }): Promise<AgentsMdRecord>;
 }
 /**
  * Workspace File admin operations exposed under `client.files`.
@@ -334,8 +408,7 @@ export declare class AgentsMdClient {
  * New run submissions usually use `File.fromPath(...)` or
  * `File.fromBytes(...)` directly inside `submit`; the SDK materializes
  * those bytes to the hosted asset store before the run lands. This namespace is the read/delete
- * surface for persisted file records plus an internal upload transport
- * retained for legacy callers.
+ * surface for persisted file records.
  */
 export declare class FilesClient {
     #private;
@@ -343,14 +416,6 @@ export declare class FilesClient {
     list(): Promise<readonly FileRecord[]>;
     get(fileId: string): Promise<FileRecord>;
     delete(fileId: string): Promise<void>;
-    /**
-     * Internal: post a pre-bundled file zip to the BFF.
-     * NOT part of the public API.
-     */
-    _uploadFile(args: {
-        readonly name: string;
-        readonly bytes: Uint8Array;
-    }): Promise<FileRecord>;
 }
 /**
  * Workspace secret management exposed under `client.secrets`, mirroring
@@ -415,25 +480,9 @@ export declare class AgentExecutor {
     readonly agentsMd: AgentsMdClient;
     readonly files: FilesClient;
     readonly secrets: SecretsClient;
+    readonly sessions: SessionClient;
+    readonly chat: ChatClient;
     constructor(options: AgentExecutorOptions);
-    /**
-     * Internal: an `AgentsMd.upload(this)` shortcut that bypasses
-     * `client.agentsMd` indirection. Forwarded to
-     * `AgentsMdClient._uploadAgentsMd`. NOT part of the public API.
-     */
-    _uploadAgentsMd(args: {
-        readonly name: string;
-        readonly content: string;
-    }): Promise<AgentsMdRecord>;
-    /**
-     * Internal: a `File.upload(this)` shortcut that bypasses
-     * `client.files` indirection. Forwarded to
-     * `FilesClient._uploadFile`. NOT part of the public API.
-     */
-    _uploadFile(args: {
-        readonly name: string;
-        readonly bytes: Uint8Array;
-    }): Promise<FileRecord>;
     /**
      * Internal: satisfies the `SecretUploader` surface so a
      * `Secret.value(...).upload(client, { name })` promotes an ephemeral secret
@@ -458,26 +507,20 @@ export declare class AgentExecutor {
         readonly contentType?: string;
     }): Promise<UploadedAsset>;
     /**
-     * Submit a run, wait until its RECORD is terminal, and collect the full
-     * {@link RunResult} — the settle-consistent "do it and give me the result"
-     * primitive. Folds the poll loop every consumer hand-rolled into one call:
-     * submit → {@link waitForRun} (polls `getRun`, NOT the earlier RUN_FINISHED
-     * event) → poll `listEvents` until the snapshot is settle-bracketed
-     * (RUN_STARTED + a terminal event present) → `listOutputs` → decode the trace
-     * and assistant text. On resolve, `getRun`/`listOutputs` are guaranteed
-     * consistent.
-     *
-     * Uses polling (portable across backends), NOT the coordinator WebSocket. By
-     * default a failed run resolves with `ok: false` and a populated `error`; pass
-     * `{ throwOnFailure: true }` to throw instead. For live events prefer `submit`
-     * + `streamEnvelopes(runId, { settleConsistent: true })`.
+     * Convenience one-shot on top of the canonical session API:
+     * open a session, send `message` as the first turn, stream until the session
+     * parks (`idle` / `suspended` / `error`), then return the collected text,
+     * events, outputs, and session record. The returned `runId` is the session id,
+     * so callers can resume later with `openSession(runId)`.
      */
-    run(options: SubmitOptions, opts?: RunCollectOptions): Promise<RunResult>;
+    run(options: SessionRunOptions, opts?: RunCollectOptions): Promise<RunResult>;
     /**
-     * Explicit, discoverable alias for {@link run}: submit, wait, and collect the
-     * full {@link RunResult} in one call.
+     * Explicit, discoverable alias for {@link run}: open a one-shot session turn
+     * and collect the full {@link RunResult} in one call.
      */
-    runAndCollect(options: SubmitOptions, opts?: RunCollectOptions): Promise<RunResult>;
+    runAndCollect(options: SessionRunOptions, opts?: RunCollectOptions): Promise<RunResult>;
+    openSession(options: SessionCreateOptions): Promise<SessionHandle>;
+    openSession(sessionId: string): Promise<SessionHandle>;
     /**
      * Submit a run and return its run id immediately. Use that id with
      * `wait`, `stream`, `outputs`, `download`, `cancel`, or `delete`.
@@ -628,4 +671,7 @@ export declare class AgentExecutor {
     /** Download only the run record (the `metadata` namespace) as a zip. */
     downloadMetadata(runId: string, options?: OutputDownloadOptions): Promise<Uint8Array>;
 }
+/** Canonical SDK client name. `AgentExecutor` remains as a compatibility alias. */
+export declare class Aex extends AgentExecutor {
+}
 export type { OutputFileType, OutputLink, OutputLinkOptions, OutputQuery, PlatformProxyEndpoint, PlatformProxyEndpointAuth };