experimental-ash 0.48.0 → 0.49.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # experimental-ash
 
+## 0.49.0
+
+### Minor Changes
+
+- 72cd8be: Channels now deliver their inbound `<*_context>` block as a dedicated session-context entry instead of prepending it onto the user's turn message. This applies to Slack, Teams, Discord, Telegram, and Twilio so the model sees the actor/channel metadata as its own message ahead of the user text, and the user turn stays clean. The unused `prependTeamsContext`, `prependDiscordContext`, and `prependTelegramContext` helpers are removed from the public API; use the corresponding `format*ContextBlock` functions if you need to render a block yourself.
+- a703ebb: Remove lifecycle hooks (`lifecycle.session`, `lifecycle.turn`) from the hook system. Hooks now only support stream-event subscribers (`events`). The `LifecycleHook`, `LifecycleHooks` types and `SessionPreparedKey` context key are removed. The `HookDefinition` interface no longer accepts a `lifecycle` field.
+
+### Patch Changes
+
+- ce09ade: Carry durable session snapshots through Workflow step results and remove `ash.session` write plumbing from current runs. The `ash.session` stream remains only as a legacy read fallback for old stream-backed handles.
+
 ## 0.48.0
 
 ### Minor Changes

package/dist/docs/internals/context.md

@@ -45,7 +45,6 @@ Set by the runtime entry point. Serialized at `"use step"` boundaries via their
 | `ParentSessionKey`     | `SessionParent`              |
 | `ChannelKey`           | `Channel`                    |
 | `BundleKey`            | `CompiledBundle`             |
-| `SessionPreparedKey`   | `boolean`                    |
 
 ## Virtual Keys
 
@@ -77,17 +76,12 @@ Framework providers use a superset `FrameworkContextProvider` that also receives
 4. Run the callback inside `contextStorage.run(ctx, ...)`
 5. Call framework provider `commit` hooks for provider-owned session state
 
-Authored hook lifecycle dispatch (`lifecycle.session`, `lifecycle.turn`)
-runs inside step (4)'s ALS scope, before the harness step. Lifecycle
-hooks receive `(ctx)`, and event hooks receive `(event, ctx)`. See
-[Hooks](./hooks.md) for the full pipeline and the `SessionPreparedKey`
-flag's failure semantics.
-
-`StepInput.modelContext` has two producers. Channels can provide
-ephemeral messages through `SendPayload.modelContext`, and lifecycle
-hooks can provide them through `LifecycleHookResult.modelContext`.
-The merge order is channel first, then `lifecycle.session`, then
-`lifecycle.turn`. The merged messages are visible to the next model
+Authored hook stream-event dispatch runs inside step (4)'s ALS scope.
+Event hooks receive `(event, ctx)`. See [Hooks](./hooks.md) for the
+full pipeline.
+
+`StepInput.modelContext` is provided by channels through
+`SendPayload.modelContext`. The messages are visible to the next model
 call only and are never persisted to durable session history.
 
 ## Channel Context

package/dist/docs/internals/hooks.md

@@ -1,8 +1,7 @@
 # Hooks
 
 Hooks are the first-class extension point for authored agent code that needs
-to run **around** a turn instead of inside it. Tools answer the model;
-hooks answer the runtime.
+to observe runtime events. Tools answer the model; hooks answer the runtime.
 
 This page explains the discovery → compile → resolve → dispatch pipeline
 and the runtime contract every authored hook handler relies on. The
@@ -11,8 +10,8 @@ end-user-facing reference lives at
 
 ## Architectural Rationale
 
-Plugins and authored agent code need to subscribe to the same lifecycle
-moments. Shipping hooks first closes the gap between "extension authored
+Plugins and authored agent code need to subscribe to the same stream
+events. Shipping hooks first closes the gap between "extension authored
 inside the agent" and "extension contributed by a plugin": both flow
 through one runtime registry, one `HookContext`, one set of ordering
 rules.
@@ -27,20 +26,14 @@ place to look when debugging.
 `id`, `auth`, `turn`, and `parent`). `session.auth` is a nested
 `SessionAuth` with `{ current, initiator }`.
 
-Lifecycle hooks receive `(ctx)` — a single `HookContext` argument.
 Event hooks receive `(event, ctx)` — event first, context last (omit `ctx` when unused).
-Per-turn `turnId` and `sequence` come from `ctx.session.turn` for
-lifecycle hooks, and from `event.data.{turnId, sequence}` for
+Per-turn `turnId` and `sequence` come from `event.data.{turnId, sequence}` for
 stream-event hooks — never duplicated on the context.
 
 ## Authoring shape
 
 ```ts
 defineHook({
-  lifecycle?: {
-    session?: LifecycleHook;
-    turn?: LifecycleHook;
-  };
   events?: {
     [K in HandleMessageStreamEvent["type"]]?: StreamEventHook<…>;
     "*"?: StreamEventHook<HandleMessageStreamEvent>;
@@ -48,10 +41,9 @@ defineHook({
 });
 ```
 
-The split between `lifecycle:` and `events:` is structural so the
-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.
+Hooks are observe-only — they cannot inject model context. Use
+`defineDynamic` + `defineInstructions` in `agent/instructions/` to
+contribute runtime model messages.
 
 ## Pipeline
 
@@ -69,17 +61,14 @@ compiler performs no per-handler validation — hook handlers are
 arbitrary functions and can only be inspected at runtime.
 
 Resolve (`src/runtime/resolve-hook.ts`) loads the authored module
-export and reads its nested `lifecycle` and `events` maps directly. Each
-declared handler must be a function; mismatches throw
-`ResolveAgentError` so typos surface at boot. There is no hardcoded
-list of valid event types — unknown event keys are accepted at resolve
-time and simply never fire at dispatch time.
+export and reads its `events` map directly. Each declared handler must
+be a function; mismatches throw `ResolveAgentError` so typos surface at
+boot. There is no hardcoded list of valid event types — unknown event
+keys are accepted at resolve time and simply never fire at dispatch time.
 
 Registry (`src/runtime/hooks/registry.ts`) builds a
 `RuntimeHookRegistry` per resolved agent node:
 
-- `session` — flat ordered array of `lifecycle.session` subscribers.
-- `turn` — flat ordered array of `lifecycle.turn` subscribers.
 - `streamEventsByType` — bucketed map keyed by event type.
 - `streamEventsWildcard` — flat array of `*` subscribers.
 
@@ -89,38 +78,6 @@ the workflow path.
 
 ## Dispatch
 
-Lifecycle dispatch lives in `src/context/hook-lifecycle.ts`. The
-workflow runtime entry point (`execution/workflow-steps.ts`) calls
-`runHookLifecycleStep` once per turn, **inside** the active ALS scope
-so hook code can read and write context like every other authored
-function. `runHookLifecycleStep` wraps `dispatchHookLifecycle`, lowers
-a `turn-failed` outcome into a parking `StepResult` (`{ next: null }`
-for conversation mode, `{ next: { done: true, output } }` for task
-mode), and otherwise hands off to the supplied harness step callback
-with the (possibly augmented) input.
-
-Dispatch is gated on `getHarnessEmissionState(session).turnId === ""`
-so tool-loop continuations and runtime-action resumes (which are
-continuations of an existing turn) skip the lifecycle stack.
-
-Stages, in order:
-
-1. **`lifecycle.session`** runs sequentially in registry order, but
-   only when `ash.sessionPrepared` is unset. The dispatcher sets the
-   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. 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`).
-
-If an event hook subscribed to one of the failure-cascade events
-itself throws while the dispatcher is emitting the recoverable
-`turn.failed`, the throw escalates and the runtime emits
-`session.failed` instead. This is the bounded second-order behavior
-when both a `lifecycle.turn` and a `turn.failed` event hook fail.
-
 ### Stream event dispatch (`handleEvent`)
 
 Every stream event passes through one `handleEvent` function
@@ -151,13 +108,6 @@ right before each model call. See the [event dispatch
 doc](../../research/active/unified-event-dispatch.md) for the full
 design.
 
-## `SessionPreparedKey`
-
-Lives in `src/context/keys.ts`. JSON-safe boolean, no codec. Set
-**before** the `lifecycle.session` chain runs so a thrown hook leaves
-the flag set — the next turn does not retry. Compaction does not clear
-the flag.
-
 ## Subagent Isolation
 
 Subagent hooks are fully isolated by structural construction:
@@ -175,19 +125,13 @@ The `discover/discover-subagent.ts` path walks each local subagent's
 
 ## Error Containment
 
-| Stage               | On throw                                                                               |
-| ------------------- | -------------------------------------------------------------------------------------- |
-| `lifecycle.session` | Re-thrown by dispatcher → terminal session failure (`session.failed`)                  |
-| `lifecycle.turn`    | Caught by dispatcher → recoverable `turn.failed` cascade emitted                       |
-| Stream-event hooks  | Propagated through the emit composer → existing harness error path emits `turn.failed` |
+| Stage              | On throw                                                                               |
+| ------------------ | -------------------------------------------------------------------------------------- |
+| Stream-event hooks | Propagated through the emit composer → existing harness error path emits `turn.failed` |
 
 ### Full per-turn execution order
 
 ```
-dispatchHookLifecycle():
-  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
   handleEvent(turn.started)      → emit, hooks, dynamic tool resolvers
@@ -213,9 +157,8 @@ emitStepActions() via handleEvent:
   (`src/runtime/hooks/registry.ts` ⇄ `runtime/hooks/registry.test.ts`,
   `src/compiler/normalize-hook.ts` ⇄ `compiler/normalize-hook.test.ts`,
   `src/runtime/resolve-hook.ts` ⇄ `runtime/resolve-hook.test.ts`).
-- Lifecycle dispatcher behavior is covered by
+- Stream-event dispatcher behavior is covered by
   `src/context/hook-lifecycle.integration.test.ts` (synthetic context,
-  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,
@@ -231,8 +174,6 @@ documented expectations:
 
 - Hook modules never import workflow primitives (`start`, `resumeHook`,
   `createHook`, `getWritable`).
-- Hook return shapes have no `state` field — durable state goes through
-  `ctx`.
 - Subagent hooks never read parent ALS context.
 
 ## Related Pages

package/dist/docs/internals/mechanical-invariants.md

@@ -92,10 +92,9 @@ hooks never read parent ALS context.
 Enforcement: rule 27 in `scripts/guard-agents-rules.mjs` fails if a
 `state:` (or `readonly state:`, `state?:`) field is declared on any
 type in `packages/ash/src/public/definitions/hook.ts`. The lint guards
-maintainers from accidentally widening `LifecycleHookResult` (which
-today exposes only `modelContext`) into a parallel state channel. The
-TypeScript surface itself rejects authored hooks that return any field
-the type does not declare.
+maintainers from accidentally widening hook types into a parallel state
+channel. The TypeScript surface itself rejects authored hooks that
+return any field the type does not declare.
 
 The complementary "subagent hooks never read parent ALS context"
 invariant is enforced structurally by the `runStep` ALS-scope split

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

@@ -46,9 +46,8 @@ step.completed → turn.completed → session.waiting / session.completed
 ```
 
 Failure variants: `step.failed`, `turn.failed`, `session.failed`.
-A thrown `lifecycle.session` hook produces a terminal `session.failed`;
-a thrown `lifecycle.turn` hook produces a recoverable `turn.failed`
-cascade. See [Hooks](./hooks.md).
+A thrown stream-event hook propagates through the emit composer; the
+existing harness error path emits `turn.failed`. See [Hooks](./hooks.md).
 
 `message.appended` and `reasoning.appended` carry both delta and cumulative text. `step.completed.data.finishReason` mirrors the model-step outcome (`tool-calls` means the turn continues).
 

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

@@ -1,28 +1,25 @@
 ---
 title: "Hooks"
-description: "Subscribe to lifecycle moments and runtime stream events from agent/hooks/."
+description: "Subscribe to runtime stream events from agent/hooks/."
 url: /hooks
 ---
 
-Hooks are Ash's authored extension points for the per-turn lifecycle and
-the runtime event stream.
+Hooks are Ash's authored extension points for the runtime event stream.
 
 This page is about `agent/hooks/*.ts` runtime hooks. For the React client hook,
 see [`useAshAgent`](../frontend/use-ash-agent.md).
 
-Use a hook when you want to run code **around** a turn (before the model
-runs, around stream events) without writing a tool, a context provider,
-or a channel adapter handler.
+Use a hook when you want to observe stream events (audit, metrics,
+alerting) without writing a tool, a context provider, or a channel
+adapter handler.
 
-<CopyPrompt text="Add an Ash hook to the user's project. Ash hooks live under agent/hooks, use defineHook from experimental-ash/hooks, and can subscribe to lifecycle.session, lifecycle.turn, or stream events. Use lifecycle hooks when the model needs side effects before the next model call (e.g. setting state); use events handlers for observe-only side effects after events are durably recorded. Inspect existing hooks and agent/lib, choose the smallest hook file and path-derived slug, use defineState only when durable shared state is needed, wrap best-effort side effects so they do not fail sessions accidentally, verify the relevant lifecycle or stream event behavior, and do not commit unless the user asks.">
+<CopyPrompt text="Add an Ash hook to the user's project. Ash hooks live under agent/hooks, use defineHook from experimental-ash/hooks, and can subscribe to stream events. Use event handlers for observe-only side effects after events are durably recorded. Inspect existing hooks and agent/lib, choose the smallest hook file and path-derived slug, use defineState only when durable shared state is needed, wrap best-effort side effects so they do not fail sessions accidentally, verify the relevant stream event behavior, and do not commit unless the user asks.">
   Add an Ash hook to the user's project. Ash hooks live under agent/hooks, use defineHook from
-  experimental-ash/hooks, and can subscribe to lifecycle.session, lifecycle.turn, or stream events.
-  Use lifecycle hooks when the model needs side effects before the next model call (e.g. setting
-  state); use events handlers for observe-only side effects after events are durably recorded.
-  Inspect existing hooks and agent/lib, choose the smallest hook file and path-derived slug, use
-  defineState only when durable shared state is needed, wrap best-effort side effects so they do not
-  fail sessions accidentally, verify the relevant lifecycle or stream event behavior, and do not
-  commit unless the user asks.
+  experimental-ash/hooks, and can subscribe to stream events. Use event handlers for observe-only
+  side effects after events are durably recorded. Inspect existing hooks and agent/lib, choose the
+  smallest hook file and path-derived slug, use defineState only when durable shared state is
+  needed, wrap best-effort side effects so they do not fail sessions accidentally, verify the
+  relevant stream event behavior, and do not commit unless the user asks.
 </CopyPrompt>
 
 ## The Main API
@@ -52,16 +49,27 @@ The slug is the path-relative basename: `agent/hooks/audit.ts` → `"audit"`,
 
 ## Shape
 
-A hook file declares two kinds of subscribers under named maps:
+A hook file declares stream-event subscribers under the `events` map:
 
-- `lifecycle: { session?, turn? }` — runs **before** the harness step.
-  Side-effect-only.
-- `events: { ... }` — runs **after** Ash has accepted a stream event
-  and written it to the durable stream. Observe-only.
+```ts
+defineHook({
+  events: {
+    "session.started"(event, ctx) {
+      /* ... */
+    },
+    "turn.completed"(event, ctx) {
+      /* ... */
+    },
+    "*"(event, ctx) {
+      /* wildcard — fires for every event */
+    },
+  },
+});
+```
 
-The split is structural so the contract is explicit at a glance: code
-under `lifecycle:` may change what the model sees on the next call;
-code under `events:` cannot.
+Handlers are observe-only — they cannot inject model context. To
+contribute runtime model messages, use `defineDynamic` +
+`defineInstructions` in `agent/instructions/`.
 
 Every handler receives the same `HookContext`:
 
@@ -110,48 +118,6 @@ callId }` with `output` typed as the tool's `TOutput`. For connections
 it includes `{ output, toolName, connectionToolName, callId }` with
 `output` as `unknown`.
 
-## Lifecycle
-
-Lifecycle hooks share one signature:
-
-```ts
-type LifecycleHook = (ctx: HookContext) => void | Promise<void>;
-```
-
-Session and turn metadata are available on `ctx.session`. For example,
-`ctx.session.turn.sequence` gives the current turn sequence number.
-
-`lifecycle.session` runs **once per durable session**, before the first
-model turn. `lifecycle.turn` runs **once per fresh delivery** — tool-loop
-continuations and HITL resumes do not re-fire it.
-
-Hooks are side-effect-only — they cannot inject model context. To
-contribute runtime model messages, use `defineDynamic` +
-`defineInstructions` in `agent/instructions/`.
-
-### Seed durable context
-
-```ts
-// agent/hooks/load-profile.ts
-import { defineState } from "experimental-ash/context";
-import { defineHook } from "experimental-ash/hooks";
-import { fetchGithubProfile, type GithubProfile } from "../lib/github";
-
-const githubProfile = defineState<GithubProfile | null>("myapp.githubProfile", () => null);
-
-export default defineHook({
-  lifecycle: {
-    async session(ctx) {
-      const profile = await fetchGithubProfile(ctx.session.id);
-      githubProfile.update(() => profile);
-    },
-  },
-});
-```
-
-The profile is now visible to every tool, provider, and subsequent hook
-through `githubProfile.get()`.
-
 ## Stream Events
 
 Side-effect-only handlers for accepted runtime events. Subscribe by
@@ -190,11 +156,9 @@ Hooks always run **after** the event is durably recorded — if a hook throws, t
 
 ## Errors
 
-| Stage               | On throw                                                                                                                                                                                             |
-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `lifecycle.session` | Terminal session failure (`session.failed`). The flag is set before the chain runs, so the next turn does not retry.                                                                                 |
-| `lifecycle.turn`    | Recoverable turn failure (`turn.failed`). Session keeps living.                                                                                                                                      |
-| `events.*`          | Propagates through the emit composer; the existing harness error path emits `turn.failed`. If the hook subscribed to a failure-cascade event also throws, the runtime escalates to `session.failed`. |
+| Stage      | On throw                                                                                                                                                                                             |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `events.*` | Propagates through the emit composer; the existing harness error path emits `turn.failed`. If the hook subscribed to a failure-cascade event also throws, the runtime escalates to `session.failed`. |
 
 If you want belt-and-suspenders semantics inside a hook, wrap the body
 in `try`/`catch` — Ash treats a thrown hook as a real failure.
@@ -208,13 +172,12 @@ context.
 
 ## When to use a hook vs a tool vs a provider
 
-| Need                                                 | Use                                          |
-| ---------------------------------------------------- | -------------------------------------------- |
-| Run before a turn (seed context, inject system text) | `lifecycle.session` / `lifecycle.turn`       |
-| Observe runtime events (audit, metrics, alerting)    | `events.<type>` (or channel adapter handler) |
-| Provide structured input to the model on demand      | a tool                                       |
-| Make a value available across the entire step        | a context provider                           |
-| Subscribe to platform-specific events                | a channel adapter handler                    |
+| Need                                              | Use                                          |
+| ------------------------------------------------- | -------------------------------------------- |
+| Observe runtime events (audit, metrics, alerting) | `events.<type>` (or channel adapter handler) |
+| Provide structured input to the model on demand   | a tool                                       |
+| Make a value available across the entire step     | a context provider                           |
+| Subscribe to platform-specific events             | a channel adapter handler                    |
 
 Stream-event hooks and channel adapter event handlers are structurally
 identical — choose the channel adapter handler when you are authoring

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

@@ -149,8 +149,7 @@ Use:
 - `instructions.md` (or `instructions.ts`) for always-on identity and behavior
 - `skills/` for optional procedures the model should load on demand
 - `tools/` for typed business logic and API calls
-- `hooks/` for lifecycle (`lifecycle.session`, `lifecycle.turn`) and
-  stream-event subscribers
+- `hooks/` for stream-event subscribers
 - `connections/` for external services exposed via MCP (model discovers and calls their tools)
 - `sandbox/` for sandbox overrides and seeded workspace files
 - `channels/` for HTTP or messaging ingress and delivery

package/dist/src/compiler/manifest.d.ts

@@ -129,7 +129,7 @@ export interface CompiledDynamicInstructionsDefinition extends ModuleSourceRef {
 /**
  * Normalized authored hook entry preserved in the compiled manifest.
  *
- * Hook lifecycle handlers are arbitrary functions — there is no static
+ * Hook event handlers are arbitrary functions — there is no static
  * shape the compiler can validate beyond the source ref. Per-handler
  * resolution happens at runtime via {@link resolveHookDefinition}.
  */

package/dist/src/compiler/normalize-hook.d.ts

@@ -4,9 +4,9 @@ import type { CompiledHookDefinition } from "./manifest.js";
  * Compiles one authored hook module into the manifest entry stored on
  * the compiled agent node.
  *
- * Hook lifecycle handlers are arbitrary functions and cannot be
- * statically validated at compile time — the normalization step only
- * derives the path-relative slug used for diagnostics and ordering.
- * Per-handler validation lives in the runtime resolver.
+ * Hook event handlers are arbitrary functions and cannot be statically
+ * validated at compile time — the normalization step only derives the
+ * path-relative slug used for diagnostics and ordering. Per-handler
+ * validation lives in the runtime resolver.
  */
 export declare function compileHookEntry(source: ModuleSourceRef): CompiledHookDefinition;

package/dist/src/context/hook-lifecycle.d.ts

@@ -1,45 +1,6 @@
-import type { HarnessEmitFn, HarnessSession, StepInput, StepResult } from "#harness/types.js";
-import type { HandleMessageStreamEvent, RuntimeIdentity } from "#protocol/message.js";
-import type { RunMode } from "#shared/run-mode.js";
+import type { HandleMessageStreamEvent } from "#protocol/message.js";
 import type { RuntimeHookRegistry } from "#runtime/hooks/registry.js";
 import type { ContextContainer } from "./container.js";
-/**
- * Outcome of {@link dispatchHookLifecycle}. `proceed` carries the
- * input augmented with merged context. `turn-failed` means a
- * `lifecycle.turn` hook threw; the recoverable `turn.failed` cascade
- * has already been emitted.
- */
-export type HookLifecycleOutcome = {
-    readonly kind: "proceed";
-    readonly input: StepInput;
-    readonly nextSession: HarnessSession;
-} | {
-    readonly kind: "turn-failed";
-    readonly message: string;
-    readonly nextSession: HarnessSession;
-};
-export interface DispatchHookLifecycleInput {
-    readonly ctx: ContextContainer;
-    readonly registry: RuntimeHookRegistry;
-    readonly session: HarnessSession;
-    readonly input: StepInput;
-    readonly emit: HarnessEmitFn;
-    readonly mode: RunMode;
-    readonly runtimeIdentity?: RuntimeIdentity;
-}
-/**
- * Runs the per-turn hook lifecycle inside the active ALS scope.
- *
- * - `lifecycle.session` runs once per session, gated by
- *   {@link SessionPreparedKey}. The flag is set **before** the chain
- *   runs so a thrown hook does not retry. A throw re-propagates and
- *   the runtime escalates to terminal `session.failed`.
- * - `lifecycle.turn` runs once per fresh delivery. Each hook may
- *   return `{ context }`; context contributions are
- *   concatenated in registry order. A thrown hook emits the recoverable
- *   `turn.failed` cascade and returns `kind: "turn-failed"`.
- */
-export declare function dispatchHookLifecycle(input: DispatchHookLifecycleInput): Promise<HookLifecycleOutcome>;
 /**
  * Fans one runtime stream event out to every matching subscriber.
  * Errors propagate — harness error paths convert them into the
@@ -51,9 +12,3 @@ export declare function dispatchStreamEventHooks(input: {
     readonly registry: RuntimeHookRegistry;
     readonly event: HandleMessageStreamEvent;
 }): Promise<void>;
-/**
- * Runs the per-turn hook lifecycle, lowers a `turn-failed` outcome
- * into a parking {@link StepResult}, and otherwise hands off to
- * `body` with the (possibly augmented) input.
- */
-export declare function runHookLifecycleStep(input: DispatchHookLifecycleInput, body: (session: HarnessSession, input: StepInput) => Promise<StepResult>): Promise<StepResult>;

package/dist/src/context/hook-lifecycle.js

@@ -1 +1 @@
-import{ContinuationTokenKey,SessionPreparedKey}from"./keys.js";import{createLogger}from"#internal/logging.js";import{getAdapterKind}from"#channel/adapter.js";import{toErrorMessage}from"#shared/errors.js";import{buildCallbackContext}from"#context/build-callback-context.js";import{BundleKey,ChannelKey}from"#runtime/sessions/runtime-context-keys.js";import{emitRecoverableFailedTurn,emitTurnPreamble,getHarnessEmissionState,setHarnessEmissionState}from"#harness/emission.js";const log=createLogger(`hooks.lifecycle`);async function dispatchHookLifecycle(e){let{ctx:n,registry:r,emit:a}=e,o=getHarnessEmissionState(e.session.state),s=buildHookContext(n),u=e.session;if(r.session.length>0&&n.get(SessionPreparedKey)!==!0){n.set(SessionPreparedKey,!0);for(let e of r.session)await e.handler(s)}let d=!1,f=o;try{for(let e of r.turn)await e.handler(s)}catch(t){let n=toErrorMessage(t);try{return d||=(f=await emitTurnPreamble(a,{message:e.input.message},o,e.runtimeIdentity),!0),{kind:`turn-failed`,message:n,nextSession:setHarnessEmissionState(u,await emitRecoverableFailedTurn(a,f,{code:`HOOK_TURN_FAILED`,message:n}))}}catch(e){throw log.error(`Event hook threw while emitting the turn.failed cascade for a lifecycle.turn failure — escalating to session.failed.`,{error:toErrorMessage(e)}),e}}return{kind:`proceed`,input:e.input,nextSession:u}}async function dispatchStreamEventHooks(e){let t=e.registry.streamEventsByType.get(e.event.type)??[],n=e.registry.streamEventsWildcard;if(t.length===0&&n.length===0)return;let r=buildHookContext(e.ctx);for(let n of t)await n.handler(e.event,r);for(let t of n)await t.handler(e.event,r)}function buildHookContext(t){let n=t.require(BundleKey),i=t.get(ChannelKey),c=t.get(ContinuationTokenKey),l=i===void 0?void 0:getAdapterKind(i);return{...buildCallbackContext(),agent:{name:n.resolvedAgent.config.name??`agent`,nodeId:n.nodeId},channel:{kind:l,continuationToken:c}}}async function runHookLifecycleStep(e,t){let n=await dispatchHookLifecycle(e);return n.kind===`turn-failed`?{next:e.mode===`conversation`?null:{done:!0,output:n.message},session:n.nextSession}:t(n.nextSession,n.input)}export{dispatchHookLifecycle,dispatchStreamEventHooks,runHookLifecycleStep};
+import{ContinuationTokenKey}from"./keys.js";import{getAdapterKind}from"#channel/adapter.js";import{buildCallbackContext}from"#context/build-callback-context.js";import{BundleKey,ChannelKey}from"#runtime/sessions/runtime-context-keys.js";async function dispatchStreamEventHooks(e){let t=e.registry.streamEventsByType.get(e.event.type)??[],n=e.registry.streamEventsWildcard;if(t.length===0&&n.length===0)return;let r=buildHookContext(e.ctx);for(let n of t)await n.handler(e.event,r);for(let t of n)await t.handler(e.event,r)}function buildHookContext(i){let a=i.require(BundleKey),o=i.get(ChannelKey),s=i.get(ContinuationTokenKey),c=o===void 0?void 0:getAdapterKind(o);return{...buildCallbackContext(),agent:{name:a.resolvedAgent.config.name??`agent`,nodeId:a.nodeId},channel:{kind:c,continuationToken:s}}}export{dispatchStreamEventHooks};

package/dist/src/context/keys.d.ts

@@ -47,15 +47,6 @@ export declare const CapabilitiesKey: ContextKey<SessionCapabilities>;
  * Optional framework-owned terminal callback metadata for this session.
  */
 export declare const SessionCallbackKey: ContextKey<SessionCallback>;
-/**
- * Marker durable boolean set by the runtime **before** the
- * `lifecycle.session` hook chain runs. The runtime checks this flag at
- * the top of every turn so the chain never runs twice for the same
- * session — including when one of the hooks throws. A thrown hook is
- * a terminal session failure (`session.failed`); the next turn does
- * not retry. See `research/active/hooks.md`.
- */
-export declare const SessionPreparedKey: ContextKey<boolean>;
 export declare const SessionKey: ContextKey<Session>;
 export declare const SandboxKey: ContextKey<SandboxAccess>;
 export interface DurableDynamicToolMetadata {

package/dist/src/context/keys.js

@@ -1 +1 @@
-import{ContextKey}from"#context/key.js";const AuthKey=new ContextKey(`ash.auth`),InitiatorAuthKey=new ContextKey(`ash.initiatorAuth`),SessionIdKey=new ContextKey(`ash.sessionId`),ContinuationTokenKey=new ContextKey(`ash.continuationToken`),ChannelInstrumentationKey=new ContextKey(`ash.channelInstrumentation`),ModeKey=new ContextKey(`ash.mode`),ParentSessionKey=new ContextKey(`ash.parentSession`),CapabilitiesKey=new ContextKey(`ash.capabilities`),SessionCallbackKey=new ContextKey(`ash.sessionCallback`),SessionPreparedKey=new ContextKey(`ash.sessionPrepared`),SessionKey=new ContextKey(`ash.session`),SandboxKey=new ContextKey(`ash.sandbox`),SessionDynamicToolMetadataKey=new ContextKey(`ash.sessionDynamicToolMetadata`),TurnDynamicToolMetadataKey=new ContextKey(`ash.turnDynamicToolMetadata`),LiveStepToolsKey=new ContextKey(`ash.liveStepTools`),DynamicSkillManifestKey=new ContextKey(`ash.dynamicSkillManifest`),SessionDynamicInstructionsKey=new ContextKey(`ash.sessionDynamicInstructions`),TurnDynamicInstructionsKey=new ContextKey(`ash.turnDynamicInstructions`);export{AuthKey,CapabilitiesKey,ChannelInstrumentationKey,ContinuationTokenKey,DynamicSkillManifestKey,InitiatorAuthKey,LiveStepToolsKey,ModeKey,ParentSessionKey,SandboxKey,SessionCallbackKey,SessionDynamicInstructionsKey,SessionDynamicToolMetadataKey,SessionIdKey,SessionKey,SessionPreparedKey,TurnDynamicInstructionsKey,TurnDynamicToolMetadataKey};
+import{ContextKey}from"#context/key.js";const AuthKey=new ContextKey(`ash.auth`),InitiatorAuthKey=new ContextKey(`ash.initiatorAuth`),SessionIdKey=new ContextKey(`ash.sessionId`),ContinuationTokenKey=new ContextKey(`ash.continuationToken`),ChannelInstrumentationKey=new ContextKey(`ash.channelInstrumentation`),ModeKey=new ContextKey(`ash.mode`),ParentSessionKey=new ContextKey(`ash.parentSession`),CapabilitiesKey=new ContextKey(`ash.capabilities`),SessionCallbackKey=new ContextKey(`ash.sessionCallback`),SessionKey=new ContextKey(`ash.session`),SandboxKey=new ContextKey(`ash.sandbox`),SessionDynamicToolMetadataKey=new ContextKey(`ash.sessionDynamicToolMetadata`),TurnDynamicToolMetadataKey=new ContextKey(`ash.turnDynamicToolMetadata`),LiveStepToolsKey=new ContextKey(`ash.liveStepTools`),DynamicSkillManifestKey=new ContextKey(`ash.dynamicSkillManifest`),SessionDynamicInstructionsKey=new ContextKey(`ash.sessionDynamicInstructions`),TurnDynamicInstructionsKey=new ContextKey(`ash.turnDynamicInstructions`);export{AuthKey,CapabilitiesKey,ChannelInstrumentationKey,ContinuationTokenKey,DynamicSkillManifestKey,InitiatorAuthKey,LiveStepToolsKey,ModeKey,ParentSessionKey,SandboxKey,SessionCallbackKey,SessionDynamicInstructionsKey,SessionDynamicToolMetadataKey,SessionIdKey,SessionKey,TurnDynamicInstructionsKey,TurnDynamicToolMetadataKey};

package/dist/src/execution/create-session-step.d.ts

@@ -1,5 +1,5 @@
 import type { RuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";
-import { type DurableSessionSnapshot, type DurableSessionState } from "#execution/durable-session-store.js";
+import { type DurableSessionState } from "#execution/durable-session-store.js";
 import type { JsonObject } from "#shared/json.js";
 /**
  * Result returned by {@link createSessionStep}.
@@ -11,8 +11,8 @@ export interface CreateSessionStepResult {
     readonly state: DurableSessionState;
 }
 /**
- * Creates the durable session and writes the initial snapshot to the
- * `ash.session` stream before the workflow enters its turn loop.
+ * Creates the durable session and returns the initial snapshot-bearing
+ * state before the workflow enters its turn loop.
  * `nodeId` targets a subagent node in the compiled graph; omitted for
  * the root agent.
  *
@@ -40,5 +40,4 @@ export declare function createSessionStep(input: {
      */
     readonly serializedContext: Record<string, unknown>;
     readonly sessionId: string;
-    readonly sessionWritable: WritableStream<DurableSessionSnapshot>;
 }): Promise<CreateSessionStepResult>;

package/dist/src/execution/create-session-step.js

@@ -1 +1 @@
-import{ROOT_RUNTIME_AGENT_NODE_ID}from"#runtime/graph.js";import{getCompiledRuntimeAgentBundle}from"#runtime/sessions/compiled-agent-cache.js";import{writeDurableSession}from"#execution/durable-session-store.js";import{createSession}from"#execution/session.js";import{buildSessionAttributes,buildSubagentRootAttributes,readParentSessionId}from"#execution/ash-workflow-attributes.js";import{setAshAttributes}from"#runtime/attributes/emit.js";async function createSessionStep(e){"use step";let t=await getCompiledRuntimeAgentBundle({compiledArtifactsSource:e.compiledArtifactsSource,nodeId:e.nodeId}),n=await writeDurableSession({session:createSession({compactionOverrides:{thresholdPercent:t.resolvedAgent.config.compaction?.thresholdPercent},continuationToken:e.continuationToken,outputSchema:e.outputSchema,rootSessionId:e.rootSessionId,sessionId:e.sessionId,turnAgent:t.turnAgent}),writable:e.sessionWritable}),r={nodeId:t.nodeId??ROOT_RUNTIME_AGENT_NODE_ID},i=readParentSessionId(e.serializedContext);return i===void 0?await setAshAttributes(buildSessionAttributes({inputMessage:e.inputMessage,serializedContext:e.serializedContext})):await setAshAttributes(buildSubagentRootAttributes({identity:r,parentSessionId:i,rootSessionId:e.rootSessionId??i,serializedContext:e.serializedContext})),{state:n}}export{createSessionStep};
+import{ROOT_RUNTIME_AGENT_NODE_ID}from"#runtime/graph.js";import{getCompiledRuntimeAgentBundle}from"#runtime/sessions/compiled-agent-cache.js";import{createDurableSessionState}from"#execution/durable-session-store.js";import{createSession}from"#execution/session.js";import{buildSessionAttributes,buildSubagentRootAttributes,readParentSessionId}from"#execution/ash-workflow-attributes.js";import{setAshAttributes}from"#runtime/attributes/emit.js";async function createSessionStep(e){"use step";let t=await getCompiledRuntimeAgentBundle({compiledArtifactsSource:e.compiledArtifactsSource,nodeId:e.nodeId}),n=createDurableSessionState({session:createSession({compactionOverrides:{thresholdPercent:t.resolvedAgent.config.compaction?.thresholdPercent},continuationToken:e.continuationToken,outputSchema:e.outputSchema,rootSessionId:e.rootSessionId,sessionId:e.sessionId,turnAgent:t.turnAgent})}),r={nodeId:t.nodeId??ROOT_RUNTIME_AGENT_NODE_ID},i=readParentSessionId(e.serializedContext);return i===void 0?await setAshAttributes(buildSessionAttributes({inputMessage:e.inputMessage,serializedContext:e.serializedContext})):await setAshAttributes(buildSubagentRootAttributes({identity:r,parentSessionId:i,rootSessionId:e.rootSessionId??i,serializedContext:e.serializedContext})),{state:n}}export{createSessionStep};

package/dist/src/execution/dispatch-runtime-actions-step.d.ts

@@ -4,16 +4,15 @@
  * Each child run starts in task mode, emits a parent `subagent.called`
  * control-plane event, and then runs independently on its own child
  * stream. Records each child's continuation token on the parent
- * session and appends the updated snapshot to `ash.session`.
+ * session and returns the updated snapshot-bearing state.
  */
 import type { RuntimeSubagentResultActionResult } from "#runtime/actions/types.js";
-import { type DurableSessionSnapshot, type DurableSessionState } from "#execution/durable-session-store.js";
+import { type DurableSessionState } from "#execution/durable-session-store.js";
 export declare function dispatchRuntimeActionsStep(input: {
     readonly callbackBaseUrl?: string;
     readonly parentWritable: WritableStream<Uint8Array>;
     readonly serializedContext: Record<string, unknown>;
     readonly sessionState: DurableSessionState;
-    readonly sessionWritable: WritableStream<DurableSessionSnapshot>;
 }): Promise<{
     readonly results: readonly RuntimeSubagentResultActionResult[];
     readonly sessionState: DurableSessionState;

package/dist/src/execution/dispatch-runtime-actions-step.js

@@ -1 +1 @@
-import{createLogger,logError}from"#internal/logging.js";import{callAdapterEventHandler}from"#channel/adapter.js";import{AuthKey,CapabilitiesKey,InitiatorAuthKey}from"#context/keys.js";import{createSubagentCalledEvent,encodeMessageStreamEvent,timestampHandleMessageStreamEvent}from"#protocol/message.js";import{toErrorMessage}from"#shared/errors.js";import{BundleKey,ChannelKey}from"#runtime/sessions/runtime-context-keys.js";import{readDurableSession,writeDurableSession}from"#execution/durable-session-store.js";import{hydrateDurableSession}from"#execution/session.js";import{deserializeContext}from"#context/serialize.js";import{buildAdapterContext}from"#channel/adapter-context.js";import{getPendingRuntimeActionBatch,recordPendingSubagentChildToken}from"#harness/runtime-actions.js";import{resolveRemoteAgentForAction,startRemoteAgentSession}from"#execution/remote-agent-dispatch.js";import{buildSubagentRunInput}from"#execution/subagent-tool.js";import{createWorkflowRuntime,workflowEntryReference}from"#execution/workflow-runtime.js";const log=createLogger(`execution.dispatch-runtime-actions`);async function dispatchRuntimeActionsStep(e){"use step";let s=await readDurableSession(e.sessionState),u=getPendingRuntimeActionBatch(s.state);if(u===void 0||u.actions.length===0)return{results:[],sessionState:e.sessionState};let d=await deserializeContext(e.serializedContext),f=d.require(BundleKey),p=hydrateDurableSession({compactionOverrides:{thresholdPercent:f.resolvedAgent.config.compaction?.thresholdPercent},durable:s,turnAgent:f.turnAgent}),m=d.require(ChannelKey),h=d.get(AuthKey)??null,g=d.get(CapabilitiesKey),_=d.get(InitiatorAuthKey)??null,v=e.parentWritable.getWriter(),y=buildAdapterContext(m,d),b=p,x=[];try{for(let r of u.actions){let i,a,s,c;switch(r.kind){case`subagent-call`:{let e=createWorkflowRuntime({compiledArtifactsSource:f.compiledArtifactsSource,nodeId:r.nodeId}),{childContinuationToken:t,runInput:n}=buildSubagentRunInput({action:r,auth:h,batchEvent:u.event,capabilities:g,initiatorAuth:_,session:p}),o=await e.run(n);b=recordPendingSubagentChildToken({callId:r.callId,childContinuationToken:t,session:b}),i=o.sessionId,a=r.name,c=r.subagentName;break}case`remote-agent-call`:{let n;try{n=resolveRemoteAgentForAction({nodeId:r.nodeId,remoteAgentName:r.remoteAgentName,registry:f.subagentRegistry.subagentsByNodeId}),i=await startRemoteAgentSession({action:r,callbackBaseUrl:e.callbackBaseUrl,remote:n,session:p})}catch(e){logError(log,`remote agent start failed`,e,{remoteAgentName:r.remoteAgentName,nodeId:r.nodeId,callId:r.callId}),x.push(createRemoteAgentStartFailureResult({action:r,error:e}));continue}a=r.name,s={url:n.url},c=r.remoteAgentName;break}default:throw Error(`Unsupported runtime action kind "${r.kind}" in workflow runtime.`)}let l=await callAdapterEventHandler(m,createSubagentCalledEvent({callId:r.callId,childSessionId:i,name:a,remote:s,sequence:u.event.sequence,sessionId:p.sessionId,toolName:c,turnId:u.event.turnId,workflowId:workflowEntryReference.workflowId}),y);await v.write(encodeMessageStreamEvent(timestampHandleMessageStreamEvent(l)))}}finally{v.releaseLock()}return{results:x,sessionState:b===p?e.sessionState:await writeDurableSession({session:b,writable:e.sessionWritable})}}function createRemoteAgentStartFailureResult(e){return{callId:e.action.callId,isError:!0,kind:`subagent-result`,output:{code:`REMOTE_AGENT_START_FAILED`,message:toErrorMessage(e.error)},subagentName:e.action.remoteAgentName}}export{dispatchRuntimeActionsStep};
+import{createLogger,logError}from"#internal/logging.js";import{callAdapterEventHandler}from"#channel/adapter.js";import{AuthKey,CapabilitiesKey,InitiatorAuthKey}from"#context/keys.js";import{createSubagentCalledEvent,encodeMessageStreamEvent,timestampHandleMessageStreamEvent}from"#protocol/message.js";import{toErrorMessage}from"#shared/errors.js";import{BundleKey,ChannelKey}from"#runtime/sessions/runtime-context-keys.js";import{createDurableSessionState,readDurableSession}from"#execution/durable-session-store.js";import{hydrateDurableSession}from"#execution/session.js";import{deserializeContext}from"#context/serialize.js";import{buildAdapterContext}from"#channel/adapter-context.js";import{getPendingRuntimeActionBatch,recordPendingSubagentChildToken}from"#harness/runtime-actions.js";import{resolveRemoteAgentForAction,startRemoteAgentSession}from"#execution/remote-agent-dispatch.js";import{buildSubagentRunInput}from"#execution/subagent-tool.js";import{createWorkflowRuntime,workflowEntryReference}from"#execution/workflow-runtime.js";const log=createLogger(`execution.dispatch-runtime-actions`);async function dispatchRuntimeActionsStep(e){"use step";let s=await readDurableSession(e.sessionState),u=getPendingRuntimeActionBatch(s.state);if(u===void 0||u.actions.length===0)return{results:[],sessionState:e.sessionState};let d=await deserializeContext(e.serializedContext),f=d.require(BundleKey),p=hydrateDurableSession({compactionOverrides:{thresholdPercent:f.resolvedAgent.config.compaction?.thresholdPercent},durable:s,turnAgent:f.turnAgent}),m=d.require(ChannelKey),h=d.get(AuthKey)??null,g=d.get(CapabilitiesKey),_=d.get(InitiatorAuthKey)??null,v=e.parentWritable.getWriter(),y=buildAdapterContext(m,d),b=p,x=[];try{for(let r of u.actions){let i,a,s,c;switch(r.kind){case`subagent-call`:{let e=createWorkflowRuntime({compiledArtifactsSource:f.compiledArtifactsSource,nodeId:r.nodeId}),{childContinuationToken:t,runInput:n}=buildSubagentRunInput({action:r,auth:h,batchEvent:u.event,capabilities:g,initiatorAuth:_,session:p}),o=await e.run(n);b=recordPendingSubagentChildToken({callId:r.callId,childContinuationToken:t,session:b}),i=o.sessionId,a=r.name,c=r.subagentName;break}case`remote-agent-call`:{let n;try{n=resolveRemoteAgentForAction({nodeId:r.nodeId,remoteAgentName:r.remoteAgentName,registry:f.subagentRegistry.subagentsByNodeId}),i=await startRemoteAgentSession({action:r,callbackBaseUrl:e.callbackBaseUrl,remote:n,session:p})}catch(e){logError(log,`remote agent start failed`,e,{remoteAgentName:r.remoteAgentName,nodeId:r.nodeId,callId:r.callId}),x.push(createRemoteAgentStartFailureResult({action:r,error:e}));continue}a=r.name,s={url:n.url},c=r.remoteAgentName;break}default:throw Error(`Unsupported runtime action kind "${r.kind}" in workflow runtime.`)}let l=await callAdapterEventHandler(m,createSubagentCalledEvent({callId:r.callId,childSessionId:i,name:a,remote:s,sequence:u.event.sequence,sessionId:p.sessionId,toolName:c,turnId:u.event.turnId,workflowId:workflowEntryReference.workflowId}),y);await v.write(encodeMessageStreamEvent(timestampHandleMessageStreamEvent(l)))}}finally{v.releaseLock()}return{results:x,sessionState:b===p?e.sessionState:createDurableSessionState({session:b})}}function createRemoteAgentStartFailureResult(e){return{callId:e.action.callId,isError:!0,kind:`subagent-result`,output:{code:`REMOTE_AGENT_START_FAILED`,message:toErrorMessage(e.error)},subagentName:e.action.remoteAgentName}}export{dispatchRuntimeActionsStep};