experimental-ash 0.43.0 → 0.44.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # experimental-ash
 
+## 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

@@ -27,5 +27,5 @@
     "zod": "4.4.3",
     "zod-validation-error": "5.0.0"
   },
-  "scriptHash": "27a236d633a4d9d7191418c0c9eb03158389a9de5ca9a6b54bd35b754147c7f6"
+  "scriptHash": "8ef773103edd72d1005178f52b446202a32dc5257541b1990f54dba807b3bbb5"
 }

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;

package/dist/src/compiled/@vercel/sandbox/network-policy.d.ts

@@ -0,0 +1,161 @@
+//#region src/network-policy.d.ts
+/**
+ * A transform applied to network requests matching a domain rule.
+ *
+ * @example
+ * {
+ *   headers: { authorization: "Bearer sk-..." }
+ * }
+ */
+type NetworkTransformer = {
+  /** Headers to set on the outgoing request. */
+  headers?: Record<string, string>;
+};
+/**
+ * Defines how a request value is matched.
+ */
+type NetworkPolicyMatcher = {
+  /** Match the value exactly. */
+  exact?: string;
+} | {
+  /** Match values that start with the provided prefix. */
+  startsWith?: string;
+} | {
+  /** Match values against an RE2 regular expression. */
+  regex?: string;
+};
+/**
+ * Matcher for key/value request entries such as headers and query parameters.
+ */
+type NetworkPolicyKeyValueMatcher = {
+  /** Matcher for the entry key. */
+  key?: NetworkPolicyMatcher;
+  /** Matcher for the entry value. */
+  value?: NetworkPolicyMatcher;
+};
+/**
+ * Request matcher for a network policy rule.
+ *
+ * All specified dimensions must match. Multiple methods are ORed; multiple
+ * header and query-string matchers are ANDed.
+ */
+type NetworkPolicyMatch = {
+  /** Match on the request path. */
+  path?: NetworkPolicyMatcher;
+  /** Match on the HTTP method. */
+  method?: string[];
+  /** Match on query-string entries. */
+  queryString?: NetworkPolicyKeyValueMatcher[];
+  /** Match on request headers. */
+  headers?: NetworkPolicyKeyValueMatcher[];
+};
+/**
+ * A rule applied to requests matching a domain in the network policy.
+ */
+type NetworkPolicyRule = {
+  /**
+   * Optional request matcher. When provided, transforms only apply to requests
+   * that match every specified dimension.
+   */
+  match?: NetworkPolicyMatch;
+  /**
+   * Transforms to apply to matching requests.
+   */
+  transform?: NetworkTransformer[];
+  /**
+   * HTTPS proxy URL to forward matching requests to. Must not include query string or fragment.
+   *
+   * You can use the `defineSandboxProxy` helper from `@vercel/sandbox/proxy` to implement the proxy handler
+   * automatically, which handles authorization and extracts metadata about the request and sandbox.
+   *
+   * @see https://vercel.com/docs/vercel-sandbox/concepts/firewall#requests-proxying
+   */
+  forwardURL?: string;
+};
+/**
+ * Network policy to define network restrictions for the sandbox.
+ *
+ * - `"allow-all"`: Full internet access (default). All traffic is allowed.
+ * - `"deny-all"`: No internet access. All traffic is denied.
+ * - Object: Custom access with explicit allow/deny lists.
+ *
+ * @example
+ * // Full internet access (default)
+ * "allow-all"
+ *
+ * @example
+ * // No external access
+ * "deny-all"
+ *
+ * @example
+ * // Custom access with specific domains (simple list)
+ * // All traffic not explicitly allowed is denied.
+ * {
+ *   allow: ["*.npmjs.org", "github.com"],
+ *   subnets: {
+ *     allow: ["10.0.0.0/8"],
+ *     deny: ["10.1.0.0/16"]
+ *   }
+ * }
+ *
+ * @example
+ * // Custom access with specific domains (record form)
+ * {
+ *   allow: {
+ *     "*.npmjs.org": [],
+ *     "github.com": [],
+ *   }
+ * }
+ *
+ * @example
+ * // Custom access with request transformers
+ * {
+ *   allow: {
+ *     "ai-gateway.vercel.sh": [
+ *       {
+ *         match: {
+ *           method: ["POST"],
+ *           path: { startsWith: "/v1/" },
+ *           headers: [
+ *             { key: { exact: "x-api-key" }, value: { exact: "placeholder" } }
+ *           ]
+ *         },
+ *         transform: [{
+ *           headers: { authorization: "Bearer ..." }
+ *         }]
+ *       }
+ *     ],
+ *     "*": []
+ *   }
+ * }
+ */
+type NetworkPolicy = "allow-all" | "deny-all" | {
+  /**
+   * Domains to allow traffic to.
+   * Use "*" prefix for wildcard matching (e.g., "*.npmjs.org").
+   *
+   * Accepts either:
+   * - `string[]`: A simple list of domains to allow.
+   * - `Record<string, NetworkPolicyRule[]>`: A map of domains to rules.
+   *   An empty array allows traffic with no additional rules.
+   */
+  allow?: string[] | Record<string, NetworkPolicyRule[]>;
+  /**
+   * Subnet-level access control using CIDR notation.
+   */
+  subnets?: {
+    /**
+     * List of CIDRs to allow traffic to.
+     * Traffic to these addresses will bypass the domain allowlist.
+     */
+    allow?: string[];
+    /**
+     * List of CIDRs to deny traffic to.
+     * These take precedence over allowed domains and CIDRs.
+     */
+    deny?: string[];
+  };
+};
+//#endregion
+export { NetworkPolicy, NetworkPolicyKeyValueMatcher, NetworkPolicyMatch, NetworkPolicyMatcher, NetworkPolicyRule, NetworkTransformer };
+//# sourceMappingURL=network-policy.d.ts.map

package/dist/src/compiled/just-bash/index.d.ts

@@ -1,3 +1,16 @@
+// The network-policy types are copied verbatim from the installed just-bash at
+// vendor time (see scripts/vendor-compiled/just-bash.mjs) so the credential-
+// brokering surface (allowedUrlPrefixes + header transforms) never drifts.
+import type { NetworkConfig } from "./network/types.js";
+
+export type {
+  AllowedUrl,
+  AllowedUrlEntry,
+  HttpMethod,
+  NetworkConfig,
+  RequestTransform,
+} from "./network/types.js";
+
 export type InitialFileContent = string | Uint8Array;
 export type InitialFiles = Record<string, InitialFileContent>;
 
@@ -17,7 +30,7 @@ export interface BashOptions {
   cwd: string;
   env?: Readonly<Record<string, string>> | undefined;
   fs: IFileSystem;
-  network?: { dangerouslyAllowFullInternetAccess?: boolean | undefined } | undefined;
+  network?: NetworkConfig | undefined;
 }
 
 export interface BashExecResult {
@@ -50,7 +63,7 @@ export interface SandboxOptions {
   cwd?: string | undefined;
   env?: Record<string, string> | undefined;
   fs?: IFileSystem | undefined;
-  network?: { dangerouslyAllowFullInternetAccess?: boolean | undefined } | undefined;
+  network?: NetworkConfig | undefined;
   timeoutMs?: number | undefined;
 }