experimental-ash 0.43.0 → 0.44.0

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

@@ -1,152 +1 @@
-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";
-/**
- * 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;
-/**
- * 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];
-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;
+export * from "#public/instrumentation/index.js";

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/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
@@ -83,6 +84,20 @@ 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>;
 }
 /**
  * Internal sandbox session, used to construct the public {@link SandboxSession}.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-ash",
-  "version": "0.43.0",
+  "version": "0.44.0",
   "bin": {
     "ash": "./bin/ash.js",
     "experimental-ash": "./bin/ash.js"