experimental-ash 0.42.0 → 0.44.0

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

@@ -75,6 +75,8 @@ export interface FetchFileResult {
     readonly mediaType?: string;
     readonly filename?: string;
 }
+export type ChannelInstrumentationMetadata = Readonly<Record<string, unknown>>;
+export type ChannelInstrumentationMetadataProjector = (state: Record<string, unknown> | undefined) => ChannelInstrumentationMetadata;
 /**
  * Plain-object channel adapter with durable state, an optional inbound
  * delivery hook, event handlers, and optional attachment resolution.
@@ -122,6 +124,17 @@ export type ChannelAdapter<TCtx extends ChannelAdapterContext<any> = ChannelAdap
      * construction time.
      */
     readonly fetchFile?: (url: string) => Promise<Buffer | FetchFileResult | null>;
+    /**
+     * Framework-owned observability projection for the active channel.
+     *
+     * Channel implementations decide which state fields are safe and
+     * meaningful to expose to instrumentation callbacks. The harness reads
+     * the resulting projection through a seed context key rather than
+     * inspecting adapter state directly.
+     */
+    readonly instrumentation?: {
+        readonly metadata?: ChannelInstrumentationMetadataProjector;
+    };
 } & ChannelEventHandlers<TCtx>;
 /**
  * Produces the default {@link StepInput} when no custom adapter `deliver`

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/instrumentation.d.ts

@@ -0,0 +1,10 @@
+import type { ChannelAdapter, ChannelInstrumentationMetadata } from "#channel/adapter.js";
+export interface ChannelInstrumentationProjection {
+    readonly kind: string;
+    readonly metadata: ChannelInstrumentationMetadata;
+}
+export declare function buildChannelInstrumentationProjection(input: {
+    readonly adapter: ChannelAdapter;
+    readonly channelName?: string;
+    readonly existingKind?: string;
+}): ChannelInstrumentationProjection;

package/dist/src/channel/instrumentation.js

@@ -0,0 +1 @@
+import{createLogger}from"#internal/logging.js";import{getAdapterKind}from"#channel/adapter.js";import{isInstrumentationChannelKind,resolveInstrumentationProjection}from"#internal/instrumentation.js";const log=createLogger(`channel.instrumentation`);function buildChannelInstrumentationProjection(e){let{adapter:t,channelName:n,existingKind:r}=e;return{kind:resolveKind({adapter:t,channelName:n,existingKind:r}),metadata:resolveMetadata(t)}}function resolveKind(e){let{adapter:r,channelName:i,existingKind:a}=e;if(a!==void 0)return a;if(i!==void 0&&i.length>0)return`channel:${i}`;let o=getAdapterKind(r);return isInstrumentationChannelKind(o)?o:`channel:${o}`}function resolveMetadata(e){let n=e.instrumentation?.metadata;return n===void 0?{}:resolveInstrumentationProjection({invoke:()=>n(e.state),log,source:getAdapterKind(e)})??{}}export{buildChannelInstrumentationProjection};

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/channel/send.js

@@ -1 +1 @@
-import{createSession}from"#channel/session.js";import{createLogger}from"#internal/logging.js";import{isRuntimeNoActiveSessionError}from"#execution/runtime-errors.js";import{serializeUrlFilePart}from"#internal/attachments/url-refs.js";const log=createLogger(`channel.send`);function createSendFn(t,r,i){return async(a,o)=>{let s=o.auth,c=o.callback,l=o.mode??`conversation`,u=o.state,d=o.continuationToken,f=`${i}:${d}`,{message:p,inputResponses:m,modelContext:h}=normalizeSendInput(a),g=serializeUrlFilePartsInMessage(p);try{let{sessionId:n}=await t.deliver({auth:s,continuationToken:f,payload:{inputResponses:m,message:g,modelContext:h}});return createSession(n,d,t)}catch(e){isRuntimeNoActiveSessionError(e)||log.warn(`deliver failed, falling back to starting a new session`,{continuationToken:f})}if(m&&m.length>0)throw Error(`Cannot deliver inputResponses — the target session was not found via continuation token.`);let _=u?{...r,state:{...r.state,...u}}:r;return createSession((await t.run({adapter:_,auth:s,capabilities:l===`conversation`?{requestInput:!0}:void 0,callback:c,continuationToken:f,input:{message:g??``,modelContext:h},mode:l})).sessionId,d,t)}}function serializeUrlFilePartsInMessage(e){if(e===void 0||typeof e==`string`)return e;let t=!1,n=e.map(e=>e.type===`file`&&e.data instanceof URL&&e.data.protocol!==`data:`?(t=!0,{...e,data:serializeUrlFilePart(e.data)}):e);return t?n:e}function normalizeSendInput(e){return typeof e==`string`||Array.isArray(e)?{message:e}:e}export{createSendFn};
+import{createSession}from"#channel/session.js";import{createLogger}from"#internal/logging.js";import{isRuntimeNoActiveSessionError}from"#execution/runtime-errors.js";import{serializeUrlFilePart}from"#internal/attachments/url-refs.js";const log=createLogger(`channel.send`);function createSendFn(t,r,i){return async(a,o)=>{let s=o.auth,c=o.callback,l=o.mode??`conversation`,u=o.state,d=o.continuationToken,f=`${i}:${d}`,{message:p,inputResponses:m,modelContext:h}=normalizeSendInput(a),g=serializeUrlFilePartsInMessage(p);try{let{sessionId:n}=await t.deliver({auth:s,continuationToken:f,payload:{inputResponses:m,message:g,modelContext:h}});return createSession(n,d,t)}catch(e){isRuntimeNoActiveSessionError(e)||log.warn(`deliver failed, falling back to starting a new session`,{continuationToken:f})}if(m&&m.length>0)throw Error(`Cannot deliver inputResponses — the target session was not found via continuation token.`);let _=u?{...r,state:{...r.state,...u}}:r;return createSession((await t.run({adapter:_,auth:s,capabilities:l===`conversation`?{requestInput:!0}:void 0,channelName:i,callback:c,continuationToken:f,input:{message:g??``,modelContext:h},mode:l})).sessionId,d,t)}}function serializeUrlFilePartsInMessage(e){if(e===void 0||typeof e==`string`)return e;let t=!1,n=e.map(e=>e.type===`file`&&e.data instanceof URL&&e.data.protocol!==`data:`?(t=!0,{...e,data:serializeUrlFilePart(e.data)}):e);return t?n:e}function normalizeSendInput(e){return typeof e==`string`||Array.isArray(e)?{message:e}:e}export{createSendFn};

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

@@ -5,6 +5,7 @@ import type { RuntimeActionResult } from "#runtime/actions/types.js";
 import type { InputRequest, InputResponse } from "#runtime/input/types.js";
 import type { ChannelAdapter } from "#channel/adapter.js";
 export type { ContextAccessor } from "#context/key.js";
+export type { ChannelInstrumentationProjection } from "#channel/instrumentation.js";
 /**
  * Identifies one turn within a session.
  */
@@ -15,8 +16,17 @@ export interface SessionTurn {
 /**
  * Stable lineage metadata describing the immediate Ash parent execution that
  * delegated the current session.
+ *
+ * `sessionId` and `turn` always describe the **immediate** parent — the
+ * agent that dispatched this child. `rootSessionId` denormalizes the top
+ * of the dispatch chain so descendants can identify the user-facing
+ * session without walking back up parent-by-parent. It is always
+ * populated at dispatch: a first-level child sets it to the top
+ * session's id (its immediate parent), and deeper descendants inherit
+ * the same root.
  */
 export interface SessionParent {
+    readonly rootSessionId: string;
     readonly sessionId: string;
     readonly turn: SessionTurn;
 }
@@ -162,6 +172,12 @@ export interface SessionCapabilities {
  */
 export interface RunInput {
     readonly adapter: ChannelAdapter<any>;
+    /**
+     * Registered channel name for root sessions started from an authored
+     * channel route. Framework runs omit this and use their framework
+     * adapter kind (`http`, `schedule`, `subagent`) directly.
+     */
+    readonly channelName?: string;
     /**
      * Authenticated caller principal for this session. `null` means the
      * request was accepted with no credentials.

package/dist/src/cli/commands/channels.d.ts

@@ -1,4 +1,4 @@
-import { type RunAddToAgentOptions } from "@vercel/ash-scaffold/steps";
+import { type DeployProjectOptions, type RunAddToAgentOptions } from "@vercel/ash-scaffold/steps";
 import { type ChannelAddPrompter } from "@vercel/ash-scaffold/cli";
 import { type DeploymentInfo } from "@vercel/ash-scaffold/primitives";
 export interface CliLogger {
@@ -11,6 +11,7 @@ export interface AddChannelCommandOptions {
 export interface ChannelsAddDependencies {
     createPrompter?: () => ChannelAddPrompter;
     detectDeployment(projectPath: string): Promise<DeploymentInfo>;
+    deployProject(options: DeployProjectOptions): Promise<void>;
     runAddToAgent(options: RunAddToAgentOptions): Promise<void>;
 }
 export declare function runChannelsAddCommand(logger: CliLogger, appRoot: string, args: {

package/dist/src/cli/commands/channels.js

@@ -1 +1 @@
-import{assertCanAddSelectedChannels,inspectExistingChannelRegistrations}from"./channel-add-conflicts.js";import{isAshProject}from"../../packages/ash-scaffold/src/project.js";import{listAuthoredChannels}from"../../packages/ash-scaffold/src/channels.js";import"../../packages/ash-scaffold/src/index.js";import{detectDeployment}from"../../packages/ash-scaffold/src/primitives/detect-deployment.js";import{createAddToAgentState,runAddToAgent}from"../../packages/ash-scaffold/src/steps/run-add-to-agent.js";import"../../packages/ash-scaffold/src/steps/index.js";import{ChannelAddCancelledError,createChannelAddPrompter}from"../../packages/ash-scaffold/src/cli/channel-add-prompter.js";import"../../packages/ash-scaffold/src/cli/index.js";import"../../packages/ash-scaffold/src/primitives/index.js";const NOT_AN_AGENT_MESSAGE="No Ash agent in this directory. Run `pnpm create experimental-ash-agent`, then run this command from inside the new project.",KNOWN_CHANNEL_KINDS=[`slack`,`web`];function isChannelKind(e){return KNOWN_CHANNEL_KINDS.includes(e)}function parseChannelKind(e){if(!isChannelKind(e))throw Error(`Unknown channel kind "${e}". Known: ${KNOWN_CHANNEL_KINDS.join(`, `)}.`);return e}const defaultChannelsAddDependencies={detectDeployment,runAddToAgent};async function runAddChannelsFlow(n,r,i,o){if(r===void 0&&(!process.stdin.isTTY||!process.stdout.isTTY))throw Error(`Pass a channel kind: \`ash channels add <${KNOWN_CHANNEL_KINDS.join(`|`)}>\`.`);let s=o.createPrompter?.()??createChannelAddPrompter();s.intro(`Add channels to your Ash agent`),s.log.message(`Checking the current Vercel project...`);let c=createAddToAgentState(await o.detectDeployment(n)),l;function inspectRegistrations(){return l===void 0&&(s.log.message(`Inspecting existing channel registrations...`),l=inspectExistingChannelRegistrations(n)),l}let u=r===void 0?(await inspectRegistrations()).disabledChannelReasons:void 0;await o.runAddToAgent({prompter:s,projectPath:n,state:c,presetChannels:r===void 0?void 0:[r],disabledChannelReasons:u,force:i.force,validateSelectedChannels:async t=>{!t.includes(`web`)&&!t.includes(`slack`)||assertCanAddSelectedChannels(t,await inspectRegistrations())}}),s.outro(c.channels.length===0?`No channels added.`:`Channels added.`)}async function runChannelsAddCommand(e,t,r,i=defaultChannelsAddDependencies){if(!await isAshProject(t)){e.error(NOT_AN_AGENT_MESSAGE),process.exitCode=1;return}try{await runAddChannelsFlow(t,r.kind===void 0?void 0:parseChannelKind(r.kind),r.options,i)}catch(t){if(t instanceof ChannelAddCancelledError)return;e.error(t instanceof Error?t.message:String(t)),process.exitCode=1}}async function runChannelsListCommand(e,t,i){if(!await isAshProject(t)){e.error(NOT_AN_AGENT_MESSAGE),process.exitCode=1;return}let a=await listAuthoredChannels(t);if(i.json){e.log(JSON.stringify({channels:a},null,2));return}if(a.length===0){e.log("No channels defined. Run `ash channels add` to add one.");return}for(let t of a)e.log(t)}export{runChannelsAddCommand,runChannelsListCommand};
+import{assertCanAddSelectedChannels,inspectExistingChannelRegistrations}from"./channel-add-conflicts.js";import{isAshProject}from"../../packages/ash-scaffold/src/project.js";import{listAuthoredChannels}from"../../packages/ash-scaffold/src/channels.js";import"../../packages/ash-scaffold/src/index.js";import{detectDeployment}from"../../packages/ash-scaffold/src/primitives/detect-deployment.js";import{createAddToAgentState,deployProject,runAddToAgent}from"../../packages/ash-scaffold/src/steps/run-add-to-agent.js";import"../../packages/ash-scaffold/src/steps/index.js";import{ChannelAddCancelledError,createChannelAddPrompter}from"../../packages/ash-scaffold/src/cli/channel-add-prompter.js";import"../../packages/ash-scaffold/src/cli/index.js";import"../../packages/ash-scaffold/src/primitives/index.js";const NOT_AN_AGENT_MESSAGE="No Ash agent in this directory. Run `pnpm create experimental-ash-agent`, then run this command from inside the new project.",KNOWN_CHANNEL_KINDS=[`slack`,`web`];function isChannelKind(e){return KNOWN_CHANNEL_KINDS.includes(e)}function parseChannelKind(e){if(!isChannelKind(e))throw Error(`Unknown channel kind "${e}". Known: ${KNOWN_CHANNEL_KINDS.join(`, `)}.`);return e}const defaultChannelsAddDependencies={detectDeployment,deployProject,runAddToAgent};async function runAddChannelsFlow(n,r,i,o){if(r===void 0&&(!process.stdin.isTTY||!process.stdout.isTTY))throw Error(`Pass a channel kind: \`ash channels add <${KNOWN_CHANNEL_KINDS.join(`|`)}>\`.`);let s=o.createPrompter?.()??createChannelAddPrompter();s.intro(`Add channels to your Ash agent`),s.log.message(`Checking the current Vercel project...`);let c=createAddToAgentState(await o.detectDeployment(n)),l;function inspectRegistrations(){return l===void 0&&(s.log.message(`Inspecting existing channel registrations...`),l=inspectExistingChannelRegistrations(n)),l}let u=r===void 0?(await inspectRegistrations()).disabledChannelReasons:void 0;await o.runAddToAgent({prompter:s,projectPath:n,state:c,presetChannels:r===void 0?void 0:[r],disabledChannelReasons:u,force:i.force,validateSelectedChannels:async t=>{!t.includes(`web`)&&!t.includes(`slack`)||assertCanAddSelectedChannels(t,await inspectRegistrations())}}),await o.deployProject({prompter:s,projectPath:n,vercelProjectId:c.vercelProjectId,state:c}),s.outro(c.channels.length===0?`No channels added.`:`Channels added.`)}async function runChannelsAddCommand(e,t,r,i=defaultChannelsAddDependencies){if(!await isAshProject(t)){e.error(NOT_AN_AGENT_MESSAGE),process.exitCode=1;return}try{await runAddChannelsFlow(t,r.kind===void 0?void 0:parseChannelKind(r.kind),r.options,i)}catch(t){if(t instanceof ChannelAddCancelledError)return;e.error(t instanceof Error?t.message:String(t)),process.exitCode=1}}async function runChannelsListCommand(e,t,i){if(!await isAshProject(t)){e.error(NOT_AN_AGENT_MESSAGE),process.exitCode=1;return}let a=await listAuthoredChannels(t);if(i.json){e.log(JSON.stringify({channels:a},null,2));return}if(a.length===0){e.log("No channels defined. Run `ash channels add` to add one.");return}for(let t of a)e.log(t)}export{runChannelsAddCommand,runChannelsListCommand};

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;
 }
 

package/dist/src/compiled/just-bash/network/types.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Network configuration types
+ *
+ * Network access is disabled by default. To enable network access (e.g., for curl),
+ * you must explicitly configure allowed URLs.
+ */
+/**
+ * DNS lookup result used for private IP resolution checks
+ */
+export interface DnsLookupResult {
+    address: string;
+    family: number;
+}
+/**
+ * HTTP methods that can be allowed
+ */
+export type HttpMethod = "GET" | "HEAD" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS";
+/**
+ * Header transform applied at the fetch boundary.
+ * Headers specified here override any user-supplied headers with the same name.
+ */
+export interface RequestTransform {
+    headers: Record<string, string>;
+}
+/**
+ * An allowed URL entry with optional header transforms.
+ * Transforms are applied at the fetch boundary so secrets never enter the sandbox.
+ */
+export interface AllowedUrl {
+    url: string;
+    transform?: RequestTransform[];
+}
+/**
+ * An entry in the allowedUrlPrefixes list: either a plain URL string or
+ * an object with a URL and optional transforms.
+ */
+export type AllowedUrlEntry = string | AllowedUrl;
+/**
+ * Configuration for network access
+ */
+export interface NetworkConfig {
+    /**
+     * List of allowed URL prefixes. Each entry must be a full origin (scheme + host),
+     * optionally followed by a path prefix:
+     * - An origin: "https://api.example.com" - allows all paths on this origin
+     * - An origin + path prefix: "https://api.example.com/v1/" - allows only paths starting with /v1/
+     *
+     * Entries can be plain strings or objects with transforms for credentials brokering:
+     * ```
+     * allowedUrlPrefixes: [
+     *   "https://other-api.com",
+     *   {
+     *     url: "https://ai-gateway.vercel.sh",
+     *     transform: [{ headers: { "Authorization": "Bearer secret" } }],
+     *   },
+     * ]
+     * ```
+     *
+     * The check is performed on the full URL, so "https://api.example.com/v1" will allow:
+     * - https://api.example.com/v1
+     * - https://api.example.com/v1/users
+     * - https://api.example.com/v1/users/123
+     *
+     * But NOT:
+     * - https://api.example.com/v10
+     * - https://api.example.com/v1-admin
+     * - https://api.example.com/v2/users
+     * - https://api.example.org/v1/users (different origin)
+     * - URLs that rely on ambiguous encoded separators like %2f or %5c
+     *
+     * Invalid entries (missing scheme, missing host, relative paths) will throw an error.
+     */
+    allowedUrlPrefixes?: AllowedUrlEntry[];
+    /**
+     * List of allowed HTTP methods. Defaults to ["GET", "HEAD"] for safety.
+     * dangerouslyAllowFullInternetAccess to enables all methods.
+     */
+    allowedMethods?: HttpMethod[];
+    /**
+     * Bypass the allow-list and allow all URLs and methods.
+     * DANGEROUS: Only use this in trusted environments.
+     */
+    dangerouslyAllowFullInternetAccess?: boolean;
+    /**
+     * Maximum number of redirects to follow (default: 20)
+     */
+    maxRedirects?: number;
+    /**
+     * Request timeout in milliseconds (default: 30000)
+     */
+    timeoutMs?: number;
+    /**
+     * Maximum response body size in bytes (default: 10MB).
+     * Responses larger than this will be rejected with ResponseTooLargeError.
+     */
+    maxResponseSize?: number;
+    /**
+     * Reject URLs with private/loopback IP addresses as hostnames.
+     * Performs both lexical hostname checks and DNS resolution to catch
+     * domains that resolve to private IPs (e.g., DNS rebinding attacks).
+     * Useful for mitigating SSRF attacks. Default: false (opt-in).
+     *
+     * When enabled, the private IP check is enforced even when
+     * `dangerouslyAllowFullInternetAccess` is true, ensuring that
+     * internal/loopback addresses are never reachable.
+     */
+    denyPrivateRanges?: boolean;
+    /**
+     * @internal Override DNS resolution for testing.
+     * When set, used instead of the default `dns.lookup` for the
+     * denyPrivateRanges DNS rebinding check.
+     */
+    _dnsResolve?: (hostname: string) => Promise<DnsLookupResult[]>;
+}
+/**
+ * Result of a network fetch operation
+ */
+export interface FetchResult {
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    /** Raw response bytes (never decoded as UTF-8 text). */
+    body: Uint8Array;
+    url: string;
+}
+/**
+ * Error thrown when a URL is not allowed
+ */
+export declare class NetworkAccessDeniedError extends Error {
+    constructor(url: string, reason?: string);
+}
+/**
+ * Error thrown when too many redirects occur
+ */
+export declare class TooManyRedirectsError extends Error {
+    constructor(maxRedirects: number);
+}
+/**
+ * Error thrown when a redirect target is not allowed
+ */
+export declare class RedirectNotAllowedError extends Error {
+    constructor(url: string);
+}
+/**
+ * Error thrown when an HTTP method is not allowed
+ */
+export declare class MethodNotAllowedError extends Error {
+    constructor(method: string, allowedMethods: string[]);
+}
+/**
+ * Error thrown when a response body exceeds the maximum allowed size
+ */
+export declare class ResponseTooLargeError extends Error {
+    constructor(maxSize: number);
+}

package/dist/src/compiler/artifacts.d.ts

@@ -22,6 +22,7 @@ export declare const COMPILE_METADATA_VERSION = 5;
  */
 export interface CompilerArtifactPaths {
     appRoot: string;
+    channelInstrumentationTypesPath: string;
     compiledManifestPath: string;
     compileDirectoryPath: string;
     compileMetadataPath: string;

package/dist/src/compiler/artifacts.js

@@ -1 +1 @@
-import{join,relative,resolve}from"node:path";import{mkdir,writeFile}from"node:fs/promises";import{resolveInstalledPackageInfo}from"#internal/application/package.js";import{createHash}from"node:crypto";import{summarizeDiscoverDiagnostics}from"#discover/diagnostics.js";import{normalizeLogicalPath}from"#discover/filesystem.js";import{createCompiledModuleMapSource}from"#compiler/module-map.js";import{compileAgentManifest}from"#compiler/normalize-manifest.js";import{materializeWorkspaceResources}from"#compiler/workspace-resources.js";const COMPILE_METADATA_KIND=`ash-compile-metadata`,COMPILE_METADATA_VERSION=5;function resolveCompilerArtifactPaths(t){let r=resolve(t),i=join(r,`.ash`,`discovery`),a=join(r,`.ash`,`compile`);return{appRoot:r,compiledManifestPath:join(a,`compiled-agent-manifest.json`),compileDirectoryPath:a,compileMetadataPath:join(a,`compile-metadata.json`),diagnosticsPath:join(i,`diagnostics.json`),discoveryManifestPath:join(i,`agent-discovery-manifest.json`),discoveryDirectoryPath:i,moduleMapPath:join(a,`module-map.mjs`)}}function createDiscoveryDiagnosticsArtifact(e){return{diagnostics:[...e],kind:`ash-discovery-diagnostics`,summary:summarizeDiscoverDiagnostics(e),version:1}}function createCompileMetadata(e){let t=resolveInstalledPackageInfo(),n=createContentHash(e.discoveryManifestJson),r=createContentHash(e.diagnosticsArtifactJson),i=createContentHash(e.moduleMapSource);return{compile:{moduleMap:{path:toArtifactRelativePath(e.appRoot,e.paths.moduleMapPath),sha256:i}},discovery:{diagnostics:{path:toArtifactRelativePath(e.appRoot,e.paths.diagnosticsPath),sha256:r},manifest:{path:toArtifactRelativePath(e.appRoot,e.paths.discoveryManifestPath),sha256:n},sourceGraphHash:createContentHash(`${n}:${r}:${i}`),summary:e.diagnosticsSummary},generator:{name:t.name,version:t.version},kind:COMPILE_METADATA_KIND,status:e.diagnosticsSummary.errors>0?`failed`:`ready`,version:5}}async function writeCompilerArtifacts(e){let t=resolveCompilerArtifactPaths(e.appRoot),n=createDiscoveryDiagnosticsArtifact(e.diagnostics),a=await materializeWorkspaceResources({compileDirectoryPath:t.compileDirectoryPath,manifest:await compileAgentManifest(e.manifest)}),o=serializeArtifactJson(a),s=serializeArtifactJson(e.manifest),c=serializeArtifactJson(n),l=createCompiledModuleMapSource({manifest:a,moduleMapPath:t.moduleMapPath}),u=createCompileMetadata({appRoot:e.appRoot,diagnosticsArtifactJson:c,diagnosticsSummary:n.summary,discoveryManifestJson:s,moduleMapSource:l,paths:t}),d=serializeArtifactJson(u);return await mkdir(t.discoveryDirectoryPath,{recursive:!0}),await mkdir(t.compileDirectoryPath,{recursive:!0}),await Promise.all([writeFile(t.compiledManifestPath,o),writeFile(t.diagnosticsPath,c),writeFile(t.discoveryManifestPath,s),writeFile(t.moduleMapPath,l),writeFile(t.compileMetadataPath,d)]),{compiledManifest:a,diagnosticsArtifact:n,metadata:u,moduleMapSource:l,paths:t}}function createContentHash(e){return createHash(`sha256`).update(e).digest(`hex`)}function serializeArtifactJson(e){return`${JSON.stringify(e,null,2)}\n`}function toArtifactRelativePath(e,r){return normalizeLogicalPath(relative(resolve(e),r))}export{COMPILE_METADATA_KIND,COMPILE_METADATA_VERSION,createCompileMetadata,resolveCompilerArtifactPaths,writeCompilerArtifacts};
+import{join,relative,resolve}from"node:path";import{mkdir,writeFile}from"node:fs/promises";import{resolveInstalledPackageInfo}from"#internal/application/package.js";import{createHash}from"node:crypto";import{summarizeDiscoverDiagnostics}from"#discover/diagnostics.js";import{normalizeLogicalPath}from"#discover/filesystem.js";import{CHANNEL_INSTRUMENTATION_TYPES_FILE_NAME,createChannelInstrumentationTypesSource}from"#compiler/channel-instrumentation-types.js";import{createCompiledModuleMapSource}from"#compiler/module-map.js";import{compileAgentManifest}from"#compiler/normalize-manifest.js";import{materializeWorkspaceResources}from"#compiler/workspace-resources.js";const COMPILE_METADATA_KIND=`ash-compile-metadata`,COMPILE_METADATA_VERSION=5;function resolveCompilerArtifactPaths(t){let r=resolve(t),i=join(r,`.ash`,`discovery`),a=join(r,`.ash`,`compile`);return{appRoot:r,channelInstrumentationTypesPath:join(a,CHANNEL_INSTRUMENTATION_TYPES_FILE_NAME),compiledManifestPath:join(a,`compiled-agent-manifest.json`),compileDirectoryPath:a,compileMetadataPath:join(a,`compile-metadata.json`),diagnosticsPath:join(i,`diagnostics.json`),discoveryManifestPath:join(i,`agent-discovery-manifest.json`),discoveryDirectoryPath:i,moduleMapPath:join(a,`module-map.mjs`)}}function createDiscoveryDiagnosticsArtifact(e){return{diagnostics:[...e],kind:`ash-discovery-diagnostics`,summary:summarizeDiscoverDiagnostics(e),version:1}}function createCompileMetadata(e){let t=resolveInstalledPackageInfo(),n=createContentHash(e.discoveryManifestJson),r=createContentHash(e.diagnosticsArtifactJson),i=createContentHash(e.moduleMapSource);return{compile:{moduleMap:{path:toArtifactRelativePath(e.appRoot,e.paths.moduleMapPath),sha256:i}},discovery:{diagnostics:{path:toArtifactRelativePath(e.appRoot,e.paths.diagnosticsPath),sha256:r},manifest:{path:toArtifactRelativePath(e.appRoot,e.paths.discoveryManifestPath),sha256:n},sourceGraphHash:createContentHash(`${n}:${r}:${i}`),summary:e.diagnosticsSummary},generator:{name:t.name,version:t.version},kind:COMPILE_METADATA_KIND,status:e.diagnosticsSummary.errors>0?`failed`:`ready`,version:5}}async function writeCompilerArtifacts(e){let t=resolveCompilerArtifactPaths(e.appRoot),n=createDiscoveryDiagnosticsArtifact(e.diagnostics),a=await materializeWorkspaceResources({compileDirectoryPath:t.compileDirectoryPath,manifest:await compileAgentManifest(e.manifest)}),o=serializeArtifactJson(a),s=serializeArtifactJson(e.manifest),c=serializeArtifactJson(n),l=createCompiledModuleMapSource({manifest:a,moduleMapPath:t.moduleMapPath}),u=createChannelInstrumentationTypesSource({manifest:a,typesPath:t.channelInstrumentationTypesPath}),d=createCompileMetadata({appRoot:e.appRoot,diagnosticsArtifactJson:c,diagnosticsSummary:n.summary,discoveryManifestJson:s,moduleMapSource:l,paths:t}),f=serializeArtifactJson(d);return await mkdir(t.discoveryDirectoryPath,{recursive:!0}),await mkdir(t.compileDirectoryPath,{recursive:!0}),await Promise.all([writeFile(t.compiledManifestPath,o),writeFile(t.diagnosticsPath,c),writeFile(t.discoveryManifestPath,s),writeFile(t.channelInstrumentationTypesPath,u),writeFile(t.moduleMapPath,l),writeFile(t.compileMetadataPath,f)]),{compiledManifest:a,diagnosticsArtifact:n,metadata:d,moduleMapSource:l,paths:t}}function createContentHash(e){return createHash(`sha256`).update(e).digest(`hex`)}function serializeArtifactJson(e){return`${JSON.stringify(e,null,2)}\n`}function toArtifactRelativePath(e,r){return normalizeLogicalPath(relative(resolve(e),r))}export{COMPILE_METADATA_KIND,COMPILE_METADATA_VERSION,createCompileMetadata,resolveCompilerArtifactPaths,writeCompilerArtifacts};

package/dist/src/compiler/channel-instrumentation-types.d.ts

@@ -0,0 +1,8 @@
+import type { CompiledAgentManifest } from "#compiler/manifest.js";
+interface ChannelInstrumentationTypesSourceInput {
+    readonly manifest: CompiledAgentManifest;
+    readonly typesPath: string;
+}
+export declare const CHANNEL_INSTRUMENTATION_TYPES_FILE_NAME = "channel-instrumentation-types.d.ts";
+export declare function createChannelInstrumentationTypesSource(input: ChannelInstrumentationTypesSourceInput): string;
+export {};

package/dist/src/compiler/channel-instrumentation-types.js

@@ -0,0 +1,2 @@
+import{dirname,join,relative}from"node:path";const CHANNEL_INSTRUMENTATION_TYPES_FILE_NAME=`channel-instrumentation-types.d.ts`;function createChannelInstrumentationTypesSource(e){let t=collectChannelInstrumentationDeclarations(e);return[`// Generated by Ash. Do not edit by hand.`,`import type { InferChannelMetadata } from "experimental-ash/channels";`,``,`declare module "experimental-ash/instrumentation" {`,...t.length===0?[`  interface ChannelMetadataMap {}`,`  interface ChannelReferenceMap {}`]:[`  interface ChannelMetadataMap {`,...t.map(e=>`    readonly ${JSON.stringify(e.kind)}: InferChannelMetadata<${renderImportedChannelType(e)}>;`),`  }`,`  interface ChannelReferenceMap {`,...t.map(e=>`    readonly ${JSON.stringify(e.kind)}: ${renderImportedChannelType(e)};`),`  }`],`}`,``].join(`
+`)}function collectChannelInstrumentationDeclarations(t){let n=dirname(t.typesPath),r=new Map;for(let e of[...t.manifest.channels].filter(e=>e.kind===`channel`).sort(compareCompiledChannels)){let i=`channel:${e.name}`;r.has(i)||r.set(i,{exportName:e.exportName,importSpecifier:createChannelImportSpecifier({agentRoot:t.manifest.agentRoot,channel:e,fromDirectory:n}),kind:i})}return[...r.values()]}function compareCompiledChannels(e,t){return e.name.localeCompare(t.name)||e.logicalPath.localeCompare(t.logicalPath)||(e.exportName??``).localeCompare(t.exportName??``)||e.sourceId.localeCompare(t.sourceId)||e.method.localeCompare(t.method)||e.urlPath.localeCompare(t.urlPath)}function createChannelImportSpecifier(e){let r=join(e.agentRoot,toRuntimeImportLogicalPath(e.channel.logicalPath)),i=relative(e.fromDirectory,r).replaceAll(`\\`,`/`);return i.startsWith(`.`)?i:`./${i}`}function toRuntimeImportLogicalPath(e){return e.endsWith(`.mts`)?`${e.slice(0,-4)}.mjs`:e.endsWith(`.cts`)?`${e.slice(0,-4)}.cjs`:e.endsWith(`.ts`)?`${e.slice(0,-3)}.js`:e}function renderImportedChannelType(e){let t=e.exportName??`default`,n=`import(${JSON.stringify(e.importSpecifier)})`;return isIdentifierName(t)?`typeof ${n}.${t}`:`typeof ${n}[${JSON.stringify(t)}]`}function isIdentifierName(e){return/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(e)}export{CHANNEL_INSTRUMENTATION_TYPES_FILE_NAME,createChannelInstrumentationTypesSource};