experimental-ash 0.22.2 → 0.24.0

package/dist/src/execution/workflow-steps.d.ts

@@ -2,11 +2,22 @@ import type { DeliverPayload, HookPayload, SessionAuthContext, SubagentInputRequ
 import { deserializeContext } from "#context/serialize.js";
 import type { HarnessSession } from "#harness/types.js";
 import type { RuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";
+import { type TurnWorkflowInput } from "#execution/turn-workflow.js";
 import type { DurableStepResult } from "#execution/types.js";
+/**
+ * Input for one atomic harness step inside a durable `"use step"`
+ * boundary.
+ */
+export interface TurnStepInput {
+    readonly input: HookPayload | undefined;
+    readonly parentWritable: WritableStream<Uint8Array>;
+    readonly serializedContext: Record<string, unknown>;
+    readonly session: HarnessSession;
+}
 /**
  * Runs one atomic harness step inside a durable `"use step"` boundary.
  */
-export declare function durableRunStep(serializedContext: Record<string, unknown>, session: HarnessSession, input: HookPayload | undefined): Promise<DurableStepResult>;
+export declare function turnStep(input: TurnStepInput): Promise<DurableStepResult>;
 /**
  * Reconciles `session.continuationToken` with the live
  * `ContinuationTokenKey` value in context.
@@ -30,6 +41,7 @@ export declare function reconcileSessionContinuationToken(ctx: Awaited<ReturnTyp
  * runs independently on its own public child stream.
  */
 export declare function dispatchPendingRuntimeActionsStep(input: {
+    readonly parentWritable: WritableStream<Uint8Array>;
     readonly serializedContext: Record<string, unknown>;
     readonly session: HarnessSession;
 }): Promise<HarnessSession>;
@@ -38,8 +50,9 @@ export declare function dispatchPendingRuntimeActionsStep(input: {
  * adapter before the workflow run tears down.
  */
 export declare function emitTerminalSessionFailureStep(input: {
-    readonly serializedContext: Record<string, unknown>;
     readonly error: unknown;
+    readonly parentWritable: WritableStream<Uint8Array>;
+    readonly serializedContext: Record<string, unknown>;
 }): Promise<void>;
 /**
  * Outcome of {@link runProxyInputRequestStep}, including the session
@@ -55,6 +68,7 @@ export interface RunProxyInputRequestResult {
  */
 export declare function runProxyInputRequestStep(input: {
     readonly hookPayload: SubagentInputRequestHookPayload;
+    readonly parentWritable: WritableStream<Uint8Array>;
     readonly serializedContext: Record<string, unknown>;
     readonly session: HarnessSession;
 }): Promise<RunProxyInputRequestResult>;
@@ -81,9 +95,20 @@ export interface RoutedProxiedDeliverResult {
  */
 export declare function routeProxiedDeliverStep(input: {
     readonly auth?: SessionAuthContext | null;
+    readonly parentWritable: WritableStream<Uint8Array>;
     readonly payload: DeliverPayload;
     readonly session: HarnessSession;
 }): Promise<RoutedProxiedDeliverResult>;
+/**
+ * Starts a per-turn child workflow for the current driver session.
+ *
+ * `parentWritable` is forwarded to the child in the workflow input so
+ * the child's step writes land directly on the driver run's stream —
+ * no copier, no double-store.
+ */
+export declare function dispatchTurnStep(input: TurnWorkflowInput): Promise<{
+    readonly runId: string;
+}>;
 /**
  * Creates the durable session state inside a step boundary before the
  * workflow enters its long-lived turn loop.

package/dist/src/execution/workflow-steps.js

@@ -1,4 +1,3 @@
-import { getWritable } from "#compiled/@workflow/core/index.js";
 import { buildAdapterContext } from "#channel/adapter-context.js";
 import { callAdapterEventHandler, defaultDeliverResult } from "#channel/adapter.js";
 import { toContextAccessor } from "#context/container.js";
@@ -19,20 +18,21 @@ import { createExecutionNodeStep } from "#execution/node-step.js";
 import { emitProxiedInputRequest, routeDeliverPayload } from "#execution/subagent-hitl-proxy.js";
 import { createSession, refreshSessionFromTurnAgent } from "#execution/session.js";
 import { buildSubagentRunInput } from "#execution/subagent-tool.js";
-import { createWorkflowRuntime, workflowEntryReference } from "#execution/workflow-runtime.js";
+import { turnWorkflow } from "#execution/turn-workflow.js";
+import { createWorkflowRuntime, startWorkflowPreferLatest, workflowEntryReference, } from "#execution/workflow-runtime.js";
 /**
  * Runs one atomic harness step inside a durable `"use step"` boundary.
  */
-export async function durableRunStep(serializedContext, session, input) {
+export async function turnStep(input) {
     "use step";
-    const ctx = await deserializeContext(serializedContext);
+    const ctx = await deserializeContext(input.serializedContext);
     const adapter = ctx.require(ChannelKey);
     // Apply deliver-time auth if present. The auth traveled through
     // resumeHook as JSON on the HookPayload. On the first turn (from
     // run()), input carries no auth because it was already seeded by
     // buildRunContext.
-    if (input?.kind === "deliver" && input.auth !== undefined) {
-        ctx.set(AuthKey, input.auth ?? null);
+    if (input.input?.kind === "deliver" && input.input.auth !== undefined) {
+        ctx.set(AuthKey, input.input.auth ?? null);
     }
     // Build the adapter context for deliver and event handlers.
     // Slack adapters override this to inject ctx.thread and ctx.slack.
@@ -41,9 +41,9 @@ export async function durableRunStep(serializedContext, session, input) {
     // custom context keys and optionally transforms the message.
     // Coalesces the resulting StepInput values.
     let resolved;
-    if (input?.kind === "deliver") {
+    if (input.input?.kind === "deliver") {
         const results = [];
-        for (const payload of input.payloads) {
+        for (const payload of input.input.payloads) {
             const result = adapter.deliver
                 ? await adapter.deliver(payload, adapterCtx)
                 : defaultDeliverResult(payload);
@@ -53,31 +53,27 @@ export async function durableRunStep(serializedContext, session, input) {
         }
         resolved = results.length === 0 ? undefined : results.reduce(coalesceTurnInputs);
     }
-    else if (input?.kind === "runtime-action-result") {
-        resolved = { runtimeActionResults: input.results };
+    else if (input.input?.kind === "runtime-action-result") {
+        resolved = { runtimeActionResults: input.input.results };
     }
     // Update adapter state on context after deliver mutations.
-    if (input?.kind === "deliver") {
+    if (input.input?.kind === "deliver") {
         const updatedAdapter = { ...adapter, state: { ...adapterCtx.state } };
         ctx.set(ChannelKey, updatedAdapter);
     }
     // Adapter handled the delivery inline (e.g. a Slack interaction that
     // only edits a message). Persist any context mutations and re-park
     // without running a model turn.
-    if (input?.kind === "deliver" && resolved === undefined) {
-        const rekeyed = reconcileSessionContinuationToken(ctx, session);
+    if (input.input?.kind === "deliver" && resolved === undefined) {
+        const rekeyed = reconcileSessionContinuationToken(ctx, input.session);
         const nextSerializedContext = serializeContext(ctx);
-        const writable = getWritable();
-        const writer = writable.getWriter();
-        writer.releaseLock();
         return {
             action: "park",
             serializedContext: nextSerializedContext,
             session: rekeyed,
         };
     }
-    const writable = getWritable();
-    const writer = writable.getWriter();
+    const writer = input.parentWritable.getWriter();
     const hookRegistry = ctx.require(BundleKey).hookRegistry;
     const emit = async (event) => {
         const toEmit = await callAdapterEventHandler(adapter, event, adapterCtx);
@@ -85,7 +81,7 @@ export async function durableRunStep(serializedContext, session, input) {
         await writer.write(encodeMessageStreamEvent(timestampHandleMessageStreamEvent(toEmit)));
         await dispatchStreamEventHooks({ ctx, registry: hookRegistry, event: toEmit });
     };
-    let stepResult = await runStep(ctx, session, async (enrichedSession) => {
+    let stepResult = await runStep(ctx, input.session, async (enrichedSession) => {
         const bundle = ctx.require(BundleKey);
         const capabilities = ctx.get(CapabilitiesKey);
         const mode = ctx.require(ModeKey);
@@ -223,8 +219,7 @@ export async function dispatchPendingRuntimeActionsStep(input) {
     const auth = ctx.get(AuthKey) ?? null;
     const capabilities = ctx.get(CapabilitiesKey);
     const initiatorAuth = ctx.get(InitiatorAuthKey) ?? null;
-    const writable = getWritable();
-    const writer = writable.getWriter();
+    const writer = input.parentWritable.getWriter();
     const adapterCtx = buildAdapterContext(adapter, toContextAccessor(ctx));
     let nextSession = input.session;
     try {
@@ -308,8 +303,7 @@ export async function emitTerminalSessionFailureStep(input) {
     // consumers (client SDK readers, event-stream replays, dashboards)
     // see a canonical terminal event instead of an abrupt stream close.
     try {
-        const writable = getWritable();
-        const writer = writable.getWriter();
+        const writer = input.parentWritable.getWriter();
         try {
             await writer.write(encodeMessageStreamEvent(timestampHandleMessageStreamEvent(event)));
         }
@@ -335,8 +329,7 @@ export async function runProxyInputRequestStep(input) {
     const adapter = ctx.require(ChannelKey);
     const adapterCtx = buildAdapterContext(adapter, toContextAccessor(ctx));
     const mode = ctx.require(ModeKey);
-    const writable = getWritable();
-    const writer = writable.getWriter();
+    const writer = input.parentWritable.getWriter();
     let proxyResult;
     try {
         const emit = async (event) => {
@@ -355,7 +348,7 @@ export async function runProxyInputRequestStep(input) {
     }
     // Persist adapter-state mutations (e.g. Slack's `pendingRequests`
     // cache populated by the `input.requested` handler) so the next
-    // `durableRunStep` observes them across the serialized context
+    // `turnStep` observes them across the serialized context
     // boundary. Without this the workflow runtime rehydrates a stale
     // adapter and later text-reply deliveries miss the cached batch.
     ctx.set(ChannelKey, { ...adapter, state: { ...adapterCtx.state } });
@@ -396,6 +389,18 @@ export async function routeProxiedDeliverStep(input) {
     }
     return { remainder: routed.forSelf };
 }
+/**
+ * Starts a per-turn child workflow for the current driver session.
+ *
+ * `parentWritable` is forwarded to the child in the workflow input so
+ * the child's step writes land directly on the driver run's stream —
+ * no copier, no double-store.
+ */
+export async function dispatchTurnStep(input) {
+    "use step";
+    const run = await startWorkflowPreferLatest(turnWorkflow, [input]);
+    return { runId: run.runId };
+}
 /**
  * Creates the durable session state inside a step boundary before the
  * workflow enters its long-lived turn loop.

package/dist/src/harness/instrumentation-config.js

@@ -1,14 +1,21 @@
 /**
- * Module-level store for the authored instrumentation config.
+ * Process-global store for the authored instrumentation config.
  *
  * Populated at server startup by the generated Nitro instrumentation plugin
  * when the user's `agent/instrumentation.ts` has a default export produced
- * by `defineInstrumentation()`.
+ * by `defineInstrumentation()`. The harness reads from this at turn time
+ * to decide whether telemetry is enabled and which settings to pass to the
+ * AI SDK.
  *
- * The harness reads from this at turn time to decide whether telemetry is
- * enabled and which settings to pass to the AI SDK.
+ * Rooted on `globalThis` so the generated Nitro instrumentation plugin
+ * (which Nitro keeps external by `file://` URL) and the bundled harness
+ * chunk (which Nitro inlines via the package's `#harness/*` import alias)
+ * share one source of truth, even though they resolve to two distinct ESM
+ * module instances. See `context/key.ts` and
+ * `runtime/sessions/runtime-session.ts` for the established pattern.
  */
-let registeredConfig;
+const INSTRUMENTATION_CONFIG_GLOBAL_KEY = Symbol.for("experimental-ash.harness-instrumentation-config");
+const globalContainer = globalThis;
 /**
  * Registers the authored instrumentation config and invokes its `setup`
  * callback with the resolved agent name.
@@ -22,7 +29,7 @@ export function registerInstrumentationConfig(config, context) {
     if (config.setup !== undefined) {
         config.setup(context);
     }
-    registeredConfig = config;
+    globalContainer[INSTRUMENTATION_CONFIG_GLOBAL_KEY] = config;
 }
 /**
  * Returns the registered instrumentation config, or `undefined` when no
@@ -31,5 +38,5 @@ export function registerInstrumentationConfig(config, context) {
  * @internal — not part of the public API.
  */
 export function getInstrumentationConfig() {
-    return registeredConfig;
+    return globalContainer[INSTRUMENTATION_CONFIG_GLOBAL_KEY];
 }

package/dist/src/harness/messages.d.ts

@@ -19,9 +19,9 @@ export declare function coalesceTurnInputs(a: StepInput, b: StepInput): StepInpu
  */
 export declare function resolveAssistantStepText(messages: readonly ModelMessage[], fallback: string | undefined): string | null;
 /**
- * Structural shape shared by both the workflow `DeliverHookPayload` and the
- * continuous `DeliverQueueItem`. Using a structural type avoids coupling
- * this helper to either runtime's concrete type.
+ * Structural shape of the workflow `DeliverHookPayload`. Using a
+ * structural type keeps this helper decoupled from the concrete
+ * runtime type.
  */
 interface DeliverLike {
     readonly auth?: SessionAuthContext | null;
@@ -32,10 +32,10 @@ interface DeliverLike {
  * Coalesces an array of deliver-like items into a single item by
  * collecting all payloads and keeping the most recent auth value.
  *
- * Used by both the workflow and continuous runtimes to batch follow-up
- * deliveries that arrived while a turn or subagent delegation was in
- * progress. Each payload is later passed to `onDeliver` individually so
- * channel-specific fields are never lost.
+ * Used by the workflow runtime to batch follow-up deliveries that
+ * arrived while a turn or subagent delegation was in progress. Each
+ * payload is later passed to `onDeliver` individually so channel-
+ * specific fields are never lost.
  */
 export declare function coalesceDeliveries<T extends DeliverLike>(items: readonly T[]): T;
 export {};

package/dist/src/harness/messages.js

@@ -122,10 +122,10 @@ function toUserContentArray(value) {
  * Coalesces an array of deliver-like items into a single item by
  * collecting all payloads and keeping the most recent auth value.
  *
- * Used by both the workflow and continuous runtimes to batch follow-up
- * deliveries that arrived while a turn or subagent delegation was in
- * progress. Each payload is later passed to `onDeliver` individually so
- * channel-specific fields are never lost.
+ * Used by the workflow runtime to batch follow-up deliveries that
+ * arrived while a turn or subagent delegation was in progress. Each
+ * payload is later passed to `onDeliver` individually so channel-
+ * specific fields are never lost.
  */
 export function coalesceDeliveries(items) {
     const [first, ...rest] = items;

package/dist/src/harness/runtime-actions.d.ts

@@ -67,10 +67,10 @@ export declare function recordPendingSubagentChildToken(input: {
 /**
  * Discriminated item consumed by {@link accumulateRuntimeActionResults}.
  *
- * Both the workflow and continuous runtimes receive interleaved deliveries
- * and runtime-action results while waiting for pending subagent calls.
- * This union abstracts over `HookPayload` and `QueueItem` so the shared
- * accumulation loop is runtime-agnostic.
+ * The workflow runtime receives interleaved deliveries and runtime-action
+ * results while waiting for pending subagent calls; this union lets the
+ * accumulation loop process both kinds without coupling to the concrete
+ * `HookPayload` shape.
  */
 export type RuntimeActionAccumulatorItem<TDeliver> = {
     readonly kind: "deliver";

package/dist/src/internal/application/package.js

@@ -6,7 +6,7 @@ import { ASH_PACKAGE_NAME } from "#package-name.js";
 let cachedPackageInfo;
 // The package build stamps the published version into `dist` so bundled
 // deployments can still report package metadata without resolving package.json.
-const BUNDLED_FALLBACK_PACKAGE_VERSION = "0.22.2";
+const BUNDLED_FALLBACK_PACKAGE_VERSION = "0.24.0";
 const BUNDLED_FALLBACK_PACKAGE_VERSION_PLACEHOLDER = "__ASH_PACKAGE_VERSION_PLACEHOLDER__";
 const WORKFLOW_MODULE_ALIASES = {
     "workflow/api": "src/compiled/@workflow/core/runtime.js",

package/dist/src/internal/workflow-bundle/workflow-builders.d.ts

@@ -28,7 +28,7 @@ export declare const WORKFLOW_QUEUE_TRIGGER: {
     readonly retryAfterSeconds: 5;
     readonly initialDelaySeconds: 0;
 };
-export declare function applyWorkflowTransform(filename: string, source: string, mode: "workflow" | "step" | "client" | false, absolutePath?: string, projectRoot?: string): Promise<{
+export declare function applyWorkflowTransform(filename: string, source: string, mode: "workflow" | "step" | "client" | false, absolutePath?: string, projectRoot?: string, stableWorkflowNames?: ReadonlySet<string>): Promise<{
     code: string;
     workflowManifest: WorkflowManifest;
 }>;

package/dist/src/internal/workflow-bundle/workflow-builders.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { STABLE_WORKFLOW_NAMES } from "#execution/workflow-runtime.js";
 import { transformWorkflowDirectives } from "./workflow-transformer.js";
 export const WORKFLOW_QUEUE_TRIGGER = {
     type: "queue/v2beta",
@@ -11,15 +12,22 @@ export const WORKFLOW_QUEUE_TRIGGER = {
 };
 const packageJsonCache = new Map();
 const projectDepsCache = new Map();
-export async function applyWorkflowTransform(filename, source, mode, absolutePath, projectRoot) {
+export async function applyWorkflowTransform(filename, source, mode, absolutePath, projectRoot, stableWorkflowNames = STABLE_WORKFLOW_NAMES) {
     const resolvedProjectRoot = projectRoot ?? process.cwd();
     const absoluteFilename = absolutePath === undefined
         ? isAbsolute(filename)
             ? filename
             : join(resolvedProjectRoot, filename)
         : absolutePath;
-    const { moduleSpecifier } = resolveModuleSpecifier(absoluteFilename, resolvedProjectRoot);
-    return transformWorkflowDirectives({ filename, mode, moduleSpecifier, source });
+    const { moduleSpecifier, stableModuleSpecifier } = resolveModuleSpecifier(absoluteFilename, resolvedProjectRoot);
+    return transformWorkflowDirectives({
+        filename,
+        mode,
+        moduleSpecifier,
+        source,
+        stableModuleSpecifier,
+        stableWorkflowNames,
+    });
 }
 export function detectWorkflowPatterns(source) {
     return {
@@ -58,17 +66,21 @@ function resolveModuleSpecifier(filePath, projectRoot) {
     const inNodeModules = isInNodeModules(filePath);
     const inWorkspace = !inNodeModules && isWorkspacePackage(filePath, projectRoot);
     if (!inNodeModules && !inWorkspace) {
-        return { moduleSpecifier: undefined };
+        return { moduleSpecifier: undefined, stableModuleSpecifier: undefined };
     }
     const pkg = findPackageJson(filePath);
     if (pkg === null) {
-        return { moduleSpecifier: undefined };
+        return { moduleSpecifier: undefined, stableModuleSpecifier: undefined };
     }
     const subpath = resolveExportSubpath(filePath, pkg);
+    // The default specifier is version-stamped for normal workflow/step
+    // ids; the stable variant drops the `@<pkg.version>` suffix so
+    // {@link STABLE_WORKFLOW_NAMES} functions emit cross-deployment
+    // routable ids.
+    const base = subpath ? `${pkg.name}${subpath}` : pkg.name;
     return {
-        moduleSpecifier: subpath
-            ? `${pkg.name}${subpath}@${pkg.version}`
-            : `${pkg.name}@${pkg.version}`,
+        moduleSpecifier: `${base}@${pkg.version}`,
+        stableModuleSpecifier: base,
     };
 }
 function findPackageJson(filePath) {

package/dist/src/internal/workflow-bundle/workflow-transformer.d.ts

@@ -5,6 +5,19 @@ export declare function transformWorkflowDirectives(input: {
     mode: WorkflowDirectiveMode;
     moduleSpecifier: string | undefined;
     source: string;
+    /**
+     * Package-qualified module specifier without the `@<pkg.version>`
+     * stamp. Used to mint workflow ids for functions named in
+     * {@link transformWorkflowDirectives.input.stableWorkflowNames} so
+     * the bundled id matches the runtime reference on every deployment.
+     */
+    stableModuleSpecifier?: string | undefined;
+    /**
+     * Workflow function names whose bundled id should be emitted without
+     * the package version stamp. See `STABLE_WORKFLOW_NAMES` in
+     * `workflow-runtime.ts` for the canonical set ash itself uses.
+     */
+    stableWorkflowNames?: ReadonlySet<string>;
 }): Promise<{
     code: string;
     workflowManifest: WorkflowManifest;

package/dist/src/internal/workflow-bundle/workflow-transformer.js

@@ -13,14 +13,19 @@ export async function transformWorkflowDirectives(input) {
     if (functions.length === 0) {
         return { code: input.source, workflowManifest: {} };
     }
-    const idBase = input.moduleSpecifier ?? `./${stripJavaScriptExtension(input.filename)}`;
+    // Step ids stay version-stamped — they are per-deployment internal
+    // identifiers, not cross-deployment routing keys. Only workflow
+    // functions whose name appears in `stableWorkflowNames` opt out of
+    // the version stamp.
+    const defaultIdBase = input.moduleSpecifier ?? `./${stripJavaScriptExtension(input.filename)}`;
+    const stableIdBase = input.stableModuleSpecifier ?? defaultIdBase;
     const manifest = {};
     const replacements = [];
     const suffixes = [];
     let hasStepRegistration = false;
     for (const fn of functions) {
         if (fn.directive === "use step") {
-            const stepId = createStepId(idBase, fn.name);
+            const stepId = createStepId(defaultIdBase, fn.name);
             manifest.steps ??= {};
             const stepsForFile = (manifest.steps[input.filename] ??= {});
             stepsForFile[fn.name] = { stepId };
@@ -44,7 +49,8 @@ export async function transformWorkflowDirectives(input) {
             }
             continue;
         }
-        const workflowId = `workflow//${idBase}//${fn.name}`;
+        const isStable = input.stableWorkflowNames?.has(fn.name) === true;
+        const workflowId = `workflow//${isStable ? stableIdBase : defaultIdBase}//${fn.name}`;
         manifest.workflows ??= {};
         const workflowsForFile = (manifest.workflows[input.filename] ??= {});
         workflowsForFile[fn.name] = { workflowId };
@@ -66,7 +72,7 @@ export async function transformWorkflowDirectives(input) {
     const hasWorkflowDirective = functions.some((fn) => fn.directive === "use workflow");
     if (input.mode === "workflow" && !hasWorkflowDirective) {
         return {
-            code: `${manifestComment}\n${createWorkflowStepProxySource(input.source, ast, functions, idBase)}`,
+            code: `${manifestComment}\n${createWorkflowStepProxySource(input.source, ast, functions, defaultIdBase)}`,
             workflowManifest: manifest,
         };
     }

package/dist/src/protocol/message.d.ts

@@ -76,20 +76,25 @@ export interface RuntimeIdentity {
  * `message` is either a plain text string or an AI SDK `UserContent`
  * array (mixing `text`, `image`, and `file` parts). Clients pass
  * multimodal attachments with the same shape AI SDK's `useChat`
- * `sendMessage({ files })` produces.
+ * `sendMessage({ files })` produces. `clientContext` is one-turn
+ * client/page context; the channel converts it into internal model context.
  */
 export type HandleMessageRequestBody = {
     readonly message: string | UserContent;
+    readonly clientContext?: string | readonly string[] | JsonObject;
 } | {
     readonly continuationToken: string;
     readonly message: string | UserContent;
+    readonly clientContext?: string | readonly string[] | JsonObject;
 } | {
     readonly continuationToken: string;
     readonly inputResponses: readonly InputResponse[];
+    readonly clientContext?: string | readonly string[] | JsonObject;
 } | {
     readonly continuationToken: string;
     readonly inputResponses: readonly InputResponse[];
     readonly message: string | UserContent;
+    readonly clientContext?: string | readonly string[] | JsonObject;
 };
 /**
  * JSON response returned when the message route accepts a start or resume

package/dist/src/public/channels/ash.js

@@ -1,8 +1,10 @@
+import {} from "ai";
 import { ASH_MESSAGE_STREAM_CONTENT_TYPE, ASH_MESSAGE_STREAM_FORMAT, ASH_MESSAGE_STREAM_VERSION, ASH_SESSION_ID_HEADER, ASH_STREAM_FORMAT_HEADER, ASH_STREAM_VERSION_HEADER, } from "#protocol/message.js";
 import { isInputResponse } from "#runtime/input/types.js";
 import { createUnauthorizedResponse } from "#public/channels/auth.js";
 import { collectUploadPolicyViolations, formatUploadPolicyViolation, mergeUploadPolicy, } from "#public/channels/upload-policy.js";
 import { defineChannel, POST, GET } from "#public/definitions/defineChannel.js";
+import { parseJsonObject } from "#shared/json.js";
 export function ashChannel(input) {
     const uploadPolicy = mergeUploadPolicy(input.uploadPolicy);
     return defineChannel({
@@ -29,7 +31,7 @@ export function ashChannel(input) {
                 if (policyRejection !== null)
                     return policyRejection;
                 const token = `ash:${crypto.randomUUID()}`;
-                const session = await send(body.message, {
+                const session = await send(createSendPayload(body), {
                     auth: sessionAuth,
                     continuationToken: token,
                 });
@@ -79,6 +81,7 @@ export function ashChannel(input) {
                 const session = await send({
                     inputResponses: body.inputResponses,
                     message: body.message,
+                    modelContext: body.modelContext,
                 }, {
                     auth: sessionAuth,
                     continuationToken: body.continuationToken,
@@ -137,10 +140,13 @@ function parseCreateBody(payload) {
     const message = parseMessageField(payload.message);
     if (message instanceof Response)
         return message;
+    const modelContext = parseClientContextField(payload.clientContext);
+    if (modelContext instanceof Response)
+        return modelContext;
     if (message === undefined) {
         return Response.json({ error: "Missing or empty 'message' field.", ok: false }, { status: 400 });
     }
-    return { message };
+    return { message, modelContext };
 }
 function parseContinueBody(payload) {
     const continuationToken = typeof payload.continuationToken === "string" && payload.continuationToken.length > 0
@@ -155,13 +161,22 @@ function parseContinueBody(payload) {
     const inputResponses = parseInputResponses(payload.inputResponses);
     if (inputResponses instanceof Response)
         return inputResponses;
+    const modelContext = parseClientContextField(payload.clientContext);
+    if (modelContext instanceof Response)
+        return modelContext;
     if (message === undefined && inputResponses === undefined) {
         return Response.json({
             error: "Expected a non-empty 'message', a non-empty 'inputResponses' array, or both.",
             ok: false,
         }, { status: 400 });
     }
-    return { message, continuationToken, inputResponses };
+    return { message, continuationToken, inputResponses, modelContext };
+}
+function createSendPayload(body) {
+    if (body.modelContext === undefined) {
+        return body.message;
+    }
+    return { message: body.message, modelContext: body.modelContext };
 }
 function parseMessageField(value) {
     if (value === undefined)
@@ -255,6 +270,38 @@ function parseInputResponses(value) {
     }
     return inputResponses;
 }
+const CLIENT_CONTEXT_PREFIX = "Ephemeral client context:\n";
+function parseClientContextField(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === "string") {
+        return value.length > 0 ? [toClientContextMessage(value)] : undefined;
+    }
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return undefined;
+        if (!value.every((entry) => typeof entry === "string" && entry.length > 0)) {
+            return Response.json({ error: "Expected 'clientContext' array entries to be non-empty strings.", ok: false }, { status: 400 });
+        }
+        return value.map((entry) => toClientContextMessage(entry));
+    }
+    if (value === null || typeof value !== "object") {
+        return Response.json({
+            error: "Expected 'clientContext' to be a string, string array, or JSON object.",
+            ok: false,
+        }, { status: 400 });
+    }
+    try {
+        const json = parseJsonObject(value);
+        return [toClientContextMessage(JSON.stringify(json))];
+    }
+    catch {
+        return Response.json({ error: "Expected 'clientContext' to be a JSON-serializable object.", ok: false }, { status: 400 });
+    }
+}
+function toClientContextMessage(content) {
+    return { role: "user", content: `${CLIENT_CONTEXT_PREFIX}${content}` };
+}
 function parseStartIndex(request) {
     const raw = new URL(request.url).searchParams.get("startIndex");
     if (raw === null)

package/dist/src/public/context/index.d.ts

@@ -2,15 +2,12 @@
  * Runtime context helpers for authored code.
  *
  * These APIs work only inside active authored runtime execution such as
- * tools and other Ash-invoked callbacks. They read from a single
- * `AshContext` container bound via `AsyncLocalStorage`.
+ * tools and other Ash-invoked callbacks.
  *
  * @example
  * ```ts
- * import { ContextKey, getContext, setContext } from "experimental-ash/context";
+ * import { defineState, getSession } from "experimental-ash/context";
  * ```
  */
-export { ensureContext, getContext, getSession, hasContext, requireContext, type Session, type SessionAuth, type SessionAuthContext, type SessionParent, type SessionTurn, setContext, } from "#context/accessors.js";
-export type { AshContext } from "#context/container.js";
-export { type ContextAccessor, ContextKey, type ContextKeyOptions } from "#context/key.js";
-export type { ContextProvider, ContextReader } from "#context/provider.js";
+export { getSession, type Session, type SessionAuth, type SessionAuthContext, type SessionParent, type SessionTurn, } from "#context/accessors.js";
+export { defineState, type StateHandle } from "#public/definitions/state.js";

package/dist/src/public/context/index.js

@@ -2,13 +2,12 @@
  * Runtime context helpers for authored code.
  *
  * These APIs work only inside active authored runtime execution such as
- * tools and other Ash-invoked callbacks. They read from a single
- * `AshContext` container bound via `AsyncLocalStorage`.
+ * tools and other Ash-invoked callbacks.
  *
  * @example
  * ```ts
- * import { ContextKey, getContext, setContext } from "experimental-ash/context";
+ * import { defineState, getSession } from "experimental-ash/context";
  * ```
  */
-export { ensureContext, getContext, getSession, hasContext, requireContext, setContext, } from "#context/accessors.js";
-export { ContextKey } from "#context/key.js";
+export { getSession, } from "#context/accessors.js";
+export { defineState } from "#public/definitions/state.js";