experimental-ash 0.45.0 → 0.47.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # experimental-ash
 
+## 0.47.0
+
+### Minor Changes
+
+- f12c464: Ash message turns can now request deterministic structured output with `outputSchema`; fulfilled turns emit `result.completed` and client results expose typed `data`. Agents may also declare task-mode `outputSchema` for structured subagent, schedule, and job results.
+
+## 0.46.0
+
+### Minor Changes
+
+- 0d26330: Dynamic instructions can now be authored with `defineDynamic` + `defineInstructions` in `agent/instructions/`, matching the pattern for dynamic tools and skills. Resolvers subscribe to lifecycle events (`session.started`, `turn.started`, `step.started`) and return branded `defineInstructions(...)` entries containing `modelContext` (model messages) or `markdown` (lowered to system messages). The `agent/instructions/` directory also supports static `.md` files alongside dynamic `.ts` resolvers. The existing singular `agent/instructions.md` and `agent/instructions.ts` forms continue to work unchanged.
+- 4cdc490: Remove `modelContext` from `LifecycleHookResult`. Lifecycle hooks are now side-effect-only and cannot inject model messages. Use `defineDynamic` + `defineInstructions` in `agent/instructions/` to contribute runtime model messages instead.
+
+### Patch Changes
+
+- edebeec: Cancel the internal durable session tail stream after reading the latest snapshot and bound session hydration reads with a 10s timeout so turn startup does not leave workflow stream reads waiting indefinitely for a future chunk.
+- a944089: Fix session-killing "assistant message prefill" error on long conversations. When compaction reduced the recent window to messages trailing with an assistant response (e.g. deferred-input continuations where no user message was appended), the model call was rejected by providers that don't support assistant prefill. A synthetic user message is now appended to ensure the conversation always resumes from a user turn.
+- c890c00: Upgrade `@workflow/core`, `@workflow/world`, and `@workflow/world-local` to the latest betas. This picks up the upstream fix for cross-run writable stream encryption keys (a child run writing into another run's stream now resolves the owning run's key correctly), letting us drop the ash-side serialization source patch we previously vendored on top of `@workflow/core`.
+
 ## 0.45.0
 
 ### Minor Changes

package/dist/docs/internals/discovery.md

@@ -13,7 +13,7 @@ Discovery answers: given an app root and agent root, what authored sources exist
 
 `discoverAgent()` reads the agent root, sorts entries by name (for stable manifest ordering), and scans each slot:
 
-- `instructions.md` / `instructions.{ts,...}` — instructions prompt source. The legacy `system.{md,ts,...}` slot is still discovered as a fallback (deprecation warning).
+- `instructions.md` / `instructions.{ts,...}` / `instructions/` — instructions prompt source. Supports a flat file or a directory of `.md` and `.ts` files (including `defineDynamic` resolvers for runtime-resolved model messages). The legacy `system.{md,ts,...}` slot is still discovered as a fallback (deprecation warning).
 - `agent.ts` — optional config module (reference only)
 - `tools/` — module-backed, never imported. File stem becomes runtime tool name.
 - `hooks/` — module-backed lifecycle and stream-event subscribers, recursively discovered. Path-relative slug becomes the hook id.

package/dist/docs/internals/hooks.md

@@ -49,9 +49,9 @@ defineHook({
 ```
 
 The split between `lifecycle:` and `events:` is structural so the
-contract is explicit at the call site. `lifecycle:` may return
-`{ modelContext? }` — visible to the next model call only, never written
-to durable history. `events:` is observe-only.
+contract is explicit at the call site. Both are side-effect-only — hooks
+cannot inject model context. Use `defineDynamic` + `defineInstructions`
+in `agent/instructions/` to contribute runtime model messages.
 
 ## Pipeline
 
@@ -110,10 +110,7 @@ Stages, in order:
    flag **before** running the chain so a thrown hook does not retry on
    the next turn — `lifecycle.session` errors are terminal session
    failures (`session.failed`).
-2. **`lifecycle.turn`** runs sequentially. Each hook may return
-   `{ modelContext? }`. Contributions from session and turn are
-   concatenated; the resulting `modelContext` becomes a one-shot
-   addition to the next model call's message list. A thrown hook is
+2. **`lifecycle.turn`** runs sequentially. A thrown hook is
    caught here and lowered into a recoverable `turn.failed` cascade
    (`session.started` once → `turn.started` → `message.received` →
    `step.failed` → `turn.failed` → `session.waiting`).
@@ -188,8 +185,8 @@ The `discover/discover-subagent.ts` path walks each local subagent's
 
 ```
 dispatchHookLifecycle():
-  lifecycle.session hooks        (once per session, produce modelContext)
-  lifecycle.turn hooks           (once per turn, produce modelContext)
+  lifecycle.session hooks        (once per session, side-effect-only)
+  lifecycle.turn hooks           (once per turn, side-effect-only)
 
 emitTurnPreamble() via handleEvent:
   handleEvent(session.started)   → emit, hooks, dynamic tool resolvers
@@ -218,7 +215,7 @@ emitStepActions() via handleEvent:
   `src/runtime/resolve-hook.ts` ⇄ `runtime/resolve-hook.test.ts`).
 - Lifecycle dispatcher behavior is covered by
   `src/context/hook-lifecycle.integration.test.ts` (synthetic context,
-  session/turn modelContext threading, recoverable turn-failed path,
+  session/turn lifecycle dispatch, recoverable turn-failed path,
   stream-event fan-out, error propagation).
 - Discovery integration is folded into
   `src/discover/agent.integration.test.ts` (recursive walk,

package/dist/docs/public/advanced/hooks.mdx

@@ -55,7 +55,7 @@ The slug is the path-relative basename: `agent/hooks/audit.ts` → `"audit"`,
 A hook file declares two kinds of subscribers under named maps:
 
 - `lifecycle: { session?, turn? }` — runs **before** the harness step.
-  May return ephemeral `modelContext` for the next model call.
+  Side-effect-only.
 - `events: { ... }` — runs **after** Ash has accepted a stream event
   and written it to the durable stream. Observe-only.
 
@@ -115,9 +115,7 @@ it includes `{ output, toolName, connectionToolName, callId }` with
 Lifecycle hooks share one signature:
 
 ```ts
-type LifecycleHook = (
-  ctx: HookContext,
-) => void | { modelContext?: readonly ModelMessage[] } | Promise<…>;
+type LifecycleHook = (ctx: HookContext) => void | Promise<void>;
 ```
 
 Session and turn metadata are available on `ctx.session`. For example,
@@ -127,16 +125,9 @@ Session and turn metadata are available on `ctx.session`. For example,
 model turn. `lifecycle.turn` runs **once per fresh delivery** — tool-loop
 continuations and HITL resumes do not re-fire it.
 
-Both keys may return `{ modelContext }`. `modelContext` contributions
-are concatenated session-then-turn before the harness's next model
-call, and are never written to durable history. Channels may also
-contribute the same `modelContext` shape through `SendPayload`;
-channel-provided messages appear before lifecycle hook messages.
-
-Browser UIs can contribute one-turn page state through `useAshAgent()`
-`prepareSend` and `clientContext`. That client context is merged before
-runtime lifecycle hook context, so use it for page state and use runtime hooks
-for server-side policy and durable context.
+Hooks are side-effect-only — they cannot inject model context. To
+contribute runtime model messages, use `defineDynamic` +
+`defineInstructions` in `agent/instructions/`.
 
 ### Seed durable context
 
@@ -161,60 +152,6 @@ export default defineHook({
 The profile is now visible to every tool, provider, and subsequent hook
 through `githubProfile.get()`.
 
-### Inject ephemeral system text
-
-```ts
-// agent/hooks/incident-context.ts
-import { defineHook } from "experimental-ash/hooks";
-import { fetchActiveIncident } from "../lib/linear";
-
-export default defineHook({
-  lifecycle: {
-    async turn(ctx) {
-      const incident = await fetchActiveIncident();
-      if (incident === null) return;
-
-      return {
-        modelContext: [
-          {
-            role: "system",
-            content: `Active incident: ${incident.title} (priority ${incident.priority}).`,
-          },
-        ],
-      };
-    },
-  },
-});
-```
-
-`modelContext` messages are appended in registry order and visible to
-the next model call only — never persisted.
-
-### Once-per-session text
-
-```ts
-// agent/hooks/welcome.ts
-import { defineHook } from "experimental-ash/hooks";
-
-export default defineHook({
-  lifecycle: {
-    async session(ctx) {
-      return {
-        modelContext: [
-          {
-            role: "system",
-            content: `Greet the user by name (${await lookupName(ctx.session.id)}).`,
-          },
-        ],
-      };
-    },
-  },
-});
-```
-
-The session contribution lands in `modelContext` for the **first** model
-call only. Subsequent turns proceed without it.
-
 ## Stream Events
 
 Side-effect-only handlers for accepted runtime events. Subscribe by

package/dist/docs/public/advanced/project-layout.md

@@ -32,20 +32,20 @@ my-agent/
 
 ## Slot Guide
 
-| Path                                   | Purpose                                                                                                                                                                                                                                | Notes                                                                                                                                                                                                                                           |
-| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `instructions.md` or `instructions.ts` | Base instructions prompt                                                                                                                                                                                                               | Exactly one instructions prompt is expected. Module-backed sources execute once at build time; the resulting markdown is baked into the compiled manifest. The legacy `system.{md,ts,...}` slot is still discovered with a deprecation warning. |
-| `agent.ts`                             | Runtime config                                                                                                                                                                                                                         | Model, metadata, build, compaction, modelOptions                                                                                                                                                                                                |
-| `instrumentation.ts`                   | Telemetry config                                                                                                                                                                                                                       | OTel exporter setup and AI SDK span settings; auto-discovered and run before agent code                                                                                                                                                         |
-| `channels/`                            | HTTP or messaging entrypoints                                                                                                                                                                                                          | Root-only today                                                                                                                                                                                                                                 |
-| `connections/`                         | External service connections (MCP)                                                                                                                                                                                                     | Each file defines one connection; name derived from filename                                                                                                                                                                                    |
-| `hooks/`                               | Lifecycle and stream-event subscribers                                                                                                                                                                                                 | Module-backed only. Recursive directories supported. See [Hooks](./hooks.mdx).                                                                                                                                                                  |
-| `skills/`                              | On-demand procedures and capability packs                                                                                                                                                                                              | Flat markdown, module-backed skills, or packaged skills                                                                                                                                                                                         |
-| `lib/`                                 | Shared authored helper code                                                                                                                                                                                                            | Import-only source, not mounted into the workspace                                                                                                                                                                                              |
-| `sandbox/` or `sandbox.ts`             | The agent's single sandbox. Use top-level `sandbox.ts` for a definition-only override; use `sandbox/sandbox.ts` + optional `sandbox/workspace/**` when you also want seeded files. Framework default applies when neither is authored. | Supported on the root agent and local subagents                                                                                                                                                                                                 |
-| `tools/`                               | Typed executable integrations                                                                                                                                                                                                          | Module-backed only                                                                                                                                                                                                                              |
-| `schedules/`                           | Recurring jobs; each schedule is a single `<name>.ts` (with `defineSchedule({...})` as the default export) or `<name>.md` (frontmatter `cron:` plus the prompt as the body). Recursive nesting supported.                              | Root-only today                                                                                                                                                                                                                                 |
-| `subagents/`                           | Specialist child agents                                                                                                                                                                                                                | Each child is its own local package                                                                                                                                                                                                             |
+| Path                                                     | Purpose                                                                                                                                                                                                                                | Notes                                                                                                                                                                                                                                                                                             |
+| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `instructions.md`, `instructions.ts`, or `instructions/` | Base instructions prompt                                                                                                                                                                                                               | A flat file or a directory of `.md` and `.ts` files. Static sources are composed at build time; dynamic sources (using `defineDynamic` + `defineInstructions`) resolve at runtime and inject model messages. The legacy `system.{md,ts,...}` slot is still discovered with a deprecation warning. |
+| `agent.ts`                                               | Runtime config                                                                                                                                                                                                                         | Model, metadata, build, compaction, modelOptions                                                                                                                                                                                                                                                  |
+| `instrumentation.ts`                                     | Telemetry config                                                                                                                                                                                                                       | OTel exporter setup and AI SDK span settings; auto-discovered and run before agent code                                                                                                                                                                                                           |
+| `channels/`                                              | HTTP or messaging entrypoints                                                                                                                                                                                                          | Root-only today                                                                                                                                                                                                                                                                                   |
+| `connections/`                                           | External service connections (MCP)                                                                                                                                                                                                     | Each file defines one connection; name derived from filename                                                                                                                                                                                                                                      |
+| `hooks/`                                                 | Lifecycle and stream-event subscribers                                                                                                                                                                                                 | Module-backed only. Recursive directories supported. See [Hooks](./hooks.mdx).                                                                                                                                                                                                                    |
+| `skills/`                                                | On-demand procedures and capability packs                                                                                                                                                                                              | Flat markdown, module-backed skills, or packaged skills                                                                                                                                                                                                                                           |
+| `lib/`                                                   | Shared authored helper code                                                                                                                                                                                                            | Import-only source, not mounted into the workspace                                                                                                                                                                                                                                                |
+| `sandbox/` or `sandbox.ts`                               | The agent's single sandbox. Use top-level `sandbox.ts` for a definition-only override; use `sandbox/sandbox.ts` + optional `sandbox/workspace/**` when you also want seeded files. Framework default applies when neither is authored. | Supported on the root agent and local subagents                                                                                                                                                                                                                                                   |
+| `tools/`                                                 | Typed executable integrations                                                                                                                                                                                                          | Module-backed only                                                                                                                                                                                                                                                                                |
+| `schedules/`                                             | Recurring jobs; each schedule is a single `<name>.ts` (with `defineSchedule({...})` as the default export) or `<name>.md` (frontmatter `cron:` plus the prompt as the body). Recursive nesting supported.                              | Root-only today                                                                                                                                                                                                                                                                                   |
+| `subagents/`                                             | Specialist child agents                                                                                                                                                                                                                | Each child is its own local package                                                                                                                                                                                                                                                               |
 
 ## Root Agent Example
 

package/dist/src/channel/adapter.js

@@ -1 +1 @@
-import{createLogger}from"#internal/logging.js";const log=createLogger(`channel.adapter`);function defaultDeliverResult(e){if(e.message!==void 0)return{inputResponses:e.inputResponses,message:e.message,modelContext:e.modelContext};if(e.inputResponses!==void 0&&e.inputResponses.length>0)return{inputResponses:e.inputResponses,modelContext:e.modelContext};if(e.modelContext!==void 0&&e.modelContext.length>0)return{modelContext:e.modelContext}}function getAdapterKind(e){return e.kind}async function callAdapterEventHandler(e,t,n){let r=e[t.type];if(r===void 0)return t;try{await r(`data`in t?t.data:void 0,n)}catch(n){log.error(`adapter event handler threw — event swallowed`,{adapterKind:getAdapterKind(e),eventType:t.type,error:n})}return t}export{callAdapterEventHandler,defaultDeliverResult,getAdapterKind};
+import{createLogger}from"#internal/logging.js";const log=createLogger(`channel.adapter`);function defaultDeliverResult(e){let{inputResponses:t,message:n,modelContext:r,outputSchema:i}=e;if(!(n===void 0&&!t?.length&&!r?.length&&i===void 0))return{inputResponses:t,message:n,modelContext:r,outputSchema:i}}function getAdapterKind(e){return e.kind}async function callAdapterEventHandler(e,n,r){let i=e[n.type];if(i===void 0)return n;try{await i(`data`in n?n.data:void 0,r)}catch(r){log.error(`adapter event handler threw — event swallowed`,{adapterKind:getAdapterKind(e),eventType:n.type,error:r})}return n}export{callAdapterEventHandler,defaultDeliverResult,getAdapterKind};

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

@@ -4,6 +4,7 @@ import type { SessionAuthContext, SessionCallback } from "#channel/types.js";
 import type { InputResponse } from "#runtime/input/types.js";
 import type { Session } from "#channel/session.js";
 import type { RunMode } from "#shared/run-mode.js";
+import type { JsonObject } from "#shared/json.js";
 export interface RouteHandlerArgs<TState = undefined> {
     send: SendFn<TState>;
     getSession: GetSessionFn;
@@ -30,6 +31,14 @@ export interface SendPayload {
      * other roles land after the user message.
      */
     readonly modelContext?: readonly ModelMessage[];
+    /**
+     * Run-scoped JSON schema the turn's result must match. Orthogonal to
+     * {@link BaseSendOptions.mode}: a schema is enforced in either mode. Mode
+     * only decides what happens when the agent fails to produce it — a
+     * conversation run parks recoverably and waits for more input, a task run
+     * (which cannot wait) finishes as an error.
+     */
+    readonly outputSchema?: JsonObject;
 }
 export type SendFn<TState = undefined> = (input: string | UserContent | SendPayload, options: SendOptions<TState>) => Promise<Session>;
 type BaseSendOptions = {

package/dist/src/channel/send.js

@@ -1 +1 @@
-import{createSession}from"#channel/session.js";import{createLogger}from"#internal/logging.js";import{isRuntimeNoActiveSessionError}from"#execution/runtime-errors.js";import{serializeUrlFilePart}from"#internal/attachments/url-refs.js";const log=createLogger(`channel.send`);function createSendFn(t,r,i){return async(a,o)=>{let s=o.auth,c=o.callback,l=o.mode??`conversation`,u=o.state,d=o.continuationToken,f=`${i}:${d}`,{message:p,inputResponses:m,modelContext:h}=normalizeSendInput(a),g=serializeUrlFilePartsInMessage(p);try{let{sessionId:n}=await t.deliver({auth:s,continuationToken:f,payload:{inputResponses:m,message:g,modelContext:h}});return createSession(n,d,t)}catch(e){isRuntimeNoActiveSessionError(e)||log.warn(`deliver failed, falling back to starting a new session`,{continuationToken:f})}if(m&&m.length>0)throw Error(`Cannot deliver inputResponses — the target session was not found via continuation token.`);let _=u?{...r,state:{...r.state,...u}}:r;return createSession((await t.run({adapter:_,auth:s,capabilities:l===`conversation`?{requestInput:!0}:void 0,channelName:i,callback:c,continuationToken:f,input:{message:g??``,modelContext:h},mode:l})).sessionId,d,t)}}function serializeUrlFilePartsInMessage(e){if(e===void 0||typeof e==`string`)return e;let t=!1,n=e.map(e=>e.type===`file`&&e.data instanceof URL&&e.data.protocol!==`data:`?(t=!0,{...e,data:serializeUrlFilePart(e.data)}):e);return t?n:e}function normalizeSendInput(e){return typeof e==`string`||Array.isArray(e)?{message:e}:e}export{createSendFn};
+import{createSession}from"#channel/session.js";import{createLogger}from"#internal/logging.js";import{isRuntimeNoActiveSessionError}from"#execution/runtime-errors.js";import{serializeUrlFilePart}from"#internal/attachments/url-refs.js";const log=createLogger(`channel.send`);function createSendFn(t,r,i){return async(a,o)=>{let s=o.auth,c=o.callback,l=o.mode??`conversation`,u=o.state,d=o.continuationToken,f=`${i}:${d}`,{message:p,inputResponses:m,modelContext:h,outputSchema:g}=normalizeSendInput(a),_=serializeUrlFilePartsInMessage(p);try{let{sessionId:n}=await t.deliver({auth:s,continuationToken:f,payload:{inputResponses:m,message:_,modelContext:h,outputSchema:g}});return createSession(n,d,t)}catch(e){isRuntimeNoActiveSessionError(e)||log.warn(`deliver failed, falling back to starting a new session`,{continuationToken:f})}if(m&&m.length>0)throw Error(`Cannot deliver inputResponses — the target session was not found via continuation token.`);let v=u?{...r,state:{...r.state,...u}}:r;return createSession((await t.run({adapter:v,auth:s,capabilities:l===`conversation`?{requestInput:!0}:void 0,channelName:i,callback:c,continuationToken:f,input:{message:_??``,modelContext:h,outputSchema:g},mode:l})).sessionId,d,t)}}function serializeUrlFilePartsInMessage(e){if(e===void 0||typeof e==`string`)return e;let t=!1,n=e.map(e=>e.type===`file`&&e.data instanceof URL&&e.data.protocol!==`data:`?(t=!0,{...e,data:serializeUrlFilePart(e.data)}):e);return t?n:e}function normalizeSendInput(e){return typeof e==`string`||Array.isArray(e)?{message:e}:e}export{createSendFn};

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

@@ -4,6 +4,7 @@ import type { RunMode } from "#shared/run-mode.js";
 import type { RuntimeActionResult } from "#runtime/actions/types.js";
 import type { InputRequest, InputResponse } from "#runtime/input/types.js";
 import type { ChannelAdapter } from "#channel/adapter.js";
+import type { JsonObject } from "#shared/json.js";
 export type { ContextAccessor } from "#context/key.js";
 export type { ChannelInstrumentationProjection } from "#channel/instrumentation.js";
 /**
@@ -70,6 +71,7 @@ export interface DeliverPayload {
     readonly inputResponses?: readonly InputResponse[];
     readonly message?: string | UserContent;
     readonly modelContext?: readonly ModelMessage[];
+    readonly outputSchema?: JsonObject;
     readonly [key: string]: unknown;
 }
 /**
@@ -214,6 +216,7 @@ export interface RunInput {
     readonly input: {
         readonly message: string | UserContent;
         readonly modelContext?: readonly ModelMessage[];
+        readonly outputSchema?: JsonObject;
     };
     readonly mode: RunMode;
     readonly parent?: SessionParent;

package/dist/src/client/index.d.ts

@@ -6,7 +6,7 @@ export { ClientSession } from "#client/session.js";
 export type { ClientAuth, ClientOptions, HeadersValue, HealthResult, MessageResult, OpenStreamOptions, SendMessageOptions, SendTurnInput, SessionState, TokenValue, } from "#client/types.js";
 export type { AshAgentReducer, AshAgentReducerEvent, ClientInputRespondedEvent, ClientMessageFailedEvent, ClientMessageSubmittedEvent, } from "#client/reducer.js";
 export type { AshMessageData, AshDynamicToolPart, AshMessageInputRequest, AshMessage, AshMessageMetadata, AshMessagePart, AshMessageToolMetadata, } from "#client/message-reducer.js";
-export type { ActionResultStreamEvent, ActionsRequestedStreamEvent, AssistantStepFinishReason, CompactionCompletedStreamEvent, CompactionRequestedStreamEvent, AuthorizationCompletedStreamEvent, ConnectionAuthorizationOutcome, AuthorizationRequiredStreamEvent, HandleMessageStreamEvent, InputRequestedStreamEvent, MessageAppendedStreamEvent, MessageCompletedStreamEvent, MessageReceivedStreamEvent, ReasoningAppendedStreamEvent, ReasoningCompletedStreamEvent, SessionCompletedStreamEvent, SessionFailedStreamEvent, SessionStartedStreamEvent, SessionWaitingStreamEvent, StepCompletedStreamEvent, StepFailedStreamEvent, StepStartedStreamEvent, SubagentCalledStreamEvent, SubagentChildEventStreamEvent, SubagentCompletedStreamEvent, SubagentStartedStreamEvent, TurnCompletedStreamEvent, TurnFailedStreamEvent, TurnStartedStreamEvent, } from "#protocol/message.js";
+export type { ActionResultStreamEvent, ActionsRequestedStreamEvent, AssistantStepFinishReason, CompactionCompletedStreamEvent, CompactionRequestedStreamEvent, AuthorizationCompletedStreamEvent, ConnectionAuthorizationOutcome, AuthorizationRequiredStreamEvent, HandleMessageStreamEvent, InputRequestedStreamEvent, MessageAppendedStreamEvent, MessageCompletedStreamEvent, MessageReceivedStreamEvent, ReasoningAppendedStreamEvent, ReasoningCompletedStreamEvent, ResultCompletedStreamEvent, SessionCompletedStreamEvent, SessionFailedStreamEvent, SessionStartedStreamEvent, SessionWaitingStreamEvent, StepCompletedStreamEvent, StepFailedStreamEvent, StepStartedStreamEvent, SubagentCalledStreamEvent, SubagentChildEventStreamEvent, SubagentCompletedStreamEvent, SubagentStartedStreamEvent, TurnCompletedStreamEvent, TurnFailedStreamEvent, TurnStartedStreamEvent, } from "#protocol/message.js";
 export { isCurrentTurnBoundaryEvent } from "#protocol/message.js";
 export type { InputOption, InputRequest, InputResponse } from "#runtime/input/types.js";
 export { inputOptionSchema, inputRequestSchema, inputResponseSchema, isInputRequest, isInputResponse, } from "#runtime/input/types.js";

package/dist/src/client/message-reducer-types.d.ts

@@ -16,6 +16,7 @@ export interface AshMessage {
 }
 export interface AshMessageMetadata {
     readonly optimistic?: true;
+    readonly result?: unknown;
     readonly status?: "complete" | "failed" | "streaming" | "submitted";
     readonly turnId?: string;
 }

package/dist/src/client/message-reducer.js

@@ -1 +1 @@
-function defaultMessageReducer(){return{initial(){return{messages:[]}},reduce(e,t){return reduceMessageData(e,t)}}}function reduceMessageData(e,t){switch(t.type){case`client.message.submitted`:return upsertMessage(e,{id:optimisticUserMessageId(t.data.submissionId),metadata:{optimistic:!0,status:`submitted`},parts:[{type:`text`,text:t.data.message}],role:`user`});case`client.message.failed`:return upsertMessage(e,{id:optimisticUserMessageId(t.data.submissionId),metadata:{optimistic:!0,status:`failed`},parts:[{type:`text`,text:t.data.message}],role:`user`});case`client.input.responded`:{let n=e;for(let e of t.data.responses)n=respondToInputRequest(n,e);return n}case`message.received`:return upsertMessage(e,{id:`${t.data.turnId}:user`,metadata:{status:`complete`,turnId:t.data.turnId},parts:[{type:`text`,text:t.data.message,state:`done`}],role:`user`});case`step.started`:return updateAssistantMessage(e,t.data.turnId,e=>ensureStepStartPart(e,t.data.stepIndex));case`reasoning.appended`:return updateAssistantMessage(e,t.data.turnId,e=>upsertPart(ensureStepStartPart(e,t.data.stepIndex),{state:`streaming`,stepIndex:t.data.stepIndex,text:t.data.reasoningSoFar,type:`reasoning`}));case`reasoning.completed`:return updateAssistantMessage(e,t.data.turnId,e=>upsertPart(ensureStepStartPart(e,t.data.stepIndex),{state:`done`,stepIndex:t.data.stepIndex,text:t.data.reasoning,type:`reasoning`}));case`actions.requested`:{let n=e;for(let e of t.data.actions){let r=normalizeActionRequest(e);n=updateAssistantMessage(n,t.data.turnId,n=>upsertPart(ensureStepStartPart(n,t.data.stepIndex),{input:`input`in e?e.input:void 0,state:`input-available`,stepIndex:t.data.stepIndex,toolCallId:e.callId,toolMetadata:createToolMetadata(r),toolName:r.toolName,type:`dynamic-tool`}))}return n}case`input.requested`:{let n=e;for(let e of t.data.requests){let r=normalizeActionRequest(e.action);n=updateAssistantMessage(n,t.data.turnId,n=>upsertPart(ensureStepStartPart(n,t.data.stepIndex),{approval:{id:e.requestId},input:e.action.input,state:`approval-requested`,stepIndex:t.data.stepIndex,toolCallId:e.action.callId,toolMetadata:createToolMetadata(r,{inputRequest:toMessageInputRequest(e)}),toolName:r.toolName,type:`dynamic-tool`}))}return n}case`action.result`:{let n=normalizeActionResult(t.data.result),r=findToolPart(e,t.data.result.callId),i=t.data.error?.code===`TOOL_EXECUTION_DENIED`,a=t.data.status===`failed`&&!i,o=r?.approval?.id??t.data.result.callId,s=mergeToolMetadata(r?.toolMetadata,createToolMetadata(n)),c={input:r?.input,stepIndex:t.data.stepIndex,toolCallId:t.data.result.callId,toolMetadata:s,toolName:r?.toolName??n.toolName,type:`dynamic-tool`},l;return l=i?{...c,approval:{approved:!1,id:o,reason:t.data.error?.message},state:`output-denied`}:a?{...c,approval:approvedApproval(r),errorText:t.data.error?.message??stringifyUnknown(t.data.result.output),state:`output-error`}:{...c,approval:approvedApproval(r),output:t.data.result.output,state:`output-available`},r===void 0?updateAssistantMessage(e,t.data.turnId,e=>upsertPart(ensureStepStartPart(e,t.data.stepIndex),l)):updateToolPart(e,t.data.result.callId,l)}case`message.appended`:return updateAssistantMessage(e,t.data.turnId,e=>upsertPart(ensureStepStartPart(e,t.data.stepIndex),{state:`streaming`,stepIndex:t.data.stepIndex,text:t.data.messageSoFar,type:`text`}));case`message.completed`:return updateAssistantMessage(e,t.data.turnId,e=>t.data.message===null?completeExistingTextPart(e):upsertPart(ensureStepStartPart(e,t.data.stepIndex),{state:`done`,stepIndex:t.data.stepIndex,text:t.data.message,type:`text`}));case`turn.completed`:return updateAssistantMetadata(e,t.data.turnId,{status:`complete`});case`turn.failed`:case`session.failed`:return e;default:return e}}function respondToInputRequest(e,t){let n=findToolPartByApprovalId(e,t.requestId);if(!n)return e;let r={id:t.requestId};return t.text!==void 0&&(r.reason=t.text),updateToolPart(e,n.toolCallId,{approval:r,input:n.input,state:`approval-responded`,stepIndex:n.stepIndex,toolCallId:n.toolCallId,toolMetadata:mergeToolMetadata(n.toolMetadata,{ash:{inputResponse:t,kind:n.toolMetadata?.ash?.kind??`unknown`,name:n.toolMetadata?.ash?.name??n.toolName}}),toolName:n.toolName,type:`dynamic-tool`})}function updateAssistantMessage(e,t,n){return upsertMessage(e,n(e.messages.find(e=>e.role===`assistant`&&e.metadata?.turnId===t)??createAssistantMessage(t)))}function updateAssistantMetadata(e,t,n){return updateAssistantMessage(e,t,e=>({...e,metadata:{...e.metadata,...n}}))}function createAssistantMessage(e){return{id:`${e}:assistant`,metadata:{status:`streaming`,turnId:e},parts:[],role:`assistant`}}function ensureStepStartPart(e,t){let n=e.parts.filter(e=>e.type===`step-start`).length;if(n>t)return e;let r=t-n+1;return{...e,parts:[...e.parts,...Array.from({length:r},()=>({type:`step-start`}))]}}function upsertPart(e,t){let n=e.parts.findIndex(e=>partKey(e)===partKey(t)),r=n===-1?[...e.parts,t]:[...e.parts.slice(0,n),t,...e.parts.slice(n+1)];return{...e,metadata:{...e.metadata,status:t.type===`text`&&t.state===`done`?`complete`:`streaming`},parts:r}}function completeExistingTextPart(e){let t=findLastIndex(e.parts,e=>e.type===`text`);if(t===-1)return e;let n=e.parts[t];return n?.type===`text`?{...e,metadata:{...e.metadata,status:`complete`},parts:[...e.parts.slice(0,t),{...n,state:`done`},...e.parts.slice(t+1)]}:e}function updateToolPart(e,t,n){let r=e.messages.find(e=>e.role===`assistant`&&e.parts.some(e=>e.type===`dynamic-tool`&&e.toolCallId===t));return r?upsertMessage(e,upsertPart(r,n)):e}function findToolPart(e,t){for(let n of e.messages)for(let e of n.parts)if(e.type===`dynamic-tool`&&e.toolCallId===t)return e}function findToolPartByApprovalId(e,t){for(let n of e.messages)for(let e of n.parts)if(e.type===`dynamic-tool`&&e.approval?.id===t)return e}function partKey(e){switch(e.type){case`text`:return`text:${e.stepIndex??0}`;case`reasoning`:return`reasoning:${e.stepIndex??0}`;case`step-start`:return`step-start`;case`dynamic-tool`:return`dynamic-tool:${e.toolCallId}`}}function upsertMessage(e,t){let n=e.messages.findIndex(e=>e.id===t.id);return n===-1?{messages:[...e.messages,t]}:{messages:[...e.messages.slice(0,n),t,...e.messages.slice(n+1)]}}function toMessageInputRequest(e){return{allowFreeform:e.allowFreeform,display:e.display,options:e.options,prompt:e.prompt,requestId:e.requestId}}function createToolMetadata(e,t){return{ash:{inputRequest:t?.inputRequest,kind:e.kind,name:e.name}}}function mergeToolMetadata(e,t){let n=t.ash?.kind??e?.ash?.kind??`unknown`,r=t.ash?.name??e?.ash?.name??`unknown`;return{ash:{...e?.ash,...t.ash,inputRequest:t.ash?.inputRequest??e?.ash?.inputRequest,inputResponse:t.ash?.inputResponse??e?.ash?.inputResponse,kind:n,name:r}}}function approvedApproval(e){if(e?.approval?.id)return{approved:!0,id:e.approval.id,isAutomatic:e.approval.isAutomatic,reason:e.approval.reason}}function normalizeActionRequest(e){switch(e.kind){case`load-skill`:return{kind:`load-skill`,name:`load_skill`,toolName:`ash:load-skill`};case`tool-call`:return{kind:`tool-call`,name:e.toolName,toolName:e.toolName};case`subagent-call`:return{kind:`subagent-call`,name:e.subagentName,toolName:`ash:subagent:${e.subagentName}`};case`remote-agent-call`:return{kind:`subagent-call`,name:e.remoteAgentName,toolName:`ash:subagent:${e.remoteAgentName}`}}}function normalizeActionResult(e){switch(e.kind){case`load-skill-result`:return{kind:`load-skill`,name:e.name??`load_skill`,toolName:`ash:load-skill`};case`tool-result`:return{kind:`tool-call`,name:e.toolName,toolName:e.toolName};case`subagent-result`:return{kind:`subagent-call`,name:e.subagentName,toolName:`ash:subagent:${e.subagentName}`}}}function optimisticUserMessageId(e){return`optimistic:${e}:user`}function stringifyUnknown(e){if(typeof e==`string`)return e;try{return JSON.stringify(e)}catch{return`Action failed.`}}function findLastIndex(e,t){for(let n=e.length-1;n>=0;--n)if(t(e[n]))return n;return-1}export{defaultMessageReducer};
+function defaultMessageReducer(){return{initial(){return{messages:[]}},reduce(e,t){return reduceMessageData(e,t)}}}function reduceMessageData(e,t){switch(t.type){case`client.message.submitted`:return upsertMessage(e,{id:optimisticUserMessageId(t.data.submissionId),metadata:{optimistic:!0,status:`submitted`},parts:[{type:`text`,text:t.data.message}],role:`user`});case`client.message.failed`:return upsertMessage(e,{id:optimisticUserMessageId(t.data.submissionId),metadata:{optimistic:!0,status:`failed`},parts:[{type:`text`,text:t.data.message}],role:`user`});case`client.input.responded`:{let n=e;for(let e of t.data.responses)n=respondToInputRequest(n,e);return n}case`message.received`:return upsertMessage(e,{id:`${t.data.turnId}:user`,metadata:{status:`complete`,turnId:t.data.turnId},parts:[{type:`text`,text:t.data.message,state:`done`}],role:`user`});case`step.started`:return updateAssistantMessage(e,t.data.turnId,e=>ensureStepStartPart(e,t.data.stepIndex));case`reasoning.appended`:return updateAssistantMessage(e,t.data.turnId,e=>upsertPart(ensureStepStartPart(e,t.data.stepIndex),{state:`streaming`,stepIndex:t.data.stepIndex,text:t.data.reasoningSoFar,type:`reasoning`}));case`reasoning.completed`:return updateAssistantMessage(e,t.data.turnId,e=>upsertPart(ensureStepStartPart(e,t.data.stepIndex),{state:`done`,stepIndex:t.data.stepIndex,text:t.data.reasoning,type:`reasoning`}));case`actions.requested`:{let n=e;for(let e of t.data.actions){let r=normalizeActionRequest(e);n=updateAssistantMessage(n,t.data.turnId,n=>upsertPart(ensureStepStartPart(n,t.data.stepIndex),{input:`input`in e?e.input:void 0,state:`input-available`,stepIndex:t.data.stepIndex,toolCallId:e.callId,toolMetadata:createToolMetadata(r),toolName:r.toolName,type:`dynamic-tool`}))}return n}case`input.requested`:{let n=e;for(let e of t.data.requests){let r=normalizeActionRequest(e.action);n=updateAssistantMessage(n,t.data.turnId,n=>upsertPart(ensureStepStartPart(n,t.data.stepIndex),{approval:{id:e.requestId},input:e.action.input,state:`approval-requested`,stepIndex:t.data.stepIndex,toolCallId:e.action.callId,toolMetadata:createToolMetadata(r,{inputRequest:toMessageInputRequest(e)}),toolName:r.toolName,type:`dynamic-tool`}))}return n}case`action.result`:{let n=normalizeActionResult(t.data.result),r=findToolPart(e,t.data.result.callId),i=t.data.error?.code===`TOOL_EXECUTION_DENIED`,a=t.data.status===`failed`&&!i,o=r?.approval?.id??t.data.result.callId,s=mergeToolMetadata(r?.toolMetadata,createToolMetadata(n)),c={input:r?.input,stepIndex:t.data.stepIndex,toolCallId:t.data.result.callId,toolMetadata:s,toolName:r?.toolName??n.toolName,type:`dynamic-tool`},l;return l=i?{...c,approval:{approved:!1,id:o,reason:t.data.error?.message},state:`output-denied`}:a?{...c,approval:approvedApproval(r),errorText:t.data.error?.message??stringifyUnknown(t.data.result.output),state:`output-error`}:{...c,approval:approvedApproval(r),output:t.data.result.output,state:`output-available`},r===void 0?updateAssistantMessage(e,t.data.turnId,e=>upsertPart(ensureStepStartPart(e,t.data.stepIndex),l)):updateToolPart(e,t.data.result.callId,l)}case`message.appended`:return updateAssistantMessage(e,t.data.turnId,e=>upsertPart(ensureStepStartPart(e,t.data.stepIndex),{state:`streaming`,stepIndex:t.data.stepIndex,text:t.data.messageSoFar,type:`text`}));case`message.completed`:return updateAssistantMessage(e,t.data.turnId,e=>t.data.message===null?completeExistingTextPart(e):upsertPart(ensureStepStartPart(e,t.data.stepIndex),{state:`done`,stepIndex:t.data.stepIndex,text:t.data.message,type:`text`}));case`result.completed`:return updateAssistantMetadata(e,t.data.turnId,{result:t.data.result});case`turn.completed`:return updateAssistantMetadata(e,t.data.turnId,{status:`complete`});case`turn.failed`:case`session.failed`:return e;default:return e}}function respondToInputRequest(e,t){let n=findToolPartByApprovalId(e,t.requestId);if(!n)return e;let r={id:t.requestId};return t.text!==void 0&&(r.reason=t.text),updateToolPart(e,n.toolCallId,{approval:r,input:n.input,state:`approval-responded`,stepIndex:n.stepIndex,toolCallId:n.toolCallId,toolMetadata:mergeToolMetadata(n.toolMetadata,{ash:{inputResponse:t,kind:n.toolMetadata?.ash?.kind??`unknown`,name:n.toolMetadata?.ash?.name??n.toolName}}),toolName:n.toolName,type:`dynamic-tool`})}function updateAssistantMessage(e,t,n){return upsertMessage(e,n(e.messages.find(e=>e.role===`assistant`&&e.metadata?.turnId===t)??createAssistantMessage(t)))}function updateAssistantMetadata(e,t,n){return updateAssistantMessage(e,t,e=>({...e,metadata:{...e.metadata,...n}}))}function createAssistantMessage(e){return{id:`${e}:assistant`,metadata:{status:`streaming`,turnId:e},parts:[],role:`assistant`}}function ensureStepStartPart(e,t){let n=e.parts.filter(e=>e.type===`step-start`).length;if(n>t)return e;let r=t-n+1;return{...e,parts:[...e.parts,...Array.from({length:r},()=>({type:`step-start`}))]}}function upsertPart(e,t){let n=e.parts.findIndex(e=>partKey(e)===partKey(t)),r=n===-1?[...e.parts,t]:[...e.parts.slice(0,n),t,...e.parts.slice(n+1)];return{...e,metadata:{...e.metadata,status:t.type===`text`&&t.state===`done`?`complete`:`streaming`},parts:r}}function completeExistingTextPart(e){let t=findLastIndex(e.parts,e=>e.type===`text`);if(t===-1)return e;let n=e.parts[t];return n?.type===`text`?{...e,metadata:{...e.metadata,status:`complete`},parts:[...e.parts.slice(0,t),{...n,state:`done`},...e.parts.slice(t+1)]}:e}function updateToolPart(e,t,n){let r=e.messages.find(e=>e.role===`assistant`&&e.parts.some(e=>e.type===`dynamic-tool`&&e.toolCallId===t));return r?upsertMessage(e,upsertPart(r,n)):e}function findToolPart(e,t){for(let n of e.messages)for(let e of n.parts)if(e.type===`dynamic-tool`&&e.toolCallId===t)return e}function findToolPartByApprovalId(e,t){for(let n of e.messages)for(let e of n.parts)if(e.type===`dynamic-tool`&&e.approval?.id===t)return e}function partKey(e){switch(e.type){case`text`:return`text:${e.stepIndex??0}`;case`reasoning`:return`reasoning:${e.stepIndex??0}`;case`step-start`:return`step-start`;case`dynamic-tool`:return`dynamic-tool:${e.toolCallId}`}}function upsertMessage(e,t){let n=e.messages.findIndex(e=>e.id===t.id);return n===-1?{messages:[...e.messages,t]}:{messages:[...e.messages.slice(0,n),t,...e.messages.slice(n+1)]}}function toMessageInputRequest(e){return{allowFreeform:e.allowFreeform,display:e.display,options:e.options,prompt:e.prompt,requestId:e.requestId}}function createToolMetadata(e,t){return{ash:{inputRequest:t?.inputRequest,kind:e.kind,name:e.name}}}function mergeToolMetadata(e,t){let n=t.ash?.kind??e?.ash?.kind??`unknown`,r=t.ash?.name??e?.ash?.name??`unknown`;return{ash:{...e?.ash,...t.ash,inputRequest:t.ash?.inputRequest??e?.ash?.inputRequest,inputResponse:t.ash?.inputResponse??e?.ash?.inputResponse,kind:n,name:r}}}function approvedApproval(e){if(e?.approval?.id)return{approved:!0,id:e.approval.id,isAutomatic:e.approval.isAutomatic,reason:e.approval.reason}}function normalizeActionRequest(e){switch(e.kind){case`load-skill`:return{kind:`load-skill`,name:`load_skill`,toolName:`ash:load-skill`};case`tool-call`:return{kind:`tool-call`,name:e.toolName,toolName:e.toolName};case`subagent-call`:return{kind:`subagent-call`,name:e.subagentName,toolName:`ash:subagent:${e.subagentName}`};case`remote-agent-call`:return{kind:`subagent-call`,name:e.remoteAgentName,toolName:`ash:subagent:${e.remoteAgentName}`}}}function normalizeActionResult(e){switch(e.kind){case`load-skill-result`:return{kind:`load-skill`,name:e.name??`load_skill`,toolName:`ash:load-skill`};case`tool-result`:return{kind:`tool-call`,name:e.toolName,toolName:e.toolName};case`subagent-result`:return{kind:`subagent-call`,name:e.subagentName,toolName:`ash:subagent:${e.subagentName}`}}}function optimisticUserMessageId(e){return`optimistic:${e}:user`}function stringifyUnknown(e){if(typeof e==`string`)return e;try{return JSON.stringify(e)}catch{return`Action failed.`}}function findLastIndex(e,t){for(let n=e.length-1;n>=0;--n)if(t(e[n]))return n;return-1}export{defaultMessageReducer};

package/dist/src/client/message-response.d.ts

@@ -16,7 +16,7 @@ interface MessageResponseInput {
  * separately — either collected via {@link result} or iterated with
  * `for await...of`.
  */
-export declare class MessageResponse implements AsyncIterable<HandleMessageStreamEvent> {
+export declare class MessageResponse<TOutput = unknown> implements AsyncIterable<HandleMessageStreamEvent> {
     #private;
     /**
      * Continuation token returned by the server for follow-up messages.
@@ -32,7 +32,7 @@ export declare class MessageResponse implements AsyncIterable<HandleMessageStrea
      * Consumes the full event stream and returns the aggregated
      * {@link MessageResult}.
      */
-    result(): Promise<MessageResult>;
+    result(): Promise<MessageResult<TOutput>>;
     /**
      * Yields stream events one at a time.
      *

package/dist/src/client/message-response.js

@@ -1 +1 @@
-import{deriveResultStatus,extractCompletedMessage}from"#client/session-utils.js";var MessageResponse=class{continuationToken;sessionId;#e=!1;#t;constructor(e){this.continuationToken=e.continuationToken,this.sessionId=e.sessionId,this.#t=e.createStream}async result(){let t=[];for await(let e of this)t.push(e);return{events:t,message:extractCompletedMessage(t),sessionId:this.sessionId,status:deriveResultStatus(t)}}[Symbol.asyncIterator](){if(this.#e)throw Error(`MessageResponse has already been consumed.`);return this.#e=!0,this.#t()}};export{MessageResponse};
+import{deriveResultStatus,extractCompletedMessage}from"#client/session-utils.js";import{extractCompletedResult}from"#client/output-schema.js";var MessageResponse=class{continuationToken;sessionId;#e=!1;#t;constructor(e){this.continuationToken=e.continuationToken,this.sessionId=e.sessionId,this.#t=e.createStream}async result(){let t=[];for await(let e of this)t.push(e);return{data:extractCompletedResult(t),events:t,message:extractCompletedMessage(t),sessionId:this.sessionId,status:deriveResultStatus(t)}}[Symbol.asyncIterator](){if(this.#e)throw Error(`MessageResponse has already been consumed.`);return this.#e=!0,this.#t()}};export{MessageResponse};

package/dist/src/client/output-schema.d.ts

@@ -0,0 +1,12 @@
+import type { StandardJSONSchemaV1 } from "#compiled/@standard-schema/spec/index.js";
+import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { JsonObject } from "#shared/json.js";
+/**
+ * Normalizes a client-supplied output schema into the wire-safe JSON Schema
+ * representation accepted by Ash message routes.
+ */
+export declare function normalizeOutputSchemaForRequest<TOutput>(schema: StandardJSONSchemaV1<unknown, TOutput> | JsonObject | undefined): JsonObject | undefined;
+/**
+ * Extracts the most recent finalized structured result from a turn event list.
+ */
+export declare function extractCompletedResult<TOutput>(events: readonly HandleMessageStreamEvent[]): TOutput | undefined;

package/dist/src/client/output-schema.js

@@ -0,0 +1 @@
+import{normalizeJsonSchemaDefinition}from"#shared/json-schema.js";function normalizeOutputSchemaForRequest(t){return t===void 0?void 0:normalizeJsonSchemaDefinition(t)}function extractCompletedResult(e){let t;for(let n of e)isResultCompletedEvent(n)&&(t=n.data.result);return t}function isResultCompletedEvent(e){return e.type===`result.completed`}export{extractCompletedResult,normalizeOutputSchemaForRequest};

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

@@ -36,14 +36,14 @@ export declare class ClientSession {
      * The session's state is updated automatically after the stream is
      * consumed.
      */
-    sendMessage(message: string, options?: SendMessageOptions): Promise<MessageResponse>;
+    sendMessage<TOutput = unknown>(message: string, options?: SendMessageOptions<TOutput>): Promise<MessageResponse<TOutput>>;
     /**
      * Sends one turn payload to the agent.
      *
      * Use this to submit follow-up text, HITL results, or both in a single
      * request.
      */
-    send(input: SendTurnInput, options?: SendMessageOptions): Promise<MessageResponse>;
+    send<TOutput = unknown>(input: SendTurnInput, options?: SendMessageOptions<TOutput>): Promise<MessageResponse<TOutput>>;
     /**
      * Opens this session's event stream using the current session ID and stream
      * index.

package/dist/src/client/session.js

@@ -1 +1 @@
-import{ASH_CREATE_SESSION_ROUTE_PATH,createAshContinueSessionRoutePath,createAshMessageStreamRoutePath}from"#protocol/routes.js";import{openStreamIterable}from"#client/open-stream.js";import{ASH_SESSION_ID_HEADER,isCurrentTurnBoundaryEvent}from"#protocol/message.js";import{ClientError}from"#client/client-error.js";import{advanceSession}from"#client/session-utils.js";import{createClientUrl}from"#client/url.js";import{MessageResponse}from"#client/message-response.js";import{isStreamDisconnectError,readNdjsonStream}from"#client/ndjson.js";var ClientSession=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 MessageResponse({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 openStreamIterable({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(n,r,a){let s=r.sessionId?createAshContinueSessionRoutePath(r.sessionId):ASH_CREATE_SESSION_ROUTE_PATH,c=createClientUrl(this.#e.host,s),l=await this.#e.resolveHeaders(a?.headers);l.set(`content-type`,`application/json`);let u=createHandleMessageBody({input:n,session:r});if(u===null)throw Error(`Session.send requires a non-empty message, inputResponses, or both.`);let d=await fetch(c,{body:JSON.stringify(u),headers:l,method:`POST`,signal:a?.signal??null});if(!d.ok){let e=await d.text();throw new ClientError(d.status,e)}let f=await d.json(),p=(typeof f.sessionId==`string`?f.sessionId:void 0)??d.headers.get(ASH_SESSION_ID_HEADER)?.trim()??r.sessionId;if(!p)throw Error(`Message route did not return a session id.`);return{continuationToken:typeof f.continuationToken==`string`?f.continuationToken:void 0,sessionId:p}}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 readNdjsonStream(n))if(i.push(e),t+=1,yield e,isCurrentTurnBoundaryEvent(e)){s=!0;break}}catch(e){if(!isStreamDisconnectError(e))throw e}if(s||o<=0)break;--o}}finally{this.#t=advanceSession({continuationToken:t,events:i,sessionId:e,session:n})}}async#i(e,t,r){let i=createClientUrl(this.#e.host,createAshMessageStreamRoutePath(e),t>0?{startIndex:String(t)}:void 0),a=await this.#e.resolveHeaders(),s=await fetch(i,{headers:a,signal:r??null});if(!s.ok){let e=await s.text();throw new ClientError(s.status,e)}if(!s.body)throw new ClientError(s.status,`Response body is null.`);return s.body}};function createHandleMessageBody(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?null:t}export{ClientSession};
+import{ASH_CREATE_SESSION_ROUTE_PATH,createAshContinueSessionRoutePath,createAshMessageStreamRoutePath}from"#protocol/routes.js";import{openStreamIterable}from"#client/open-stream.js";import{ASH_SESSION_ID_HEADER,isCurrentTurnBoundaryEvent}from"#protocol/message.js";import{ClientError}from"#client/client-error.js";import{advanceSession}from"#client/session-utils.js";import{createClientUrl}from"#client/url.js";import{MessageResponse}from"#client/message-response.js";import{normalizeOutputSchemaForRequest}from"#client/output-schema.js";import{isStreamDisconnectError,readNdjsonStream}from"#client/ndjson.js";var ClientSession=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 MessageResponse({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 openStreamIterable({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(n,r,a){let s=r.sessionId?createAshContinueSessionRoutePath(r.sessionId):ASH_CREATE_SESSION_ROUTE_PATH,c=createClientUrl(this.#e.host,s),l=await this.#e.resolveHeaders(a?.headers);l.set(`content-type`,`application/json`);let u=createHandleMessageBody({input:n,outputSchema:normalizeOutputSchemaForRequest(a?.outputSchema),session:r});if(u===null)throw Error(`Session.send requires a non-empty message, inputResponses, or both.`);let d=await fetch(c,{body:JSON.stringify(u),headers:l,method:`POST`,signal:a?.signal??null});if(!d.ok){let e=await d.text();throw new ClientError(d.status,e)}let f=await d.json(),p=(typeof f.sessionId==`string`?f.sessionId:void 0)??d.headers.get(ASH_SESSION_ID_HEADER)?.trim()??r.sessionId;if(!p)throw Error(`Message route did not return a session id.`);return{continuationToken:typeof f.continuationToken==`string`?f.continuationToken:void 0,sessionId:p}}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 readNdjsonStream(n))if(i.push(e),t+=1,yield e,isCurrentTurnBoundaryEvent(e)){s=!0;break}}catch(e){if(!isStreamDisconnectError(e))throw e}if(s||o<=0)break;--o}}finally{this.#t=advanceSession({continuationToken:t,events:i,sessionId:e,session:n})}}async#i(e,t,r){let i=createClientUrl(this.#e.host,createAshMessageStreamRoutePath(e),t>0?{startIndex:String(t)}:void 0),a=await this.#e.resolveHeaders(),s=await fetch(i,{headers:a,signal:r??null});if(!s.ok){let e=await s.text();throw new ClientError(s.status,e)}if(!s.body)throw new ClientError(s.status,`Response body is null.`);return s.body}};function createHandleMessageBody(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.outputSchema!==void 0&&(t.outputSchema=e.outputSchema),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?null:t}export{ClientSession};

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

@@ -1,4 +1,5 @@
 import type { UserContent } from "ai";
+import type { StandardJSONSchemaV1 } from "#compiled/@standard-schema/spec/index.js";
 import type { HandleMessageStreamEvent } from "#protocol/message.js";
 import type { InputResponse } from "#runtime/input/types.js";
 import type { JsonObject } from "#shared/json.js";
@@ -54,7 +55,16 @@ export interface ClientOptions {
 /**
  * Per-message options for {@link Client.sendMessage}.
  */
-export interface SendMessageOptions {
+export interface SendMessageOptions<TOutput = unknown> {
+    /**
+     * Optional schema the harness must satisfy before this turn terminates.
+     *
+     * The client lowers Standard Schema implementations (Zod, Valibot,
+     * ArkType, etc.) to JSON Schema before sending the request. The server is
+     * authoritative for validation; {@link MessageResult.data} is typed to this
+     * schema's output type and is not revalidated client-side.
+     */
+    readonly outputSchema?: StandardJSONSchemaV1<unknown, TOutput> | JsonObject;
     /**
      * Abort signal for cancelling the request.
      */
@@ -104,7 +114,12 @@ export interface OpenStreamOptions {
  * Aggregated result of one message turn, returned by
  * {@link MessageResponse.result}.
  */
-export interface MessageResult {
+export interface MessageResult<TOutput = unknown> {
+    /**
+     * Final structured result emitted by the harness, when this turn requested
+     * an output schema and the server fulfilled it.
+     */
+    readonly data: TOutput | undefined;
     /**
      * The final completed assistant message text, or `undefined` if no terminal
      * `message.completed` event was observed.

package/dist/src/compiled/.vendor-stamp.json

@@ -22,10 +22,11 @@
     "turndown": "7.2.4",
     "@vercel/oidc": "3.5.0",
     "@vercel/sandbox": "2.1.0",
-    "@workflow/core": "5.0.0-beta.10",
+    "@workflow/core": "5.0.0-beta.11",
     "@workflow/errors": "5.0.0-beta.6",
+    "@workflow/world": "5.0.0-beta.6",
     "zod": "4.4.3",
     "zod-validation-error": "5.0.0"
   },
-  "scriptHash": "3ca25d8480d76331751f15b85150bcb6cea056aa28c4fc04012dddcdaccae3e5"
+  "scriptHash": "d058df06982d76ea3f28a17d85e12bfd9d19a58aede5830e27938e6ee911c5f4"
 }