experimental-ash 0.43.0 → 0.45.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # experimental-ash
 
+## 0.45.0
+
+### Minor Changes
+
+- 8672b13: Dynamic skills now clear stale model announcements when removed, reject duplicate dynamic names before materializing, and remove stale skill package directories through the Ash sandbox file API. Sandbox sessions also expose `removePath()` for deleting files or directory trees.
+
+## 0.44.0
+
+### Minor Changes
+
+- ed89a1b: Generate channel instrumentation metadata typings from authored `agent/channels/*` files so `input.channel.metadata` narrows after checking `input.channel.kind` or calling `isChannel(input.channel, channel)`.
+- 5faaf2b: Add `sandbox.setNetworkPolicy(policy)` to the live sandbox handle returned by `ctx.getSandbox()`, so any tool, hook, or channel event can apply a firewall network policy at run time — for cases where the policy must change _during_ a turn (e.g. brokering a credential resolved mid-turn). Configuring a policy known at session start in the backend factory or `onSession`'s `use()` remains valid and is often preferable; both accept the same `transform` shape for credential brokering, which injects headers at the firewall so secrets authenticate egress without entering the sandbox process. The local backend rejects `setNetworkPolicy` (just-bash applies its network policy only at creation and runs no binaries to govern). The `@vercel/sandbox` and `just-bash` network-policy types are now copied verbatim from the installed packages at vendor time (instead of hand-written stubs), so the brokering surface (`match`/`transform`/`forwardURL`/matchers, and just-bash's `allowedUrlPrefixes` transforms) never drifts.
+
 ## 0.43.0
 
 ### Minor Changes

package/bin/ash.js

@@ -18,6 +18,7 @@ function createBootstrapOptions(overrides = {}) {
       overrides.cliEntrypointPath ?? resolve(packageRoot, "dist", "src", "cli", "run.js"),
     packageRoot,
     postBuildScriptPaths: overrides.postBuildScriptPaths ?? [
+      resolve(packageRoot, "scripts", "copy-compiled-assets.mjs"),
       resolve(packageRoot, "scripts", "copy-docs.mjs"),
       resolve(packageRoot, "scripts", "stamp-version-tokens.mjs"),
     ],

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

@@ -49,6 +49,22 @@ This is enforced on three layers:
 Markdown frontmatter is treated the same way: `name:` is no longer a
 recognized field on system or skill markdown.
 
+## Release Metadata
+
+### Changeset Package Keys Match Workspace Names
+
+Changeset frontmatter must name the package exactly as it appears in that
+workspace package's `package.json`. Directory names, binary names, and
+marketing names are not valid substitutes; for example, the package under
+`packages/ash` is named `experimental-ash`.
+
+Enforcement: rule 29 in `scripts/guard-agents-rules.mjs` parses changeset
+YAML frontmatter with `gray-matter`, reads the package patterns from
+`pnpm-workspace.yaml`, resolves workspace package names from their
+`package.json` files, and fails if any `.changeset/*.md` package key does not
+match one of those names. This keeps invalid release metadata from reaching
+the post-merge `changesets/action` workflow.
+
 ## Runtime Boundaries
 
 ### Workflow APIs Stay In Runtime Code

package/dist/docs/public/advanced/instrumentation.md

@@ -61,32 +61,88 @@ Use `metadata["step.started"]` when the metadata depends on the current session,
 channel, or model input:
 
 ```ts
-import type { SlackInstrumentationMetadata } from "experimental-ash/channels/slack";
+import { defineInstrumentation } from "experimental-ash/instrumentation";
+
+export default defineInstrumentation({
+  metadata: {
+    "step.started"(input) {
+      if (input.channel.kind !== "channel:support") {
+        return {};
+      }
+
+      return {
+        "slack.channel_id": input.channel.metadata.channelId ?? "",
+        "slack.user_id": input.channel.metadata.triggeringUserId ?? "",
+      };
+    },
+  },
+});
+```
+
+For authored channels, TypeScript gets channel metadata types from a compiler-owned declaration
+file. When Ash compiles `agent/channels/support.ts`, it writes
+`.ash/compile/channel-instrumentation-types.d.ts` with a `ChannelMetadataMap` entry for the
+filename-derived kind and a `ChannelReferenceMap` entry for `isChannel`:
+
+```ts
+import type { InferChannelMetadata } from "experimental-ash/channels";
 
-// A Slack-backed channel authored at `agent/channels/support.ts` has kind
-// `channel:support` (its filename).
 declare module "experimental-ash/instrumentation" {
   interface ChannelMetadataMap {
-    readonly "channel:support": SlackInstrumentationMetadata;
+    readonly "channel:support": InferChannelMetadata<
+      typeof import("../../agent/channels/support.js").default
+    >;
+  }
+  interface ChannelReferenceMap {
+    readonly "channel:support": typeof import("../../agent/channels/support.js").default;
   }
 }
+```
+
+Keep `.ash/**/*.d.ts` in your app's `tsconfig.json` `include` list so TypeScript sees that file.
+Then either `input.channel.kind === "channel:support"` or `isChannel(input.channel, supportChannel)`
+narrows `input.channel.metadata` to the return type of the channel's `metadata(state)` function:
+
+```ts
+// agent/channels/support.ts
+import { defineChannel, POST } from "experimental-ash/channels";
+
+export default defineChannel({
+  state: { ticketId: null as string | null },
+  // Ash uses this function's runtime value for instrumentation metadata and
+  // makes its return type available to instrumentation.ts.
+  metadata(state) {
+    return { ticketId: state.ticketId };
+  },
+  routes: [POST("/support", async () => new Response("ok"))],
+});
+```
+
+```ts
+// agent/instrumentation.ts
+import { defineInstrumentation, isChannel } from "experimental-ash/instrumentation";
+
+import supportChannel from "./channels/support.js";
 
 export default defineInstrumentation({
   metadata: {
     "step.started"(input) {
-      if (input.channel.kind !== "channel:support") {
+      if (!isChannel(input.channel, supportChannel)) {
         return {};
       }
 
       return {
-        "slack.channel_id": input.channel.metadata.channelId ?? "",
-        "slack.user_id": input.channel.metadata.triggeringUserId ?? "",
+        "support.ticket_id": input.channel.metadata.ticketId ?? "",
       };
     },
   },
 });
 ```
 
+Built-in wrapper return types expose their concrete metadata too. For example, a file named
+`agent/channels/support.ts` that default-exports `slackChannel()` still narrows under
+`input.channel.kind === "channel:support"` to Slack's projected metadata shape.
+
 The callback runs after Ash has assembled the model input for the attempt and before constructing
 the AI SDK call. That timing lets the returned values attach to the AI SDK model-call span and its
 child spans. It runs for each model-call attempt, including a retry of the same logical step when
@@ -109,31 +165,25 @@ channels it is `channel:<name>`, where `<name>` is the channel's filename under
 Channel metadata is channel-owned. Built-in channels expose only the fields they choose to make
 observable; for example, Slack projects `channelId`, `teamId`, `threadTs`, and `triggeringUserId`
 from its durable channel state. User-authored channels expose their own projection by returning
-`metadata(state)` from `defineChannel`. To make TypeScript narrow `input.channel.metadata`,
-declaration-merge the same `channel:<name>` kind into `ChannelMetadataMap`:
+`metadata(state)` from `defineChannel`. Runtime instrumentation never falls back to raw channel
+state.
 
 `metadata(state)` must return an object composed of JSON primitives, arrays, and plain objects.
 Ash omits `undefined` object properties and drops projections containing values such as `Date` or
 `Map` with a warning.
 
+Manual `ChannelMetadataMap` declaration merging is only the escape hatch for unusual setups where
+the generated `.ash/**/*.d.ts` file is not available to the TypeScript program, or where a channel
+is typed outside the normal `agent/channels/<name>` compile path:
+
 ```ts
-import { defineChannel } from "experimental-ash/channels";
+import type { SlackInstrumentationMetadata } from "experimental-ash/channels/slack";
 
 declare module "experimental-ash/instrumentation" {
   interface ChannelMetadataMap {
-    readonly "channel:support": {
-      readonly triggeringUserId: string | null;
-    };
+    readonly "channel:support": SlackInstrumentationMetadata;
   }
 }
-
-export default defineChannel({
-  state: { triggeringUserId: null as string | null },
-  metadata(state) {
-    return { triggeringUserId: state.triggeringUserId };
-  },
-  routes: [],
-});
 ```
 
 Metadata failures are non-destructive. If the callback throws, returns a non-record, or returns

package/dist/docs/public/advanced/typescript-api.md

@@ -58,7 +58,7 @@ Session metadata, sandbox access, and skill access are available through the `ct
 passed to tool `execute`, hook handlers, and channel event handlers:
 
 - `ctx.session` - current session, turn, auth, and optional parent lineage
-- `ctx.getSandbox()` - live sandbox handle for the current agent
+- `ctx.getSandbox()` - live sandbox handle for the current agent; `sandbox.setNetworkPolicy(policy)` applies a firewall network policy at run time (egress control, credential brokering) without an `onSession` hook
 - `ctx.getSkill(identifier)` - handle for a named skill visible to the current agent
 - `defineState(name, initial)` - typed durable state with `get()` and `update()` (`experimental-ash/context`)
 

package/dist/docs/public/sandbox.md

@@ -359,6 +359,44 @@ or to apply it only after the template has been built, set it in `onSession`'s `
 common pattern: leave the factory open so `bootstrap` can `git clone` and `npm install`, then
 lock down via `onSession`.
 
+`onSession`'s `use()` (and the factory) accept the full policy shape, including per-domain
+`transform`s for **credential brokering** — injecting headers at the firewall so a secret
+authenticates egress without ever entering the sandbox process. When the brokered credential is
+known at session start, configuring it up front in `onSession` is the right choice:
+
+```ts
+onSession: async ({ use }) => {
+  await use({
+    networkPolicy: {
+      allow: {
+        "github.com": [{ transform: [{ headers: { authorization: "Basic …" } }] }],
+        "*": [],
+      },
+    },
+  });
+};
+```
+
+When the policy must change **during a turn** — to broker a credential resolved mid-turn, or to
+tighten egress after fetching data — call `setNetworkPolicy` on the live sandbox handle from a
+tool, hook, or channel event. It accepts the same policy shape:
+
+```ts
+const sandbox = await ctx.getSandbox();
+await sandbox.setNetworkPolicy({
+  allow: {
+    "github.com": [{ transform: [{ headers: { authorization: "Basic …" } }] }],
+    "*": [],
+  },
+});
+```
+
+The `"*": []` catch-all keeps general egress open while the `transform` applies only to
+`github.com`. The policy takes effect from the time the call resolves, so await it before the
+egress you want governed. The local backend rejects `setNetworkPolicy` — just-bash takes its
+network policy only at sandbox creation and runs no binaries to govern — so run-time updates are
+a Vercel-backend capability.
+
 ### Timeout
 
 Sandbox VMs shut down after a configurable timeout. Ash defaults to **30 minutes**. Set a different

package/dist/src/channel/compiled-channel.d.ts

@@ -3,7 +3,7 @@ import type { RouteHandler, SendFn } from "#channel/routes.js";
 import type { Session } from "#channel/session.js";
 import type { SessionAuthContext } from "#channel/types.js";
 export declare const CHANNEL_SENTINEL: "ash:channel";
-export interface CompiledChannel<TState = undefined, TReceiveArgs = Record<string, unknown>> {
+export interface CompiledChannel<TState = undefined, TReceiveArgs = Record<string, unknown>, TMetadata extends Record<string, unknown> = Record<string, unknown>> {
     readonly __kind: typeof CHANNEL_SENTINEL;
     readonly routes: readonly {
         method: string;
@@ -11,6 +11,7 @@ export interface CompiledChannel<TState = undefined, TReceiveArgs = Record<strin
         handler: RouteHandler<TState>;
     }[];
     readonly adapter: ChannelAdapter<any>;
+    readonly __metadata?: TMetadata;
     readonly receive?: (input: {
         readonly message: string;
         readonly args: Readonly<TReceiveArgs>;
@@ -20,3 +21,5 @@ export interface CompiledChannel<TState = undefined, TReceiveArgs = Record<strin
     }) => Promise<Session>;
 }
 export declare function isCompiledChannel(value: unknown): value is CompiledChannel;
+export declare function getChannelInstrumentationKind(value: unknown): string | undefined;
+export declare function setChannelInstrumentationKind(channel: CompiledChannel, kind: string): void;

package/dist/src/channel/compiled-channel.js

@@ -1 +1 @@
-const CHANNEL_SENTINEL=`ash:channel`;function isCompiledChannel(e){return typeof e==`object`&&!!e&&e.__kind===`ash:channel`}export{CHANNEL_SENTINEL,isCompiledChannel};
+const CHANNEL_SENTINEL=`ash:channel`,CHANNEL_INSTRUMENTATION_KIND=Symbol.for(`ash.channel.instrumentationKind`);function isCompiledChannel(e){return typeof e==`object`&&!!e&&e.__kind===`ash:channel`}function getChannelInstrumentationKind(e){if(!isCompiledChannel(e))return;let t=Reflect.get(e,CHANNEL_INSTRUMENTATION_KIND);if(typeof t==`string`&&t.length>0)return t;let n=e.adapter.kind;return typeof n==`string`&&n.startsWith(`channel:`)?n:void 0}function setChannelInstrumentationKind(e,t){Object.defineProperty(e,CHANNEL_INSTRUMENTATION_KIND,{configurable:!0,enumerable:!1,value:t})}export{CHANNEL_SENTINEL,getChannelInstrumentationKind,isCompiledChannel,setChannelInstrumentationKind};

package/dist/src/channel/routes.d.ts

@@ -32,6 +32,12 @@ export interface SendPayload {
     readonly modelContext?: readonly ModelMessage[];
 }
 export type SendFn<TState = undefined> = (input: string | UserContent | SendPayload, options: SendOptions<TState>) => Promise<Session>;
+type BaseSendOptions = {
+    auth: SessionAuthContext | null;
+    callback?: SessionCallback;
+    continuationToken: string;
+    mode?: RunMode;
+};
 /**
  * Options for {@link SendFn}. The channel owns its continuation-token
  * format — pass the channel-local raw token (the framework prepends
@@ -39,16 +45,7 @@ export type SendFn<TState = undefined> = (input: string | UserContent | SendPayl
  * state via {@link state}, which becomes the new session's `state`
  * on first `runtime.run()` and is ignored on subsequent `deliver`s.
  */
-export type SendOptions<TState = undefined> = TState extends undefined ? {
-    auth: SessionAuthContext | null;
-    callback?: SessionCallback;
-    continuationToken: string;
-    mode?: RunMode;
-} : {
-    auth: SessionAuthContext | null;
-    callback?: SessionCallback;
-    continuationToken: string;
-    mode?: RunMode;
+export type SendOptions<TState = undefined> = [TState] extends [undefined] ? BaseSendOptions : BaseSendOptions & {
     state: TState;
 };
 export type GetSessionFn = (sessionId: string) => Session;
@@ -63,3 +60,4 @@ export declare function POST<TState = undefined>(path: string, handler: RouteHan
 export declare function PUT<TState = undefined>(path: string, handler: RouteHandler<TState>): RouteDefinition<TState>;
 export declare function PATCH<TState = undefined>(path: string, handler: RouteHandler<TState>): RouteDefinition<TState>;
 export declare function DELETE<TState = undefined>(path: string, handler: RouteHandler<TState>): RouteDefinition<TState>;
+export {};

package/dist/src/compiled/.vendor-stamp.json

@@ -21,11 +21,11 @@
     "@standard-schema/spec": "1.1.0",
     "turndown": "7.2.4",
     "@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",
     "zod": "4.4.3",
     "zod-validation-error": "5.0.0"
   },
-  "scriptHash": "27a236d633a4d9d7191418c0c9eb03158389a9de5ca9a6b54bd35b754147c7f6"
+  "scriptHash": "3ca25d8480d76331751f15b85150bcb6cea056aa28c4fc04012dddcdaccae3e5"
 }

package/dist/src/compiled/@vercel/sandbox/index.d.ts

@@ -1,23 +1,16 @@
-export interface NetworkTransformer {
-  headers?: Record<string, string> | undefined;
-}
-
-export interface NetworkPolicyRule {
-  transform?: NetworkTransformer[] | undefined;
-}
+// The firewall network-policy types are copied verbatim from the installed
+// `@vercel/sandbox` at vendor time (see scripts/vendor-compiled/@vercel/sandbox.mjs)
+// so the credential-brokering surface never drifts from the SDK.
+import type { NetworkPolicy } from "./network-policy.js";
 
-export type NetworkPolicy =
-  | "allow-all"
-  | "deny-all"
-  | {
-      allow?: string[] | Record<string, NetworkPolicyRule[]> | undefined;
-      subnets?:
-        | {
-            allow?: string[] | undefined;
-            deny?: string[] | undefined;
-          }
-        | undefined;
-    };
+export type {
+  NetworkPolicy,
+  NetworkPolicyKeyValueMatcher,
+  NetworkPolicyMatch,
+  NetworkPolicyMatcher,
+  NetworkPolicyRule,
+  NetworkTransformer,
+} from "./network-policy.js";
 
 export interface SandboxKeepLastSnapshotsConfig {
   count: number;
@@ -70,6 +63,17 @@ export interface SandboxRunCommandParams {
   sudo?: boolean | undefined;
 }
 
+export interface SandboxRmOptions {
+  force?: boolean | undefined;
+  recursive?: boolean | undefined;
+  signal?: AbortSignal | undefined;
+}
+
+export declare class FileSystem {
+  rm(path: string, options?: SandboxRmOptions): Promise<void>;
+  unlink(path: string, options?: { signal?: AbortSignal | undefined }): Promise<void>;
+}
+
 export interface SandboxCommandLogMessage {
   data: string;
   stream: "stdout" | "stderr";
@@ -96,6 +100,7 @@ export type SandboxCommandResult = SandboxCommandFinished;
 
 export declare class Sandbox {
   currentSnapshotId?: string | undefined;
+  readonly fs: FileSystem;
   id: string;
   name: string;
   networkPolicy?: NetworkPolicy | undefined;