experimental-ash 0.22.2 → 0.24.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # experimental-ash
 
+## 0.24.0
+
+### Minor Changes
+
+- 1a43bef: Remove `result` from `RunHandle`. The workflow runtime's terminal state is observed through the durable event stream's `session.completed` / `session.failed` events. The continuous runtime keeps `result` via a new `ContinuousRunHandle` subtype (in-process resolution; no polling).
+- 5a9f798: Split the durable workflow runtime into a long-lived session driver plus per-turn child workflows. The driver acquires the session's writable once in its workflow body and forwards it to each turn workflow as the second positional `start()` argument; the per-turn child writes directly to the driver's stream, preserving the stable client session stream while preparing turn execution for deployment updates. Requires `@workflow/core` ≥ 5.0.0-beta.6 ([vercel/workflow#2059](https://github.com/vercel/workflow/pull/2059)), which routes child writes to the parent run's stream with a parent-key encrypt-only handshake.
+- 8b2957a: Remove the continuous (in-memory, non-durable) runtime and its supporting
+  machinery. The workflow runtime is now the only runtime. Deleted public
+  exports: `createContinuousLoopRuntime`, `createContinuousLoopRuntimeFactory`,
+  `ContinuousRuntime`, `ContinuousCreateRuntime`, `ContinuousRunHandle`. The
+  process-local subagent HITL dispatcher registry
+  (`registerContinuousSubagentInputRequestDispatcher` /
+  `unregisterContinuousSubagentInputRequestDispatcher`) is also removed —
+  subagent `input.requested` events now always forward to the parent via the
+  workflow `resumeHook` path.
+
+### Patch Changes
+
+- 8ca8600: fix(ash): honor `defineInstrumentation` exports when running under Nitro
+
+  Nitro evaluates the harness's instrumentation-config module twice (once via the generated plugin's `file://` URL, once via the inlined `#harness/*` alias), so a module-local store left the harness reading `undefined` even after the plugin registered a config. The config now lives on `globalThis` under a stable `Symbol.for(...)`, so telemetry actually flows when an `agent/instrumentation.ts` default export is present.
+
+## 0.23.0
+
+### Minor Changes
+
+- 316f6c5: feat(ash): add `defineState` for typed durable state, remove raw `ContextKey` from public API
+
+  `defineState(name, initial)` creates a typed state handle with `get()` and `update()`. All operations throw outside the Ash context scope. Replaces the `ContextKey` + `ensureContext` / `setContext` / `requireContext` pattern with a single primitive.
+
+  Breaking: `ContextKey`, `ensureContext`, `getContext`, `setContext`, `requireContext`, `hasContext`, `ContextAccessor`, `AshContext`, `ContextProvider`, and `ContextReader` are no longer exported from `experimental-ash/context`.
+
+### Patch Changes
+
+- 5aedab4: Add browser client support for one-turn `clientContext`, React `prepareSend`, and AI SDK `UserContent` messages.
+
 ## 0.22.2
 
 ### Patch Changes

package/dist/docs/internals/hooks.md

@@ -84,22 +84,19 @@ the workflow path.
 
 ## Dispatch
 
-Lifecycle dispatch lives in `src/context/hook-lifecycle.ts`. Both
-runtime entry points (`execution/workflow-steps.ts` for the durable
-workflow path and `execution/continuous-entry.ts` for the in-memory
-continuous path) call `runHookLifecycleStep` once per turn, **inside**
-the active ALS scope so hook code can read and write `ctx.ash` like
-every other authored function. `runHookLifecycleStep` wraps
-`dispatchHookLifecycle`, lowers a `turn-failed` outcome into a parking
-`StepResult` (`{ next: null }` for conversation mode,
-`{ next: { done: true, output } }` for task mode), and otherwise hands
-off to the supplied harness step callback with the (possibly
-augmented) input.
-
-Both runtime entry points gate dispatch on
-`getHarnessEmissionState(session).turnId === ""` so tool-loop
-continuations and runtime-action resumes (which are continuations of
-an existing turn) skip the lifecycle stack.
+Lifecycle dispatch lives in `src/context/hook-lifecycle.ts`. The
+workflow runtime entry point (`execution/workflow-steps.ts`) calls
+`runHookLifecycleStep` once per turn, **inside** the active ALS scope
+so hook code can read and write `ctx.ash` like every other authored
+function. `runHookLifecycleStep` wraps `dispatchHookLifecycle`, lowers
+a `turn-failed` outcome into a parking `StepResult` (`{ next: null }`
+for conversation mode, `{ next: { done: true, output } }` for task
+mode), and otherwise hands off to the supplied harness step callback
+with the (possibly augmented) input.
+
+Dispatch is gated on `getHarnessEmissionState(session).turnId === ""`
+so tool-loop continuations and runtime-action resumes (which are
+continuations of an existing turn) skip the lifecycle stack.
 
 Stages, in order:
 

package/dist/docs/internals/message-runtime.md

@@ -64,4 +64,4 @@ The runtime stores both `auth.current` and `auth.initiator`. Follow-up messages
 
 The runtime owns stream plumbing; the channel owns delivery policy. The runtime calls `channel.onEvent(event)` for each lifecycle event — the channel may transform it or perform platform side effects. The harness emits events without knowing the transport.
 
-Authored stream-event hooks fan out alongside `callAdapterEventHandler` from the same `HarnessEmitFn` composer (`workflow-steps.ts` and `continuous-runtime.ts`). Hook errors propagate through the emit composer and are caught by the existing harness error path, which emits the recoverable `turn.failed` cascade. See [Hooks](./hooks.md).
+Authored stream-event hooks fan out alongside `callAdapterEventHandler` from the same `HarnessEmitFn` composer (`workflow-steps.ts`). Hook errors propagate through the emit composer and are caught by the existing harness error path, which emits the recoverable `turn.failed` cascade. See [Hooks](./hooks.md).

package/dist/docs/public/auth-and-route-protection.md

@@ -110,9 +110,9 @@ Important behavior:
 - follow-up messages update `auth.current` without changing `auth.initiator`
 - unprotected agents expose both as `null`
 
-Auth on follow-up messages (`deliver()`) is honored by both the workflow and continuous runtimes.
-When a different user sends a follow-up to the same session, `session.auth.current` reflects the
-new caller on that turn while `session.auth.initiator` stays the same.
+Auth on follow-up messages (`deliver()`) is honored by the workflow runtime. When a different
+user sends a follow-up to the same session, `session.auth.current` reflects the new caller on
+that turn while `session.auth.initiator` stays the same.
 
 ## What Ash Does Not Do
 

package/dist/docs/public/faqs.md

@@ -0,0 +1,67 @@
+---
+title: "FAQs"
+description: "Frequently asked questions about Ash."
+---
+
+# FAQs
+
+## How do I view my agent's observability and drill into conversation traces?
+
+When you deploy an Ash agent to Vercel, the platform auto-detects `ash` as the
+framework, which surfaces an **Agent Runs** tab under your project's
+**Observability** view in the Vercel dashboard. From there you can browse
+sessions and drill into each conversation's trace.
+
+> The Agent Runs tab is currently gated — your Vercel team needs the feature
+> enabled before it appears. If you don't see it, reach out to your Vercel
+> contact to get your team enabled.
+
+Agent Runs is separate from the OpenTelemetry exporters configured in
+[`instrumentation.ts`](./instrumentation.md) — those still work and are the
+recommended path if you want spans in Braintrust, Datadog, or another
+third-party backend.
+
+## Does Ash use the Chat SDK?
+
+Ash uses Chat SDK's **card-builder components** (Cards, Buttons,
+Actions, etc.) for composing rich Slack messages — when you build a card with
+Ash's Slack channel, the underlying primitives come from Chat SDK and get
+converted to Slack Block Kit at post time.
+
+Ash does **not** use Chat SDK's runtime. The `Chat`, `Adapter`, and `Thread`
+primitives are never imported or reachable through Ash's public API. Ash's
+channel layer — webhook handling, signature verification, event parsing, and
+thread management — is implemented inside Ash itself (see [Channels](./channels/)).
+
+In short:
+
+- **Building Slack messages** → the components feel just like Chat SDK cards.
+- **Wiring a channel** → you author against Ash's `defineChannel(...)` API, not
+  a Chat SDK adapter.
+
+## How is session data persisted?
+
+Ash persists session state automatically using the
+[Workflow SDK](https://workflow-sdk.dev) — an open-source TypeScript
+library that makes ordinary functions durable, resumable, and crash-safe.
+Each Ash session corresponds to one workflow run: when a new message comes in,
+the runtime either starts a new workflow or resumes an existing one, and the
+durable context is serialized and threaded forward across each model-call
+boundary so the session can be reloaded on the next turn.
+
+You don't write workflow code directly. Workflow primitives (`start()`,
+`resumeHook()`, etc.) are an implementation detail of Ash's runtime layer —
+channels, tools, and hooks never touch them. This separation is enforced by
+the framework's mechanical invariants.
+
+If you want session data from your own code, there are two supported surfaces:
+
+- **Tools** can read the current session's metadata (sessionId, turn, auth,
+  parent lineage) via `getSession()` from `experimental-ash/context`. This is
+  read-only.
+- **Durable context keys + `ContextProvider`** are the supported pattern for
+  reading or writing session-scoped durable state from authored code — see
+  [Session Context](./session-context.md).
+
+For the wire-level session lifecycle (creating sessions, streaming events,
+reconnecting by event index) see [Sessions And Streaming](./runs-and-streaming.md).

package/dist/docs/public/meta.json

@@ -25,6 +25,7 @@
     "cli-build-and-debugging",
     "typescript-api",
     "...",
+    "faqs",
     "---",
     "research"
   ]

package/dist/docs/public/schedules.md

@@ -166,6 +166,17 @@ In both cases, the schedule session uses the **app principal**: `getSession().au
 
 The session goes through the same durable runtime engine as any other Ash session.
 
+## On Vercel
+
+On hosted Vercel builds, Ash compiles every `defineSchedule(...)` into a Vercel Cron Job. Each schedule's `cron` expression becomes an entry in `.vercel/output/config.json` `crons[]`, which the platform reads at deploy time.
+
+You can view and monitor your schedules in two places in the Vercel dashboard:
+
+- **Settings → Cron Jobs** — lists every schedule the deployment registered, with its cron expression and target path. Use this to confirm a schedule was discovered and shipped.
+- **Observability → Cron Jobs** — shows execution history (when each schedule fired, success/failure, latency). Use this to confirm a schedule is actually firing on cadence.
+
+The execution itself runs through the same durable runtime engine as any other Ash session, so per-run logs also appear under **Observability → Logs**.
+
 ## When to use a schedule
 
 Use a schedule when the agent should initiate work on its own cadence:

package/dist/docs/public/session-context.md

@@ -1,6 +1,6 @@
 ---
 title: "Session Context"
-description: "Runtime helpers: getSession, getSandbox, getSkill, and ContextKey."
+description: "Runtime helpers: getSession, getSandbox, getSkill, and defineState."
 ---
 
 Ash exposes runtime helpers for authored code:
@@ -8,16 +8,10 @@ Ash exposes runtime helpers for authored code:
 - `getSession()`
 - `getSandbox()`
 - `getSkill(identifier)`
-- `getContext(key)` -- returns `T | undefined`
-- `requireContext(key)` -- returns `T`, throws if unset
-- `hasContext(key)` -- returns `boolean`
-- `setContext(key, valueOrUpdater)` -- returns `T`
-- `ensureContext(key, factory)` -- returns `T`
+- `defineState(name, initial)` -- typed durable state with `get()` and `update()`
 
 These APIs work only inside active authored runtime execution such as tools, channel event
-handlers, and authored hooks. Under the hood, they read from a single `AshContext` container that
-the framework binds to the current async call chain via `AsyncLocalStorage`. Authored hooks
-receive the same `ContextAccessor` on `HookContext.ash` -- see [Hooks](./hooks.md).
+handlers, and authored hooks. They throw when called outside a managed context.
 
 ## `getSession()`
 
@@ -107,112 +101,75 @@ Important behavior:
 
 See [Skills](./skills.md) for the full authoring model.
 
-## Passing Custom Context From a Channel
+## Custom State With `defineState`
 
-Channels can inject custom typed durable context into the agent via the channel's `state` and
-`context()` properties on `defineChannel`, or via the auth attributes returned from `onAppMention`
-or `onDirectMessage` on `slackChannel()`. This is useful when a channel needs to pass
-platform-specific metadata (tenant ID, feature flags, etc.) that authored tools can read on the
-same turn and on later turns.
+Use `defineState` when your agent needs durable typed state that tools, hooks, and channel
+handlers can share. State survives across workflow step boundaries.
 
-### Defining a key
+### Defining state
 
-Declare a `ContextKey` at module scope. The key is shared between the channel and the tools that
-read it.
+Declare the state handle at module scope. The handle is shared between all code that imports it.
 
-`agent/channels/keys.ts`
+`agent/lib/budget.ts`
 
 ```ts
-import { ContextKey } from "experimental-ash/context";
+import { defineState } from "experimental-ash/context";
 
-export const TenantKey = new ContextKey<string>("myapp.tenant");
-```
-
-### Setting context from a channel
-
-Use `slackChannel()` and seed context via the `onAppMention` return value's auth attributes:
-
-`agent/channels/slack.ts`
+interface BudgetState {
+  readonly count: number;
+  readonly cap: number;
+}
 
-```ts
-import { slackChannel } from "experimental-ash/channels/slack";
-import { TenantKey } from "./keys.js";
-
-export default slackChannel({
-  onAppMention(ctx, message) {
-    if (!message.author) return null;
-    const tenantId = lookupTenant(message);
-    return {
-      auth: {
-        principalId: message.author.userId,
-        principalType: "user",
-        authenticator: "slack",
-        attributes: { tenantId },
-      },
-    };
-  },
-  events: {
-    "message.completed"(event, ctx) {
-      if (event.finishReason === "tool-calls") return;
-      if (event.message) ctx.thread.post(event.message);
-    },
-    "session.failed"(event, ctx) {
-      ctx.thread.post("Something went wrong.");
-    },
-  },
-});
+export const budget = defineState<BudgetState>("myapp.budget", () => ({
+  count: 0,
+  cap: 25,
+}));
 ```
 
-Auth lives on the return value of `onAppMention` (or `onDirectMessage` for 1:1 DMs), not on a
-separate channel object.
-
-### Reading context from a tool
+### Reading and writing from tools
 
 ```ts
-import { requireContext } from "experimental-ash/context";
 import { defineTool } from "experimental-ash/tools";
 import { z } from "zod";
-import { TenantKey } from "../channels/keys.js";
+import { budget } from "../lib/budget.js";
 
 export default defineTool({
-  description: "Return the active tenant.",
+  description: "Check the remaining tool budget.",
   inputSchema: z.object({}),
   async execute() {
-    const tenant = requireContext(TenantKey);
-    return { tenant };
+    const current = budget.get();
+    return { remaining: current.cap - current.count };
   },
 });
 ```
 
-### Rebuilding virtual values with `ContextProvider`
-
-If a channel needs to vend a live non-serializable object each step, declare a `ContextProvider`.
-Providers derive live step-local values from durable context keys.
-
-The intended pattern is:
-
-- The channel's event handler or `run()` setup writes durable serializable facts such as
-  tenant IDs, channel IDs, or installation IDs.
-- A `ContextProvider` derives live step-local values such as SDK clients from those durable keys.
-- Tools and other authored step code read the derived value with `requireContext(...)` or
-  `getContext(...)`.
+### Updating from hooks
 
 ```ts
-import { ContextKey, type ContextProvider } from "experimental-ash/context";
-
-const TenantKey = new ContextKey<string>("myapp.tenant");
-const SlackClientKey = new ContextKey<{ readonly tenantId: string }>("myapp.slackClient");
-
-const slackClientProvider: ContextProvider<{ readonly tenantId: string }> = {
-  key: SlackClientKey,
-  create(ctx) {
-    return { tenantId: ctx.require(TenantKey) };
+import { defineHook } from "experimental-ash/hooks";
+import { budget } from "../lib/budget.js";
+
+export default defineHook({
+  lifecycle: {
+    turn() {
+      // Reset budget each turn
+      budget.update(() => ({ count: 0, cap: 25 }));
+    },
+  },
+  events: {
+    "actions.requested"() {
+      budget.update((s) => ({ ...s, count: s.count + 1 }));
+    },
   },
-};
+});
 ```
 
-Provider output is readable through `requireContext(SlackClientKey)` or
-`getContext(SlackClientKey)` during that step, but it is not serialized.
+### API
+
+| Method       | Description                                                                      |
+| ------------ | -------------------------------------------------------------------------------- |
+| `get()`      | Read the current value. Returns `initial()` on first access. Throws outside ALS. |
+| `update(fn)` | Apply a function to the current value. Throws outside ALS.                       |
 
 ## Where These APIs Work
 
@@ -233,7 +190,7 @@ explaining the required scope.
 
 ## How It Works
 
-All three accessors read from the same `AshContext` container bound by a single `AsyncLocalStorage`.
+All runtime accessors read from the same `AshContext` container bound by a single `AsyncLocalStorage`.
 The framework sets up this context before invoking authored code:
 
 1. The runtime entry point creates an `AshContext` and populates durable seed keys (auth, session

package/dist/docs/public/skills.md

@@ -137,6 +137,19 @@ Do not use a skill for:
 - shell or filesystem setup for the agent -> use `sandbox/`
 - a truly separate specialist surface -> use a subagent
 
+## Skill Scoping Across Agents
+
+Skills are scoped to the agent that declares them. The root agent's `skills/` are available only
+to the root agent; a subagent's `skills/` (under `agent/subagents/<id>/skills/`) are available
+only to that subagent.
+
+There is no shared-skill mechanism. If two agents need the same procedure, either duplicate the
+markdown under each agent's `skills/`, or — if both agents really need the _same_ identity around
+it — reconsider whether the subagent boundary makes sense.
+
+For sharing executable helpers (not skill instructions), use `lib/` — modules under `lib/` are not
+indexed as skills, but can be imported from any tool or hook in the same agent tree.
+
 ## TypeScript-Authored Skills
 
 If markdown is not enough, you can author a skill in TypeScript with `defineSkill(...)`.

package/dist/docs/public/subagents.md

@@ -69,14 +69,20 @@ Subagent execution gets:
 - its own instructions prompt
 - its own tools
 - its own sandbox (independent of the parent's sandbox)
-- its own skill activation state
+- its own `skills/` set (independent of the parent's skills)
 - immediate parent lineage in `getSession().parent`
 
-The subagent's sandbox does not inherit from the parent. Different agents generally have different
-skills, so sharing a filesystem would be confusing. Each subagent gets the framework default
-sandbox unless it authors its own override at `subagents/<name>/sandbox.ts` (or
-`subagents/<name>/sandbox/sandbox.ts` when paired with a `workspace/` folder). A subagent can also
-author only `subagents/<name>/sandbox/workspace/` to seed files without overriding the definition.
+Skills and sandboxes do not cross the parent/child boundary. The subagent only sees skills
+authored under `agent/subagents/<id>/skills/`; skills under the root `agent/skills/` are not
+available inside the subagent's turns. If two subagents need the same procedure, duplicate the
+markdown under each subagent's `skills/` (or, for typed code reuse, share helpers via `lib/`).
+
+The subagent's sandbox follows the same rule: it does not inherit from the parent, since different
+agents generally have different skills and sharing a filesystem would be confusing. Each subagent
+gets the framework default sandbox unless it authors its own override at
+`subagents/<name>/sandbox.ts` (or `subagents/<name>/sandbox/sandbox.ts` when paired with a
+`workspace/` folder). A subagent can also author only `subagents/<name>/sandbox/workspace/` to seed
+files without overriding the definition.
 
 ## Stream Behavior
 

package/dist/docs/public/tools.md

@@ -40,7 +40,7 @@ There is no `name` override and no compile-time normalization — if you want a
 identifier, name the file in snake_case.
 
 `defineTool`, `disableTool`, `defineBashTool`, `defineReadFileTool`, and `defineWriteFileTool` live on the `experimental-ash/tools` subpath.
-Runtime context helpers (`getSession`, `getContext`, `requireContext`, `hasContext`, `setContext`, `ensureContext`) live on `experimental-ash/context`.
+Runtime context helpers (`getSession`, `defineState`) live on `experimental-ash/context`.
 `getSandbox` lives on `experimental-ash/sandbox` and `getSkill` lives on `experimental-ash/skills`.
 
 ## What A Tool Definition Needs
@@ -205,14 +205,13 @@ The runtime tool name comes from the filename (here, `repo_shell`, `read_file`,
 When replacing the framework `read_file`, the authored version inherits the same compaction
 state-reset behavior by default. Provide an explicit `onCompact` to override that.
 
-### Replace A Default With Custom Context
+### Replace A Default With Custom State
 
-`agent/tools/todo.ts` - replace the framework `todo` tool with a custom durable context-backed
-version. Declare your own `ContextKey`, initialize it with `ensureContext`, and read/write it with
-`requireContext` / `setContext`:
+`agent/tools/todo.ts` - replace the framework `todo` tool with a custom durable state-backed
+version using `defineState`:
 
 ```ts
-import { ContextKey, ensureContext, requireContext, setContext } from "experimental-ash/context";
+import { defineState } from "experimental-ash/context";
 import { defineTool } from "experimental-ash/tools";
 import { z } from "zod";
 
@@ -220,7 +219,7 @@ interface NoteListState {
   readonly notes: readonly string[];
 }
 
-const NoteListStateKey = new ContextKey<NoteListState>("myapp.notes");
+const noteList = defineState<NoteListState>("myapp.notes", () => ({ notes: [] }));
 
 export default defineTool({
   description: "Append a note or read the running list of notes.",
@@ -228,15 +227,12 @@ export default defineTool({
     note: z.string().optional(),
   }),
   async execute(input) {
-    ensureContext(NoteListStateKey, () => ({ notes: [] }));
-
     if (typeof input.note === "string" && input.note.length > 0) {
-      const next = input.note;
-      setContext(NoteListStateKey, (current) => ({
-        notes: [...(current?.notes ?? []), next],
+      noteList.update((current) => ({
+        notes: [...current.notes, input.note!],
       }));
     }
-    return requireContext(NoteListStateKey);
+    return noteList.get();
   },
 });
 ```

package/dist/docs/public/typescript-api.md

@@ -53,17 +53,17 @@ Each runtime accessor lives on the subpath that owns its concern:
 - `getSession()` - current session, turn, auth, and optional parent lineage (`experimental-ash/context`)
 - `getSandbox()` - live sandbox handle for the current agent (`experimental-ash/sandbox`)
 - `getSkill(identifier)` - handle for a named skill visible to the current agent (`experimental-ash/skills`)
-- `getContext(key)` / `requireContext(key)` / `hasContext(key)` / `setContext(key)` / `ensureContext(key, factory)` - unified context helpers (`experimental-ash/context`)
+- `defineState(name, initial)` - typed durable state with `get()` and `update()` (`experimental-ash/context`)
 
 Related exported types by subpath:
 
-- `experimental-ash/context`: `Session`, `SessionAuth`, `SessionAuthContext`, `SessionParent`, `SessionTurn`, `ContextKey`, `ContextKeyOptions`, `ContextProvider`, `ContextReader`, `ContextAccessor`, `AshContext`
+- `experimental-ash/context`: `Session`, `SessionAuth`, `SessionAuthContext`, `SessionParent`, `SessionTurn`, `StateHandle`
 - `experimental-ash/skills`: `SkillHandle`, `SkillFile`, `SkillDefinition`
 - `experimental-ash`: `RunMode`
 - `experimental-ash/evals`: eval types
 
-Ash also exports lower-level runtime primitives such as `createToolLoopHarness(...)`,
-`createContinuousLoopRuntime(...)`, and `createWorkflowRuntime(...)`.
+Ash also exports lower-level runtime primitives such as `createToolLoopHarness(...)`
+and `createWorkflowRuntime(...)`.
 
 Channel and Slack types exported from `experimental-ash/channels/slack`:
 

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

@@ -38,9 +38,9 @@ export interface SessionAuthContext {
 /**
  * Function provided by the runtime that writes one event to the event stream.
  *
- * Backed by `getWritable()` in the workflow runtime or a `TransformStream`
- * in the continuous loop runtime. Not part of the adapter interface —
- * the runtime always writes events to the stream itself.
+ * Backed by `getWritable()` in the workflow runtime. Not part of the
+ * adapter interface — the runtime always writes events to the stream
+ * itself.
  */
 export type EventEmitFn = (event: HandleMessageStreamEvent) => Promise<void>;
 /**
@@ -195,7 +195,10 @@ export interface DeliverInput {
     readonly payload: DeliverPayload;
 }
 /**
- * Terminal outcome of a runtime turn, resolved via `RunHandle.result`.
+ * Terminal outcome of a runtime run.
+ *
+ * Terminal state on the workflow runtime is observed through the durable
+ * event stream's `session.completed` / `session.failed` events.
  */
 export type RunResult = {
     readonly status: "completed";
@@ -207,19 +210,14 @@ export type RunResult = {
  * Handle returned immediately by `runtime.run()` before the step loop
  * completes.
  *
- * Carries the identifiers needed for stream endpoints and the eventual
- * result as a promise.
+ * Carries the identifiers needed for stream endpoints.
  */
 export interface RunHandle {
     readonly continuationToken: string;
     readonly events: ReadableStream<HandleMessageStreamEvent>;
-    readonly result: Promise<RunResult>;
     /**
-     * Runtime-owned identifier for this session.
-     *
-     * Used for stream and inspection APIs. Workflow-backed runs expose
-     * the workflow run id; continuous runs mint an in-memory session id
-     * when the run starts.
+     * Runtime-owned identifier for this session. Used for stream and
+     * inspection APIs — workflow-backed runs expose the workflow run id.
      */
     readonly sessionId: string;
 }

package/dist/src/chunks/{client-CKsU8Li3.js → client-nshDsWNF.js}

@@ -1,4 +1,4 @@
 import{i as e,t}from"./chunk-8L7ocgPr.js";import{_ as n,f as r,g as i,l as a,p as o,v as s}from"./types-MZUhN0Zy.js";import{n as c,r as l,t as u}from"./token-util-CHjOk3A7.js";var d=class extends Error{status;body;constructor(e,t){super(t||`Server returned ${e}.`),this.name=`ClientError`,this.status=e,this.body=t}};function f(e){if(e instanceof DOMException)return e.name===`AbortError`;if(!(e instanceof Error))return!1;let t=`code`in e&&typeof e.code==`string`?e.code:void 0;return e.name===`AbortError`||e.message===`terminated`||t===`UND_ERR_SOCKET`||/abort|cancel|disconnect|premature close|socket|terminated/i.test(e.message)}async function*p(e){let t=e.getReader(),n=new TextDecoder,r=``;try{for(;;){let e=await t.read();if(e.done){r+=n.decode();break}e.value&&(r+=n.decode(e.value,{stream:!0}));let i=r.indexOf(`
 `);for(;i!==-1;){let e=r.slice(0,i).trim();r=r.slice(i+1),e.length>0&&(yield JSON.parse(e)),i=r.indexOf(`
 `)}}let e=r.trim();e.length>0&&(yield JSON.parse(e))}finally{t.releaseLock()}}function m(e,t,n){let r=t.startsWith(`/`)?t:`/${t}`,i=_(n);if(h(e)){let t=new URL(e);return t.pathname=`${g(t.pathname)}${r}`,t.search=i,t.hash=``,t.toString()}return`${g(e)}${r}${i}`}function h(e){return/^[a-z][a-z\d+\-.]*:/i.test(e)}function g(e){return e===`/`?``:e.endsWith(`/`)?e.slice(0,-1):e}function _(e){return!e||Object.keys(e).length===0?``:`?${new URLSearchParams(e).toString()}`}async function*v(e){let t=e.startIndex,n=e.maxReconnectAttempts;for(;;){let r=m(e.host,s(e.sessionId),t>0?{startIndex:String(t)}:void 0),i=await e.resolveHeaders(),a=await fetch(r,{headers:i,signal:e.signal??null});if(!a.ok){let e=await a.text();throw new d(a.status,e)}if(!a.body)throw new d(a.status,`Response body is null.`);let o=!1;try{for await(let e of p(a.body))t+=1,yield e}catch(e){if(!f(e))throw e;o=!0}if(!o||n<=0)return;--n}}var y=t(((e,t)=>{var n=Object.defineProperty,r=Object.getOwnPropertyDescriptor,i=Object.getOwnPropertyNames,a=Object.prototype.hasOwnProperty,o=(e,t)=>{for(var r in t)n(e,r,{get:t[r],enumerable:!0})},s=(e,t,o,s)=>{if(t&&typeof t==`object`||typeof t==`function`)for(let c of i(t))!a.call(e,c)&&c!==o&&n(e,c,{get:()=>t[c],enumerable:!(s=r(t,c))||s.enumerable});return e},c=e=>s(n({},`__esModule`,{value:!0}),e),l={};o(l,{SYMBOL_FOR_REQ_CONTEXT:()=>u,getContext:()=>d}),t.exports=c(l);let u=Symbol.for(`@vercel/request-context`);function d(){return globalThis[u]?.get?.()??{}}})),b=t(((t,n)=>{var r=Object.defineProperty,i=Object.getOwnPropertyDescriptor,a=Object.getOwnPropertyNames,o=Object.prototype.hasOwnProperty,s=(e,t)=>{for(var n in t)r(e,n,{get:t[n],enumerable:!0})},c=(e,t,n,s)=>{if(t&&typeof t==`object`||typeof t==`function`)for(let c of a(t))!o.call(e,c)&&c!==n&&r(e,c,{get:()=>t[c],enumerable:!(s=i(t,c))||s.enumerable});return e},u=e=>c(r({},`__esModule`,{value:!0}),e),d={};s(d,{getVercelOidcToken:()=>m,getVercelOidcTokenSync:()=>h}),n.exports=u(d);var f=y(),p=l();async function m(t){let n=``,r;try{n=h()}catch(e){r=e}try{let[{getTokenPayload:r,isExpired:i},{refreshToken:a}]=await Promise.all([await import(`./token-util-CHjOk3A7.js`).then(t=>e(t.t())),await import(`./token-DtoyQZy2.js`).then(t=>e(t.default))]);(!n||i(r(n),t?.expirationBufferMs))&&(await a(t),n=h())}catch(e){let t=r instanceof Error?r.message:``;throw e instanceof Error&&(t=`${t}
-${e.message}`),t?new p.VercelOidcTokenError(t):e}return n}function h(){let e=(0,f.getContext)().headers?.[`x-vercel-oidc-token`]??process.env.VERCEL_OIDC_TOKEN;if(!e)throw Error(`The 'x-vercel-oidc-token' header is missing from the request. Do you have the OIDC option enabled in the Vercel project settings?`);return e}})),x=t(((e,t)=>{var n=Object.defineProperty,r=Object.getOwnPropertyDescriptor,i=Object.getOwnPropertyNames,a=Object.prototype.hasOwnProperty,o=(e,t)=>{for(var r in t)n(e,r,{get:t[r],enumerable:!0})},s=(e,t,o,s)=>{if(t&&typeof t==`object`||typeof t==`function`)for(let c of i(t))!a.call(e,c)&&c!==o&&n(e,c,{get:()=>t[c],enumerable:!(s=r(t,c))||s.enumerable});return e},l=e=>s(n({},`__esModule`,{value:!0}),e),d={};o(d,{AccessTokenMissingError:()=>m.AccessTokenMissingError,RefreshAccessTokenFailedError:()=>m.RefreshAccessTokenFailedError,getContext:()=>p.getContext,getVercelOidcToken:()=>f.getVercelOidcToken,getVercelOidcTokenSync:()=>f.getVercelOidcTokenSync,getVercelToken:()=>h.getVercelToken}),t.exports=l(d);var f=b(),p=y(),m=c(),h=u()})),S=x();const C=`${i}/`,w=new Set([`localhost`,`127.0.0.1`,`0.0.0.0`,`::1`,`[::1]`]);function T(e){return w.has(e.hostname)}const E=`x-vercel-protection-bypass`,D=`x-vercel-trusted-oidc-idp-token`;function O(e){return e.pathname.endsWith(`/ash/v1`)||e.pathname.includes(C)}async function k(e){let t=A(e),n=await M(t,e.resourceUrl);return n!==null&&j(t,n),t}function A(e){let t=new Headers(F(e.headers)),n=process.env.VERCEL_AUTOMATION_BYPASS_SECRET?.trim();return n&&O(e.resourceUrl)&&t.set(E,n),t}function j(e,t){e.has(`authorization`)||e.set(`authorization`,`Bearer ${t}`),e.set(D,t)}async function M(e,t){return N(t)?e.get(`x-vercel-oidc-token`)?.trim()||await P():null}function N(e){return!(!O(e)||T(e))}async function P(){let e=process.env.VERCEL_OIDC_TOKEN?.trim();try{let e=(await(0,S.getVercelOidcToken)()).trim();if(e.length>0)return e}catch{return e??null}return e??null}function F(e){if(e!==void 0)return e instanceof Headers?e:Array.isArray(e)?e.map(([e,t])=>[e,t]):e}function I(){return{streamIndex:0}}function L(e){let t=B(e.events),n=e.session.streamIndex+e.events.length;return t?.type===`session.waiting`?{continuationToken:e.continuationToken??e.session.continuationToken,sessionId:e.sessionId,streamIndex:n}:I()}function R(e){let t;for(let n of e)V(n)&&(t=n.data.message??void 0);return t}function z(e){let t=B(e);return t?.type===`session.waiting`?`waiting`:t?.type===`session.failed`?`failed`:`completed`}function B(e){for(let t=e.length-1;t>=0;t--){let n=e[t];if(n!==void 0&&a(n))return n}}function V(e){return e.type===`message.completed`&&e.data.finishReason!==`tool-calls`}var H=class{continuationToken;sessionId;#e=!1;#t;constructor(e){this.continuationToken=e.continuationToken,this.sessionId=e.sessionId,this.#t=e.createStream}async result(){let e=[];for await(let t of this)e.push(t);return{events:e,message:R(e),sessionId:this.sessionId,status:z(e)}}[Symbol.asyncIterator](){if(this.#e)throw Error(`MessageResponse has already been consumed.`);return this.#e=!0,this.#t()}},U=class{#e;#t;constructor(e,t){this.#e=e,this.#t=t}get state(){return this.#t}async sendMessage(e,t){return this.send({message:e},t)}async send(e,t){let n=this.#t,{continuationToken:r,sessionId:i}=await this.#n(e,n,t);return new H({continuationToken:r,createStream:()=>this.#r(i,r,n,t),sessionId:i})}openStream(e){let t=this.#t.sessionId;if(!t)throw Error(`Session has no session ID. Send a message first.`);return v({host:this.#e.host,maxReconnectAttempts:this.#e.maxReconnectAttempts,resolveHeaders:()=>this.#e.resolveHeaders(),sessionId:t,signal:e?.signal,startIndex:e?.startIndex??this.#t.streamIndex})}async#n(e,t,i){let a=t.sessionId?n(t.sessionId):r,o=m(this.#e.host,a),s=await this.#e.resolveHeaders(i?.headers);s.set(`content-type`,`application/json`);let c=W({input:e,session:t});if(c===null)throw Error(`Session.send requires a non-empty message, inputResponses, or both.`);let l=await fetch(o,{body:JSON.stringify(c),headers:s,method:`POST`,signal:i?.signal??null});if(!l.ok){let e=await l.text();throw new d(l.status,e)}let u=await l.json(),f=(typeof u.sessionId==`string`?u.sessionId:void 0)??l.headers.get(`x-ash-session-id`)?.trim()??t.sessionId;if(!f)throw Error(`Message route did not return a session id.`);return{continuationToken:typeof u.continuationToken==`string`?u.continuationToken:void 0,sessionId:f}}async*#r(e,t,n,r){let i=[];try{let t=n.sessionId===e?n.streamIndex:0,o=this.#e.maxReconnectAttempts;for(;;){let n=await this.#i(e,t,r?.signal),s=!1;try{for await(let e of p(n))if(i.push(e),t+=1,yield e,a(e)){s=!0;break}}catch(e){if(!f(e))throw e}if(s||o<=0)break;--o}}finally{this.#t=L({continuationToken:t,events:i,sessionId:e,session:n})}}async#i(e,t,n){let r=m(this.#e.host,s(e),t>0?{startIndex:String(t)}:void 0),i=await this.#e.resolveHeaders(),a=await fetch(r,{headers:i,signal:n??null});if(!a.ok){let e=await a.text();throw new d(a.status,e)}if(!a.body)throw new d(a.status,`Response body is null.`);return a.body}};function W(e){let t={};return e.input.message!==void 0&&(t.message=e.input.message),e.input.inputResponses!==void 0&&e.input.inputResponses.length>0&&(t.inputResponses=e.input.inputResponses),e.session.continuationToken!==void 0&&(t.continuationToken=e.session.continuationToken),Object.keys(t).length===0||e.session.continuationToken===void 0&&t.message===void 0||`continuationToken`in t&&Object.keys(t).length===1?null:t}var G=class{#e;#t;#n;#r;constructor(e){this.#n=e.host,this.#e=e.auth,this.#t=e.headers,this.#r=e.maxReconnectAttempts??3}async health(){let e=m(this.#n,o),t=await this.#i(),n=await fetch(e,{headers:t});if(!n.ok){let e=await n.text();throw new d(n.status,e)}return await n.json()}session(e){let t;return t=typeof e==`string`?{continuationToken:e,streamIndex:0}:e||I(),new U({host:this.#n,maxReconnectAttempts:this.#r,resolveHeaders:e=>this.#i(e)},t)}async#i(e){let t=new Headers,n=await q(this.#t);for(let[e,r]of Object.entries(n))t.set(e,r);if(e)for(let[n,r]of Object.entries(e))t.set(n,r);let r=await this.#a();return r&&t.set(`authorization`,r),t}async#a(){let e=this.#e;if(e){if(`bearer`in e){let t=(await K(e.bearer)).trim();return t.length===0?void 0:`Bearer ${t}`}if(`basic`in e){let t=await K(e.basic.password);return`Basic ${J(e.basic.username,t)}`}}}};async function K(e){return typeof e==`function`?e():e}async function q(e){return e===void 0?{}:typeof e==`function`?await e():e}function J(e,t){let n=new TextEncoder().encode(`${e}:${t}`),r=Array.from(n,e=>String.fromCodePoint(e)).join(``);return btoa(r)}export{x as a,k as i,E as n,v as o,D as r,d as s,G as t};
+${e.message}`),t?new p.VercelOidcTokenError(t):e}return n}function h(){let e=(0,f.getContext)().headers?.[`x-vercel-oidc-token`]??process.env.VERCEL_OIDC_TOKEN;if(!e)throw Error(`The 'x-vercel-oidc-token' header is missing from the request. Do you have the OIDC option enabled in the Vercel project settings?`);return e}})),x=t(((e,t)=>{var n=Object.defineProperty,r=Object.getOwnPropertyDescriptor,i=Object.getOwnPropertyNames,a=Object.prototype.hasOwnProperty,o=(e,t)=>{for(var r in t)n(e,r,{get:t[r],enumerable:!0})},s=(e,t,o,s)=>{if(t&&typeof t==`object`||typeof t==`function`)for(let c of i(t))!a.call(e,c)&&c!==o&&n(e,c,{get:()=>t[c],enumerable:!(s=r(t,c))||s.enumerable});return e},l=e=>s(n({},`__esModule`,{value:!0}),e),d={};o(d,{AccessTokenMissingError:()=>m.AccessTokenMissingError,RefreshAccessTokenFailedError:()=>m.RefreshAccessTokenFailedError,getContext:()=>p.getContext,getVercelOidcToken:()=>f.getVercelOidcToken,getVercelOidcTokenSync:()=>f.getVercelOidcTokenSync,getVercelToken:()=>h.getVercelToken}),t.exports=l(d);var f=b(),p=y(),m=c(),h=u()})),S=x();const C=`${i}/`,w=new Set([`localhost`,`127.0.0.1`,`0.0.0.0`,`::1`,`[::1]`]);function T(e){return w.has(e.hostname)}const E=`x-vercel-protection-bypass`,D=`x-vercel-trusted-oidc-idp-token`;function O(e){return e.pathname.endsWith(`/ash/v1`)||e.pathname.includes(C)}async function k(e){let t=A(e),n=await M(t,e.resourceUrl);return n!==null&&j(t,n),t}function A(e){let t=new Headers(F(e.headers)),n=process.env.VERCEL_AUTOMATION_BYPASS_SECRET?.trim();return n&&O(e.resourceUrl)&&t.set(E,n),t}function j(e,t){e.has(`authorization`)||e.set(`authorization`,`Bearer ${t}`),e.set(D,t)}async function M(e,t){return N(t)?e.get(`x-vercel-oidc-token`)?.trim()||await P():null}function N(e){return!(!O(e)||T(e))}async function P(){let e=process.env.VERCEL_OIDC_TOKEN?.trim();try{let e=(await(0,S.getVercelOidcToken)()).trim();if(e.length>0)return e}catch{return e??null}return e??null}function F(e){if(e!==void 0)return e instanceof Headers?e:Array.isArray(e)?e.map(([e,t])=>[e,t]):e}function I(){return{streamIndex:0}}function L(e){let t=B(e.events),n=e.session.streamIndex+e.events.length;return t?.type===`session.waiting`?{continuationToken:e.continuationToken??e.session.continuationToken,sessionId:e.sessionId,streamIndex:n}:I()}function R(e){let t;for(let n of e)V(n)&&(t=n.data.message??void 0);return t}function z(e){let t=B(e);return t?.type===`session.waiting`?`waiting`:t?.type===`session.failed`?`failed`:`completed`}function B(e){for(let t=e.length-1;t>=0;t--){let n=e[t];if(n!==void 0&&a(n))return n}}function V(e){return e.type===`message.completed`&&e.data.finishReason!==`tool-calls`}var H=class{continuationToken;sessionId;#e=!1;#t;constructor(e){this.continuationToken=e.continuationToken,this.sessionId=e.sessionId,this.#t=e.createStream}async result(){let e=[];for await(let t of this)e.push(t);return{events:e,message:R(e),sessionId:this.sessionId,status:z(e)}}[Symbol.asyncIterator](){if(this.#e)throw Error(`MessageResponse has already been consumed.`);return this.#e=!0,this.#t()}},U=class{#e;#t;constructor(e,t){this.#e=e,this.#t=t}get state(){return this.#t}async sendMessage(e,t){return this.send({message:e},t)}async send(e,t){let n=this.#t,{continuationToken:r,sessionId:i}=await this.#n(e,n,t);return new H({continuationToken:r,createStream:()=>this.#r(i,r,n,t),sessionId:i})}openStream(e){let t=this.#t.sessionId;if(!t)throw Error(`Session has no session ID. Send a message first.`);return v({host:this.#e.host,maxReconnectAttempts:this.#e.maxReconnectAttempts,resolveHeaders:()=>this.#e.resolveHeaders(),sessionId:t,signal:e?.signal,startIndex:e?.startIndex??this.#t.streamIndex})}async#n(e,t,i){let a=t.sessionId?n(t.sessionId):r,o=m(this.#e.host,a),s=await this.#e.resolveHeaders(i?.headers);s.set(`content-type`,`application/json`);let c=W({input:e,session:t});if(c===null)throw Error(`Session.send requires a non-empty message, inputResponses, or both.`);let l=await fetch(o,{body:JSON.stringify(c),headers:s,method:`POST`,signal:i?.signal??null});if(!l.ok){let e=await l.text();throw new d(l.status,e)}let u=await l.json(),f=(typeof u.sessionId==`string`?u.sessionId:void 0)??l.headers.get(`x-ash-session-id`)?.trim()??t.sessionId;if(!f)throw Error(`Message route did not return a session id.`);return{continuationToken:typeof u.continuationToken==`string`?u.continuationToken:void 0,sessionId:f}}async*#r(e,t,n,r){let i=[];try{let t=n.sessionId===e?n.streamIndex:0,o=this.#e.maxReconnectAttempts;for(;;){let n=await this.#i(e,t,r?.signal),s=!1;try{for await(let e of p(n))if(i.push(e),t+=1,yield e,a(e)){s=!0;break}}catch(e){if(!f(e))throw e}if(s||o<=0)break;--o}}finally{this.#t=L({continuationToken:t,events:i,sessionId:e,session:n})}}async#i(e,t,n){let r=m(this.#e.host,s(e),t>0?{startIndex:String(t)}:void 0),i=await this.#e.resolveHeaders(),a=await fetch(r,{headers:i,signal:n??null});if(!a.ok){let e=await a.text();throw new d(a.status,e)}if(!a.body)throw new d(a.status,`Response body is null.`);return a.body}};function W(e){let t={};return e.input.message!==void 0&&(t.message=e.input.message),e.input.inputResponses!==void 0&&e.input.inputResponses.length>0&&(t.inputResponses=e.input.inputResponses),e.input.clientContext!==void 0&&(t.clientContext=e.input.clientContext),e.session.continuationToken!==void 0&&(t.continuationToken=e.session.continuationToken),Object.keys(t).length===0||e.session.continuationToken===void 0&&t.message===void 0||e.session.continuationToken!==void 0&&t.message===void 0&&t.inputResponses===void 0||`continuationToken`in t&&Object.keys(t).length===1?null:t}var G=class{#e;#t;#n;#r;constructor(e){this.#n=e.host,this.#e=e.auth,this.#t=e.headers,this.#r=e.maxReconnectAttempts??3}async health(){let e=m(this.#n,o),t=await this.#i(),n=await fetch(e,{headers:t});if(!n.ok){let e=await n.text();throw new d(n.status,e)}return await n.json()}session(e){let t;return t=typeof e==`string`?{continuationToken:e,streamIndex:0}:e||I(),new U({host:this.#n,maxReconnectAttempts:this.#r,resolveHeaders:e=>this.#i(e)},t)}async#i(e){let t=new Headers,n=await q(this.#t);for(let[e,r]of Object.entries(n))t.set(e,r);if(e)for(let[n,r]of Object.entries(e))t.set(n,r);let r=await this.#a();return r&&t.set(`authorization`,r),t}async#a(){let e=this.#e;if(e){if(`bearer`in e){let t=(await K(e.bearer)).trim();return t.length===0?void 0:`Bearer ${t}`}if(`basic`in e){let t=await K(e.basic.password);return`Basic ${J(e.basic.username,t)}`}}}};async function K(e){return typeof e==`function`?e():e}async function q(e){return e===void 0?{}:typeof e==`function`?await e():e}function J(e,t){let n=new TextEncoder().encode(`${e}:${t}`),r=Array.from(n,e=>String.fromCodePoint(e)).join(``);return btoa(r)}export{x as a,k as i,E as n,v as o,D as r,d as s,G as t};