experimental-ash 0.25.2 → 0.27.0

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

@@ -1,242 +1 @@
-import { getAdapterKind } from "../channel/adapter.js";
-import { emitRecoverableFailedTurn, emitTurnPreamble, getHarnessEmissionState, setHarnessEmissionState, } from "../harness/emission.js";
-import { createLogger } from "../internal/logging.js";
-import { toErrorMessage } from "../shared/errors.js";
-import { normalizeSkillPackage, writeSkillPackageToSandbox, } from "../shared/skill-package.js";
-import { formatAvailableSkillsSection } from "#execution/skills/instructions.js";
-import { BundleKey, ChannelKey, ContinuationTokenKey, SandboxKey, SessionIdKey, SessionPreparedKey, } from "./keys.js";
-const log = createLogger("hooks.lifecycle");
-/**
- * Runs the per-turn hook lifecycle inside the active ALS scope and
- * returns the outcome.
- *
- * Stages:
- *
- *  1. `lifecycle.session` — runs once per durable session, gated by the
- *     framework-owned {@link SessionPreparedKey} flag. The dispatcher
- *     sets the flag **before** running the chain so a thrown hook does
- *     not retry on the next turn — `lifecycle.session` errors
- *     propagate through this function and are interpreted by the
- *     runtime as a terminal session failure (`session.failed`).
- *
- *  2. `lifecycle.turn` — runs once per fresh delivery (the caller
- *     gates dispatch with `isHarnessBetweenTurns(session)`). Each
- *     hook may return `{ modelContext, skills }`; model-context
- *     contributions are concatenated in registry order and skills are
- *     materialized into the live sandbox before the model call. A
- *     thrown hook is caught here, the recoverable `turn.failed`
- *     cascade is emitted, and the dispatcher returns
- *     `kind: "turn-failed"` so the caller can park the session.
- *
- *  Errors:
- *
- *  - `lifecycle.session` throws → re-thrown. Runtime escalates to
- *    `session.failed`.
- *  - `lifecycle.turn` throws → caught, recoverable `turn.failed`
- *    emitted, outcome `kind: "turn-failed"`. Session keeps living.
- *
- *  Stream-event hook errors are not handled here — they propagate
- *  through {@link dispatchStreamEventHooks} and are caught wherever the
- *  emit composer sits inside the harness.
- */
-export async function dispatchHookLifecycle(input) {
-    const { ctx, registry, emit } = input;
-    const emissionState = getHarnessEmissionState(input.session);
-    const turnId = `turn_${emissionState.sequence}`;
-    const sequence = emissionState.sequence;
-    const hookCtx = buildHookContext(ctx);
-    const lifecycleInput = {
-        session: { sessionId: input.session.sessionId },
-        turn: { sequence, turnId },
-    };
-    const modelContext = [];
-    let nextSession = input.session;
-    // ---------- lifecycle.session ----------
-    if (registry.session.length > 0 && ctx.get(SessionPreparedKey) !== true) {
-        // Set the flag BEFORE running the chain. A thrown session hook is
-        // a terminal session failure; the next turn must not retry.
-        ctx.set(SessionPreparedKey, true);
-        const stageSkills = [];
-        for (const entry of registry.session) {
-            const result = (await entry.handler(lifecycleInput, hookCtx));
-            if (result?.modelContext !== undefined && result.modelContext.length > 0) {
-                modelContext.push(...result.modelContext);
-            }
-            stageSkills.push(...normalizeLifecycleSkillResults(ctx, result));
-        }
-        nextSession = await materializeLifecycleSkills(ctx, nextSession, stageSkills);
-    }
-    // ---------- lifecycle.turn ----------
-    let preambleEmitted = false;
-    let preambleState = emissionState;
-    try {
-        const stageSkills = [];
-        for (const entry of registry.turn) {
-            const result = (await entry.handler(lifecycleInput, hookCtx));
-            if (result?.modelContext !== undefined && result.modelContext.length > 0) {
-                modelContext.push(...result.modelContext);
-            }
-            stageSkills.push(...normalizeLifecycleSkillResults(ctx, result));
-        }
-        nextSession = await materializeLifecycleSkills(ctx, nextSession, stageSkills);
-    }
-    catch (error) {
-        const message = toErrorMessage(error);
-        try {
-            if (!preambleEmitted) {
-                preambleState = await emitTurnPreamble(emit, { message: input.input.message }, emissionState, input.runtimeIdentity);
-                preambleEmitted = true;
-            }
-            const failedState = await emitRecoverableFailedTurn(emit, preambleState, {
-                code: "HOOK_TURN_FAILED",
-                message,
-            });
-            return {
-                kind: "turn-failed",
-                message,
-                nextSession: setHarnessEmissionState(nextSession, failedState),
-            };
-        }
-        catch (cascadeError) {
-            // An event hook subscribed to one of the failure-cascade events
-            // (eg. `events["turn.failed"]`) threw while we were emitting the
-            // recoverable failure. Re-throwing escalates to a terminal
-            // `session.failed` via the runtime's outer error path. Document
-            // this as the bounded second-order behavior: when both a
-            // `lifecycle.turn` and a `turn.failed` event hook throw, the
-            // session ends.
-            log.error("Event hook threw while emitting the turn.failed cascade for a lifecycle.turn failure — escalating to session.failed.", { error: toErrorMessage(cascadeError) });
-            throw cascadeError;
-        }
-    }
-    const channelContext = input.input.modelContext ?? [];
-    const mergedModelContext = channelContext.length === 0 ? modelContext : [...channelContext, ...modelContext];
-    return {
-        kind: "proceed",
-        input: mergedModelContext.length > 0
-            ? { ...input.input, modelContext: mergedModelContext }
-            : input.input,
-        nextSession,
-    };
-}
-function normalizeLifecycleSkillResults(ctx, result) {
-    if (result?.skills === undefined || result.skills.length === 0) {
-        return [];
-    }
-    const authoredSkillNames = new Set(ctx.require(BundleKey).resolvedAgent.skills.map((skill) => skill.name));
-    const dynamicSkills = new Map();
-    for (const skill of result.skills) {
-        const normalized = normalizeSkillPackage(skill);
-        if (authoredSkillNames.has(normalized.name)) {
-            throw new Error(`Hook-contributed skill "${normalized.name}" conflicts with an authored skill.`);
-        }
-        dynamicSkills.set(normalized.name, normalized);
-    }
-    return [...dynamicSkills.values()];
-}
-async function materializeLifecycleSkills(ctx, session, skills) {
-    if (skills.length === 0) {
-        return session;
-    }
-    const dedupedSkills = new Map(skills.map((skill) => [skill.name, skill]));
-    const sandbox = await ctx.require(SandboxKey).get();
-    if (sandbox === null) {
-        throw new Error("Dynamic skills require a sandbox for the current agent.");
-    }
-    for (const skill of dedupedSkills.values()) {
-        await writeSkillPackageToSandbox({ sandbox, skill });
-    }
-    const announcement = formatAvailableSkillsSection([...dedupedSkills.values()]);
-    if (announcement === null) {
-        return session;
-    }
-    return {
-        ...session,
-        history: [
-            ...session.history,
-            {
-                role: "system",
-                content: announcement,
-            },
-        ],
-    };
-}
-/**
- * Fans one runtime stream event out to every matching subscriber on the
- * registry.
- *
- * Errors propagate out of this function. The harness's emit composer
- * is the natural caller; existing harness error paths catch propagated
- * exceptions and emit the recoverable `turn.failed` cascade. If a
- * hook subscribed to a failure-cascade event itself throws, the
- * outer runtime escalates to `session.failed`.
- *
- * Caller is responsible for running this inside an active ALS scope so
- * hook code can read the same context the rest of the step sees.
- */
-export async function dispatchStreamEventHooks(input) {
-    const typed = input.registry.streamEventsByType.get(input.event.type) ?? [];
-    const wildcard = input.registry.streamEventsWildcard;
-    if (typed.length === 0 && wildcard.length === 0) {
-        return;
-    }
-    const hookCtx = buildHookContext(input.ctx);
-    for (const entry of typed) {
-        await entry.handler(input.event, hookCtx);
-    }
-    for (const entry of wildcard) {
-        await entry.handler(input.event, hookCtx);
-    }
-}
-/**
- * Builds the read-only {@link HookContext} surfaced to one hook handler.
- *
- * The context is a thin view over the active ALS-bound
- * {@link ContextContainer}. Durable reads/writes go through `ctx.ash`,
- * so hooks reuse the single state channel tools, providers, and channels
- * already use.
- *
- * Optional fields stay `undefined` rather than substituting sentinel
- * strings — authors who care about the channel kind or continuation
- * token check for absence explicitly.
- */
-function buildHookContext(ctx) {
-    const bundle = ctx.require(BundleKey);
-    const channelAdapter = ctx.get(ChannelKey);
-    const continuationToken = ctx.get(ContinuationTokenKey);
-    const kind = channelAdapter !== undefined ? getAdapterKind(channelAdapter) : undefined;
-    return {
-        agent: {
-            name: bundle.resolvedAgent.config.name ?? "agent",
-            nodeId: bundle.nodeId,
-        },
-        channel: {
-            kind,
-            continuationToken,
-        },
-        session: { sessionId: ctx.get(SessionIdKey) ?? "" },
-        ash: ctx,
-    };
-}
-/**
- * Runtime adapter on top of {@link dispatchHookLifecycle}: 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.
- *
- * The `Step` suffix signals the return type — both runtime entry points
- * call this from inside their `runStep` callback so the
- * recoverable-failure-to-`StepResult` mapping lives in one place.
- *
- * Caller must already be inside the active ALS scope.
- */
-export async function runHookLifecycleStep(input, body) {
-    const outcome = await dispatchHookLifecycle(input);
-    if (outcome.kind === "turn-failed") {
-        return {
-            next: input.mode === "conversation" ? null : { done: true, output: outcome.message },
-            session: outcome.nextSession,
-        };
-    }
-    return body(outcome.nextSession, outcome.input);
-}
+import{getAdapterKind}from"../channel/adapter.js";import{emitRecoverableFailedTurn,emitTurnPreamble,getHarnessEmissionState,setHarnessEmissionState}from"../harness/emission.js";import{createLogger}from"../internal/logging.js";import{toErrorMessage}from"../shared/errors.js";import{normalizeSkillPackage,writeSkillPackageToSandbox}from"../shared/skill-package.js";import{BundleKey,ChannelKey,ContinuationTokenKey,SandboxKey,SessionIdKey,SessionPreparedKey}from"./keys.js";import{formatAvailableSkillsSection}from"#execution/skills/instructions.js";var log=createLogger(`hooks.lifecycle`);async function dispatchHookLifecycle(e){let{ctx:a,registry:o,emit:s}=e,c=getHarnessEmissionState(e.session),l=`turn_${c.sequence}`,u=c.sequence,d=buildHookContext(a),f={session:{sessionId:e.session.sessionId},turn:{sequence:u,turnId:l}},p=[],m=e.session;if(o.session.length>0&&a.get(SessionPreparedKey)!==!0){a.set(SessionPreparedKey,!0);let e=[];for(let t of o.session){let n=await t.handler(f,d);n?.modelContext!==void 0&&n.modelContext.length>0&&p.push(...n.modelContext),e.push(...normalizeLifecycleSkillResults(a,n))}m=await materializeLifecycleSkills(a,m,e)}let h=!1,g=c;try{let e=[];for(let t of o.turn){let n=await t.handler(f,d);n?.modelContext!==void 0&&n.modelContext.length>0&&p.push(...n.modelContext),e.push(...normalizeLifecycleSkillResults(a,n))}m=await materializeLifecycleSkills(a,m,e)}catch(r){let a=toErrorMessage(r);try{h||=(g=await emitTurnPreamble(s,{message:e.input.message},c,e.runtimeIdentity),!0);let r=await emitRecoverableFailedTurn(s,g,{code:`HOOK_TURN_FAILED`,message:a});return{kind:`turn-failed`,message:a,nextSession:setHarnessEmissionState(m,r)}}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}}let _=e.input.modelContext??[],v=_.length===0?p:[..._,...p];return{kind:`proceed`,input:v.length>0?{...e.input,modelContext:v}:e.input,nextSession:m}}function normalizeLifecycleSkillResults(e,t){if(t?.skills===void 0||t.skills.length===0)return[];let n=new Set(e.require(BundleKey).resolvedAgent.skills.map(e=>e.name)),r=new Map;for(let e of t.skills){let t=normalizeSkillPackage(e);if(n.has(t.name))throw Error(`Hook-contributed skill "${t.name}" conflicts with an authored skill.`);r.set(t.name,t)}return[...r.values()]}async function materializeLifecycleSkills(e,t,n){if(n.length===0)return t;let r=new Map(n.map(e=>[e.name,e])),i=await e.require(SandboxKey).get();if(i===null)throw Error(`Dynamic skills require a sandbox for the current agent.`);for(let e of r.values())await writeSkillPackageToSandbox({sandbox:i,skill:e});let a=formatAvailableSkillsSection([...r.values()]);return a===null?t:{...t,history:[...t.history,{role:`system`,content:a}]}}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),r=t.get(ChannelKey),i=t.get(ContinuationTokenKey),a=r===void 0?void 0:getAdapterKind(r);return{agent:{name:n.resolvedAgent.config.name??`agent`,nodeId:n.nodeId},channel:{kind:a,continuationToken:i},session:{sessionId:t.get(SessionIdKey)??``},ash:t}}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};

package/dist/src/context/key.js

@@ -1,39 +1 @@
-/**
- * Process-wide registry mapping key names to instances. Populated automatically
- * by the {@link ContextKey} constructor so `deserializeContext` can resolve
- * string names back to typed keys without an explicit list.
- *
- * Rooted on `globalThis` so Nitro-inlined Ash and disk-imported Ash share one
- * registry. Each Nitro workflow chunk can carry its own evaluated copy of
- * `key.ts`; without a shared registry, a key registered by one chunk is
- * invisible to `resolveKey()` in another, and `serializeContext` /
- * `deserializeContext` silently drop entries at step boundaries.
- *
- * See `context/container.ts` (`ASH_CONTEXT_STORAGE_KEY`) and
- * `runtime/sessions/runtime-session.ts` (`RUNTIME_SESSION_STORAGE_GLOBAL_KEY`)
- * for the established pattern.
- */
-const KEY_REGISTRY_GLOBAL_KEY = Symbol.for("experimental-ash.context-key-registry");
-const globalKeyRegistryContainer = globalThis;
-if (globalKeyRegistryContainer[KEY_REGISTRY_GLOBAL_KEY] === undefined) {
-    globalKeyRegistryContainer[KEY_REGISTRY_GLOBAL_KEY] = new Map();
-}
-const keyRegistry = globalKeyRegistryContainer[KEY_REGISTRY_GLOBAL_KEY];
-/**
- * Typed key that identifies a named context slot.
- */
-export class ContextKey {
-    name;
-    codec;
-    constructor(name, options = {}) {
-        this.name = name;
-        this.codec = options.codec;
-        keyRegistry.set(name, this);
-    }
-}
-/**
- * Looks up a registered key by name. Returns `undefined` for unknown names.
- */
-export function resolveKey(name) {
-    return keyRegistry.get(name);
-}
+var KEY_REGISTRY_GLOBAL_KEY=Symbol.for(`experimental-ash.context-key-registry`),globalKeyRegistryContainer=globalThis;globalKeyRegistryContainer[KEY_REGISTRY_GLOBAL_KEY]===void 0&&(globalKeyRegistryContainer[KEY_REGISTRY_GLOBAL_KEY]=new Map);var keyRegistry=globalKeyRegistryContainer[KEY_REGISTRY_GLOBAL_KEY],ContextKey=class{name;codec;constructor(e,t={}){this.name=e,this.codec=t.codec,keyRegistry.set(e,this)}};function resolveKey(e){return keyRegistry.get(e)}export{ContextKey,resolveKey};

package/dist/src/context/keys.js

@@ -1,43 +1 @@
-import { getAdapterKind } from "#channel/adapter.js";
-import { deserializeRuntimeAdapter } from "#runtime/channels/registry.js";
-import { getCompiledRuntimeAgentBundle } from "#runtime/sessions/compiled-agent-cache.js";
-import { ContextKey } from "#context/key.js";
-// Re-export seed keys so existing consumers of `context/keys` keep working.
-export { AuthKey, CapabilitiesKey, ContinuationTokenKey, InitiatorAuthKey, ModeKey, ParentSessionKey, SessionCallbackKey, SessionIdKey, SessionPreparedKey, } from "#context/seed-keys.js";
-export const ChannelKey = new ContextKey("ash.channel", {
-    codec: {
-        serialize(adapter) {
-            return {
-                kind: getAdapterKind(adapter),
-                state: adapter.state ? { ...adapter.state } : {},
-            };
-        },
-        deserialize(data, ctx) {
-            const bundle = ctx.get(BundleKey);
-            if (bundle === undefined) {
-                throw new Error('Cannot deserialize "ash.channel" before "ash.bundle". The runtime bundle must be present in context.');
-            }
-            return deserializeRuntimeAdapter(bundle.adapterRegistry, data);
-        },
-    },
-});
-export const BundleKey = new ContextKey("ash.bundle", {
-    codec: {
-        serialize: (bundle) => ({
-            nodeId: bundle.nodeId,
-            source: bundle.compiledArtifactsSource,
-        }),
-        deserialize: (data) => {
-            const { source, nodeId } = data;
-            return getCompiledRuntimeAgentBundle({
-                compiledArtifactsSource: source,
-                nodeId,
-            });
-        },
-    },
-});
-// ---------------------------------------------------------------------------
-// Derived keys — reconstructed by providers each step, never serialized
-// ---------------------------------------------------------------------------
-export const SessionKey = new ContextKey("ash.session");
-export const SandboxKey = new ContextKey("ash.sandbox");
+import{AuthKey,CapabilitiesKey,ContinuationTokenKey,InitiatorAuthKey,ModeKey,ParentSessionKey,SessionCallbackKey,SessionIdKey,SessionPreparedKey}from"#context/seed-keys.js";import{ContextKey}from"#context/key.js";import{getAdapterKind}from"#channel/adapter.js";import{deserializeRuntimeAdapter}from"#runtime/channels/registry.js";import{getCompiledRuntimeAgentBundle}from"#runtime/sessions/compiled-agent-cache.js";var ChannelKey=new ContextKey(`ash.channel`,{codec:{serialize(e){return{kind:getAdapterKind(e),state:e.state?{...e.state}:{}}},deserialize(e,t){let n=t.get(BundleKey);if(n===void 0)throw Error(`Cannot deserialize "ash.channel" before "ash.bundle". The runtime bundle must be present in context.`);return deserializeRuntimeAdapter(n.adapterRegistry,e)}}}),BundleKey=new ContextKey(`ash.bundle`,{codec:{serialize:e=>({nodeId:e.nodeId,source:e.compiledArtifactsSource}),deserialize:e=>{let{source:t,nodeId:n}=e;return getCompiledRuntimeAgentBundle({compiledArtifactsSource:t,nodeId:n})}}}),SessionKey=new ContextKey(`ash.session`),SandboxKey=new ContextKey(`ash.sandbox`);export{AuthKey,BundleKey,CapabilitiesKey,ChannelKey,ContinuationTokenKey,InitiatorAuthKey,ModeKey,ParentSessionKey,SandboxKey,SessionCallbackKey,SessionIdKey,SessionKey,SessionPreparedKey};

package/dist/src/context/node.js

@@ -1,9 +1 @@
-import { BundleKey } from "#context/keys.js";
-/**
- * Returns the active runtime node from the compiled bundle on the
- * context. The bundle is already resolved to the correct node (root or
- * subagent) at run start.
- */
-export function getActiveRuntimeNode(ctx) {
-    return ctx.require(BundleKey).graph.root;
-}
+import{BundleKey}from"#context/keys.js";function getActiveRuntimeNode(e){return e.require(BundleKey).graph.root}export{getActiveRuntimeNode};

package/dist/src/context/provider.js

@@ -1 +1 @@
-export {};
+export{};

package/dist/src/context/providers/connection.js

@@ -1,17 +1 @@
-import { ConnectionRegistryImpl } from "#runtime/connections/registry.js";
-import { ConnectionRegistryKey } from "#runtime/framework-tools/connection-search.js";
-import { BundleKey } from "#context/keys.js";
-import { getActiveRuntimeNode } from "#context/node.js";
-export const connectionProvider = {
-    key: ConnectionRegistryKey,
-    create(ctx, _session) {
-        const bundle = ctx.get(BundleKey);
-        if (bundle === undefined)
-            return undefined;
-        const node = getActiveRuntimeNode(ctx);
-        const connections = node.agent?.connections;
-        if (!connections || connections.length === 0)
-            return undefined;
-        return { value: new ConnectionRegistryImpl(connections) };
-    },
-};
+import{BundleKey}from"#context/keys.js";import{ConnectionRegistryImpl}from"#runtime/connections/registry.js";import{ConnectionRegistryKey}from"#runtime/framework-tools/connection-search.js";import{getActiveRuntimeNode}from"#context/node.js";var connectionProvider={key:ConnectionRegistryKey,create(e,t){if(e.get(BundleKey)===void 0)return;let n=getActiveRuntimeNode(e).agent?.connections;if(!(!n||n.length===0))return{value:new ConnectionRegistryImpl(n)}}};export{connectionProvider};

package/dist/src/context/providers/sandbox.js

@@ -1,46 +1 @@
-import { ensureSandboxAccess } from "#execution/sandbox/ensure.js";
-import { getAdapterKind } from "#channel/adapter.js";
-import { contextStorage } from "#context/container.js";
-import { BundleKey, ChannelKey, SandboxKey, SessionIdKey, } from "#context/keys.js";
-import { getActiveRuntimeNode } from "#context/node.js";
-export const sandboxProvider = {
-    key: SandboxKey,
-    async create(ctx, session) {
-        const bundle = ctx.get(BundleKey);
-        if (bundle === undefined)
-            return undefined;
-        const node = getActiveRuntimeNode(ctx);
-        const registry = node.sandboxRegistry;
-        const sessionId = ctx.require(SessionIdKey);
-        return {
-            value: await ensureSandboxAccess({
-                compiledArtifactsSource: bundle.compiledArtifactsSource,
-                nodeId: node.nodeId,
-                registry,
-                runOnSession: async (callback) => await contextStorage.run(ctx, callback),
-                sessionId,
-                state: session.sandboxState ?? null,
-                tags: {
-                    agent: resolveTagAgentName({ bundle, node }),
-                    channel: resolveTagChannelKind(ctx.get(ChannelKey)),
-                    sessionId,
-                },
-            }),
-        };
-    },
-    async commit(access, session) {
-        const state = await access.captureState();
-        return { ...session, sandboxState: state };
-    },
-};
-function resolveTagAgentName(input) {
-    const partialNode = input.node;
-    const partialBundle = input.bundle;
-    return (partialNode.agent?.config?.name ??
-        partialBundle.resolvedAgent?.config?.name ??
-        partialNode.nodeId ??
-        "unknown");
-}
-function resolveTagChannelKind(channel) {
-    return channel === undefined ? "unknown" : getAdapterKind(channel);
-}
+import{contextStorage}from"#context/container.js";import{BundleKey,ChannelKey,SandboxKey,SessionIdKey}from"#context/keys.js";import{getAdapterKind}from"#channel/adapter.js";import{getActiveRuntimeNode}from"#context/node.js";import{ensureSandboxAccess}from"#execution/sandbox/ensure.js";var sandboxProvider={key:SandboxKey,async create(r,i){let a=r.get(BundleKey);if(a===void 0)return;let o=getActiveRuntimeNode(r),s=o.sandboxRegistry,c=r.require(SessionIdKey);return{value:await ensureSandboxAccess({compiledArtifactsSource:a.compiledArtifactsSource,nodeId:o.nodeId,registry:s,runOnSession:async t=>await contextStorage.run(r,t),sessionId:c,state:i.sandboxState??null,tags:{agent:resolveTagAgentName({bundle:a,node:o}),channel:resolveTagChannelKind(r.get(ChannelKey)),sessionId:c}})}},async commit(e,t){let n=await e.captureState();return{...t,sandboxState:n}}};function resolveTagAgentName(e){let t=e.node,n=e.bundle;return t.agent?.config?.name??n.resolvedAgent?.config?.name??t.nodeId??`unknown`}function resolveTagChannelKind(e){return e===void 0?`unknown`:getAdapterKind(e)}export{sandboxProvider};

package/dist/src/context/providers/session.js

@@ -1,18 +1 @@
-import { AuthKey, InitiatorAuthKey, ParentSessionKey, SessionIdKey, SessionKey, } from "#context/keys.js";
-export const sessionProvider = {
-    key: SessionKey,
-    create(ctx) {
-        const currentAuth = ctx.require(AuthKey);
-        return {
-            value: Object.freeze({
-                auth: {
-                    current: currentAuth,
-                    initiator: ctx.get(InitiatorAuthKey) ?? currentAuth,
-                },
-                parent: ctx.get(ParentSessionKey),
-                sessionId: ctx.require(SessionIdKey),
-                turn: { id: `turn-${crypto.randomUUID()}`, sequence: 0 },
-            }),
-        };
-    },
-};
+import{AuthKey,InitiatorAuthKey,ParentSessionKey,SessionIdKey,SessionKey}from"#context/keys.js";var sessionProvider={key:SessionKey,create(e){let t=e.require(AuthKey);return{value:Object.freeze({auth:{current:t,initiator:e.get(InitiatorAuthKey)??t},parent:e.get(ParentSessionKey),sessionId:e.require(SessionIdKey),turn:{id:`turn-${crypto.randomUUID()}`,sequence:0}})}}};export{sessionProvider};

package/dist/src/context/run-step.js

@@ -1,51 +1 @@
-import { contextStorage } from "#context/container.js";
-import { connectionProvider } from "#context/providers/connection.js";
-import { sandboxProvider } from "#context/providers/sandbox.js";
-import { sessionProvider } from "#context/providers/session.js";
-/**
- * Framework providers in dependency order.
- *
- * Session runs first (depends only on durable seed values). Later providers
- * may read framework-derived virtual values through the unified context view.
- */
-const frameworkProviders = [
-    sessionProvider,
-    connectionProvider,
-    sandboxProvider,
-];
-/**
- * Runs one step inside the unified context.
- *
- * 1. Clears all previous step-local provider values.
- * 2. Builds framework virtual providers in dependency order.
- * 3. Runs `callback` inside the ALS scope so authored code can read context.
- * 4. After the step, runs framework provider commit hooks to persist
- *    provider-owned session data (for example sandbox snapshots).
- */
-export async function runStep(ctx, harnessSession, callback) {
-    let session = harnessSession;
-    ctx.clearVirtualContext();
-    // 1. Build framework providers
-    for (const provider of frameworkProviders) {
-        const result = await provider.create(ctx, session);
-        if (result !== undefined) {
-            ctx.setVirtualContext(provider.key, result.value);
-            if (result.session !== undefined) {
-                session = result.session;
-            }
-        }
-    }
-    // 2. Run callback inside ALS scope
-    const stepResult = await contextStorage.run(ctx, () => callback(session));
-    // 3. Commit framework providers
-    let committed = stepResult.session;
-    for (const provider of frameworkProviders) {
-        if (provider.commit && ctx.has(provider.key)) {
-            committed = await provider.commit(ctx.require(provider.key), committed);
-        }
-    }
-    if (committed === stepResult.session) {
-        return stepResult;
-    }
-    return { next: stepResult.next, session: committed };
-}
+import{contextStorage}from"#context/container.js";import{connectionProvider}from"#context/providers/connection.js";import{sandboxProvider}from"#context/providers/sandbox.js";import{sessionProvider}from"#context/providers/session.js";var frameworkProviders=[sessionProvider,connectionProvider,sandboxProvider];async function runStep(t,n,r){let i=n;t.clearVirtualContext();for(let e of frameworkProviders){let n=await e.create(t,i);n!==void 0&&(t.setVirtualContext(e.key,n.value),n.session!==void 0&&(i=n.session))}let a=await contextStorage.run(t,()=>r(i)),o=a.session;for(let e of frameworkProviders)e.commit&&t.has(e.key)&&(o=await e.commit(t.require(e.key),o));return o===a.session?a:{next:a.next,session:o}}export{runStep};

package/dist/src/context/seed-keys.js

@@ -1,37 +1 @@
-/**
- * Simple seed keys — serializable values carried across workflow step
- * boundaries. These keys have no codec and no heavyweight imports, so
- * they can be safely imported from channel code without triggering
- * circular module dependencies.
- *
- * Complex codec keys ({@link import("./keys.js").ChannelKey ChannelKey},
- * {@link import("./keys.js").BundleKey BundleKey}) and derived keys
- * ({@link import("./keys.js").SessionKey SessionKey}, etc.) live in
- * `context/keys.ts` which re-exports everything from this module.
- */
-import { ContextKey } from "#context/key.js";
-export const AuthKey = new ContextKey("ash.auth");
-export const InitiatorAuthKey = new ContextKey("ash.initiatorAuth");
-export const SessionIdKey = new ContextKey("ash.sessionId");
-export const ContinuationTokenKey = new ContextKey("ash.continuationToken");
-export const ModeKey = new ContextKey("ash.mode");
-export const ParentSessionKey = new ContextKey("ash.parentSession");
-/**
- * Session-level capability flags (see {@link SessionCapabilities}). Set
- * on root runs by channel routes and inherited pointwise by subagent
- * dispatch so HITL readiness flows through a conversation chain.
- */
-export const CapabilitiesKey = new ContextKey("ash.capabilities");
-/**
- * Optional framework-owned terminal callback metadata for this session.
- */
-export const SessionCallbackKey = new ContextKey("ash.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 const SessionPreparedKey = new ContextKey("ash.sessionPrepared");
+import{ContextKey}from"#context/key.js";var AuthKey=new ContextKey(`ash.auth`),InitiatorAuthKey=new ContextKey(`ash.initiatorAuth`),SessionIdKey=new ContextKey(`ash.sessionId`),ContinuationTokenKey=new ContextKey(`ash.continuationToken`),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`);export{AuthKey,CapabilitiesKey,ContinuationTokenKey,InitiatorAuthKey,ModeKey,ParentSessionKey,SessionCallbackKey,SessionIdKey,SessionPreparedKey};

package/dist/src/context/serialize.js

@@ -1,44 +1 @@
-import { ContextContainer } from "#context/container.js";
-import { resolveKey } from "#context/key.js";
-import { BundleKey } from "#context/keys.js";
-/**
- * Serializes every value in the context to a plain JSON record.
- *
- * Keys with a codec are run through `codec.serialize`; keys without one
- * are stored as-is (they must already be JSON-safe).
- */
-export function serializeContext(ctx) {
-    const data = {};
-    for (const [key, value] of ctx.entries()) {
-        data[key.name] = key.codec ? key.codec.serialize(value) : value;
-    }
-    return data;
-}
-/**
- * Deserializes a plain JSON record into a fresh context container.
- *
- * Each entry is matched to a registered {@link ContextKey} by name.
- * Unknown entries (no registered key) are silently dropped.
- */
-export async function deserializeContext(data) {
-    const ctx = new ContextContainer();
-    const serializedBundle = data[BundleKey.name];
-    if (serializedBundle !== undefined) {
-        const codec = BundleKey.codec;
-        if (codec === undefined) {
-            throw new Error('Context key "ash.bundle" is missing a codec.');
-        }
-        ctx.set(BundleKey, await codec.deserialize(serializedBundle, ctx));
-    }
-    for (const [name, raw] of Object.entries(data)) {
-        if (raw === undefined)
-            continue;
-        if (name === BundleKey.name)
-            continue;
-        const key = resolveKey(name);
-        if (key !== undefined) {
-            ctx.set(key, key.codec ? await key.codec.deserialize(raw, ctx) : raw);
-        }
-    }
-    return ctx;
-}
+import{ContextContainer}from"#context/container.js";import{BundleKey}from"#context/keys.js";import{resolveKey}from"#context/key.js";function serializeContext(e){let t={};for(let[n,r]of e.entries())t[n.name]=n.codec?n.codec.serialize(r):r;return t}async function deserializeContext(r){let i=new ContextContainer,a=r[BundleKey.name];if(a!==void 0){let e=BundleKey.codec;if(e===void 0)throw Error(`Context key "ash.bundle" is missing a codec.`);i.set(BundleKey,await e.deserialize(a,i))}for(let[e,a]of Object.entries(r)){if(a===void 0||e===BundleKey.name)continue;let r=resolveKey(e);r!==void 0&&i.set(r,r.codec?await r.codec.deserialize(a,i):a)}return i}export{deserializeContext,serializeContext};