eve 0.81.1 → 0.83.0

package/CHANGELOG.md

@@ -1,5 +1,98 @@
 # eve
 
+## 0.83.0
+
+### Minor Changes
+
+- 12a1e90: `DefaultSandbox` now selects its provider once, when eve prepares the sandbox, and records the choice in the build: Vercel Sandbox on Vercel, then Docker when a daemon is reachable, then just-bash only in `eve dev` and `eve eval`. The runtime uses the recorded provider instead of probing the host again, so a build and its server can no longer select different providers. A production `eve build` with neither Vercel nor Docker no longer falls back to just-bash: the build succeeds, and opening the sandbox fails with an error that asks you to start Docker and rebuild, deploy to Vercel, or select a provider explicitly.
+  
+  `DefaultSandbox.environment().open()` now accepts `networkPolicy`, and its sessions expose `setNetworkPolicy()`. eve forwards the policy to the selected provider. Docker rejects any policy other than `"allow-all"` or `"deny-all"` when it opens the sandbox, instead of starting the container with open network access, and just-bash rejects any policy other than `"allow-all"`.
+  
+  Sessions now record their sandbox under the provider name `"default"` instead of `vercel`, `docker`, or `just-bash`. Sessions saved by an earlier eve under the provider that `DefaultSandbox` selected resume the same sandbox. When a session's recorded state belongs to another provider or state protocol, for example after you change providers, eve now starts a fresh sandbox instead of failing; the old sandbox is not deleted. This upgrade is one-way: if you roll back to an earlier eve release, sessions created on this release fail to open their sandbox, because earlier releases reject state recorded under `"default"`.
+  
+  `VercelSandbox.environment()` no longer captures a snapshot when the environment has no `prepare` callback, no managed workspace or skill files, and no `source`. Session sandboxes start from the image and install the base runtime themselves, as `DefaultSandbox` already did on Vercel. Such sessions now apply a `networkPolicy` set on the environment after base setup; before, only a policy passed to `open()` applied, so `VercelSandbox.environment({ networkPolicy })` and `DefaultSandbox.environment({ vercel: { networkPolicy } })` could leave a session with open network access.
+- 62112b5: The just-bash sandbox provider now runs on the public `defineSandboxProvider()` API, and `customCommands` and `filesystem` use eve-owned types from `eve/sandbox/just-bash`, such as `JustBashCommand` and `JustBashFilesystem`, that still accept just-bash's `defineCommand()` results and filesystems. Local just-bash templates rebuild once after upgrading, since their keys no longer include custom commands or the filesystem; reading a directory now rejects instead of returning `null`, and a command ending in a `# comment` runs in any working directory.
+- 8b68a92: Remove the microsandbox sandbox provider. The `eve/sandbox/microsandbox` export and the `microsandbox` option on `DefaultSandbox.environment()` are gone, and `DefaultSandbox` now selects Vercel Sandbox on Vercel, then Docker when a daemon is reachable, then just-bash. To migrate, switch `MicrosandboxSandbox.image()` and `MicrosandboxSandbox.dockerfile()` to `DockerSandbox.image()` and `DockerSandbox.dockerfile()` from `eve/sandbox/docker`, and remove the `microsandbox` dependency. A session that recorded a microsandbox sandbox starts a fresh sandbox from its current provider on its next `ctx.getSandbox()`.
+  
+  eve no longer cleans up what microsandbox left on your machine. Before you uninstall `microsandbox`, use its tooling to remove sandboxes and snapshots whose names start with `eve-sbx-`. Then delete `.eve/sandbox-cache/microsandbox` in each app. If you used `MicrosandboxSandbox.dockerfile()`, also run `docker rm -f eve-sandbox-registry` to remove the local image registry it started, and remove the local images tagged `127.0.0.1:51921/eve/…`.
+  
+  Deployed self-modification (`eve/self-modification/remote`) now requires deploying on Vercel. Builds still succeed on any host, but in a deployment outside Vercel the deployed subagent fails with an error that names this requirement when it opens its sandbox.
+- 5b27aa8: **Breaking for custom sandbox providers.** `defineSandboxProvider()` now takes a byte-level `SandboxConnection` (`spawn`, `readFile`, `writeFiles`, `removePath`, `stop`, optional `close` and `extensions`), and eve derives the full sandbox session from it. Built-in providers are unchanged. See the [custom sandbox providers guide](https://eve.dev/docs/sandbox/custom-providers). To migrate a provider:
+  
+  - Return `{ connection, state }` from `start()` and a connection from `resume()`. `onSandboxStop()` and `onRuntimeShutdown()` become `connection.stop()`, and `onSandboxDelete()` folds into `onSessionEnd()` with `reason: "deleted"`.
+  - Replace `ctx.resources` and `ctx.sourceRevision` with `ctx.templateKey()` and `ctx.populate()`, and remove your own `prepare` option, which eve now runs. `environment()` receives `{}` instead of `undefined` when no options are passed. Set `toolSessions: true` to support keyed `invokeTool` calls.
+  - Rename `SandboxPreparedArtifact` to `SandboxJson`, `SandboxProviderSessionContext` to `SandboxSessionContext`, and `SandboxProviderPrepareContext` to `SandboxPrepareContext`. `SandboxProviderHandle` and the `SandboxProviderResource*` and `SandboxProviderTargetFile` types are removed, as is `ctx.host`.
+  
+  `eve/sandbox/provider` also exports `SandboxSessionGoneError`, `SandboxTemplateNotProvisionedError`, and `SANDBOX_AGENT_ENV`. In `eve/sandbox`, `SandboxSession` gains a required `writeFiles()`, so hand-built sessions such as test doubles need one, and `SandboxNetworkPolicy` is now an eve-owned type rather than the Vercel Sandbox SDK's `NetworkPolicy`.
+- 3f698dd: Sandbox providers now key each sandbox by its session: `start()` must return the existing sandbox for `ctx.session.id` when one exists, and the required `onSessionEnd(ctx, state | null, { reason })` takes no artifact and must delete by key when `state` is `null`. Session end now removes a sandbox even when the session never recorded it, such as one a subagent sharing the sandbox opened first. Built-in providers keep a session's sandbox across rebuilds and open-option changes.
+- 950409f: `VercelSandbox` now runs on the public `defineSandboxProvider()` API, keeping existing sandbox names, session state, and snapshots. Breaking: a relative `workingDirectory` now resolves from `/workspace`, and `eve/sandbox/vercel` no longer re-exports `Drive`, so import it from `@vercel/sandbox` instead.
+
+### Patch Changes
+
+- bd050f8: Clearer sandbox error messages. Sandbox errors now say what went wrong and how to fix it, for example when the build and the runtime select different providers, a prepared template is missing, a session's sandbox came from another provider, or the sandbox file does not export its environment.
+- 95571f1: Fix discovery of extension mounts written as `export { default } from "<pkg>"` inside a packaged extension, which `eve extension build` compiles to `import x from "<pkg>"; export { x as default };`.
+- 7066b20: `eve dev` memory no longer grows with every save. Each rebuild now compiles and bundles your agent in a short-lived child process, and each new version of your code is served by a fresh worker, so old copies of authored modules no longer stay loaded. Modules imported by relative path now keep their package's `sideEffects` setting, so identical source bundles the same way on every save; in `"type": "module"` apps, default imports of older CommonJS packages that set `__esModule` now follow Node's rules. Thanks @callicles for reporting this in #5203.
+- dff87bc: `eve dev` now rebuilds once per edit to a source-backed workspace extension. Before, the temporary `.eve-extension-build-*` files from the extension build started a second, unnecessary rebuild.
+- 2b07d0a: The Discord channel can now answer DMs, mentions, and thread replies. `discordChannel({ gateway: {} })` accepts messages forwarded from the Discord Gateway, and `experimental_runDiscordGatewayRelay` from the new `eve/channels/discord/gateway` entry point holds that connection, for example in a Vercel Daemon. In text channels, a mention starts a thread that holds the conversation, and a reply to any bot message continues the session that posted it; set `gateway.startThread: false` to answer in the channel, or return `conversation` or `startThread` from `gateway.onMessage` to decide per message. `defaultDiscordMessageAuth` gives a message's author the same principal `defaultDiscordAuth` gives them for commands and button presses.
+- 87962a0: `eve add channel/discord` now first asks whether people reach the agent through DMs, mentions, and threads, or a slash command. The first scaffolds the Discord Gateway relay in `daemon/`, registers it as a Vercel Daemon in `vercel.json`, enables `gateway` on the channel, turns on the bot's Message Content intent when Discord allows it, and skips registering `/ask`; the second keeps today's slash command setup and is what `--yes` picks. Non-interactive runs answer `discord-messages` with `"gateway"` or `"commands"`.
+- acc76d5: The Discord channel now shows connection sign-ins. In a DM it posts the sign-in link and any confirmation code; in a server it posts a **Sign in** button that shows the link only to the person who has to sign in, in an ephemeral message. The message updates once the sign-in completes or is cancelled.
+- 4db529f: `DockerSandbox` now runs on the public `defineSandboxProvider()` contract. Container names, recorded session state, and template image references stay the same, so running sessions and prepared images from earlier builds keep working. A few behaviors change: `sandbox.delete()` removes the session's container by its session-derived name, honors the caller's `abortSignal`, and succeeds when the container is already gone; eve normalizes relative paths such as `logs/../out.txt` to `/workspace/out.txt` before they reach the container; and a Docker environment's `prepare` callback is typed with `DockerSandboxSession`.
+- 5cf30b6: A dynamic model resolver's `step.started` event now carries the index of the step it selects a model for. From the second step of a turn on, it used to carry the previous step's index, so per-step work keyed on `stepIndex` was attributed to the wrong step.
+- 3c25e62: A dynamic skill that stops returning `files` but is still returned now keeps the files already written to the sandbox, so files the sandbox provides another way, such as from its snapshot, stay in place. If you dropped `files` to take files away from some callers, stop returning the skill for them instead: a skill the resolver stops returning still has its files removed. On Vercel Sandbox, eve now writes a dynamic skill's files in one batch, with one path lookup and one upload instead of two round trips per file.
+- 1bbe939: `eve eval` artifacts now record each eval's `startedAt` and `completedAt` in `summary.json`, `results.jsonl`, and the per-eval detail file.
+- 448804d: An eval's `derived.usage` now takes each session's latest usage by time. An eval that captured a session again with an earlier snapshot reported that snapshot's lower total. Its `costUsd` is now absent when a counted session reported no cost, instead of summing only the sessions that did.
+- 94784e1: Validate idle session state inside the workflow before starting a deployment handoff, avoiding unnecessary successor starts when durable work is still pending. Preserve inbox ownership and the original session stream throughout the move.
+- 580417f: Fix repeated horizontal rules and question text accumulating in terminal scrollback during human-in-the-loop prompts. Question and approval drawers now fit small terminals, keeping the focused choice or text editor visible.
+- b848a51: Avoid an extra setup command when creating a Vercel sandbox from a prepared snapshot of the standard eve image without Drive mounts. eve now checks the base runtime again after authored preparation, so a `prepare` callback that breaks it fails the build; existing sandboxes, resumes, custom images or sources, Drive mounts, and sandboxes without a prepared snapshot keep their setup checks. Vercel templates rebuild once so every snapshot has passed the new check.
+- 39a8b4c: A session whose sandbox is gone (for example after a removed Docker container, a deleted Vercel Sandbox, or a deleted just-bash session directory) now starts a fresh sandbox on its next `ctx.getSandbox()`. Previously every sandbox call in that session failed with the same resume error until the session ended. Thanks @bradhallett for reporting this in #5113 and @moinulmoin for the just-bash case in #4440.
+- bb4afff: New sessions start their first model step sooner, and later turns no longer wait for their cancellation hooks to register before their first step. Thanks @Lukavyi for reporting the startup latency in #876.
+- 798a91e: The Linq channel now rejects inbound webhooks with a 401 whenever its webhook verifier returns any falsy value, including the `null` that `vercelOidc()` returns for a missing or invalid token. Previously only `false` rejected a request, so Vercel Connect setups without a `signingSecret` accepted unsigned webhooks.
+- aaae448: Self-hosted `eve start` servers now reject requests to `/.well-known/workflow/v1/flow` that did not come from the server's own workflow queue, so a client can no longer forge a workflow delivery with a chosen run context or principal. Startup always recovers pending and running local workflow runs through the authenticated queue, ignoring `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS`; queue deliveries must stay on the process that enqueued them.
+- 9d1998f: Export `agentWithModel` for `agent/tools/agent.ts` to opt into a root-copy tool whose model-facing input selects the AI Gateway model for each task.
+- cbc87ae: OpenAPI connection tool calls now follow redirects only within the base URL's origin. A redirect to another origin is returned as the tool result, with its target in `location`, instead of followed, so credentials in custom headers, such as an `apiKey` security scheme's header, no longer reach the redirect target. A same-origin redirect loop now fails after 10 hops with an explicit error.
+- 7a908f5: Compaction summaries now run on the AI SDK model instance set as `compaction.model`. Before, a direct model instance there was ignored and summaries ran on the agent's top-level `model`.
+- 84daf59: Compiles now prune `node_modules/.cache/eve/authored-modules` in the background, deleting cached bundles that no running eve process can still import, so the directory no longer grows without bound locally or in persisted Vercel build caches. Thanks @ryantbrown for reporting this in #847 and @kevludwig for reporting the Vercel build-cache impact.
+- 9bd75df: `server-only` and `client-only` imports now load as empty modules in every eve bundle, so tools, channels, workflow steps, and shared workspace packages that import them build and boot without `--conditions=react-server` or a direct dependency. Thanks @jakeleventhal for the original implementation in #3752.
+- b9f984c: Update the bundled Workflow runtime to reduce redundant history reads during concurrent hook registration and avoid unnecessary input/output reads when resuming hooks. Include replay-ordering fixes and the local-world fix for deliveries that race a session handoff.
+- f5b36b3: Repair orphaned local tool calls in saved history before the next model request with an explicit unknown-outcome error. The repair never reruns tools or moves recorded results, and leaves provider-executed calls, approval requests and duplicate call IDs alone.
+- 1fe0d91: Dynamic skills with supporting files are written into a sandbox that eve recreates after the old one was gone, at the start of the next turn. Before, the recreated sandbox got the same identity as the old one, so its skills were missing their files until the skill changed.
+- b3ede07: The Linq and Photon channels' default webhook verification now only accepts Vercel OIDC tokens from the same project and environment.
+- 00aa593: eve now runs every sandbox provider, including `DefaultSandbox`, directly on the public `defineSandboxProvider()` contract, and calls `connection.close()` when the step that opened a connection ends, so the next step resumes through a new connection. Server shutdown stops only connections eve still holds, so a custom provider that defines `close()` and runs remote compute should bound idle compute itself, for example with an idle timeout.
+- c3bbae4: Relative symlinks in an agent's `sandbox/workspace/` files, in skill packages, and in sandbox templates now stay relative in build output and in each sandbox session. Before, eve rewrote them as absolute host paths: `just-bash` sessions rejected them with `EACCES ... resolves outside sandbox`, and they did not resolve inside Docker, microsandbox, or remote sandboxes.
+- 00aa593: Custom sandbox providers can declare `workspaceRoot` on a connection, and eve resolves relative paths, the default working directory, `resolvePath(".")`, and build-time workspace seeding from it; built-in providers keep `/workspace`. The `read_file`, `write_file`, `glob`, and `grep` tools now accept paths relative to the workspace root, and the workspace and skills prompt sections no longer name `/workspace`.
+- db18149: `eve start` and the `withEve` production server for Next.js now fail fast with a clear "port is already in use" error when another process holds the port, instead of reporting a server they did not start and leaving the built server running in the background. Thanks @KingAmo for reporting this in #4938.
+- 9d804f2: A sandbox that was stopped and then ended no longer stays registered for server shutdown, so long-running eve servers stop accumulating ended sessions and shutdown no longer stops their connections again.
+- f1656a5: Tools can now hand the model a file by URL. `toolOutputPart.fileUrl(url, { mediaType })` from `eve/tools` returns a `{ type: "file", data: { type: "url", url } }` content part from `toModelOutput`, so a large file such as a presigned PDF link reaches the model without being base64-encoded, staged into the sandbox, or stored in session history. Only `https:` URLs are accepted, and the URL must stay readable for the rest of the session because every later model call sends it again.
+- ea3a387: Calling `prewarm()` on an existing session can now prepare an idle owner on the Vercel deployment accepting the request before the next message. Apps can trigger it when typing starts; it preserves the session, history, stream, and expiry, and does not block Send or run the model.
+  
+  Preparation uses the existing `POST /eve/v1/session/:sessionId` endpoint with no body or `{}`. Requests with messages or input responses keep their existing behavior.
+- 07dbdef: Each start or resume of a `workflow` tool program may now run up to 30 seconds of JavaScript and take up to 5 minutes in total, and time spent waiting for child agents counts toward neither limit.
+- dd0aac6: A `"use step"` helper in a workflow tool can now call `ctx.getSandbox()` to open the sandbox of the session that called the tool, on any sandbox provider, so a task can prepare files the session's later tool calls read. When the session had not recorded its sandbox when it called the tool, the step opens it with the owning session's sandbox definition; the step never owns the sandbox, and the session removes it when the session ends.
+
+## 0.82.0
+
+### Minor Changes
+
+- c543585: Breaking: replace `limits.maxInputTokensPerSession`, `limits.maxOutputTokensPerSession` and `limits.maxTokenCostUsdPerSession` with one `limits.sessionUsage` function. It receives the session's `total` usage and its `window` since the last approved continuation, and returns `true` when the limit is reached; Continue starts a new window. The default is 40M new input tokens (input minus cache reads) per window. Subagents now check their own window with their own `sessionUsage` or the root agent's instead of receiving a share of the parent's remaining quota. Sessions that can't ask now fail with `SESSION_USAGE_LIMIT_REACHED`, replacing `SESSION_TOKEN_LIMIT_REACHED` and `SESSION_TOKEN_COST_LIMIT_REACHED`.
+
+### Patch Changes
+
+- baf3030: Attach the agent trace session ID to auto-instrumented child spans on Vercel so Agent Runs can include network and other third-party spans in a session trace.
+- 91b3183: The session input-token limit now counts only new input (uncached input plus cache writes). Cache reads no longer count toward the limit, the grant after Continue, or the quota shared with subagents, so long cache-heavy sessions stop hitting continuation prompts for replaying their own history. Usage telemetry still reports raw input and cache totals. Providers that report no cache details count exactly as before.
+- 8aba0f6: Allow authored workflow tools to select an AI Gateway model when they open a local session with `ctx.agent()`. The child keeps the target agent's other configuration, and the selected model applies for the session's lifetime.
+- 0aea7fc: `eve eval` now runs while an `eve dev` session for the same agent is open, instead of failing with "A dev server is already running for this eve agent." The eval server keeps its runtime generations, local Workflow data, and server record in a per-run directory under `.eve/eval-servers/`, so it never swaps or prunes the dev session's state.
+- a9f5065: Channel and session sends and responses now accept `idempotencyKey` to ignore retries across replay and owner handoffs. Photon supplies message IDs automatically; deduplication requires a shared Workflow World and only covers keys in the session's recent-key window.
+- 6752c95: Fix a workflow tool task running twice when the session was interrupted while publishing `task.started`, for example during a slow `task.started` hook. The session now records each task's run before it publishes the event, so a retry only publishes `task.started` again and never starts a second run.
+- 964a41f: `limits.sessionTimeoutMs` is now an idle timeout: the window restarts each time a turn settles, so a session in active use no longer ends 30 days after it was created. Idle sessions still complete when the window elapses, and the next channel message at their address starts a fresh session as before.
+- dd8c231: Linq and Photon iMessage channels now tell the model when a message is a reply, and include the text of the message it quotes.
+- cf824a8: The Photon and Linq channels can now pass tapbacks to the agent with a new `onTapback` hook, which can also answer the approval or question posted in the message the tapback is on, for example approving with a like. `channel.tapbackTool()` gives the model a tool that reacts to the latest message with a standard tapback or any emoji. Tapbacks stay ignored unless you opt in.
+- 743b498: `eve start --no-schedules` and `EVE_SCHEDULES_DISABLED=1` start a server that does not fire authored cron schedules, so only one process runs them when you scale out.
+- b34844b: Channel `send()`, channel message hooks, and a new `create()` on channel addresses accept `history` to add prior user and assistant messages, such as a stored transcript, as real turns. `create()` starts a session that waits for its first message and reports with `created` whether it did. A new `history.imported` stream event publishes added messages; the default client reducer renders them, and `transcriptReducer()` includes them. Slack `threadContext` now adds earlier replies as history when a message starts the thread's session; later messages keep the existing transcript.
+- e40d7d7: `eve build` and `eve dev` now evaluate a module shared by several tools, channels, or other authored files once per compile instead of once per importing file. Compile memory now grows with the code an agent actually has, not with the number of files that import it, so agents with many tools over a shared SDK or workspace package no longer run out of memory on smaller build machines. Authored modules transpiled to CommonJS with an `__esModule` marker, such as a `tools/*.cjs` file with `exports.default = …`, now also compile and run correctly instead of resolving to the whole `exports` object. On Windows, CommonJS authored modules can now `require()` eve and other external packages.
+- 62d3227: Skip the final Slack reply when the message that started the turn was deleted, instead of letting Slack post it as a top-level channel message.
+- ee5e8e9: Self-hosted `eve build` output now carries a build identity derived from its contents. eve exposes it to Workflow Worlds as `WORKFLOW_DEPLOYMENT_ID` unless that variable is already set, and records it in `eve build --profile` reports.
+- 7b8a520: Fix unnecessary `eve dev` runtime-generation changes when Nitro installs newer Rolldown versions. No-op rebuilds and environment-only reloads now keep the active runtime snapshot unchanged instead of treating bundler debug comments as runtime changes.
+
 ## 0.81.1
 
 ### Patch Changes

package/NOTICE

@@ -4,7 +4,7 @@ Copyright 2026 Vercel, Inc. and contributors
 This product includes software developed at Vercel, Inc.
 (https://vercel.com/).
 
-The bundled code-mode runtime includes run, Copyright 2023 Vercel, Inc.,
+The bundled workflow program runtime is run, Copyright 2023 Vercel, Inc.,
 licensed under the Apache License, Version 2.0.
 
 run embeds devalue 5.8.2, quickjs-wasi 3.6.0, and QuickJS under the MIT

package/dist/src/channel/channel-address.d.ts

@@ -4,27 +4,46 @@ import { type ChannelDeliverySource } from "#channel/delivery-metadata.js";
 import type { SendPayload } from "#channel/routes.js";
 import { type Session } from "#channel/session.js";
 import type { CancelTurnResult, ClearSessionResult, CompactSessionResult, ResetSessionResult, Runtime, SessionAuthContext, SessionCallback, TurnPolicy } from "#channel/types.js";
+interface BaseChannelAddressCreateOptions {
+    readonly auth: SessionAuthContext | null;
+    readonly history?: SendPayload["history"];
+    readonly initiatorAuth?: SessionAuthContext | null;
+    readonly title?: string;
+}
+type ChannelAddressCreateOptions<TState = undefined> = [TState] extends [undefined] ? BaseChannelAddressCreateOptions : BaseChannelAddressCreateOptions & {
+    readonly state?: Partial<TState>;
+};
 interface BaseChannelAddressDeliveryOptions {
+    readonly idempotencyKey?: string;
     readonly auth: SessionAuthContext | null;
     readonly callback?: SessionCallback;
     readonly initiatorAuth?: SessionAuthContext | null;
     readonly title?: string;
     readonly turnPolicy?: TurnPolicy;
 }
+/**
+ * Result of `create()`. `created` is `false` when another session already owned the address, or
+ * won it concurrently; that session is returned unchanged and any `history` was not added.
+ */
+export interface ChannelCreateResult {
+    readonly created: boolean;
+    readonly session: Session;
+}
 /** Delivery options for a channel address whose continuation token is already bound. */
 export type ChannelAddressDeliveryOptions<TState = undefined> = [TState] extends [undefined] ? BaseChannelAddressDeliveryOptions : BaseChannelAddressDeliveryOptions & {
     readonly state?: Partial<TState>;
 };
 /**
  * Dynamic handle for whichever durable session currently owns one channel-local address.
- * Only {@link send} may create a session: when the address is unowned, or in
- * place of a stranded session that another eve version built. Sends to a session whose
+ * Only {@link create} and {@link send} may create a session: when the address is unowned, and
+ * `send` also in place of a stranded session that another eve version built. Sends to a session whose
  * owner is only unavailable throw `SessionStrandedError` and deliver nothing.
  * Responses to an address no session holds throw `SessionNotActiveError`.
  */
 interface ChannelAddress<TState = undefined> {
     readonly continuationToken: string;
     deliver(input: SendPayload, options: ChannelAddressDeliveryOptions<TState>): Promise<Session>;
+    create(options: ChannelAddressCreateOptions<TState>): Promise<ChannelCreateResult>;
     send(message: string | UserContent, options: ChannelAddressDeliveryOptions<TState>): Promise<Session>;
     respond(inputResponses: SendPayload["inputResponses"], options: ChannelAddressDeliveryOptions<TState>): Promise<Session>;
     cancel(options?: {

package/dist/src/channel/channel-address.js

@@ -1 +1 @@
-import{createSession,sessionCallbackToTurnCaller}from"#channel/session.js";import{createChannelDeliveryMetadata}from"#channel/delivery-metadata.js";import{normalizeSendInput,serializeFilePartsInMessage}from"#channel/send-input.js";import{SessionNotActiveError}from"#channel/session-not-active-error.js";import{DEFAULT_TURN_POLICY}from"#channel/types.js";import{isReservedSessionCommandToken}from"#execution/session-inbox/address.js";function createChannelAddress(e){let t=e.metadata??{},n=`${e.channelName}:${e.continuationToken}`;if(isReservedSessionCommandToken(n))throw Error(`Channel address "${n}" uses eve's reserved session namespace.`);return{continuationToken:e.continuationToken,async deliver(r,i){let a=t.channelKind!==void 0&&t.channelName!==void 0?createChannelDeliveryMetadata(t):void 0,o=normalizeSendInput(r),s=sessionCallbackToTurnCaller(i.callback),c={auth:i.auth,delivery:a,kind:`send`,payload:{...o,message:serializeFilePartsInMessage(o.message)},requestId:t.requestId,turnPolicy:o.message===void 0?void 0:i.turnPolicy??e.turnPolicy??DEFAULT_TURN_POLICY},l=s===void 0?c:{...c,caller:s},u=i.state,d={adapter:u===void 0?e.adapter:{...e.adapter,state:{...e.adapter.state,...u}},auth:i.auth,capabilities:{requestInput:!0},callback:i.callback,channelName:e.channelName,continuationConflictCommand:l,continuationToken:n,delivery:a,initiatorAuth:i.initiatorAuth,input:{context:o.context,message:serializeFilePartsInMessage(o.message)??``,outputSchema:o.outputSchema,state:o.state},requestId:t.requestId,title:i.title},toSession=n=>createSession(n,e.runtime,{...t,turnPolicy:e.turnPolicy}),f=await e.runtime.dispatchContinuation({command:l,continuationToken:n,successor:d});if(f.status===`accepted`)return toSession(f.sessionId);if(o.inputResponses&&o.inputResponses.length>0)throw new SessionNotActiveError;return toSession((await e.runtime.createSession(d)).sessionId)},async send(e,t){return await this.deliver({message:e},t)},async respond(e,t){if(e===void 0||e.length===0)throw Error(`respond() requires at least one input response.`);return await this.deliver({inputResponses:e},t)},async cancel(t){return await e.runtime.dispatchContinuation({command:{kind:`cancel`,turnId:t?.turnId},continuationToken:n})},async compact(){return await e.runtime.dispatchContinuation({command:{kind:`compact`},continuationToken:n})},async clear(){return await e.runtime.dispatchContinuation({command:{kind:`clear`},continuationToken:n})},async reset(t){return await e.runtime.dispatchContinuation({command:{kind:`reset`,reason:t?.reason},continuationToken:n})},async resolveSession(){let r=await e.runtime.resolveContinuation(n);return r===void 0?void 0:createSession(r.sessionId,e.runtime,{...t,turnPolicy:e.turnPolicy})}}}function createChannelAddressFn(e){return t=>createChannelAddress({...e,continuationToken:t})}export{createChannelAddress,createChannelAddressFn};
+import{createSession,sessionCallbackToTurnCaller}from"#channel/session.js";import{validateDeliveryIdempotencyKey}from"#channel/delivery-idempotency.js";import{createChannelDeliveryMetadata}from"#channel/delivery-metadata.js";import{normalizeSendInput,serializeFilePartsInMessage}from"#channel/send-input.js";import{SessionNotActiveError}from"#channel/session-not-active-error.js";import{SessionStrandedError,describeStrandedSession}from"#channel/session-stranded-error.js";import{DEFAULT_TURN_POLICY}from"#channel/types.js";import{isReservedSessionCommandToken}from"#execution/session-inbox/address.js";import{validateSessionHistory}from"#shared/session-history.js";function createChannelAddress(e){let t=e.metadata??{},n=`${e.channelName}:${e.continuationToken}`;if(isReservedSessionCommandToken(n))throw Error(`Channel address "${n}" uses eve's reserved session namespace.`);return{continuationToken:e.continuationToken,async deliver(r,i){validateDeliveryIdempotencyKey(i.idempotencyKey);let a=t.channelKind!==void 0&&t.channelName!==void 0?createChannelDeliveryMetadata(t):void 0,o=withValidatedHistory(normalizeSendInput(r)),s=sessionCallbackToTurnCaller(i.callback),c={idempotencyKey:i.idempotencyKey,auth:i.auth,delivery:a,kind:`send`,payload:{...o,message:serializeFilePartsInMessage(o.message)},requestId:t.requestId,turnPolicy:o.message===void 0?void 0:i.turnPolicy??e.turnPolicy??DEFAULT_TURN_POLICY},l=s===void 0?c:{...c,caller:s},u=i.state,d=u===void 0?e.adapter:{...e.adapter,state:{...e.adapter.state,...u}},f={idempotencyKey:i.idempotencyKey,adapter:d,auth:i.auth,capabilities:{requestInput:!0},callback:i.callback,channelName:e.channelName,continuationConflictCommand:l,continuationToken:n,delivery:a,initiatorAuth:i.initiatorAuth,input:{context:o.context,history:o.history,message:serializeFilePartsInMessage(o.message)??``,outputSchema:o.outputSchema,state:o.state},requestId:t.requestId,title:i.title},toSession=n=>createSession(n,e.runtime,{...t,turnPolicy:e.turnPolicy}),p=await e.runtime.dispatchContinuation({command:l,continuationToken:n,successor:f});if(p.status===`accepted`)return toSession(p.sessionId);if(o.inputResponses&&o.inputResponses.length>0)throw new SessionNotActiveError;return toSession((await e.runtime.createSession(f)).sessionId)},async create(r){let i=validateSessionHistory(r.history),toSession=n=>createSession(n,e.runtime,{...t,turnPolicy:e.turnPolicy}),a;try{a=await e.runtime.resolveContinuation(n,{runnable:!0})}catch(e){throw SessionStrandedError.is(e)?new SessionStrandedError(e.owner,describeStrandedSession(e.owner,`Call reset() on the address, then create() again to start a session from your history.`)):e}if(a!==void 0)return{created:!1,session:toSession(a.sessionId)};let o=r.state,s=await e.runtime.createSession({adapter:o===void 0?e.adapter:{...e.adapter,state:{...e.adapter.state,...o}},auth:r.auth,capabilities:{requestInput:!0},channelName:e.channelName,continuationToken:n,initiatorAuth:r.initiatorAuth,input:i===void 0?{}:{history:i},requestId:t.requestId,title:r.title}),c=await waitForContinuationOwner(e.runtime,n,s.sessionId);return{created:c.sessionId===s.sessionId,session:toSession(c.sessionId)}},async send(e,t){return await this.deliver({message:e},t)},async respond(e,t){if(e===void 0||e.length===0)throw Error(`respond() requires at least one input response.`);return await this.deliver({inputResponses:e},t)},async cancel(t){return await e.runtime.dispatchContinuation({command:{kind:`cancel`,turnId:t?.turnId},continuationToken:n})},async compact(){return await e.runtime.dispatchContinuation({command:{kind:`compact`},continuationToken:n})},async clear(){return await e.runtime.dispatchContinuation({command:{kind:`clear`},continuationToken:n})},async reset(t){return await e.runtime.dispatchContinuation({command:{kind:`reset`,reason:t?.reason},continuationToken:n})},async resolveSession(){let r=await e.runtime.resolveContinuation(n);return r===void 0?void 0:createSession(r.sessionId,e.runtime,{...t,turnPolicy:e.turnPolicy})}}}function createChannelAddressFn(e){return t=>createChannelAddress({...e,continuationToken:t})}function withValidatedHistory(e){let{history:t,...n}=e,r=validateSessionHistory(t);return r===void 0?n:{...n,history:r}}const CREATE_CLAIM_TIMEOUT_MS=15e3;async function waitForContinuationOwner(e,t,n){let r=Date.now()+CREATE_CLAIM_TIMEOUT_MS;for(let i=25;;i=Math.min(i*2,500)){let a=await e.resolveContinuation(t);if(a!==void 0)return a;if(Date.now()+i>r)throw Error(`create() started session "${n}" for "${t}", but no session claimed the address within ${CREATE_CLAIM_TIMEOUT_MS/1e3}s. Call resolveSession() on the address to find its owner once one does.`);await new Promise(e=>setTimeout(e,i))}}export{createChannelAddress,createChannelAddressFn};

package/dist/src/channel/channel-operations.d.ts

@@ -1,14 +1,25 @@
 import type { UserContent } from "ai";
 import type { ChannelAdapter } from "#channel/adapter.js";
 import type { ChannelDeliverySource } from "#channel/delivery-metadata.js";
+import { type ChannelCreateResult } from "#channel/channel-address.js";
+export type { ChannelCreateResult } from "#channel/channel-address.js";
 import type { Session } from "#channel/session.js";
 import type { CancelTurnResult, ClearSessionResult, CompactSessionResult, ResetSessionResult, Runtime, SessionAuthContext, SessionCallback, TurnPolicy } from "#channel/types.js";
 import { type InputResponse, type StrictInputResponses } from "#shared/input.js";
 import type { JsonObject } from "#shared/json.js";
+import type { SessionHistoryMessage } from "#shared/session-history.js";
 interface BaseChannelSendOptions {
+    /** Stable delivery identity, deduplicated within this session's recent-key window. */
+    readonly idempotencyKey?: string;
     readonly auth: SessionAuthContext | null;
     readonly callback?: SessionCallback;
     readonly context?: readonly string[];
+    /**
+     * Prior conversation added as user and assistant turns before this
+     * message and its `context`. Seeds a session this send creates, or
+     * extends the history of the session that owns the address.
+     */
+    readonly history?: readonly SessionHistoryMessage[];
     readonly initiatorAuth?: SessionAuthContext | null;
     /** JSON Schema for a structured final answer, as on `Session.send()`. */
     readonly outputSchema?: JsonObject;
@@ -20,16 +31,37 @@ export type ChannelSendOptions<TState = undefined> = [TState] extends [undefined
     readonly state: TState;
 };
 interface BaseChannelRespondOptions<TState = undefined> {
+    /** Stable delivery identity, with the same scope and retention as `send()`. */
+    readonly idempotencyKey?: string;
     readonly auth: SessionAuthContext | null;
     readonly context?: readonly string[];
     readonly state?: Partial<TState>;
 }
 /** Options for answering pending input requests at an existing continuation address. */
 export type ChannelRespondOptions<TState = undefined> = BaseChannelRespondOptions<TState>;
+interface BaseChannelCreateOptions {
+    readonly auth: SessionAuthContext | null;
+    /** Prior conversation the session starts with; it joins history with the first message. */
+    readonly history?: readonly SessionHistoryMessage[];
+    readonly initiatorAuth?: SessionAuthContext | null;
+    readonly title?: string;
+}
+/** Options for creating a session at a channel-local address without running a turn. */
+export type ChannelCreateOptions<TState = undefined> = [TState] extends [undefined] ? BaseChannelCreateOptions : BaseChannelCreateOptions & {
+    readonly state: TState;
+};
 /** Dynamic handle for whichever session currently owns one channel-local address. */
 export interface ChannelSource<TState = undefined> {
     /** Starts or resumes a turn with a user message. May create a session. */
     send(message: string | UserContent, options: ChannelSendOptions<TState>): Promise<Session>;
+    /**
+     * Creates a session that waits for its first message, without running a
+     * turn. When another session owns the address, or claims it concurrently,
+     * returns that session unchanged with `created: false`; its `history` was not
+     * added. Throws `SessionStrandedError` when the owner is stranded; reset the
+     * address, then create again.
+     */
+    create(options: ChannelCreateOptions<TState>): Promise<ChannelCreateResult>;
     /** Answers pending input requests. Never creates a session. */
     respond<const TResponses extends readonly InputResponse[]>(inputResponses: StrictInputResponses<TResponses>, options: ChannelRespondOptions<TState>): Promise<Session>;
     /** Cooperatively cancels the active turn without creating a session. */
@@ -62,4 +94,3 @@ export declare function createChannelOperations<TState = undefined>(input: {
     readonly runtime: Runtime;
     readonly turnPolicy?: TurnPolicy;
 }): ChannelReceiveContext<TState>;
-export {};

package/dist/src/channel/channel-operations.js

@@ -1 +1 @@
-import{attachInputText,readInputText}from"#internal/input-text.js";import{createChannelAddressFn}from"#channel/channel-address.js";import{parseInputResponses}from"#shared/input.js";function createChannelOperations(e){let t=createChannelAddressFn(e);return{from(e){let n=t(e);return{async send(e,t){return await n.deliver(attachInputText({context:t.context,message:e,outputSchema:t.outputSchema,state:t.state},readInputText(t)),t)},async respond(e,t){if(e.length===0)throw Error(`respond() requires at least one input response.`);let r=parseInputResponses(e);return await n.deliver({context:t.context,inputResponses:r,state:t.state},t)},async cancel(e){return await n.cancel(e)},async compact(){return await n.compact()},async clear(){return await n.clear()},async reset(e){return await n.reset(e)}}},async resolveSession(e){return await t(e).resolveSession()}}}export{createChannelOperations};
+import{attachInputText,readInputText}from"#internal/input-text.js";import{createChannelAddressFn}from"#channel/channel-address.js";import{parseInputResponses}from"#shared/input.js";function createChannelOperations(e){let t=createChannelAddressFn(e);return{from(e){let n=t(e);return{async send(e,t){return await n.deliver(attachInputText({context:t.context,history:t.history,message:e,outputSchema:t.outputSchema,state:t.state},readInputText(t)),t)},async create(e){return await n.create(e)},async respond(e,t){if(e.length===0)throw Error(`respond() requires at least one input response.`);let r=parseInputResponses(e);return await n.deliver({context:t.context,inputResponses:r,state:t.state},t)},async cancel(e){return await n.cancel(e)},async compact(){return await n.compact()},async clear(){return await n.clear()},async reset(e){return await n.reset(e)}}},async resolveSession(e){return await t(e).resolveSession()}}}export{createChannelOperations};

package/dist/src/channel/delivery-idempotency.d.ts

@@ -0,0 +1,4 @@
+/** Maximum number of distinct delivery keys remembered by one logical session. */
+export declare const DELIVERY_IDEMPOTENCY_WINDOW = 1024;
+export declare const MAX_DELIVERY_IDEMPOTENCY_KEY_LENGTH = 256;
+export declare function validateDeliveryIdempotencyKey(key: unknown): asserts key is string | undefined;

package/dist/src/channel/delivery-idempotency.js

@@ -0,0 +1 @@
+const DELIVERY_IDEMPOTENCY_WINDOW=1024,MAX_DELIVERY_IDEMPOTENCY_KEY_LENGTH=256;function validateDeliveryIdempotencyKey(e){if(e!==void 0&&(typeof e!=`string`||e.length===0||e.length>256))throw Error(`idempotencyKey must be a nonempty string of at most 256 characters.`)}export{DELIVERY_IDEMPOTENCY_WINDOW,MAX_DELIVERY_IDEMPOTENCY_KEY_LENGTH,validateDeliveryIdempotencyKey};

package/dist/src/channel/pending-authorization.d.ts

@@ -7,4 +7,9 @@ type AuthorizationRequired = AuthorizationRequiredStreamEvent["data"];
  * `attemptId`, so one attempt completing never hides another still pending.
  */
 export declare function findPendingAuthorization(session: Pick<Session, "getEventStream">, matches: (event: AuthorizationRequired) => boolean): Promise<AuthorizationRequired | undefined>;
+/** Identifies one sign-in attempt: a connection name and its `attemptId`. */
+export declare function attemptKey(event: {
+    readonly attemptId?: string;
+    readonly name: string;
+}): string;
 export {};

package/dist/src/channel/pending-authorization.js

@@ -1 +1 @@
-async function findPendingAuthorization(e,t){let n=new Map,r=(await e.getEventStream({follow:!1,startIndex:-500})).getReader();try{for(;;){let e=await r.read();if(e.done)break;let i=e.value;if(i.type===`authorization.required`&&t(i.data)){let e=attemptKey(i.data);n.delete(e),n.set(e,i.data)}else i.type===`authorization.completed`&&n.delete(attemptKey(i.data))}}finally{await r.cancel().catch(()=>{})}return[...n.values()].at(-1)}function attemptKey(e){return JSON.stringify([e.name,e.attemptId??null])}export{findPendingAuthorization};
+async function findPendingAuthorization(e,t){let n=new Map,r=(await e.getEventStream({follow:!1,startIndex:-500})).getReader();try{for(;;){let e=await r.read();if(e.done)break;let i=e.value;if(i.type===`authorization.required`&&t(i.data)){let e=attemptKey(i.data);n.delete(e),n.set(e,i.data)}else i.type===`authorization.completed`&&n.delete(attemptKey(i.data))}}finally{await r.cancel().catch(()=>{})}return[...n.values()].at(-1)}function attemptKey(e){return JSON.stringify([e.name,e.attemptId??null])}export{attemptKey,findPendingAuthorization};

package/dist/src/channel/routes.d.ts

@@ -5,6 +5,7 @@ import type { InvokeToolFn } from "#channel/invoke-tool.js";
 import type { InputResponse } from "#shared/input.js";
 import type { Session } from "#channel/session.js";
 import type { JsonObject } from "#shared/json.js";
+import type { SessionHistoryMessage } from "#shared/session-history.js";
 import type { ChannelMethod } from "#public/definitions/channel.js";
 import type { AgentDescription, AgentSkillFileDescription } from "#channel/agent-description.js";
 type WebSocketHeaders = Headers | readonly (readonly [string, string])[] | Record<string, string>;
@@ -65,6 +66,11 @@ export interface SendPayload {
      * message and persists it across the session.
      */
     readonly context?: readonly string[];
+    /**
+     * Prior conversation added as user and assistant turns before this
+     * delivery's `context` and message.
+     */
+    readonly history?: readonly SessionHistoryMessage[];
     /**
      * Run-scoped JSON schema the turn's result must match.
      */

package/dist/src/channel/session.d.ts

@@ -6,6 +6,7 @@ import type { CancelTurnResult, ClearSessionResult, CompactSessionResult, GetEve
 import type { SessionAuth } from "#context/keys.js";
 import { type InputResponse, type StrictInputResponses } from "#shared/input.js";
 import type { JsonObject } from "#shared/json.js";
+import { type SessionHistoryMessage } from "#shared/session-history.js";
 /** Immutable-ID handle for one exact durable session. */
 export interface Session {
     readonly id: string;
@@ -21,6 +22,8 @@ export interface Session {
     cancel(options?: {
         turnId?: string;
     }): Promise<CancelTurnResult>;
+    /** Prepares an idle session on the deployment accepting this request, without a model turn. */
+    prewarm(): Promise<import("#protocol/prewarm-session.js").PrewarmSessionResult>;
     /** Queues compaction on this exact session ID. */
     compact(): Promise<CompactSessionResult>;
     /** Queues a context clear on this exact session ID. */
@@ -38,6 +41,8 @@ export interface Session {
     getStreamTailIndex(): Promise<number>;
 }
 interface SessionDeliveryOptions {
+    /** Stable delivery identity, deduplicated within this session's recent-key window. */
+    readonly idempotencyKey?: string;
     readonly auth: SessionAuthContext | null;
     /** Public callback destination for a delegated continuation turn. */
     readonly callback?: SessionCallback;
@@ -46,6 +51,8 @@ interface SessionDeliveryOptions {
 }
 /** Options for sending a message through a fixed session handle. */
 export type SessionSendOptions = SessionDeliveryOptions & {
+    /** Prior conversation added as user and assistant turns before this message and its `context`. */
+    readonly history?: readonly SessionHistoryMessage[];
     /** Initial workflow title for a prewarmed session. */
     readonly title?: string;
     readonly turnPolicy?: TurnPolicy;

package/dist/src/channel/session.js

@@ -1 +1 @@
-import{attachClientContext,readClientContext}from"#internal/client-context.js";import{createChannelDeliveryMetadata}from"#channel/delivery-metadata.js";import{serializeFilePartsInMessage}from"#channel/send-input.js";import{DEFAULT_TURN_POLICY}from"#channel/types.js";import{parseInputResponses}from"#shared/input.js";import{AuthKey,ContinuationHookTokensKey,ContinuationTokenKey,InitiatorAuthKey,SessionIdKey}from"#context/keys.js";import{toChannelLocalContinuationToken}from"#shared/continuation-token.js";function createSession(e,t,n={}){return{id:e,async send(r,i){let a=createDelivery(n),o=sessionCallbackToTurnCaller(i.callback),s=attachClientContext({message:serializeFilePartsInMessage(r)},readClientContext(i));i.context!==void 0&&(s.context=i.context),i.outputSchema!==void 0&&(s.outputSchema=i.outputSchema);let c={auth:i.auth,delivery:a,kind:`send`,payload:s,requestId:n.requestId,turnPolicy:i.turnPolicy??n.turnPolicy??DEFAULT_TURN_POLICY,title:i.title};return await t.dispatchSession({command:o===void 0?c:{...c,caller:o},sessionId:e})},async respond(r,i){if(r.length===0)throw Error(`respond() requires at least one input response.`);let a=parseInputResponses(r),o=sessionCallbackToTurnCaller(i.callback),s=createDelivery(n),c=attachClientContext({inputResponses:a},readClientContext(i));i.context!==void 0&&(c.context=i.context),i.outputSchema!==void 0&&(c.outputSchema=i.outputSchema);let l={auth:i.auth,delivery:s,kind:`send`,payload:c,requestId:n.requestId};return await t.dispatchSession({command:o===void 0?l:{...l,caller:o},sessionId:e})},async cancel(n){let r={kind:`cancel`};return n?.turnId!==void 0&&(r.turnId=n.turnId),await t.dispatchSession({command:r,sessionId:e})},async compact(){return await t.dispatchSession({command:{kind:`compact`},sessionId:e})},async clear(){return await t.dispatchSession({command:{kind:`clear`},sessionId:e})},async reset(n){return await t.dispatchSession({command:{kind:`reset`,reason:n?.reason},sessionId:e})},async getEventStream(n){return t.getEventStream(e,n)},async getStreamTailIndex(){return t.getStreamTailIndex(e)}}}function createAttachSessionFn(e,t={}){return n=>createSession(n,e,t)}function createDelivery(e){return e.channelKind!==void 0&&e.channelName!==void 0?createChannelDeliveryMetadata(e):void 0}function buildSessionHandle(e){return{get id(){return e.get(SessionIdKey)??``},get auth(){return{current:e.get(AuthKey)??null,initiator:e.get(InitiatorAuthKey)??null}},get continuation(){let t=e.get(ContinuationTokenKey);if(t!==void 0&&t.length!==0)return{token:toChannelLocalContinuationToken(t),alias(n){if(n.length===0)throw Error(`A session alias requires a nonempty token.`);let r=namespaceContinuationToken(t,n);t!==r&&(e.set(ContinuationHookTokensKey,e=>{let n=e??[t];return n.includes(r)?n:[...n,r]}),e.set(ContinuationTokenKey,r))}}}}}function namespaceContinuationToken(e,t){let n=e.indexOf(`:`);if(n<=0)throw Error(`Cannot set session continuation token without an existing namespaced continuation token. Start the session with a placeholder continuationToken.`);return`${e.slice(0,n+1)}${t}`}function sessionCallbackToTurnCaller(e){return e===void 0?void 0:{callId:e.callId,replyTo:{kind:`callback`,token:e.token,url:e.url},subagentName:e.subagentName}}export{buildSessionHandle,createAttachSessionFn,createSession,sessionCallbackToTurnCaller};
+import{attachClientContext,readClientContext}from"#internal/client-context.js";import{validateDeliveryIdempotencyKey}from"#channel/delivery-idempotency.js";import{createChannelDeliveryMetadata}from"#channel/delivery-metadata.js";import{serializeFilePartsInMessage}from"#channel/send-input.js";import{DEFAULT_TURN_POLICY}from"#channel/types.js";import{validateSessionHistory}from"#shared/session-history.js";import{parseInputResponses}from"#shared/input.js";import{AuthKey,ContinuationHookTokensKey,ContinuationTokenKey,InitiatorAuthKey,SessionIdKey}from"#context/keys.js";import{toChannelLocalContinuationToken}from"#shared/continuation-token.js";function createSession(e,t,n={}){return{id:e,async send(r,i){validateDeliveryIdempotencyKey(i.idempotencyKey);let a=createDelivery(n),o=sessionCallbackToTurnCaller(i.callback),s=validateSessionHistory(i.history),c=attachClientContext({message:serializeFilePartsInMessage(r)},readClientContext(i));i.context!==void 0&&(c.context=i.context),s!==void 0&&(c.history=s),i.outputSchema!==void 0&&(c.outputSchema=i.outputSchema);let l={idempotencyKey:i.idempotencyKey,auth:i.auth,delivery:a,kind:`send`,payload:c,requestId:n.requestId,turnPolicy:i.turnPolicy??n.turnPolicy??DEFAULT_TURN_POLICY,title:i.title};return await t.dispatchSession({command:o===void 0?l:{...l,caller:o},sessionId:e})},async respond(r,i){if(validateDeliveryIdempotencyKey(i.idempotencyKey),r.length===0)throw Error(`respond() requires at least one input response.`);let a=parseInputResponses(r),o=sessionCallbackToTurnCaller(i.callback),s=createDelivery(n),c=attachClientContext({inputResponses:a},readClientContext(i));i.context!==void 0&&(c.context=i.context),i.outputSchema!==void 0&&(c.outputSchema=i.outputSchema);let l={idempotencyKey:i.idempotencyKey,auth:i.auth,delivery:s,kind:`send`,payload:c,requestId:n.requestId};return await t.dispatchSession({command:o===void 0?l:{...l,caller:o},sessionId:e})},async cancel(n){let r={kind:`cancel`};return n?.turnId!==void 0&&(r.turnId=n.turnId),await t.dispatchSession({command:r,sessionId:e})},async prewarm(){return await t.dispatchSession({command:{kind:`prewarm`,targetDeploymentId:n.acceptedDeploymentId},sessionId:e})},async compact(){return await t.dispatchSession({command:{kind:`compact`},sessionId:e})},async clear(){return await t.dispatchSession({command:{kind:`clear`},sessionId:e})},async reset(n){return await t.dispatchSession({command:{kind:`reset`,reason:n?.reason},sessionId:e})},async getEventStream(n){return t.getEventStream(e,n)},async getStreamTailIndex(){return t.getStreamTailIndex(e)}}}function createAttachSessionFn(e,t={}){return n=>createSession(n,e,t)}function createDelivery(e){return e.channelKind!==void 0&&e.channelName!==void 0?createChannelDeliveryMetadata(e):void 0}function buildSessionHandle(e){return{get id(){return e.get(SessionIdKey)??``},get auth(){return{current:e.get(AuthKey)??null,initiator:e.get(InitiatorAuthKey)??null}},get continuation(){let t=e.get(ContinuationTokenKey);if(t!==void 0&&t.length!==0)return{token:toChannelLocalContinuationToken(t),alias(n){if(n.length===0)throw Error(`A session alias requires a nonempty token.`);let r=namespaceContinuationToken(t,n);t!==r&&(e.set(ContinuationHookTokensKey,e=>{let n=e??[t];return n.includes(r)?n:[...n,r]}),e.set(ContinuationTokenKey,r))}}}}}function namespaceContinuationToken(e,t){let n=e.indexOf(`:`);if(n<=0)throw Error(`Cannot set session continuation token without an existing namespaced continuation token. Start the session with a placeholder continuationToken.`);return`${e.slice(0,n+1)}${t}`}function sessionCallbackToTurnCaller(e){return e===void 0?void 0:{callId:e.callId,replyTo:{kind:`callback`,token:e.token,url:e.url},subagentName:e.subagentName}}export{buildSessionHandle,createAttachSessionFn,createSession,sessionCallbackToTurnCaller};

package/dist/src/channel/types.d.ts

@@ -6,8 +6,8 @@ import type { CancelTurnResult as ProtocolCancelTurnResult } from "#protocol/can
 import type { RuntimeSubagentChildResult, RuntimeSubagentDispatchFailure, RuntimeToolResultActionResult } from "#shared/action-types.js";
 import type { InputRequest, InputResponse } from "#shared/input.js";
 import type { ChannelAdapter } from "#channel/adapter.js";
-import type { AgentLimitsDefinition } from "#shared/agent-definition.js";
 import type { JsonObject } from "#shared/json.js";
+import type { SessionHistoryMessage } from "#shared/session-history.js";
 import type { InstrumentationDecision } from "#shared/instrumentation-decision.js";
 import type { ForwardedTraceAssertion } from "#shared/forwarded-trace-policy.js";
 import type { ConversationContext } from "#shared/conversation-context.js";
@@ -15,7 +15,6 @@ import type { StubScope } from "#tool-stubs/types.js";
 export type { ContextAccessor } from "#context/key.js";
 export type { ChannelInstrumentationProjection } from "#channel/instrumentation.js";
 import type { ChannelInstrumentationProjection } from "#channel/instrumentation.js";
-export type RunSessionLimits = Pick<AgentLimitsDefinition, "maxInputTokensPerSession" | "maxOutputTokensPerSession" | "maxTokenCostUsdPerSession">;
 /** Identifies the session turn to cancel. */
 export interface CancelTurnInput {
     readonly sessionId: string;
@@ -155,6 +154,8 @@ export interface DeliverPayload {
     readonly inputResponses?: readonly InputResponse[];
     readonly message?: string | UserContent;
     readonly context?: readonly string[];
+    /** Prior conversation added as user and assistant turns before this delivery's input. */
+    readonly history?: readonly SessionHistoryMessage[];
     readonly outputSchema?: JsonObject;
     readonly [key: string]: unknown;
 }
@@ -164,6 +165,7 @@ export type TurnPolicy = "steer" | "queue";
 export declare const DEFAULT_TURN_POLICY: TurnPolicy;
 /** One command accepted by a durable session inbox. */
 export type SessionCommand = {
+    readonly idempotencyKey?: string;
     readonly auth?: SessionAuthContext | null;
     readonly caller?: TurnCaller;
     /** Initial workflow title when delivering to a prewarmed session. */
@@ -177,6 +179,9 @@ export type SessionCommand = {
 } | {
     readonly kind: "cancel";
     readonly turnId?: string;
+} | {
+    readonly kind: "prewarm";
+    readonly targetDeploymentId?: string;
 } | {
     readonly kind: "compact";
 } | {
@@ -202,6 +207,8 @@ export type ResetSessionResult = {
     readonly status: "no_active_session";
 };
 export type SessionCommandResult<TCommand extends SessionCommand = SessionCommand> = TCommand extends {
+    readonly kind: "prewarm";
+} ? import("#protocol/prewarm-session.js").PrewarmSessionResult : TCommand extends {
     readonly kind: "send";
 } ? SessionSendCommandResult : TCommand extends {
     readonly kind: "cancel";
@@ -230,6 +237,7 @@ export interface DispatchSessionInput<TCommand extends SessionCommand = SessionC
  * metadata so both cross the durable hook boundary outside adapter-owned data.
  */
 export interface DeliverHookPayload {
+    readonly idempotencyKey?: string;
     readonly schedule?: import("#context/session-schedule.js").SessionSchedule;
     /** Initial workflow title; ignored once session initialization has run. */
     readonly title?: string;
@@ -371,6 +379,8 @@ export interface SessionCapabilities {
  * subagent tool wrapper).
  */
 export interface RunInput {
+    /** Optional stable identity of the initial delivery, scoped to this logical session. */
+    readonly idempotencyKey?: string;
     /**
      * @internal Set by the server after it authorizes tool stubs.
      * Local subagents match rules qualified by their full path, such as researcher/list_tasks.
@@ -456,6 +466,8 @@ export interface RunInput {
         /** Omitted only when creating a conversation session before its first turn. */
         readonly message?: string | UserContent;
         readonly context?: readonly string[];
+        /** Prior conversation; with no message, it waits for the first message's turn. */
+        readonly history?: readonly SessionHistoryMessage[];
         readonly outputSchema?: JsonObject;
         /** Channel payload state for the first delivery, as later deliveries carry it. */
         readonly state?: unknown;
@@ -470,13 +482,6 @@ export interface RunInput {
      * because trace state is scoped to one session's context.
      */
     readonly parentTraceContext?: SessionTraceContext;
-    /**
-     * Runtime-supplied session limits. Delegated local subagents use this to
-     * carry the parent's remaining quota and delegation caps with the same limit
-     * fields authors configure on agents; `false` means no inherited token cap
-     * for that axis.
-     */
-    readonly limits?: RunSessionLimits;
     /** Framework-owned metadata for a protocol-neutral external invocation. */
     readonly externalInvocation?: {
         readonly continuationToken: string;
@@ -551,9 +556,12 @@ export interface Runtime {
     /**
      * Resolves the session that currently owns a continuation token without
      * delivering input or starting a run. Returns `undefined` when no session
-     * owns the token.
+     * owns the token. With `runnable`, throws `SessionStrandedError` when the
+     * owner is stranded and can run nothing.
      */
-    resolveContinuation(continuationToken: string): Promise<{
+    resolveContinuation(continuationToken: string, options?: {
+        readonly runnable?: boolean;
+    }): Promise<{
         sessionId: string;
     } | undefined>;
     /**