@cursor/bdk 0.2.1

package/dist/internal/hosted-delivery-protocol.js

@@ -0,0 +1,516 @@
+export const HOSTED_DELIVERY_PROTOCOL_VERSION = 2;
+export const HOSTED_DELIVERY_HEADER = "x-agent-sdk-hosted-delivery";
+export const HOSTED_ADMISSION_PATH = "/v1/internal/hosted-admission";
+export const HOSTED_EXECUTION_PATH = "/v1/internal/hosted-execution";
+export const HOSTED_GUEST_RETRY_TRANSIENT = "transient";
+export const HOSTED_GUEST_RETRY_TERMINAL = "terminal";
+export const HOSTED_FAILURE_CLASSIFICATION_VERSION = 1;
+const HOSTED_FAILURE_DOMAINS = new Set([
+    "configuration",
+    "protocol",
+    "platform",
+    "agent",
+    "dependency",
+    "cancellation",
+    "unknown",
+]);
+const HOSTED_FAILURE_SOURCES = new Set([
+    "tas",
+    "factory",
+    "anyrun",
+    "engine",
+    "agent",
+]);
+export const HOSTED_FAILURE_CLASSIFICATIONS = {
+    agent_admission_threw: { domain: "agent", source: "agent" },
+    agent_dependency_failed: { domain: "dependency", source: "factory" },
+    background_dispatch_failed: { domain: "agent", source: "agent" },
+    bound_secrets_not_consumed: { domain: "platform", source: "engine" },
+    channel_dispatch_failed: { domain: "agent", source: "agent" },
+    channel_kind_mismatch: { domain: "configuration", source: "engine" },
+    channel_not_found: { domain: "configuration", source: "engine" },
+    channel_outcome_missing: { domain: "protocol", source: "agent" },
+    forbidden: { domain: "configuration", source: "engine" },
+    guest_connect_stalled: { domain: "platform", source: "engine" },
+    guest_network_unavailable: { domain: "platform", source: "anyrun" },
+    hosted_admission_session_mismatch: { domain: "protocol", source: "engine" },
+    hosted_admission_unavailable: { domain: "platform", source: "engine" },
+    hosted_deferred_session_unusable: { domain: "agent", source: "agent" },
+    hosted_local_send_rejected: { domain: "agent", source: "agent" },
+    hosted_send_limit_exceeded: { domain: "agent", source: "agent" },
+    internal_error: { domain: "unknown", source: "engine" },
+    invalid_hosted_admission: { domain: "protocol", source: "engine" },
+    invalid_hosted_execution: { domain: "protocol", source: "engine" },
+    invalid_request: { domain: "protocol", source: "engine" },
+    method_not_allowed: { domain: "protocol", source: "engine" },
+    not_found: { domain: "protocol", source: "engine" },
+    session_busy: { domain: "platform", source: "engine" },
+    turn_cancelled: { domain: "cancellation", source: "agent" },
+    turn_failed: { domain: "agent", source: "agent" },
+    unauthorized: { domain: "configuration", source: "engine" },
+    unpaid_invoice: { domain: "configuration", source: "agent" },
+    usage_limit: { domain: "configuration", source: "agent" },
+    v2_identity_conflict: { domain: "protocol", source: "engine" },
+};
+export function hostedFailureClassification(code) {
+    var _a, _b;
+    const known = HOSTED_FAILURE_CLASSIFICATIONS[code];
+    return {
+        v: HOSTED_FAILURE_CLASSIFICATION_VERSION,
+        domain: (_a = known === null || known === void 0 ? void 0 : known.domain) !== null && _a !== void 0 ? _a : "unknown",
+        source: (_b = known === null || known === void 0 ? void 0 : known.source) !== null && _b !== void 0 ? _b : "engine",
+    };
+}
+export function parseHostedFailureClassification(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return undefined;
+    }
+    const body = value;
+    if (body.v !== HOSTED_FAILURE_CLASSIFICATION_VERSION ||
+        typeof body.domain !== "string" ||
+        !HOSTED_FAILURE_DOMAINS.has(body.domain) ||
+        typeof body.source !== "string" ||
+        !HOSTED_FAILURE_SOURCES.has(body.source)) {
+        return undefined;
+    }
+    return body;
+}
+/**
+ * Hosted delivery is the only HTTP surface whose failures drive Temporal
+ * retries. Keep its retry disposition explicit instead of making the shared
+ * HTTP error helper guess from a status code.
+ */
+export function hostedGuestErrorResponse(input) {
+    const body = {
+        ok: false,
+        error: input.error,
+        retry: input.retry,
+        classification: hostedFailureClassification(input.error),
+        message: input.message,
+        turnStatus: input.turnStatus,
+        errorCode: input.errorCode,
+    };
+    return Response.json(body, { status: input.status });
+}
+/**
+ * Filename under the serve `--state-root` (not the per-slug SessionEngine
+ * dir). Hosted freeze uses `/workspace/.agent-serve`; the Temporal host
+ * reads this path after hosted-execution and logs it on the activity span.
+ * Must match `AGENT_SERVE_ENGINE_HOSTED_EXECUTION_DIAG_PATH` basename.
+ */
+export const HOSTED_EXECUTION_DIAG_FILENAME = "hosted-execution.json";
+/**
+ * Reserved hosted-admission `channelKind` for durable reminder fires.
+ * Bypasses authored channel admission and invokes ReminderRunner.dispatch.
+ * Backend builds envelopes with this constant + {@link HOSTED_REMINDER_EVENT_TYPE}.
+ */
+export const HOSTED_REMINDER_CHANNEL_KIND = "agent-sdk:reminder";
+/**
+ * Reserved hosted-admission `eventType` for durable reminder fires.
+ * Payload is {@link HostedReminderFirePayload}.
+ */
+export const HOSTED_REMINDER_EVENT_TYPE = "agent-sdk.reminder/fire";
+/**
+ * Cap on delivery IDs an owner execute may report as consumed (primary +
+ * accepted active-guest enqueues). Enqueue requests beyond this return
+ * `not_active`.
+ */
+export const HOSTED_MAX_CONSUMED_DELIVERY_IDS = 16;
+const DELIVERY_KEYS = new Set([
+    "v",
+    "channelId",
+    "channelKind",
+    "eventType",
+    "deliveryId",
+    "sessionMode",
+    "mailboxContinuationKey",
+    "payload",
+    "managedAutomation",
+    "platformHandoff",
+]);
+const MANAGED_AUTOMATION_KEYS = new Set(["automationUuid", "mcpServerNames", "slackChannels"]);
+export const HOSTED_PLATFORM_HANDOFF_KEYS = new Set(["v", "slackPlaceholder"]);
+export const HOSTED_SLACK_PLACEHOLDER_HANDOFF_KEYS = new Set([
+    "messageTs",
+    "channelId",
+    "threadTs",
+    "streamed",
+]);
+/** More names than any real automation configures is a malformed envelope. */
+const MANAGED_AUTOMATION_MAX_SERVERS = 64;
+/** More channels than the dashboard picker allows is a malformed envelope. */
+const MANAGED_AUTOMATION_MAX_SLACK_CHANNELS = 64;
+const EXECUTION_KEYS = new Set(["v", "admissionToken", "sessionPublicId", "mode"]);
+function boundedString(value, max) {
+    return typeof value === "string" && value.length > 0 && value.length <= max;
+}
+/**
+ * Parse the optional managed-automation slice. Absent → valid (undefined);
+ * present-but-malformed → invalid (the whole admission fails closed, the
+ * strict posture the rest of the envelope already takes).
+ */
+function parseManagedAutomation(value) {
+    if (value === undefined) {
+        return {};
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return undefined;
+    }
+    const body = value;
+    if (Object.keys(body).some(key => !MANAGED_AUTOMATION_KEYS.has(key)) ||
+        !boundedString(body.automationUuid, 128) ||
+        !Array.isArray(body.mcpServerNames) ||
+        body.mcpServerNames.length > MANAGED_AUTOMATION_MAX_SERVERS ||
+        !body.mcpServerNames.every(name => boundedString(name, 256))) {
+        return undefined;
+    }
+    if (body.slackChannels !== undefined) {
+        if (!Array.isArray(body.slackChannels) ||
+            body.slackChannels.length === 0 ||
+            body.slackChannels.length > MANAGED_AUTOMATION_MAX_SLACK_CHANNELS ||
+            !body.slackChannels.every(channel => boundedString(channel, 64))) {
+            return undefined;
+        }
+    }
+    return {
+        managedAutomation: Object.assign({ automationUuid: body.automationUuid, mcpServerNames: body.mcpServerNames }, (body.slackChannels === undefined
+            ? {}
+            : { slackChannels: body.slackChannels })),
+    };
+}
+/**
+ * Parse optional control-plane Slack placeholder handoff. Absent → valid;
+ * present-but-malformed → invalid (fail closed like managedAutomation).
+ */
+function parsePlatformHandoff(value) {
+    if (value === undefined) {
+        return {};
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return undefined;
+    }
+    const body = value;
+    if (Object.keys(body).some(key => !HOSTED_PLATFORM_HANDOFF_KEYS.has(key)) || body.v !== 1) {
+        return undefined;
+    }
+    const placeholder = body.slackPlaceholder;
+    if (typeof placeholder !== "object" || placeholder === null || Array.isArray(placeholder)) {
+        return undefined;
+    }
+    const slot = placeholder;
+    if (Object.keys(slot).some(key => !HOSTED_SLACK_PLACEHOLDER_HANDOFF_KEYS.has(key)) ||
+        !boundedString(slot.messageTs, 64) ||
+        !boundedString(slot.channelId, 64) ||
+        !boundedString(slot.threadTs, 64) ||
+        slot.streamed !== false) {
+        return undefined;
+    }
+    return {
+        platformHandoff: {
+            v: 1,
+            slackPlaceholder: {
+                messageTs: slot.messageTs,
+                channelId: slot.channelId,
+                threadTs: slot.threadTs,
+                streamed: slot.streamed,
+            },
+        },
+    };
+}
+export function parseHostedAdmission(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return undefined;
+    }
+    const body = value;
+    if (Object.keys(body).some(key => !DELIVERY_KEYS.has(key)) ||
+        !Object.hasOwn(body, "payload") ||
+        body.v !== HOSTED_DELIVERY_PROTOCOL_VERSION ||
+        !boundedString(body.channelId, 128) ||
+        !boundedString(body.channelKind, 128) ||
+        !boundedString(body.eventType, 128) ||
+        !boundedString(body.deliveryId, 256) ||
+        (body.sessionMode !== "event" && body.sessionMode !== "continuation") ||
+        !boundedString(body.mailboxContinuationKey, 512) ||
+        parseManagedAutomation(body.managedAutomation) === undefined ||
+        parsePlatformHandoff(body.platformHandoff) === undefined) {
+        return undefined;
+    }
+    const prefix = body.sessionMode === "event" ? "evt:" : "cont:";
+    return body.mailboxContinuationKey.startsWith(prefix) ? body : undefined;
+}
+export function parseHostedExecution(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return undefined;
+    }
+    const body = value;
+    if (Object.keys(body).some(key => !EXECUTION_KEYS.has(key)) ||
+        body.v !== HOSTED_DELIVERY_PROTOCOL_VERSION ||
+        !boundedString(body.admissionToken, 128) ||
+        typeof body.sessionPublicId !== "string" ||
+        !/^ses_[a-f0-9]{24}$/.test(body.sessionPublicId)) {
+        return undefined;
+    }
+    if (body.mode !== undefined && body.mode !== "execute" && body.mode !== "enqueue") {
+        return undefined;
+    }
+    return body;
+}
+const HOSTED_EXECUTION_OUTCOME_KEYS = new Set(["ok", "v", "outcome", "consumedDeliveryIds"]);
+function parseConsumedDeliveryIds(value) {
+    if (!Array.isArray(value) || value.length === 0) {
+        return undefined;
+    }
+    if (value.length > HOSTED_MAX_CONSUMED_DELIVERY_IDS) {
+        return undefined;
+    }
+    if (!value.every(id => boundedString(id, 256))) {
+        return undefined;
+    }
+    return value;
+}
+export function parseHostedExecutionOutcome(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return undefined;
+    }
+    const body = value;
+    if (Object.keys(body).some(key => !HOSTED_EXECUTION_OUTCOME_KEYS.has(key)) ||
+        body.ok !== true ||
+        body.v !== HOSTED_DELIVERY_PROTOCOL_VERSION) {
+        return undefined;
+    }
+    if (body.outcome === "enqueued" || body.outcome === "not_active") {
+        if (body.consumedDeliveryIds !== undefined) {
+            return undefined;
+        }
+        return body;
+    }
+    if (body.outcome !== "send") {
+        return undefined;
+    }
+    // Old guests omit consumedDeliveryIds; accept and let callers normalize.
+    if (body.consumedDeliveryIds === undefined) {
+        return { ok: true, v: 2, outcome: "send" };
+    }
+    const consumedDeliveryIds = parseConsumedDeliveryIds(body.consumedDeliveryIds);
+    if (consumedDeliveryIds === undefined) {
+        return undefined;
+    }
+    return {
+        ok: true,
+        v: 2,
+        outcome: "send",
+        consumedDeliveryIds,
+    };
+}
+/**
+ * True when the admission envelope is the reserved internal reminder fire
+ * path (not an authored channel event).
+ */
+export function isHostedReminderAdmission(delivery) {
+    return (delivery.channelKind === HOSTED_REMINDER_CHANNEL_KIND &&
+        delivery.eventType === HOSTED_REMINDER_EVENT_TYPE);
+}
+/**
+ * Parse `{ reminderId, fireCount }` from a reserved reminder admission
+ * payload. Rejects unknown keys and non-integer fireCount.
+ */
+export function parseHostedReminderFirePayload(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return undefined;
+    }
+    const body = value;
+    const keys = Object.keys(body);
+    if (keys.length !== 2 ||
+        !Object.hasOwn(body, "reminderId") ||
+        !Object.hasOwn(body, "fireCount") ||
+        !boundedString(body.reminderId, 128) ||
+        typeof body.fireCount !== "number" ||
+        !Number.isInteger(body.fireCount) ||
+        body.fireCount < 0) {
+        return undefined;
+    }
+    return {
+        reminderId: body.reminderId,
+        fireCount: body.fireCount,
+    };
+}
+const HOSTED_REMINDER_FIRE_DESCRIPTOR_KEYS = new Set([
+    "protocolVersion",
+    "id",
+    "fireCount",
+    "generation",
+    "purpose",
+    "channelId",
+    "continuationToken",
+    "target",
+    "scheduleKind",
+    "scheduleValue",
+    "intervalMs",
+    "prompt",
+    "handler",
+    "args",
+    "hasRunHandler",
+    "hasUntilFn",
+    "untilPrompt",
+    "busyPolicy",
+    "nextFireAtMs",
+    "claimedAtMs",
+]);
+const HOSTED_REMINDER_SCHEDULE_KINDS = new Set(["every", "cron", "delay", "at"]);
+const HOSTED_REMINDER_BUSY_POLICIES = new Set(["skipIfBusy", "queueBehindTurn"]);
+const HOSTED_REMINDER_JSON_MAX_DEPTH = 8;
+/** Reject non-JSON values (NaN/Infinity/undefined/bigint/function/symbol). */
+function isJsonSafeValue(value, depth) {
+    if (depth > HOSTED_REMINDER_JSON_MAX_DEPTH) {
+        return false;
+    }
+    if (value === null) {
+        return true;
+    }
+    const type = typeof value;
+    if (type === "string" || type === "boolean") {
+        return true;
+    }
+    if (type === "number") {
+        return Number.isFinite(value);
+    }
+    if (type !== "object") {
+        return false;
+    }
+    if (Array.isArray(value)) {
+        return value.every(entry => isJsonSafeValue(entry, depth + 1));
+    }
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null) {
+        return false;
+    }
+    for (const entry of Object.values(value)) {
+        if (!isJsonSafeValue(entry, depth + 1)) {
+            return false;
+        }
+    }
+    return true;
+}
+function parseOptionalJsonObjectField(value, maxBytes) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return undefined;
+    }
+    if (!isJsonSafeValue(value, 0)) {
+        return undefined;
+    }
+    try {
+        const encoded = JSON.stringify(value);
+        if (encoded === undefined || Buffer.byteLength(encoded, "utf8") > maxBytes) {
+            return undefined;
+        }
+        const roundTrip = JSON.parse(encoded);
+        if (typeof roundTrip !== "object" || roundTrip === null || Array.isArray(roundTrip)) {
+            return undefined;
+        }
+        return roundTrip;
+    }
+    catch (_a) {
+        return undefined;
+    }
+}
+/**
+ * Parse the immutable CP fire descriptor. Rejects unknown keys, non-enum
+ * schedule/busy values, and non-JSON-safe optional object fields.
+ */
+export function parseHostedReminderFireDescriptorPayload(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return undefined;
+    }
+    const body = value;
+    if (Object.keys(body).some(key => !HOSTED_REMINDER_FIRE_DESCRIPTOR_KEYS.has(key))) {
+        return undefined;
+    }
+    if (body.protocolVersion !== 1 ||
+        typeof body.id !== "string" ||
+        body.id.length === 0 ||
+        body.id.length > 128 ||
+        typeof body.fireCount !== "number" ||
+        !Number.isInteger(body.fireCount) ||
+        body.fireCount < 0 ||
+        typeof body.generation !== "number" ||
+        !Number.isInteger(body.generation) ||
+        body.generation < 0 ||
+        typeof body.purpose !== "string" ||
+        body.purpose.length === 0 ||
+        body.purpose.length > 512 ||
+        typeof body.channelId !== "string" ||
+        body.channelId.length === 0 ||
+        body.channelId.length > 128 ||
+        typeof body.continuationToken !== "string" ||
+        body.continuationToken.length === 0 ||
+        body.continuationToken.length > 512 ||
+        typeof body.scheduleKind !== "string" ||
+        !HOSTED_REMINDER_SCHEDULE_KINDS.has(body.scheduleKind) ||
+        typeof body.scheduleValue !== "string" ||
+        body.scheduleValue.length === 0 ||
+        body.scheduleValue.length > 512 ||
+        typeof body.hasRunHandler !== "boolean" ||
+        typeof body.hasUntilFn !== "boolean" ||
+        typeof body.busyPolicy !== "string" ||
+        !HOSTED_REMINDER_BUSY_POLICIES.has(body.busyPolicy) ||
+        typeof body.nextFireAtMs !== "number" ||
+        !Number.isFinite(body.nextFireAtMs) ||
+        typeof body.claimedAtMs !== "number" ||
+        !Number.isFinite(body.claimedAtMs) ||
+        !Number.isInteger(body.claimedAtMs) ||
+        body.claimedAtMs < 0) {
+        return undefined;
+    }
+    if (body.intervalMs !== undefined) {
+        if (typeof body.intervalMs !== "number" ||
+            !Number.isFinite(body.intervalMs) ||
+            !Number.isInteger(body.intervalMs) ||
+            body.intervalMs <= 0) {
+            return undefined;
+        }
+    }
+    if (body.prompt !== undefined) {
+        if (typeof body.prompt !== "string" || body.prompt.length > 8192) {
+            return undefined;
+        }
+    }
+    if (body.handler !== undefined) {
+        if (typeof body.handler !== "string" ||
+            body.handler.length === 0 ||
+            body.handler.length > 128) {
+            return undefined;
+        }
+    }
+    if (body.untilPrompt !== undefined) {
+        if (typeof body.untilPrompt !== "string" || body.untilPrompt.length > 8192) {
+            return undefined;
+        }
+    }
+    const target = parseOptionalJsonObjectField(body.target, 16 * 1024);
+    if (body.target !== undefined && target === undefined) {
+        return undefined;
+    }
+    const args = parseOptionalJsonObjectField(body.args, 32 * 1024);
+    if (body.args !== undefined && args === undefined) {
+        return undefined;
+    }
+    return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ protocolVersion: 1, id: body.id, fireCount: body.fireCount, generation: body.generation, purpose: body.purpose, channelId: body.channelId, continuationToken: body.continuationToken }, (target === undefined ? {} : { target })), { scheduleKind: body.scheduleKind, scheduleValue: body.scheduleValue }), (body.intervalMs === undefined ? {} : { intervalMs: body.intervalMs })), (body.prompt === undefined ? {} : { prompt: body.prompt })), (body.handler === undefined ? {} : { handler: body.handler })), (args === undefined ? {} : { args })), { hasRunHandler: body.hasRunHandler, hasUntilFn: body.hasUntilFn }), (body.untilPrompt === undefined ? {} : { untilPrompt: body.untilPrompt })), { busyPolicy: body.busyPolicy, nextFireAtMs: body.nextFireAtMs, claimedAtMs: body.claimedAtMs });
+}
+export function parseHostedAdmissionOutcome(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return undefined;
+    }
+    const body = value;
+    if (body.ok !== true ||
+        body.v !== HOSTED_DELIVERY_PROTOCOL_VERSION ||
+        (body.outcome !== "skip" && body.outcome !== "send" && body.outcome !== "task")) {
+        return undefined;
+    }
+    if (body.outcome === "send" && !boundedString(body.admissionToken, 128)) {
+        return undefined;
+    }
+    return body;
+}

package/dist/internal/hosted-delivery.d.ts

@@ -0,0 +1,110 @@
+import type { ChannelHandlerArgs, SendMessageOptions } from "../types.js";
+import { type HostedBoundSecretsResult } from "./cursor/hosted-bound-secrets.js";
+import { type GuestNetworkWaitResult } from "./guest-network.js";
+import { type HostedAdmission, type HostedReminderFireDescriptorPayload } from "./hosted-delivery-protocol.js";
+import type { LogRingEntry } from "./log-ring.js";
+import type { Router } from "./router.js";
+import type { SessionRunExecutionWrite } from "./session-run-log.js";
+type DispatchInput = {
+    delivery: HostedAdmission;
+    definition: object;
+    args: ChannelHandlerArgs;
+};
+type PendingSend = {
+    channelId: string;
+    message: string;
+    options: SendMessageOptions;
+    mailboxContinuationKey: string;
+};
+type AdmissionDispatch = {
+    response: Response;
+    pendingSend?: PendingSend;
+};
+/**
+ * Run authored admission without creating a framework session. Authored
+ * `task` callbacks execute as sessionless work; the first `send` is captured
+ * and executed only after the control plane allocates `ses_…`. Capturing
+ * does not terminate the caller — `send` returns an inert deferred handle so
+ * a task body runs to completion before the admission response is computed.
+ *
+ * Dispatch is the adapter the mounted channel attached. Hosted delivery
+ * does not switch on `channelKind`.
+ */
+export declare function dispatchHostedAdmission(input: DispatchInput): Promise<AdmissionDispatch>;
+export declare function registerHostedDeliveryRoute(input: {
+    router: Router;
+    base: string;
+    channels: Array<{
+        id: string;
+        definition: object;
+    }>;
+    buildHandlerArgs(channelId: string, sessionPublicId?: string): ChannelHandlerArgs;
+    /**
+     * Reserved reminder admission: dispatch a hydrated ReminderRunner fire
+     * without authored channel admission. Returns the runner's outcome so the
+     * route can map fired → task and noop → skip.
+     */
+    fireReminder?(reminderId: string, expectedFireCount: number): Promise<{
+        reminderId: string;
+        outcome: "fired" | "noop";
+        reason?: string;
+    }>;
+    /**
+     * Architecture v2: execute an immutable CP fire descriptor and apply the
+     * structured outcome via the hosted ReminderControlPlane client.
+     */
+    executeReminderDescriptor?(descriptor: HostedReminderFireDescriptorPayload): Promise<{
+        reminderId: string;
+        outcome: "fired" | "noop";
+        reason?: string;
+    }>;
+    /**
+     * Await the session's durable mirror (dispatch chain + storage queue)
+     * before the execution reply: the control plane may park the pod the
+     * moment the reply lands, and a shed session-record flush would strand
+     * the conversation on the next wake.
+     */
+    drainSessionDurability?(sessionId: string): Promise<void>;
+    /**
+     * Export in-memory OTel batches before the HTTP reply. Hosted v2 may
+     * destroy the VM as soon as that reply lands; SIGTERM is not guaranteed.
+     */
+    flushOtel?(): Promise<void>;
+    /**
+     * Serve `--state-root` (not the per-slug SessionEngine dir). Hosted
+     * freeze is `/workspace/.agent-serve`; the Temporal host reads
+     * `hosted-execution.json` from that path after the POST returns.
+     */
+    stateRoot?: string;
+    /**
+     * Upsert this execution into the v2 session-level framework-store log.
+     * Called for the pre-turn `running` claim and every terminal outcome so
+     * a dead Node process still leaves a leftover. Soft-fail inside the
+     * store; this path still awaits so a parked pod cannot shed the write.
+     */
+    persistSessionRun?(write: SessionRunExecutionWrite): Promise<void>;
+    /** Snapshot the local `start.log` tee onto `logs/{ses_…}`. */
+    flushStartLog?(startLogId: string): Promise<void>;
+    /** Snapshot of the process log ring at persist time. */
+    snapshotLogs?(): LogRingEntry[];
+    /**
+     * Drop the cached SDK agent handle before the HTTP reply. Hosted v2
+     * hibernates this process as soon as the reply lands; leaving the handle
+     * in memory freezes a dead Connect/HTTP2 session that the next wake
+     * then reuses.
+     */
+    evictSdkSession?(sessionId: string): void;
+    /**
+     * Wait until guest egress works before authored admission/execution.
+     * Defaults to {@link waitForGuestNetworkReady}. Tests inject a stub.
+     */
+    waitForGuestNetwork?(): Promise<GuestNetworkWaitResult | unknown>;
+    /**
+     * Hydrate `process.env` from the task-bind secret files and remove them
+     * from disk. Defaults to {@link consumeHostedBoundSecrets}. Tests inject a
+     * stub.
+     */
+    consumeBoundSecrets?(): HostedBoundSecretsResult;
+}): void;
+export {};
+//# sourceMappingURL=hosted-delivery.d.ts.map

package/dist/internal/hosted-delivery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosted-delivery.d.ts","sourceRoot":"","sources":["../../src/internal/hosted-delivery.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAc,kBAAkB,EAAE,kBAAkB,EAAe,MAAM,aAAa,CAAC;AAEnG,OAAO,EAEL,KAAK,wBAAwB,EAC9B,MAAM,kCAAkC,CAAC;AAO1C,OAAO,EAKL,KAAK,sBAAsB,EAG5B,MAAM,oBAAoB,CAAC;AAS5B,OAAO,EAQL,KAAK,eAAe,EAEpB,KAAK,mCAAmC,EAQzC,MAAM,+BAA+B,CAAC;AAmBvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAIlD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAErE,KAAK,aAAa,GAAG;IACnB,QAAQ,EAAE,eAAe,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,kBAAkB,CAAC;CAC1B,CAAC;AAEF,KAAK,WAAW,GAAG;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,kBAAkB,CAAC;IAC5B,sBAAsB,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF,KAAK,iBAAiB,GAAG;IACvB,QAAQ,EAAE,QAAQ,CAAC;IACnB,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B,CAAC;AAiHF;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAU9F;AAkQD,wBAAgB,2BAA2B,CAAC,KAAK,EAAE;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,kBAAkB,CAAC;IAClF;;;;OAIG;IACH,YAAY,CAAC,CACX,UAAU,EAAE,MAAM,EAClB,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC;QACT,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC;QAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;IACH;;;OAGG;IACH,yBAAyB,CAAC,CAAC,UAAU,EAAE,mCAAmC,GAAG,OAAO,CAAC;QACnF,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC;QAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;IACH;;;;;OAKG;IACH,sBAAsB,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D;;;OAGG;IACH,SAAS,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,iBAAiB,CAAC,CAAC,KAAK,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE,8DAA8D;IAC9D,aAAa,CAAC,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,wDAAwD;IACxD,YAAY,CAAC,IAAI,YAAY,EAAE,CAAC;IAChC;;;;;OAKG;IACH,eAAe,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C;;;OAGG;IACH,mBAAmB,CAAC,IAAI,OAAO,CAAC,sBAAsB,GAAG,OAAO,CAAC,CAAC;IAClE;;;;OAIG;IACH,mBAAmB,CAAC,IAAI,wBAAwB,CAAC;CAClD,GAAG,IAAI,CA0aP"}