@aexhq/sdk 0.32.0 → 0.33.1

package/dist/client.js

@@ -1,4 +1,4 @@
-import { AexError, DEFAULT_RUN_PROVIDER, HttpClient, RunConfigValidationError, RunStateError, SecretString, isRunSettled, operations, providersForModel, streamCoordinatorEvents, summarizeRunTrace, textOf, parseRunLimits, BUILTIN_TOOL_NAMES, TERMINAL_RUN_STATUSES } from "./_contracts/index.js";
+import { AexError, DEFAULT_RUN_PROVIDER, HttpClient, RunConfigValidationError, RunStateError, SecretString, customName, isRunSettled, operations, providersForModel, streamCoordinatorEvents, summarizeRunTrace, textOf, parseRunLimits, BUILTIN_TOOL_NAMES, TERMINAL_RUN_STATUSES } from "./_contracts/index.js";
 import { AgentsMd } from "./agents-md.js";
 import { uploadAsset } from "./asset-upload.js";
 import { File } from "./file.js";
@@ -7,6 +7,199 @@ import { splitProxyEndpoints } from "./proxy-endpoint.js";
 import { splitSecretEnv } from "./secret.js";
 import { Skill } from "./skill.js";
 import { Tool } from "./tool.js";
+export class SessionTurnStream {
+    #run;
+    #done;
+    constructor(run) {
+        this.#run = run;
+    }
+    [Symbol.asyncIterator]() {
+        return this.#run();
+    }
+    done() {
+        this.#done ??= (async () => {
+            const iterator = this.#run();
+            let next = await iterator.next();
+            while (!next.done) {
+                next = await iterator.next();
+            }
+            return next.value;
+        })();
+        return this.#done;
+    }
+}
+export const ChatTurnStream = SessionTurnStream;
+const internalSessionSenders = new WeakMap();
+function sendSessionInternal(session, input, options = {}) {
+    const sender = internalSessionSenders.get(session);
+    if (sender === undefined) {
+        throw new Error("Aex: invalid session handle");
+    }
+    return sender(normaliseSessionInput(input, "SessionHandle.send", "input"), options);
+}
+export class SessionHandle {
+    #http;
+    #session;
+    constructor(http, session) {
+        this.#http = http;
+        this.#session = session;
+        internalSessionSenders.set(this, (input, options = {}) => new SessionTurnStream(() => this.#send(input, options)));
+    }
+    get id() {
+        return this.#session.sessionId ?? this.#session.id;
+    }
+    get record() {
+        return this.#session;
+    }
+    send(input, options = {}) {
+        assertNoSessionSendSignal(options, "SessionHandle.send");
+        return sendSessionInternal(this, input, options);
+    }
+    async *#send(input, options) {
+        const accepted = await operations.sendSessionMessage(this.#http, this.id, { input }, { idempotencyKey: options.idempotencyKey ?? generateIdempotencyKey() });
+        this.#session = accepted.session;
+        const turn = accepted.turn;
+        const events = [];
+        for await (const event of streamSessionTurnEvents(this.#http, this.id, turn, {
+            ...options,
+            from: options.from ?? accepted.eventCursor ?? turn.eventCursor ?? 0
+        })) {
+            events.push(event);
+            yield event;
+        }
+        const terminalStatus = terminalSessionStatusFromEvents(events, turn.turnSeq);
+        const readSession = await operations.getSession(this.#http, this.id).catch(() => this.#session);
+        this.#session = withTerminalSessionStatus(readSession, terminalStatus);
+        const outputs = await operations.listSessionOutputs(this.#http, this.id).catch(() => []);
+        return {
+            sessionId: this.id,
+            session: this.#session,
+            turn,
+            status: this.#session.status,
+            text: textOf(events),
+            events,
+            outputs
+        };
+    }
+    async suspend(options = {}) {
+        const accepted = await operations.suspendSession(this.#http, this.id, options);
+        this.#session = accepted.session;
+        return accepted;
+    }
+    async cancel(options = {}) {
+        const accepted = await operations.cancelSession(this.#http, this.id, options);
+        this.#session = accepted.session;
+        return accepted;
+    }
+    async resume(options = {}) {
+        const accepted = await operations.resumeSession(this.#http, this.id, options);
+        this.#session = accepted.session;
+        return accepted;
+    }
+    async delete(options = {}) {
+        const accepted = await operations.deleteSession(this.#http, this.id, options);
+        if (accepted && typeof accepted === "object" && "session" in accepted) {
+            this.#session = accepted.session;
+        }
+    }
+    listEvents() {
+        return operations.listSessionEvents(this.#http, this.id);
+    }
+    listOutputs(query) {
+        return operations.listSessionOutputs(this.#http, this.id, query);
+    }
+}
+export const ChatSession = SessionHandle;
+export class SessionClient {
+    #http;
+    #buildCreateRequest;
+    constructor(http, buildCreateRequest) {
+        this.#http = http;
+        this.#buildCreateRequest = buildCreateRequest;
+    }
+    async create(options) {
+        const request = await this.#buildCreateRequest(options);
+        const session = await operations.createSession(this.#http, request, { idempotencyKey: options.idempotencyKey ?? generateIdempotencyKey() });
+        return new SessionHandle(this.#http, session);
+    }
+    async open(sessionId) {
+        return new SessionHandle(this.#http, await operations.getSession(this.#http, sessionId));
+    }
+    get(sessionId) {
+        return operations.getSession(this.#http, sessionId);
+    }
+    list(query) {
+        return operations.listSessions(this.#http, query);
+    }
+    async run(options) {
+        const { message, deleteAfter, messageIdempotencyKey, stream, ...createOptions } = options;
+        assertNoLegacySessionFields(options, "Aex.sessions.run");
+        const input = normaliseSessionInput(message, "Aex.sessions.run", "message");
+        const session = await this.create(createOptions);
+        const result = await session.send(input, {
+            ...(stream ?? {}),
+            idempotencyKey: messageIdempotencyKey ?? generateIdempotencyKey()
+        }).done();
+        if (deleteAfter) {
+            await session.delete();
+        }
+        return result;
+    }
+}
+export const ChatClient = SessionClient;
+async function* streamSessionTurnEvents(http, sessionId, turn, options) {
+    const first = await operations.getSessionCoordinatorTicket(http, sessionId);
+    yield* streamCoordinatorEvents({
+        wsUrl: first.wsUrl,
+        from: options.from ?? 0,
+        fetchTicket: async () => (await operations.getSessionCoordinatorTicket(http, sessionId)).ticket,
+        isTerminal: (event) => isSessionTurnTerminalEvent(event, turn.turnSeq),
+        ...(options.signal ? { signal: options.signal } : {}),
+        ...(options.webSocketFactory ? { webSocketFactory: options.webSocketFactory } : {}),
+        ...(options.idleTimeoutMs !== undefined ? { idleTimeoutMs: options.idleTimeoutMs } : {}),
+        ...(options.pingIntervalMs !== undefined ? { pingIntervalMs: options.pingIntervalMs } : {})
+    });
+}
+function isSessionTurnTerminalEvent(event, turnSeq) {
+    const name = customName(event);
+    if (name !== "aex.session.idle" &&
+        name !== "aex.session.suspended" &&
+        name !== "aex.session.error") {
+        return false;
+    }
+    const value = event.data.value;
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return true;
+    }
+    const eventTurnSeq = value.turnSeq;
+    return typeof eventTurnSeq !== "number" || eventTurnSeq === turnSeq;
+}
+function terminalSessionStatusFromEvents(events, turnSeq) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const event = events[i];
+        if (!isSessionTurnTerminalEvent(event, turnSeq))
+            continue;
+        const name = customName(event);
+        if (name === "aex.session.idle")
+            return "idle";
+        if (name === "aex.session.suspended")
+            return "suspended";
+        if (name === "aex.session.error")
+            return "error";
+    }
+    return undefined;
+}
+function withTerminalSessionStatus(session, terminalStatus) {
+    if (terminalStatus === undefined || session.status === terminalStatus)
+        return session;
+    if (session.status !== "creating" &&
+        session.status !== "running" &&
+        session.status !== "suspending" &&
+        session.status !== "cancelling") {
+        return session;
+    }
+    return { ...session, status: terminalStatus };
+}
 /**
  * Workspace skill admin operations exposed under `client.skills`.
  *
@@ -181,6 +374,8 @@ export class AgentExecutor {
     agentsMd;
     files;
     secrets;
+    sessions;
+    chat;
     constructor(options) {
         if (!options.apiToken) {
             throw new Error("AgentExecutor: apiToken is required");
@@ -201,6 +396,8 @@ export class AgentExecutor {
         this.agentsMd = new AgentsMdClient(this.#http);
         this.files = new FilesClient(this.#http);
         this.secrets = new SecretsClient(this.#http);
+        this.chat = new ChatClient(this.#http, (options) => this.#buildSessionCreateRequest(options));
+        this.sessions = this.chat;
     }
     /**
      * Internal: satisfies the `SecretUploader` surface so a
@@ -227,57 +424,78 @@ export class AgentExecutor {
         });
     }
     /**
-     * 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)`.
      */
     async run(options, opts = {}) {
-        const signal = opts.signal ?? options.signal;
-        const runId = await this.submit(options);
-        const run = await this.waitForRun(runId, {
-            ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
-            ...(signal ? { signal } : {})
-        });
-        const events = await this.#collectSettledEvents(runId, signal);
-        const outputs = await this.listOutputs(runId);
-        const ok = run.status === "succeeded";
-        const costUsd = run.costTelemetry?.billedCostUsd;
-        const errorMessage = typeof run.errorMessage === "string" && run.errorMessage ? run.errorMessage : undefined;
-        const result = {
-            runId,
-            run,
-            status: run.status,
-            ok,
-            text: textOf(events),
-            events,
-            trace: summarizeRunTrace(events),
-            outputs,
-            ...(run.usage ? { usage: run.usage } : {}),
-            ...(typeof costUsd === "number" ? { costUsd } : {}),
-            ...(!ok && errorMessage ? { error: errorMessage } : {})
-        };
-        if (opts.throwOnFailure && !ok) {
-            throw new RunStateError(`AgentExecutor.run: run ${runId} ended ${run.status}${errorMessage ? `: ${errorMessage}` : ""}`, { runId, status: run.status });
+        const scopedSignal = scopedAbortSignal(opts.timeoutMs);
+        try {
+            const { message, deleteAfter, messageIdempotencyKey, stream, ...createOptions } = options;
+            assertNoLegacySessionFields(options, "Aex.run");
+            const input = normaliseSessionInput(message, "Aex.run", "message");
+            assertNoSessionSendSignal(stream, "Aex.run stream");
+            const streamOptions = {
+                ...(stream ?? {}),
+                ...(scopedSignal?.signal ? { signal: scopedSignal.signal } : {}),
+                ...(opts.webSocketFactory ? { webSocketFactory: opts.webSocketFactory } : {}),
+                ...(opts.idleTimeoutMs !== undefined ? { idleTimeoutMs: opts.idleTimeoutMs } : {}),
+                ...(opts.pingIntervalMs !== undefined ? { pingIntervalMs: opts.pingIntervalMs } : {})
+            };
+            const session = await this.sessions.create(createOptions);
+            const turnResult = await sendSessionInternal(session, input, {
+                ...streamOptions,
+                idempotencyKey: messageIdempotencyKey ?? generateIdempotencyKey()
+            }).done();
+            if (deleteAfter) {
+                await session.delete();
+            }
+            const runId = turnResult.sessionId;
+            const run = sessionToRun(turnResult.session);
+            const events = turnResult.events;
+            const outputs = turnResult.outputs;
+            const ok = turnResult.status === "idle" || turnResult.status === "suspended";
+            const costUsd = typeof turnResult.session.costUsd === "number" ? turnResult.session.costUsd : undefined;
+            const errorMessage = typeof turnResult.session.errorMessage === "string" && turnResult.session.errorMessage ? turnResult.session.errorMessage : undefined;
+            const result = {
+                runId,
+                run,
+                sessionId: runId,
+                session: turnResult.session,
+                turn: turnResult.turn,
+                status: turnResult.status,
+                ok,
+                text: turnResult.text,
+                events,
+                trace: summarizeRunTrace(events),
+                outputs,
+                ...(turnResult.session.usage ? { usage: turnResult.session.usage } : {}),
+                ...(typeof costUsd === "number" ? { costUsd } : {}),
+                ...(!ok && errorMessage ? { error: errorMessage } : {})
+            };
+            if (opts.throwOnFailure && !ok) {
+                throw new RunStateError(`AgentExecutor.run: session ${runId} ended ${turnResult.status}${errorMessage ? `: ${errorMessage}` : ""}`, { runId, status: turnResult.status });
+            }
+            return result;
+        }
+        finally {
+            scopedSignal?.clear();
         }
-        return result;
     }
     /**
-     * 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, opts) {
         return this.run(options, opts);
     }
+    openSession(optionsOrId) {
+        return typeof optionsOrId === "string"
+            ? this.sessions.open(optionsOrId)
+            : this.sessions.create(optionsOrId);
+    }
     /**
      * Poll `listEvents` until the snapshot is settle-bracketed — both a
      * RUN_STARTED and a terminal (RUN_FINISHED / RUN_ERROR) event present — then
@@ -328,7 +546,7 @@ export class AgentExecutor {
         if (!options || typeof options !== "object") {
             throw new RunConfigValidationError("AgentExecutor.submit: options is required");
         }
-        assertNoRemovedSubmitFields(options);
+        assertNoRemovedSubmitFields(options, "AgentExecutor.submit");
         // A model maps to one or more upstream providers (see MODEL_PROVIDER_IDS).
         // `providersForModel` returns the supported providers in priority order, or
         // `[]` for an unknown model string (the model check below then rejects it).
@@ -342,11 +560,11 @@ export class AgentExecutor {
                 `model ${JSON.stringify(options.model)} (supported: ${supportedProviders.join(", ")})`);
         }
         const provider = options.provider ?? supportedProviders[0] ?? DEFAULT_RUN_PROVIDER;
-        validateSubmitCredentials(options, provider);
+        validateSubmitCredentials(options, provider, "AgentExecutor.submit");
         if (typeof options.model !== "string" || !options.model) {
             throw new RunConfigValidationError("AgentExecutor.submit: model is required");
         }
-        const prompt = normalisePrompt(options.prompt);
+        const prompt = normalisePrompt(options.prompt, "AgentExecutor.submit", "prompt");
         const { endpoints: proxyEndpointDeclarations, auth: proxyEndpointAuthFromInstances } = splitProxyEndpoints(options.proxyEndpoints ?? []);
         const mergedProxyAuth = mergeProxyEndpointAuth(proxyEndpointAuthFromInstances, options.secrets?.proxyEndpointAuth ?? []);
         // Split secretEnv into value-free declarations (hashed submission) and
@@ -416,7 +634,6 @@ export class AgentExecutor {
             ...(mergedProxyAuth.length > 0 ? { proxyEndpointAuth: mergedProxyAuth } : {}),
             ...(Object.keys(envSecretValues).length > 0 ? { envSecrets: envSecretValues } : {})
         };
-        const postHook = postHookForWire(options.postHook);
         const request = {
             idempotencyKey: options.idempotencyKey ?? generateIdempotencyKey(),
             // Always include `provider` on the wire so dashboard / proxy
@@ -427,7 +644,6 @@ export class AgentExecutor {
             submission,
             ...(options.runtimeSize ? { runtimeSize: options.runtimeSize } : {}),
             ...(options.timeout ? { timeout: options.timeout } : {}),
-            ...(postHook ? { postHook } : {}),
             ...(options.parentRunId ? { parentRunId: options.parentRunId } : {}),
             // Operational/delivery concern — sibling of idempotencyKey, NOT part of
             // the hashed brief. The idempotency key here is randomly generated, so
@@ -445,6 +661,80 @@ export class AgentExecutor {
         const run = await operations.submitRun(this.#http, request);
         return getSubmittedRunId(run);
     }
+    async #buildSessionCreateRequest(options) {
+        if (!options || typeof options !== "object") {
+            throw new RunConfigValidationError("Aex.openSession: options is required");
+        }
+        assertNoLegacySessionFields(options, "Aex.openSession");
+        const supportedProviders = providersForModel(options.model);
+        if (options.provider &&
+            supportedProviders.length > 0 &&
+            !supportedProviders.includes(options.provider)) {
+            throw new RunConfigValidationError(`Aex.openSession: provider ${JSON.stringify(options.provider)} is not available for ` +
+                `model ${JSON.stringify(options.model)} (supported: ${supportedProviders.join(", ")})`);
+        }
+        const provider = options.provider ?? supportedProviders[0] ?? DEFAULT_RUN_PROVIDER;
+        validateApiKeys(options.apiKeys, provider, "Aex.openSession");
+        if (typeof options.model !== "string" || !options.model) {
+            throw new RunConfigValidationError("Aex.openSession: model is required");
+        }
+        const { endpoints: proxyEndpointDeclarations, auth: proxyEndpointAuthFromInstances } = splitProxyEndpoints(options.proxyEndpoints ?? []);
+        const mergedProxyAuth = mergeProxyEndpointAuth(proxyEndpointAuthFromInstances, []);
+        const { declarations: secretEnvDeclarations, values: envSecretValues } = splitSecretEnv(options.environment?.secrets);
+        let limits;
+        try {
+            limits = parseRunLimits(options.overrides?.maxSpendUsd === undefined
+                ? undefined
+                : { maxSpendUsd: options.overrides.maxSpendUsd });
+        }
+        catch (err) {
+            throw new AexError("RUN_CONFIG_INVALID", `Aex.openSession: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const uploader = (args) => this._uploadAsset(args);
+        const preparedSkills = await prepareSkills(options.skills ?? [], uploader);
+        const preparedTools = await prepareTools(options.tools ?? [], uploader);
+        const preparedAgentsMd = await prepareAgentsMd(options.agentsMd ?? [], uploader);
+        const preparedFiles = await prepareFiles(options.files ?? [], uploader);
+        const { submissionMcpServers, mergedMcpSecrets } = mergeMcpServers(options.mcpServers ?? [], []);
+        const outputCapture = outputsForWire(options.outputs);
+        const environment = sessionEnvironmentForWire(options.environment);
+        const submission = {
+            model: options.model,
+            ...(options.system ? { system: options.system } : {}),
+            skills: preparedSkills,
+            tools: [...preparedTools.builtinNames, ...preparedTools.refs],
+            agentsMd: preparedAgentsMd,
+            files: preparedFiles,
+            mcpServers: submissionMcpServers,
+            ...(Object.keys(secretEnvDeclarations).length > 0 ? { secretEnv: secretEnvDeclarations } : {}),
+            ...(environment ? { environment: environment } : {}),
+            ...(options.metadata ? { metadata: options.metadata } : {}),
+            ...(outputCapture ? { outputs: outputCapture } : {}),
+            ...(options.includeBuiltinTools !== undefined
+                ? { includeBuiltinTools: options.includeBuiltinTools }
+                : {}),
+            ...(options.outputMode !== undefined ? { outputMode: options.outputMode } : {})
+        };
+        const secrets = {
+            ...(options.apiKeys ? { apiKeys: options.apiKeys } : {}),
+            ...(mergedMcpSecrets.length > 0 ? { mcpServers: mergedMcpSecrets } : {}),
+            ...(mergedProxyAuth.length > 0 ? { proxyEndpointAuth: mergedProxyAuth } : {}),
+            ...(Object.keys(envSecretValues).length > 0 ? { envSecrets: envSecretValues } : {})
+        };
+        const retention = sessionRetentionForWire(options);
+        return {
+            provider,
+            submission,
+            ...(options.runtime ? { runtimeSize: options.runtime } : {}),
+            ...(options.overrides?.timeout ? { timeout: options.overrides.timeout } : {}),
+            ...(limits ? { limits } : {}),
+            retention,
+            secrets,
+            ...(proxyEndpointDeclarations.length > 0
+                ? { proxyEndpoints: proxyEndpointDeclarations }
+                : {})
+        };
+    }
     getRun(runId) {
         return operations.getRun(this.#http, runId);
     }
@@ -743,6 +1033,9 @@ export class AgentExecutor {
         return writeOptionalFile(await operations.downloadMetadata(this.#http, runId), options?.to);
     }
 }
+/** Canonical SDK client name. `AgentExecutor` remains as a compatibility alias. */
+export class Aex extends AgentExecutor {
+}
 // `Run.status` is a loose `string` on the wire shape, so we membership-test
 // against the canonical terminal set rather than re-deriving one (which is how
 // `timed_out` got dropped from the old hardcoded list).
@@ -750,6 +1043,31 @@ const TERMINAL_STATUSES = new Set(TERMINAL_RUN_STATUSES);
 function isTerminal(status) {
     return typeof status === "string" && TERMINAL_STATUSES.has(status);
 }
+function sessionToRun(session) {
+    const id = session.sessionId ?? session.id;
+    return {
+        id,
+        status: String(session.status),
+        ...(typeof session.workspaceId === "string" ? { workspaceId: session.workspaceId } : {}),
+        ...(typeof session.createdAt === "string" ? { createdAt: session.createdAt } : {}),
+        ...(typeof session.updatedAt === "string" ? { updatedAt: session.updatedAt } : {}),
+        ...(session.errorMessage !== undefined ? { errorMessage: session.errorMessage } : {}),
+        ...(session.usage ? { usage: session.usage } : {})
+    };
+}
+function scopedAbortSignal(timeoutMs) {
+    if (timeoutMs === undefined) {
+        return undefined;
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), Math.max(0, timeoutMs));
+    return {
+        signal: controller.signal,
+        clear() {
+            clearTimeout(timer);
+        }
+    };
+}
 /** Escape a literal string for safe interpolation into a RegExp. */
 function escapeRegExp(input) {
     return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -830,49 +1148,104 @@ function generateIdempotencyKey() {
         return cryptoObj.randomUUID();
     return `idem-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
 }
-function normalisePrompt(input) {
+function normalisePrompt(input, surface = "AgentExecutor.submit", field = "prompt") {
     if (typeof input === "string") {
         if (!input) {
-            throw new RunConfigValidationError("AgentExecutor.submit: prompt must be a non-empty string");
+            throw new RunConfigValidationError(`${surface}: ${field} must be a non-empty string`);
         }
         return [input];
     }
     if (!Array.isArray(input) || input.length === 0) {
-        throw new RunConfigValidationError("AgentExecutor.submit: prompt must be a non-empty string or string array");
+        throw new RunConfigValidationError(`${surface}: ${field} must be a non-empty string or string array`);
     }
     for (const segment of input) {
         if (typeof segment !== "string" || !segment) {
-            throw new RunConfigValidationError("AgentExecutor.submit: prompt segments must be non-empty strings");
+            throw new RunConfigValidationError(`${surface}: ${field} segments must be non-empty strings`);
         }
     }
     return [...input];
 }
-function assertNoRemovedSubmitFields(options) {
+function normaliseSessionInput(input, surface, field) {
+    if (typeof input === "string") {
+        if (!input) {
+            throw new RunConfigValidationError(`${surface}: ${field} must be a non-empty string`);
+        }
+        return input;
+    }
+    if (!Array.isArray(input) || input.length === 0) {
+        throw new RunConfigValidationError(`${surface}: ${field} must be a non-empty string or string array`);
+    }
+    for (const segment of input) {
+        if (typeof segment !== "string" || !segment) {
+            throw new RunConfigValidationError(`${surface}: ${field} segments must be non-empty strings`);
+        }
+    }
+    return [...input];
+}
+function assertNoRemovedSubmitFields(options, surface, extraFields = []) {
     const record = options;
-    for (const field of ["credentialMode", "runtime", "region", "apiKey", "credentials"]) {
+    for (const field of ["credentialMode", "runtime", "region", "apiKey", "credentials", "postHook", ...extraFields]) {
         if (Object.prototype.hasOwnProperty.call(record, field)) {
-            throw new RunConfigValidationError(`AgentExecutor.submit: ${field} is not a supported option; use the managed path with secrets.apiKeys[provider].`);
+            throw new RunConfigValidationError(`${surface}: ${field} is not a supported option; use the managed path with secrets.apiKeys[provider].`);
         }
     }
     const secrets = record.secrets;
     if (secrets && typeof secrets === "object" && !Array.isArray(secrets) && Object.prototype.hasOwnProperty.call(secrets, "apiKey")) {
-        throw new RunConfigValidationError("AgentExecutor.submit: secrets.apiKey is not supported; use secrets.apiKeys[provider].");
+        throw new RunConfigValidationError(`${surface}: secrets.apiKey is not supported; use secrets.apiKeys[provider].`);
+    }
+}
+function assertNoLegacySessionFields(options, surface) {
+    const record = options;
+    const messages = {
+        input: "send user messages with session.send(...) or use run({ message }).",
+        prompt: "use message for one-shot run input or session.send(...) for follow-up messages.",
+        instructions: "use system.",
+        idleSuspendAfter: "use overrides.idleTtl.",
+        idleTtl: "use overrides.idleTtl.",
+        retention: "use overrides.idleTtl.",
+        secretEnv: "use environment.secrets.",
+        secrets: "use top-level apiKeys for provider keys and environment.secrets for run secrets.",
+        runtimeSize: "use runtime.",
+        parentRunId: "subagents are session-internal; parentRunId is not part of the session API.",
+        limits: "use overrides.",
+        timeout: "use overrides.timeout.",
+        signal: "use session.cancel() / session.suspend() for remote control.",
+        postHook: "send a follow-up validation message when the session returns idle.",
+        webhook: "send a follow-up validation message instead of a submit webhook."
+    };
+    for (const [field, message] of Object.entries(messages)) {
+        if (Object.prototype.hasOwnProperty.call(record, field)) {
+            throw new RunConfigValidationError(`${surface}: ${field} is not a supported option; ${message}`);
+        }
+    }
+    const overrides = record.overrides;
+    if (overrides && typeof overrides === "object" && !Array.isArray(overrides)) {
+        const overrideRecord = overrides;
+        if (Object.prototype.hasOwnProperty.call(overrideRecord, "idleSuspendAfter")) {
+            throw new RunConfigValidationError(`${surface}: overrides.idleSuspendAfter is not a supported option; use overrides.idleTtl.`);
+        }
     }
 }
-function validateSubmitCredentials(options, provider) {
+function assertNoSessionSendSignal(options, surface) {
+    const record = options;
+    if (record && typeof record === "object" && Object.prototype.hasOwnProperty.call(record, "signal")) {
+        throw new RunConfigValidationError(`${surface}: signal is not a supported option; use session.cancel() / session.suspend() for remote control.`);
+    }
+}
+function validateSubmitCredentials(options, provider, surface) {
     if (options.parentRunId) {
         return;
     }
     const key = options.secrets?.apiKeys?.[provider];
     if (typeof key !== "string" || key.length === 0) {
-        throw new RunConfigValidationError(`AgentExecutor.submit: a provider API key is required — pass secrets.apiKeys[${JSON.stringify(provider)}].`);
+        throw new RunConfigValidationError(`${surface}: a provider API key is required — pass secrets.apiKeys[${JSON.stringify(provider)}].`);
     }
 }
-function postHookForWire(input) {
-    if (input === undefined || typeof input.command !== "string" || input.command.trim().length === 0) {
-        return undefined;
+function validateApiKeys(apiKeys, provider, surface) {
+    const key = apiKeys?.[provider];
+    if (typeof key !== "string" || key.length === 0) {
+        throw new RunConfigValidationError(`${surface}: a provider API key is required — pass apiKeys[${JSON.stringify(provider)}].`);
     }
-    return input;
 }
 function outputsForWire(outputs) {
     if (outputs === undefined) {
@@ -896,6 +1269,24 @@ function outputsForWire(outputs) {
         ...(outputs.maxFiles !== undefined ? { maxFiles: outputs.maxFiles } : {})
     };
 }
+const DEFAULT_SESSION_IDLE_TTL = "3m";
+function sessionRetentionForWire(options) {
+    return {
+        idleTtl: options.overrides?.idleTtl ?? DEFAULT_SESSION_IDLE_TTL
+    };
+}
+function sessionEnvironmentForWire(environment) {
+    if (environment === undefined) {
+        return undefined;
+    }
+    const { variables, secrets: _secrets, ...rest } = environment;
+    void _secrets;
+    const out = {
+        ...rest,
+        ...(variables !== undefined ? { envVars: variables } : {})
+    };
+    return Object.keys(out).length === 0 ? undefined : out;
+}
 /**
  * Resolve a draft's asset id: reuse the cached id from a prior submit, otherwise
  * upload the bytes and cache the result on the instance.