experimental-ash 0.43.0 → 0.45.0

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

@@ -1 +1 @@
-function defineInstrumentation(e){return e}export{defineInstrumentation};
+export*from"#public/instrumentation/index.js";export{};

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

@@ -1,6 +1,6 @@
 import type { Optional } from "#shared/optional.js";
 import type { SandboxDefinition as SharedSandboxDefinition } from "#shared/sandbox-definition.js";
-export type { SandboxCommandResult, SandboxProcess, SandboxReadBinaryFileOptions, SandboxReadFileOptions, SandboxReadTextFileOptions, SandboxRunOptions, SandboxSession, SandboxSpawnOptions, SandboxWriteBinaryFileOptions, SandboxWriteFileOptions, SandboxWriteTextFileOptions, } from "#shared/sandbox-session.js";
+export type { SandboxCommandResult, SandboxProcess, SandboxReadBinaryFileOptions, SandboxReadFileOptions, SandboxRemovePathOptions, SandboxReadTextFileOptions, SandboxRunOptions, SandboxSession, SandboxSpawnOptions, SandboxWriteBinaryFileOptions, SandboxWriteFileOptions, SandboxWriteTextFileOptions, } from "#shared/sandbox-session.js";
 export type { SandboxBootstrapUseFn, SandboxSessionUseFn, SandboxBootstrapContext, SandboxSessionContext, } from "#shared/sandbox-definition.js";
 export type SandboxDefinition<BO = Record<string, never>, SO = Record<string, never>> = Optional<SharedSandboxDefinition<BO, SO>, "backend">;
 /**

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

@@ -1 +1,178 @@
-export * from "#public/definitions/instrumentation.js";
+import type { ExactDefinition } from "#public/definitions/exact.js";
+/**
+ * Instrumentation authoring helpers for `agent/instrumentation.ts`.
+ */
+import type { ModelMessage, SystemModelMessage } from "ai";
+import type { SessionAuthContext, SessionParent } from "#channel/types.js";
+import type { Channel } from "#public/definitions/defineChannel.js";
+/**
+ * Context passed to the {@link InstrumentationDefinition.setup} callback.
+ */
+export interface InstrumentationSetupContext {
+    /**
+     * The agent name declared by `defineAgent`.
+     *
+     * Use this as the `serviceName` for `registerOTel` instead of
+     * hard-coding a string — it prevents copy-paste drift across agents.
+     */
+    readonly agentName: string;
+}
+/**
+ * User-authored metadata attached to AI SDK telemetry spans.
+ *
+ * Keys beginning with `ash.` are reserved for framework-owned metadata
+ * and are ignored when returned from authored instrumentation.
+ */
+export type InstrumentationMetadata = Readonly<Record<string, string>>;
+/**
+ * Base channel metadata shape used by framework channel kinds.
+ */
+export type InstrumentationChannelMetadata = Readonly<Record<string, unknown>>;
+/**
+ * Channel metadata projections keyed by instrumentation channel kind.
+ *
+ * Channel packages and user-authored channels declaration-merge additional
+ * `channel:<registered-name>` entries into this map so `input.channel.metadata`
+ * narrows after checking `input.channel.kind`.
+ */
+export interface ChannelMetadataMap {
+    readonly http: InstrumentationChannelMetadata;
+    readonly schedule: InstrumentationChannelMetadata;
+    readonly subagent: InstrumentationChannelMetadata;
+    readonly unknown: InstrumentationChannelMetadata;
+}
+export type InstrumentationChannelKind = keyof ChannelMetadataMap;
+/**
+ * Authored channel values keyed by path-derived instrumentation channel kind.
+ *
+ * Ash generates declaration-merged entries for authored channel files. Use
+ * this map through {@link isChannel}; authored code should not merge it by
+ * hand except for unusual setups outside the compiler-owned path.
+ */
+export interface ChannelReferenceMap {
+}
+/**
+ * Channel projection exposed to instrumentation callbacks.
+ *
+ * `kind` is the channel identity Ash has for the current turn (`"http"`,
+ * `"schedule"`, `"subagent"`, or `channel:<name>` for authored channels,
+ * where `<name>` is the channel's filename under `agent/channels/`).
+ */
+export interface InstrumentationChannelForKind<K extends InstrumentationChannelKind> {
+    readonly kind: K;
+    readonly metadata: ChannelMetadataMap[K];
+}
+export type InstrumentationChannel = {
+    readonly [K in InstrumentationChannelKind]: InstrumentationChannelForKind<K>;
+}[InstrumentationChannelKind];
+type ChannelReferenceKind<TChannel> = {
+    readonly [K in keyof ChannelReferenceMap]: [TChannel] extends [ChannelReferenceMap[K]] ? [ChannelReferenceMap[K]] extends [TChannel] ? K : never : never;
+}[keyof ChannelReferenceMap];
+export type InstrumentationChannelForChannel<TChannel> = Extract<InstrumentationChannel, {
+    readonly kind: Extract<ChannelReferenceKind<TChannel>, InstrumentationChannelKind>;
+}>;
+export interface InstrumentationSession {
+    readonly auth: {
+        readonly current: SessionAuthContext | null;
+        readonly initiator: SessionAuthContext | null;
+    };
+    readonly id: string;
+    readonly parent?: SessionParent;
+}
+export interface InstrumentationTurn {
+    readonly id: string;
+    readonly sequence: number;
+}
+export interface InstrumentationStep {
+    readonly index: number;
+}
+export interface InstrumentationModelInput {
+    readonly instructions: string | readonly SystemModelMessage[] | undefined;
+    readonly messages: readonly ModelMessage[];
+}
+/**
+ * Input passed to `metadata["step.started"]`.
+ *
+ * The callback runs after Ash has built the final model input for this
+ * model-call attempt and before the AI SDK model call is constructed.
+ */
+export interface InstrumentationStepStartedMetadataInput {
+    readonly channel: InstrumentationChannel;
+    readonly modelInput: InstrumentationModelInput;
+    readonly session: InstrumentationSession;
+    readonly step: InstrumentationStep;
+    readonly turn: InstrumentationTurn;
+}
+/**
+ * Metadata hooks accepted by {@link defineInstrumentation}.
+ */
+export interface InstrumentationMetadataConfig {
+    /**
+     * Per-attempt metadata resolved before the model call so child spans
+     * created by the AI SDK inherit the returned values.
+     */
+    readonly "step.started"?: (input: InstrumentationStepStartedMetadataInput) => InstrumentationMetadata;
+}
+/**
+ * Authored instrumentation settings accepted by `defineInstrumentation`.
+ *
+ * The presence of a `defineInstrumentation` export implicitly enables
+ * telemetry — there is no separate `isEnabled` toggle.
+ */
+export interface InstrumentationDefinition {
+    /**
+     * Override the default function identifier attached to telemetry spans.
+     *
+     * When omitted, Ash derives the identifier from the agent name.
+     */
+    readonly functionId?: string;
+    /**
+     * Additional metadata merged into AI SDK telemetry spans.
+     */
+    readonly metadata?: InstrumentationMetadataConfig;
+    /**
+     * Whether to record full model inputs in telemetry spans.
+     *
+     * Defaults to `true` when `instrumentation.ts` is present. Set to `false`
+     * to disable recording inputs, which may be useful if inputs contain
+     * sensitive content or you want to reduce span payload size.
+     */
+    readonly recordInputs?: boolean;
+    /**
+     * Whether to record full model outputs in telemetry spans.
+     *
+     * Defaults to `true` when `instrumentation.ts` is present. Set to `false`
+     * to disable recording outputs.
+     */
+    readonly recordOutputs?: boolean;
+    /**
+     * Optional setup callback invoked at server startup with the resolved
+     * agent name.
+     *
+     * Use this to call `registerOTel` or any other OTel provider setup.
+     * The `context.agentName` value comes from `defineAgent`, so you never
+     * need to hard-code a service name.
+     */
+    readonly setup?: (context: InstrumentationSetupContext) => void;
+}
+/**
+ * Defines instrumentation settings for the agent application.
+ *
+ * Export the result as the default export of `agent/instrumentation.ts`.
+ * Ash picks up these settings at server startup and applies them to every
+ * AI SDK model call.
+ *
+ * The `setup` callback is invoked later by the framework with the resolved
+ * agent name — it is not called during `defineInstrumentation` itself.
+ */
+export declare function defineInstrumentation<T extends InstrumentationDefinition>(definition: ExactDefinition<T, InstrumentationDefinition>): T;
+/**
+ * Narrows an instrumentation channel by comparing it to an app-owned channel
+ * value imported from `agent/channels/*`.
+ *
+ * The comparison uses the compiler's path-derived `channel:<slug>` identity.
+ * It does not read durable channel state; metadata remains the explicit
+ * projection returned by the channel's `metadata(state)` function.
+ */
+export declare function isChannel<TChannel extends Channel<any, any, any>>(channel: InstrumentationChannel, target: TChannel): channel is InstrumentationChannelForChannel<TChannel>;
+export {};

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

@@ -1 +1 @@
-export*from"#public/definitions/instrumentation.js";export{};
+import{getChannelInstrumentationKind}from"#channel/compiled-channel.js";function defineInstrumentation(e){return e}function isChannel(t,n){return t.kind===getChannelInstrumentationKind(n)}export{defineInstrumentation,isChannel};

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

@@ -4,6 +4,7 @@
  */
 export { defineSandbox, type SandboxBootstrapContext, type SandboxBootstrapUseFn, type SandboxCommandResult, type SandboxDefinition, type SandboxProcess, type SandboxReadBinaryFileOptions, type SandboxReadFileOptions, type SandboxReadTextFileOptions, type SandboxRunOptions, type SandboxSession, type SandboxSpawnOptions, type SandboxSessionContext, type SandboxSessionUseFn, type SandboxWriteBinaryFileOptions, type SandboxWriteFileOptions, type SandboxWriteTextFileOptions, } from "#public/definitions/sandbox.js";
 export type { SandboxBackend, SandboxBackendCreateInput, SandboxBackendHandle, SandboxBackendPrewarmInput, SandboxBackendRuntimeContext, SandboxBackendSessionState, SandboxSeedFile, } from "#public/definitions/sandbox-backend.js";
+export type { SandboxNetworkPolicy } from "#shared/sandbox-network-policy.js";
 export { SandboxTemplateNotProvisionedError } from "#public/definitions/sandbox-backend.js";
 export { defaultBackend } from "#public/sandbox/backends/default.js";
 export { localBackend } from "#public/sandbox/backends/local.js";

package/dist/src/runtime/resolve-channel.js

@@ -1 +1 @@
-import{toErrorMessage}from"#shared/errors.js";import{normalizeChannelDefinition}from"#internal/authored-definition/channel.js";import{ResolveAgentError,createResolvedModuleSourceRef,loadResolvedModuleExport}from"#runtime/resolve-helpers.js";import{HTTP_ADAPTER_KIND}from"#channel/http.js";async function resolveChannelDefinition(r,i,a){try{let e=normalizeChannelDefinition(await loadResolvedModuleExport({definition:r,kindLabel:`channel`,moduleMap:i,nodeId:a}),`Expected the channel export "${r.exportName??`default`}" from "${r.logicalPath}" to match the public Ash shape.`),n=createResolvedModuleSourceRef({exportName:r.exportName,logicalPath:r.logicalPath,sourceId:r.sourceId}),o=e.routes.find(e=>e.method.toUpperCase()===r.method.toUpperCase()&&e.path===r.urlPath),s=e.adapter;return s&&s.kind!==HTTP_ADAPTER_KIND&&(s.kind=`channel:${r.name}`),{name:r.name,method:r.method,urlPath:r.urlPath,fetch:async(e,t)=>o?o.handler(e,t):Response.json({error:`No matching route handler.`,ok:!1},{status:404}),handler:o?.handler,receive:e.receive,definition:e,adapter:s,...n}}catch(t){throw t instanceof ResolveAgentError?t:new ResolveAgentError(`Failed to attach the channel definition from "${r.logicalPath}": ${toErrorMessage(t)}`,{logicalPath:r.logicalPath,sourceId:r.sourceId})}}export{resolveChannelDefinition};
+import{setChannelInstrumentationKind}from"#channel/compiled-channel.js";import{toErrorMessage}from"#shared/errors.js";import{normalizeChannelDefinition}from"#internal/authored-definition/channel.js";import{ResolveAgentError,createResolvedModuleSourceRef,loadResolvedModuleExport}from"#runtime/resolve-helpers.js";import{HTTP_ADAPTER_KIND}from"#channel/http.js";async function resolveChannelDefinition(r,i,a){try{let t=normalizeChannelDefinition(await loadResolvedModuleExport({definition:r,kindLabel:`channel`,moduleMap:i,nodeId:a}),`Expected the channel export "${r.exportName??`default`}" from "${r.logicalPath}" to match the public Ash shape.`),n=createResolvedModuleSourceRef({exportName:r.exportName,logicalPath:r.logicalPath,sourceId:r.sourceId}),o=t.routes.find(e=>e.method.toUpperCase()===r.method.toUpperCase()&&e.path===r.urlPath),s=`channel:${r.name}`;setChannelInstrumentationKind(t,s);let c=t.adapter;return c&&c.kind!==HTTP_ADAPTER_KIND&&(c.kind=s),{name:r.name,method:r.method,urlPath:r.urlPath,fetch:async(e,t)=>o?o.handler(e,t):Response.json({error:`No matching route handler.`,ok:!1},{status:404}),handler:o?.handler,receive:t.receive,definition:t,adapter:c,...n}}catch(e){throw e instanceof ResolveAgentError?e:new ResolveAgentError(`Failed to attach the channel definition from "${r.logicalPath}": ${toErrorMessage(e)}`,{logicalPath:r.logicalPath,sourceId:r.sourceId})}}export{resolveChannelDefinition};

package/dist/src/shared/sandbox-network-policy.d.ts

@@ -0,0 +1,23 @@
+import type { NetworkPolicy } from "#compiled/@vercel/sandbox/index.js";
+/**
+ * Firewall network policy applied to a live sandbox session.
+ *
+ * Ash-owned alias of the backend network-policy shape. Use it to restrict
+ * egress (`"deny-all"`, an allow-list) or to broker credentials onto
+ * outgoing requests — a per-domain `transform` injects headers at the
+ * firewall so secrets never enter the sandbox process:
+ *
+ * ```ts
+ * const sandbox = await ctx.getSandbox();
+ * await sandbox.setNetworkPolicy({
+ *   allow: {
+ *     "github.com": [{ transform: [{ headers: { authorization: "Basic …" } }] }],
+ *     "*": [],
+ *   },
+ * });
+ * ```
+ *
+ * The local backend rejects `setNetworkPolicy`: just-bash cannot update its
+ * network policy at run time and runs no binaries to govern.
+ */
+export type SandboxNetworkPolicy = NetworkPolicy;

package/dist/src/shared/sandbox-network-policy.js

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

package/dist/src/shared/sandbox-session.d.ts

@@ -1,4 +1,5 @@
 import type { Experimental_Sandbox as AiSdkSandbox } from "ai";
+import type { SandboxNetworkPolicy } from "#shared/sandbox-network-policy.js";
 /**
  * Options for running one command in a sandbox. Shape mirrors the AI
  * SDK {@link AiSdkSandbox} `run` argument so authored code that targets
@@ -49,6 +50,19 @@ export type SandboxWriteBinaryFileOptions = Parameters<AiSdkSandbox["writeBinary
  * Options for writing one text file to a sandbox.
  */
 export type SandboxWriteTextFileOptions = Parameters<AiSdkSandbox["writeTextFile"]>[0];
+/**
+ * Options for removing a path from a sandbox.
+ *
+ * Relative paths resolve from `/workspace`; absolute paths pass through.
+ * `force` ignores missing paths. `recursive` permits removing non-empty
+ * directories.
+ */
+export interface SandboxRemovePathOptions {
+    readonly abortSignal?: AbortSignal;
+    readonly force?: boolean;
+    readonly path: string;
+    readonly recursive?: boolean;
+}
 /**
  * Public Ash-owned sandbox session exposed to authored lifecycle hooks.
  *
@@ -83,6 +97,26 @@ export interface SandboxSession extends Pick<AiSdkSandbox, "run" | "spawn" | "re
      * The read and write methods already apply this internally.
      */
     resolvePath(path: string): string;
+    /**
+     * Applies a firewall network policy to this live sandbox at run time —
+     * for changing the policy *during* a turn (e.g. brokering a credential
+     * resolved mid-turn, or tightening egress after fetching data). A
+     * per-domain `transform` injects headers at the firewall so secrets
+     * never enter the sandbox process. The policy takes effect from the time
+     * the call resolves, so await it before the egress you want governed.
+     *
+     * When the policy is known at session start, prefer configuring it up
+     * front in the sandbox backend factory or `onSession`'s `use()`. The
+     * local backend rejects this call: just-bash cannot update its network
+     * policy at run time and runs no binaries to govern.
+     */
+    setNetworkPolicy(policy: SandboxNetworkPolicy): Promise<void>;
+    /**
+     * Removes one file or directory from the sandbox filesystem.
+     *
+     * Relative paths resolve from `/workspace`; absolute paths pass through.
+     */
+    removePath(options: SandboxRemovePathOptions): Promise<void>;
 }
 /**
  * Internal sandbox session, used to construct the public {@link SandboxSession}.
@@ -103,6 +137,8 @@ export interface InternalSandboxSession extends Pick<AiSdkSandbox, "spawn" | "re
      * Stable identifier surfaced on the public {@link SandboxSession}.
      */
     readonly id: string;
+    /** Removes an already-resolved path from the backend filesystem. */
+    removePath(options: SandboxRemovePathOptions): Promise<void>;
     /** Translates a user-facing path to the backend's native path. */
     resolvePath(path: string): string;
 }

package/dist/src/shared/skill-package.d.ts

@@ -36,6 +36,13 @@ export declare function writeSkillPackageToSandbox(input: {
     readonly sandbox: SandboxSession;
     readonly skill: MaterializableSkillPackage;
 }): Promise<void>;
+/**
+ * Removes a skill package from the live sandbox.
+ */
+export declare function removeSkillPackageFromSandbox(input: {
+    readonly sandbox: SandboxSession;
+    readonly name: string;
+}): Promise<void>;
 /**
  * Validates a runtime-contributed skill name before it becomes one path
  * segment under `/workspace/skills`.

package/dist/src/shared/skill-package.js

@@ -1 +1 @@
-import{dirname,join}from"node:path";import{mkdir,writeFile}from"node:fs/promises";import{Buffer}from"node:buffer";function normalizeSkillPackage(e){assertSafeSkillPackageName(e.name);let t=[{content:Buffer.from(e.markdown,`utf8`),relativePath:`SKILL.md`}];for(let[n,r]of Object.entries(e.files??{}))assertSafeSkillPackageFilePath(n),t.push({content:contentToBuffer(r),relativePath:n});return t.sort((e,t)=>comparePaths(e.relativePath,t.relativePath)),{description:e.description,files:t,license:e.license,markdown:e.markdown,metadata:e.metadata===void 0?void 0:{...e.metadata},name:e.name}}async function writeSkillPackageDirectory(i){for(let a of i.skill.files){let o=join(i.rootPath,`skills`,i.skill.name,a.relativePath);await mkdir(dirname(o),{recursive:!0}),await writeFile(o,a.content)}}async function writeSkillPackageToSandbox(e){for(let t of e.skill.files)await e.sandbox.writeBinaryFile({content:t.content,path:`/workspace/skills/${e.skill.name}/${t.relativePath}`})}function assertSafeSkillPackageName(e){if(e.length===0||e.trim()!==e||e.startsWith(`.`)||e.includes(`/`)||e.includes(`\\`)||e.includes(`..`)||/^[A-Za-z]:/.test(e))throw Error(`Expected skill name to be a non-empty safe path segment without whitespace, separators, "." prefix, or "..".`)}function assertSafeSkillPackageFilePath(e){if(e===`SKILL.md`)throw Error(`Skill package files must not include "SKILL.md"; Ash generates it.`);if(e.length===0||e.startsWith(`/`)||e.includes(`\\`)||/^[A-Za-z]:/.test(e)||e.split(`/`).some(e=>e.length===0||e===`.`||e===`..`))throw Error(`Expected skill package file paths to be relative POSIX paths.`)}function contentToBuffer(e){return typeof e==`string`?Buffer.from(e,`utf8`):Buffer.from(e)}function comparePaths(e,t){return e<t?-1:+(e>t)}export{assertSafeSkillPackageName,normalizeSkillPackage,writeSkillPackageDirectory,writeSkillPackageToSandbox};
+import{dirname,join}from"node:path";import{mkdir,writeFile}from"node:fs/promises";import{Buffer}from"node:buffer";const WORKSPACE_ROOT=`/workspace`;function normalizeSkillPackage(e){assertSafeSkillPackageName(e.name);let t=[{content:Buffer.from(e.markdown,`utf8`),relativePath:`SKILL.md`}];for(let[n,r]of Object.entries(e.files??{}))assertSafeSkillPackageFilePath(n),t.push({content:contentToBuffer(r),relativePath:n});return t.sort((e,t)=>comparePaths(e.relativePath,t.relativePath)),{description:e.description,files:t,license:e.license,markdown:e.markdown,metadata:e.metadata===void 0?void 0:{...e.metadata},name:e.name}}async function writeSkillPackageDirectory(i){for(let a of i.skill.files){let o=join(i.rootPath,`skills`,i.skill.name,a.relativePath);await mkdir(dirname(o),{recursive:!0}),await writeFile(o,a.content)}}async function writeSkillPackageToSandbox(e){for(let t of e.skill.files)await e.sandbox.writeBinaryFile({content:t.content,path:`${WORKSPACE_ROOT}/skills/${e.skill.name}/${t.relativePath}`})}async function removeSkillPackageFromSandbox(e){assertSafeSkillPackageName(e.name),await e.sandbox.removePath({force:!0,path:`${WORKSPACE_ROOT}/skills/${e.name}`,recursive:!0})}function assertSafeSkillPackageName(e){if(e.length===0||e.startsWith(`.`)||e.includes(`/`)||e.includes(`\\`)||e.includes(`..`)||!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(e)||/^[A-Za-z]:/.test(e))throw Error(`Expected skill name to be a non-empty shell-safe path segment starting with an alphanumeric character and containing only alphanumerics, ".", "_", or "-".`)}function assertSafeSkillPackageFilePath(e){if(e===`SKILL.md`)throw Error(`Skill package files must not include "SKILL.md"; Ash generates it.`);if(e.length===0||e.startsWith(`/`)||e.includes(`\\`)||/^[A-Za-z]:/.test(e)||e.split(`/`).some(e=>e.length===0||e===`.`||e===`..`))throw Error(`Expected skill package file paths to be relative POSIX paths.`)}function contentToBuffer(e){return typeof e==`string`?Buffer.from(e,`utf8`):Buffer.from(e)}function comparePaths(e,t){return e<t?-1:+(e>t)}export{assertSafeSkillPackageName,normalizeSkillPackage,removeSkillPackageFromSandbox,writeSkillPackageDirectory,writeSkillPackageToSandbox};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-ash",
-  "version": "0.43.0",
+  "version": "0.45.0",
   "bin": {
     "ash": "./bin/ash.js",
     "experimental-ash": "./bin/ash.js"
@@ -188,7 +188,7 @@
     "@types/react": "19.2.15",
     "@types/react-test-renderer": "19.1.0",
     "@vercel/oidc": "3.5.0",
-    "@vercel/sandbox": "2.0.1",
+    "@vercel/sandbox": "2.1.0",
     "@workflow/core": "5.0.0-beta.10",
     "@workflow/errors": "5.0.0-beta.6",
     "@workflow/world": "5.0.0-beta.5",