experimental-ash 0.20.1 → 0.22.0

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

@@ -2,8 +2,10 @@ 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 { contextStorage } from "./container.js";
-import { BundleKey, ChannelKey, ContinuationTokenKey, SessionIdKey, SessionPreparedKey, } from "./keys.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
@@ -20,11 +22,12 @@ const log = createLogger("hooks.lifecycle");
  *
  *  2. `lifecycle.turn` — runs once per fresh delivery (the caller
  *     gates dispatch with `isHarnessBetweenTurns(session)`). Each
- *     hook may return `{ modelContext }`; contributions are
- *     concatenated in registry order. 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.
+ *     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:
  *
@@ -48,56 +51,63 @@ export async function dispatchHookLifecycle(input) {
         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;
-    for (const entry of registry.turn) {
-        try {
+    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));
         }
-        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(input.session, 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 hook "${entry.slug}" — escalating to session.failed.`, { error: toErrorMessage(cascadeError) });
-                throw cascadeError;
+        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 ?? [];
@@ -107,7 +117,49 @@ export async function dispatchHookLifecycle(input) {
         input: mergedModelContext.length > 0
             ? { ...input.input, modelContext: mergedModelContext }
             : input.input,
-        nextSession: input.session,
+        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,
+            },
+        ],
     };
 }
 /**

package/dist/src/evals/cli/eval.js

@@ -1 +1 @@
-import{n as e}from"../../chunks/paths-BcM3el4Q.js";import{loadDevelopmentEnvironmentFiles as t}from"../../cli/dev/environment.js";import{a as n,n as r,t as i}from"../../chunks/client-CKsU8Li3.js";import{n as a}from"../../chunks/host-Dxf7CGaE.js";import{discoverAndImportSuites as o,discoverSuiteFiles as s,importSuiteFile as c}from"../runner/discover.js";import{executeSuite as l}from"../runner/execute-suite.js";import{ConsoleReporter as u}from"../runner/reporters/console.js";var d=n();function f(e,t){e.command(`eval`).description(`Run eval suites against an Ash agent.`).option(`--suite <id...>`,`Suite IDs to run (repeatable)`).option(`--all`,`Run all discovered suites`).option(`--url <url>`,`Remote agent URL (skip local host startup)`).option(`--timeout <ms>`,`Per-case timeout in milliseconds`).option(`--max-concurrency <n>`,`Max concurrent case executions per suite`).option(`--json`,`Output results as JSON`).option(`--list-suites`,`List discovered suites and exit`).option(`--skip-report`,`Skip suite-defined reporters (e.g. Braintrust)`).action(async e=>{await p(e,t)})}async function p(n,r){let i=e();if(t(i),n.listSuites){await y(i,r);return}let s=n.suite,c=await o(i,s);if(c.length===0){s&&s.length>0?r.error(`No suites found matching: ${s.join(`, `)}`):r.error(`No eval suites found. Create suite files under evals/ with the *.eval.ts extension.`),process.exitCode=1;return}let u,d;n.url?d={kind:`remote`,url:n.url}:(u=await a(i,{host:`127.0.0.1`,port:0}),d={kind:`local`,url:u.url});let f=m(d);try{let e=[];for(let t of c){let r=_(t,n),a=v(r,{json:n.json===!0,skipReport:n.skipReport===!0}),o=await l({suite:r,target:d,reporters:a,appRoot:i,client:f});e.push(o)}n.json&&r.log(JSON.stringify(e,null,2)),e.some(e=>e.errored>0)&&(process.exitCode=1)}finally{u&&await u.close()}process.exit(process.exitCode??0)}function m(e){if(e.kind===`local`)return new i({host:e.url});let t={},n=process.env.VERCEL_AUTOMATION_BYPASS_SECRET?.trim();return n&&(t[r]=n),new i({auth:h(),headers:Object.keys(t).length>0?t:void 0,host:e.url})}function h(){let e=process.env.ASH_EVAL_AUTH_TOKEN?.trim();return e?{bearer:e}:{bearer:g}}async function g(){try{let e=(await(0,d.getVercelOidcToken)()).trim();if(e.length>0)return e}catch{}return process.env.VERCEL_OIDC_TOKEN?.trim()??``}function _(e,t){let n=t.maxConcurrency?Number.parseInt(t.maxConcurrency,10):void 0,r=t.timeout?Number.parseInt(t.timeout,10):void 0;if(n===void 0&&r===void 0)return e;let i={...e};return n!==void 0&&(i.maxConcurrency=n),r!==void 0&&(i.timeoutMs=r),i}function v(e,t){let n=t.json?[]:[new u];return!t.skipReport&&e.reporters&&n.push(...e.reporters),n}async function y(e,t){let n=await s(e);if(n.length===0){t.log(`No eval suites found.`);return}t.log(`Found ${n.length} eval suite file(s):\n`);for(let r of n){let n=await c(e,r);t.log(`  ${n.id}${n.description?`  - ${n.description}`:``}`)}}export{f as registerEvalCommand,p as runEvalCommand};
+import{n as e}from"../../chunks/paths-DZTgjrW-.js";import{loadDevelopmentEnvironmentFiles as t}from"../../cli/dev/environment.js";import{a as n,n as r,t as i}from"../../chunks/client-CKsU8Li3.js";import{n as a}from"../../chunks/host-Btr4S69C.js";import{discoverAndImportSuites as o,discoverSuiteFiles as s,importSuiteFile as c}from"../runner/discover.js";import{executeSuite as l}from"../runner/execute-suite.js";import{ConsoleReporter as u}from"../runner/reporters/console.js";var d=n();function f(e,t){e.command(`eval`).description(`Run eval suites against an Ash agent.`).option(`--suite <id...>`,`Suite IDs to run (repeatable)`).option(`--all`,`Run all discovered suites`).option(`--url <url>`,`Remote agent URL (skip local host startup)`).option(`--timeout <ms>`,`Per-case timeout in milliseconds`).option(`--max-concurrency <n>`,`Max concurrent case executions per suite`).option(`--json`,`Output results as JSON`).option(`--list-suites`,`List discovered suites and exit`).option(`--skip-report`,`Skip suite-defined reporters (e.g. Braintrust)`).action(async e=>{await p(e,t)})}async function p(n,r){let i=e();if(t(i),n.listSuites){await y(i,r);return}let s=n.suite,c=await o(i,s);if(c.length===0){s&&s.length>0?r.error(`No suites found matching: ${s.join(`, `)}`):r.error(`No eval suites found. Create suite files under evals/ with the *.eval.ts extension.`),process.exitCode=1;return}let u,d;n.url?d={kind:`remote`,url:n.url}:(u=await a(i,{host:`127.0.0.1`,port:0}),d={kind:`local`,url:u.url});let f=m(d);try{let e=[];for(let t of c){let r=_(t,n),a=v(r,{json:n.json===!0,skipReport:n.skipReport===!0}),o=await l({suite:r,target:d,reporters:a,appRoot:i,client:f});e.push(o)}n.json&&r.log(JSON.stringify(e,null,2)),e.some(e=>e.errored>0)&&(process.exitCode=1)}finally{u&&await u.close()}process.exit(process.exitCode??0)}function m(e){if(e.kind===`local`)return new i({host:e.url});let t={},n=process.env.VERCEL_AUTOMATION_BYPASS_SECRET?.trim();return n&&(t[r]=n),new i({auth:h(),headers:Object.keys(t).length>0?t:void 0,host:e.url})}function h(){let e=process.env.ASH_EVAL_AUTH_TOKEN?.trim();return e?{bearer:e}:{bearer:g}}async function g(){try{let e=(await(0,d.getVercelOidcToken)()).trim();if(e.length>0)return e}catch{}return process.env.VERCEL_OIDC_TOKEN?.trim()??``}function _(e,t){let n=t.maxConcurrency?Number.parseInt(t.maxConcurrency,10):void 0,r=t.timeout?Number.parseInt(t.timeout,10):void 0;if(n===void 0&&r===void 0)return e;let i={...e};return n!==void 0&&(i.maxConcurrency=n),r!==void 0&&(i.timeoutMs=r),i}function v(e,t){let n=t.json?[]:[new u];return!t.skipReport&&e.reporters&&n.push(...e.reporters),n}async function y(e,t){let n=await s(e);if(n.length===0){t.log(`No eval suites found.`);return}t.log(`Found ${n.length} eval suite file(s):\n`);for(let r of n){let n=await c(e,r);t.log(`  ${n.id}${n.description?`  - ${n.description}`:``}`)}}export{f as registerEvalCommand,p as runEvalCommand};

package/dist/src/execution/skills/instructions.d.ts

@@ -1,4 +1,7 @@
-import type { ResolvedSkillDefinition } from "#runtime/types.js";
+export interface AvailableSkillDescription {
+    readonly description: string;
+    readonly name: string;
+}
 /**
  * Formats the "Available skills" system prompt section.
  *
@@ -7,7 +10,8 @@ import type { ResolvedSkillDefinition } from "#runtime/types.js";
  * has them from the `load_skill` tool result. This keeps the system
  * prompt identical across the entire session, preserving prompt caching.
  *
- * Called at graph resolution time so the section is part of the turn
- * agent's static instructions rather than injected per-step.
+ * Authored skills call this at graph resolution time so the section is
+ * part of the turn agent's static instructions. Hook-contributed skills
+ * reuse the same formatter for durable history announcements.
  */
-export declare function formatAvailableSkillsSection(skills: readonly ResolvedSkillDefinition[]): string | null;
+export declare function formatAvailableSkillsSection(skills: readonly AvailableSkillDescription[]): string | null;

package/dist/src/execution/skills/instructions.js

@@ -7,8 +7,9 @@ import { WORKSPACE_ROOT } from "#runtime/workspace/types.js";
  * has them from the `load_skill` tool result. This keeps the system
  * prompt identical across the entire session, preserving prompt caching.
  *
- * Called at graph resolution time so the section is part of the turn
- * agent's static instructions rather than injected per-step.
+ * Authored skills call this at graph resolution time so the section is
+ * part of the turn agent's static instructions. Hook-contributed skills
+ * reuse the same formatter for durable history announcements.
  */
 export function formatAvailableSkillsSection(skills) {
     if (skills.length === 0) {

package/dist/src/harness/attachment-staging.js

@@ -84,7 +84,11 @@ export async function stageAttachmentsToSandbox(message) {
     const adapter = container.get(ChannelKey);
     const adapterCtx = adapter
         ? buildAdapterContext(adapter, container)
-        : { ctx: container, state: {}, session: buildSessionHandle(container) };
+        : {
+            ctx: container,
+            state: {},
+            session: buildSessionHandle(container),
+        };
     return stageAttachmentsForAdapter(message, sandbox, adapterCtx);
 }
 /**

package/dist/src/harness/tool-loop.js

@@ -299,10 +299,18 @@ export function createToolLoopHarness(config) {
         // bloating every future step boundary.
         const hydratedMessages = await hydrateSandboxAttachments(messages);
         const ephemeralContext = stepInput.input?.modelContext;
-        // AI SDK rejects role:"system" in `messages` — route those entries
-        // to `instructions` instead.
+        // AI SDK rejects role:"system" in `messages` — route durable history
+        // and ephemeral context system entries to `instructions` instead.
         const systemMessages = [];
         const nonSystemMessages = [];
+        for (const entry of hydratedMessages) {
+            if (entry.role === "system") {
+                systemMessages.push(entry);
+            }
+            else {
+                nonSystemMessages.push(entry);
+            }
+        }
         if (ephemeralContext !== undefined) {
             for (const entry of ephemeralContext) {
                 if (entry.role === "system") {
@@ -334,7 +342,7 @@ export function createToolLoopHarness(config) {
             tools: effectiveTools,
         };
         const agent = new ToolLoopAgent(agentSettings);
-        const modelMessages = nonSystemMessages.length > 0 ? [...hydratedMessages, ...nonSystemMessages] : hydratedMessages;
+        const modelMessages = nonSystemMessages;
         let result;
         const executeModelCall = async () => {
             if (emit) {

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.20.1";
+const BUNDLED_FALLBACK_PACKAGE_VERSION = "0.22.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/authored-definition/core.js

@@ -118,7 +118,7 @@ export function normalizeInstructionsDefinition(value, message) {
  */
 export function normalizeSkillDefinition(value, message) {
     const record = expectObjectRecord(value, message);
-    expectOnlyKnownKeys(record, ["description", "license", "markdown", "metadata"], message);
+    expectOnlyKnownKeys(record, ["description", "files", "license", "markdown", "metadata"], message);
     const definition = {
         description: expectString(record.description, message),
         markdown: expectString(record.markdown, message),
@@ -131,8 +131,23 @@ export function normalizeSkillDefinition(value, message) {
     if (metadata !== undefined) {
         definition.metadata = metadata;
     }
+    if (record.files !== undefined) {
+        definition.files = normalizeSkillFiles(record.files, message);
+    }
     return definition;
 }
+function normalizeSkillFiles(value, message) {
+    const files = expectObjectRecord(value, message);
+    const normalized = {};
+    for (const [filePath, content] of Object.entries(files)) {
+        if (typeof content === "string" || content instanceof Uint8Array) {
+            normalized[filePath] = content;
+            continue;
+        }
+        throw new Error(`${message} Expected skill file "${filePath}" to be a string or Uint8Array.`);
+    }
+    return normalized;
+}
 /**
  * Normalizes one authored schedule definition into the canonical internal
  * shape.

package/dist/src/internal/nitro/routes/workflow-route-helpers.d.ts

@@ -1,8 +1,8 @@
 import type { H3Event } from "nitro";
-export declare const WORKFLOW_RUNS_API_ROUTE_PATH = "/api/runs";
-export declare const WORKFLOW_RUN_ROUTE_PATTERN = "/api/runs/:runId";
-export declare const WORKFLOW_RUN_STEPS_ROUTE_PATTERN = "/api/runs/:runId/steps";
-export declare const WORKFLOW_RUN_EVENTS_ROUTE_PATTERN = "/api/runs/:runId/events";
+export declare const WORKFLOW_RUNS_API_ROUTE_PATH = "/ash/v1/runs";
+export declare const WORKFLOW_RUN_ROUTE_PATTERN = "/ash/v1/runs/:runId";
+export declare const WORKFLOW_RUN_STEPS_ROUTE_PATTERN = "/ash/v1/runs/:runId/steps";
+export declare const WORKFLOW_RUN_EVENTS_ROUTE_PATTERN = "/ash/v1/runs/:runId/events";
 declare const WORKFLOW_RUN_STATUSES: readonly ["pending", "running", "completed", "failed", "cancelled"];
 export type WorkflowRunStatus = (typeof WORKFLOW_RUN_STATUSES)[number];
 export interface PaginationQuery {

package/dist/src/internal/nitro/routes/workflow-route-helpers.js

@@ -1,7 +1,8 @@
-export const WORKFLOW_RUNS_API_ROUTE_PATH = "/api/runs";
-export const WORKFLOW_RUN_ROUTE_PATTERN = "/api/runs/:runId";
-export const WORKFLOW_RUN_STEPS_ROUTE_PATTERN = "/api/runs/:runId/steps";
-export const WORKFLOW_RUN_EVENTS_ROUTE_PATTERN = "/api/runs/:runId/events";
+import { ASH_ROUTE_PREFIX } from "#protocol/routes.js";
+export const WORKFLOW_RUNS_API_ROUTE_PATH = `${ASH_ROUTE_PREFIX}/runs`;
+export const WORKFLOW_RUN_ROUTE_PATTERN = `${ASH_ROUTE_PREFIX}/runs/:runId`;
+export const WORKFLOW_RUN_STEPS_ROUTE_PATTERN = `${ASH_ROUTE_PREFIX}/runs/:runId/steps`;
+export const WORKFLOW_RUN_EVENTS_ROUTE_PATTERN = `${ASH_ROUTE_PREFIX}/runs/:runId/events`;
 const MAX_PAGE_LIMIT = 1000;
 const WORKFLOW_RUN_STATUSES = ["pending", "running", "completed", "failed", "cancelled"];
 function createWorkflowApiResponse(payload, status) {
@@ -119,7 +120,7 @@ export function resolveRunIdFromNitroEvent(event) {
         return routeRunId;
     }
     const path = new URL(event.req.url).pathname;
-    const pathMatch = path.match(/^\/api\/runs\/([^/]+)(?:\/.*)?$/);
+    const pathMatch = path.match(/^\/ash\/v1\/runs\/([^/]+)(?:\/.*)?$/);
     if (pathMatch === null) {
         return null;
     }

package/dist/src/internal/nitro/routes/workflow-run-events.d.ts

@@ -7,7 +7,7 @@ export declare function handleWorkflowRunEventsRequest(input: {
     readonly runId: string;
 }): Promise<Response>;
 /**
- * Nitro route for `GET /api/runs/:runId/events`.
+ * Nitro route for `GET /ash/v1/runs/:runId/events`.
  */
 declare const _default: (event: H3Event) => Promise<Response>;
 export default _default;

package/dist/src/internal/nitro/routes/workflow-run-events.js

@@ -27,7 +27,7 @@ export async function handleWorkflowRunEventsRequest(input) {
     }
 }
 /**
- * Nitro route for `GET /api/runs/:runId/events`.
+ * Nitro route for `GET /ash/v1/runs/:runId/events`.
  */
 export default async (event) => {
     const runId = resolveRunIdFromNitroEvent(event);

package/dist/src/internal/nitro/routes/workflow-run-steps.d.ts

@@ -7,7 +7,7 @@ export declare function handleWorkflowRunStepsRequest(input: {
     readonly runId: string;
 }): Promise<Response>;
 /**
- * Nitro route for `GET /api/runs/:runId/steps`.
+ * Nitro route for `GET /ash/v1/runs/:runId/steps`.
  */
 declare const _default: (event: H3Event) => Promise<Response>;
 export default _default;

package/dist/src/internal/nitro/routes/workflow-run-steps.js

@@ -27,7 +27,7 @@ export async function handleWorkflowRunStepsRequest(input) {
     }
 }
 /**
- * Nitro route for `GET /api/runs/:runId/steps`.
+ * Nitro route for `GET /ash/v1/runs/:runId/steps`.
  */
 export default async (event) => {
     const runId = resolveRunIdFromNitroEvent(event);

package/dist/src/internal/nitro/routes/workflow-run.d.ts

@@ -6,7 +6,7 @@ export declare function handleWorkflowRunRequest(input: {
     runId: string;
 }): Promise<Response>;
 /**
- * Nitro route for `GET /api/runs/:runId`.
+ * Nitro route for `GET /ash/v1/runs/:runId`.
  */
 declare const _default: (event: H3Event) => Promise<Response>;
 export default _default;

package/dist/src/internal/nitro/routes/workflow-run.js

@@ -21,7 +21,7 @@ export async function handleWorkflowRunRequest(input) {
     }
 }
 /**
- * Nitro route for `GET /api/runs/:runId`.
+ * Nitro route for `GET /ash/v1/runs/:runId`.
  */
 export default async (event) => {
     const runId = resolveRunIdFromNitroEvent(event);

package/dist/src/internal/nitro/routes/workflow-runs.d.ts

@@ -4,7 +4,7 @@ import type { H3Event } from "nitro";
  */
 export declare function handleWorkflowRunsRequest(request: Request): Promise<Response>;
 /**
- * Nitro route for `GET /api/runs`.
+ * Nitro route for `GET /ash/v1/runs`.
  */
 declare const _default: (event: H3Event) => Promise<Response>;
 export default _default;

package/dist/src/internal/nitro/routes/workflow-runs.js

@@ -21,7 +21,7 @@ export async function handleWorkflowRunsRequest(request) {
     }
 }
 /**
- * Nitro route for `GET /api/runs`.
+ * Nitro route for `GET /ash/v1/runs`.
  */
 export default async (event) => {
     return await handleWorkflowRunsRequest(event.req);

package/dist/src/internal/workflow-bundle/vercel-workflow-output.js

@@ -11,6 +11,7 @@ export const WORKFLOW_STEP_EXTERNAL_PACKAGES = ["@mongodb-js/zstd", "node-liblzm
  * Nitro performs the final bundling/tracing pass for hosted output.
  */
 export const WORKFLOW_BUILDER_DEFERRED_PACKAGES = ["@chat-adapter/slack", "chat"];
+const WORKFLOW_FUNCTION_NODE_OPTIONS = "--experimental-require-module";
 /**
  * Builds the environment block every generated Vercel workflow function needs.
  */
@@ -19,6 +20,7 @@ export function createWorkflowFunctionEnvironment(environment) {
     if (isRecord(environment)) {
         Object.assign(nextEnvironment, environment);
     }
+    nextEnvironment.NODE_OPTIONS = WORKFLOW_FUNCTION_NODE_OPTIONS;
     return nextEnvironment;
 }
 function isRecord(value) {

package/dist/src/public/definitions/hook.d.ts

@@ -1,6 +1,7 @@
 import type { ModelMessage } from "ai";
 import type { ContextAccessor } from "../../context/key.js";
 import type { HandleMessageStreamEvent } from "../../protocol/message.js";
+import type { NamedSkillDefinition } from "./skill.js";
 /**
  * Context passed to every hook handler.
  *
@@ -45,15 +46,22 @@ export interface LifecycleHookInput {
  * `lifecycle.turn`).
  *
  * `modelContext` messages are appended to the next model call's message
- * list and never written to durable session history. Each lifecycle key
- * runs in registry order; contributions are concatenated session-then-
- * turn before the harness's first model call.
+ * list and never written to durable session history. `skills` are
+ * materialized into the live sandbox and announced through durable
+ * system history. Each lifecycle key runs in registry order;
+ * contributions are concatenated session-then-turn before the harness's
+ * first model call.
  *
  * Returning `void` (or `undefined`) means "no opinion" — the turn
  * proceeds with no additional model context from this hook.
  */
 export interface LifecycleHookResult {
     readonly modelContext?: readonly ModelMessage[];
+    /**
+     * Skill packages to materialize into the live durable sandbox before the
+     * next model call. Authored skill names cannot be overwritten.
+     */
+    readonly skills?: readonly NamedSkillDefinition[];
 }
 /**
  * Lifecycle hook signature shared by `lifecycle.session` and

package/dist/src/public/definitions/skill.d.ts

@@ -1,4 +1,5 @@
-import type { InternalSkillDefinition } from "#shared/skill-definition.js";
+import type { NamedSkillDefinition, SkillFileContent, SkillPackageDefinition } from "#shared/skill-definition.js";
+export type { NamedSkillDefinition, SkillFileContent, SkillPackageDefinition };
 /**
  * Public definition for skill instructions lowered from authored markdown
  * or authored directly in TypeScript via {@link defineSkill}.
@@ -6,9 +7,9 @@ import type { InternalSkillDefinition } from "#shared/skill-definition.js";
  * Identity is derived from the file path under `agent/skills/`; authored
  * definitions do not carry a `name` field.
  */
-export type SkillDefinition = Omit<InternalSkillDefinition, "name">;
+export type SkillDefinition = SkillPackageDefinition;
 /**
  * Defines a skill in TypeScript using the same shape discovery produces from
- * markdown.
+ * markdown, with optional package-relative sibling files.
  */
 export declare function defineSkill<TSkill extends SkillDefinition>(definition: TSkill): TSkill;

package/dist/src/public/definitions/skill.js

@@ -1,6 +1,6 @@
 /**
  * Defines a skill in TypeScript using the same shape discovery produces from
- * markdown.
+ * markdown, with optional package-relative sibling files.
  */
 export function defineSkill(definition) {
     return definition;

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

@@ -0,0 +1,74 @@
+import type { NextConfig } from "next";
+/**
+ * Private route namespace used when a Vercel deployment hosts Ash as a
+ * separate experimental service behind the Next.js app.
+ */
+export declare const ASH_NEXT_SERVICE_PREFIX = "/_ash_internal/ash";
+type ArrayElement<T> = T extends readonly (infer TElement)[] ? TElement : never;
+type NextRewrites = Awaited<ReturnType<NonNullable<NextConfig["rewrites"]>>>;
+/**
+ * Next.js rewrite rule used by {@link withAsh}.
+ */
+export type AshNextRewriteRule = ArrayElement<NextRewrites>;
+/**
+ * Values accepted by Next.js `rewrites`.
+ */
+export type AshNextRewrites = NextRewrites;
+/**
+ * Sectioned Next.js rewrite rules.
+ */
+export type AshNextRewriteSections = Extract<NextRewrites, {
+    readonly afterFiles?: AshNextRewriteRule[];
+    readonly beforeFiles?: AshNextRewriteRule[];
+    readonly fallback?: AshNextRewriteRule[];
+}>;
+/**
+ * Next.js config object accepted by {@link withAsh}.
+ */
+export type AshNextConfig = NextConfig;
+/**
+ * Minimal structural shape for a Next.js config function.
+ */
+export type AshNextConfigFunction<TConfig extends AshNextConfig = AshNextConfig> = (phase: string, context: {
+    readonly defaultConfig: TConfig;
+}) => TConfig | Promise<TConfig>;
+/**
+ * Next.js config input accepted by {@link withAsh}.
+ */
+export type AshNextConfigInput<TConfig extends AshNextConfig = AshNextConfig> = AshNextConfigFunction<TConfig> | TConfig;
+/**
+ * Options for {@link withAsh}.
+ */
+export interface WithAshOptions {
+    /**
+     * Path to the Ash application root, relative to `process.cwd()` unless
+     * absolute. Defaults to the Next.js app root.
+     */
+    readonly ashRoot?: string;
+    /**
+     * Set to `false` to skip creating or updating `vercel.json`.
+     *
+     * By default `withAsh` ensures `vercel.json` contains `experimentalServices`
+     * for the Next.js app and Ash app.
+     */
+    readonly configureVercelJson?: boolean;
+    /**
+     * Private Vercel service prefix for the Ash deployment. This must match the
+     * Ash service's `routePrefix` in `vercel.json`.
+     */
+    readonly servicePrefix?: string;
+}
+/**
+ * Wraps a Next.js config so same-origin Ash endpoints proxy to a separate Ash
+ * service.
+ *
+ * In development, `withAsh` starts `ash dev --no-repl --port 0` for the Ash
+ * app and rewrites Ash protocol endpoints to that local URL. In production on
+ * Vercel, it rewrites to the private Ash service prefix configured in
+ * `vercel.json` using the deployment origin from `VERCEL_URL`. Outside Vercel
+ * production, it serves an existing `.output/server/index.mjs` Ash build on a
+ * stable local port when present; otherwise set `ASH_NEXT_PRODUCTION_ORIGIN` to
+ * the origin that serves the Ash service namespace.
+ */
+export declare function withAsh<TConfig extends AshNextConfig>(configOrFunction: AshNextConfigInput<TConfig>, options?: WithAshOptions): AshNextConfigFunction<TConfig>;
+export {};