experimental-ash 0.40.0 → 0.41.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # experimental-ash
 
+## 0.41.0
+
+### Minor Changes
+
+- d4dd396: Move code mode from the `CODE_MODE` environment variable to a per-agent
+  `experimental.codeMode` flag on `defineAgent({ experimental: { codeMode: true } })`.
+  Each agent and subagent can now opt in independently. For backwards
+  compatibility, agents that omit the flag fall back to the
+  `ASH_EXPERIMENTAL_CODE_MODE` environment variable (`"1"` enables it); the
+  previous `CODE_MODE` variable is no longer read.
+- 09beab5: Add `defineTools` and `defineTool` dynamic overloads for runtime tool resolution.
+
+  Tools can now be resolved dynamically at runtime based on session context via `defineTools({ events: { "session.started": handler } })` and `defineTool({ events: { "session.started": handler } })`. Session-scoped resolvers run once and are cached; step-scoped resolvers re-resolve before every model call. Dynamic tools appear in the model's tool list identically to static tools.
+
+## 0.40.1
+
+### Patch Changes
+
+- 35ca14b: Fix cross-deployment turn workflows so forwarded parent streams resolve the parent run's encryption key instead of the latest deployment's key.
+
 ## 0.40.0
 
 ### Minor Changes

package/dist/docs/public/tools.md

@@ -368,6 +368,171 @@ full API.
 Note: `retentionPolicy` and `onCompact` operate on the projected output (what the model sees),
 not the full `execute` return.
 
+## Dynamic Tools
+
+Dynamic tools resolve at runtime based on session context — tenant configuration, feature flags, user roles, or external data. Use `defineTools` with an `events` object to produce tools dynamically.
+
+### Single Dynamic Tool
+
+`agent/tools/analytics.ts`
+
+```ts
+import { defineTool } from "experimental-ash/tools";
+import { z } from "zod";
+
+export default defineTool({
+  events: {
+    "session.started": async (event, ctx) => {
+      const flags = await fetchFeatureFlags(ctx.session.id);
+      if (!flags.advancedAnalytics) return null;
+
+      return {
+        description: "Run an advanced analytics query.",
+        inputSchema: z.object({ query: z.string() }),
+        async execute(input) {
+          return runAnalytics(input.query);
+        },
+      };
+    },
+  },
+});
+```
+
+Return `null` to produce no tool. The tool name is the file slug (`analytics`), identical to a static `defineTool`.
+
+### Multiple Dynamic Tools
+
+`agent/tools/tenant.ts`
+
+```ts
+import { defineTools, tool } from "experimental-ash/tools";
+import { z } from "zod";
+
+export default defineTools({
+  events: {
+    "session.started": async (event, ctx) => {
+      const tenant = await fetchTenant(ctx.session.id);
+      if (!tenant) return null;
+
+      return {
+        export: tool({
+          description: `Export ${tenant.name} data`,
+          inputSchema: z.object({ format: z.enum(["csv", "json"]) }),
+          async execute(input) {
+            // input.format is typed as "csv" | "json"
+            return callTenantApi(tenant.apiUrl, "export", input.format);
+          },
+        }),
+        query: tool({
+          description: `Query ${tenant.name} data`,
+          inputSchema: z.object({ sql: z.string() }),
+          async execute(input) {
+            // input.sql is typed as string
+            return callTenantApi(tenant.apiUrl, "query", input.sql);
+          },
+        }),
+      };
+    },
+  },
+});
+```
+
+Each entry must be wrapped with `tool()` — it captures the schema type so `execute(input)` is inferred from `inputSchema`, matching the AI SDK's `tool()` pattern.
+
+### Tool Naming
+
+Dynamic tool names are derived from the file path and the definition function:
+
+| Definition    | File                       | Entry keys        | Tool name(s)                      |
+| ------------- | -------------------------- | ----------------- | --------------------------------- |
+| `defineTool`  | `agent/tools/analytics.ts` | _(single entry)_  | `analytics`                       |
+| `defineTools` | `agent/tools/tenant.ts`    | `export`, `query` | `tenant__export`, `tenant__query` |
+| `defineTools` | `agent/tools/search.ts`    | `run`             | `search__run`                     |
+
+`defineTool` always produces one tool named after the file slug — identical to static tools. `defineTools` always uses `slug__key`, even when the resolver returns a single entry. This keeps names stable: adding a second entry to a `defineTools` file does not rename the first.
+
+### Event Scopes
+
+The `events` object uses the same event names as hook stream events:
+
+| Event             | When the resolver runs  | I/O behavior                        |
+| ----------------- | ----------------------- | ----------------------------------- |
+| `session.started` | Once per session        | Runs once; results cached durably   |
+| `turn.started`    | Once per turn           | Runs once per turn; cached for turn |
+| `step.started`    | Before every model call | Runs every step; no caching         |
+
+Session-scoped resolvers can do I/O (fetch from a database, call an API). The framework's bundler transform ensures the I/O executes once per session — subsequent workflow steps reconstruct execute functions from stored closure variables without re-running the resolver. Resolvers run concurrently — if multiple dynamic tool files declare the same event, their I/O overlaps.
+
+### Multiple Events
+
+A single file can declare handlers for multiple events. The result of the most recently fired handler owns the tool set for that file:
+
+```ts
+import { defineTools, tool } from "experimental-ash/tools";
+
+export default defineTools({
+  events: {
+    "session.started": async (event, ctx) => {
+      return { query: tool({ description: "Query", inputSchema: {}, execute: async () => {} }) };
+    },
+    "turn.started": async (event, ctx) => {
+      // Turn handler replaces session handler's tools for this file
+      return { search: tool({ description: "Search", inputSchema: {}, execute: async () => {} }) };
+    },
+  },
+});
+```
+
+### Type Inference
+
+`inputSchema` accepts Zod, Standard Schema, or plain JSON Schema — same as static `defineTool`. When using Zod, the `tool()` wrapper infers the `execute` input type automatically:
+
+```ts
+return {
+  query: tool({
+    inputSchema: z.object({ city: z.string() }),
+    async execute(input) {
+      // input.city is typed as string
+      return fetchWeather(input.city);
+    },
+  }),
+};
+```
+
+The `execute` signature matches static tools: `execute(input: TInput, ctx: ToolContext)`.
+
+### Helper Functions
+
+`execute` can live inside helper functions, `.map()` callbacks, or IIFEs — the bundler transform follows nested scopes and captures all referenced variables:
+
+```ts
+import { defineTools, tool } from "experimental-ash/tools";
+import { z } from "zod";
+
+export default defineTools({
+  events: {
+    "session.started": async (event, ctx) => {
+      const tenant = await fetchTenant(ctx.session.id);
+
+      function buildTool(action: string) {
+        const endpoint = `${tenant.apiUrl}/${action}`;
+        return tool({
+          description: `${action} for ${tenant.name}`,
+          inputSchema: z.object({ query: z.string() }),
+          async execute(input) {
+            return callApi(endpoint, input.query);
+          },
+        });
+      }
+
+      return { query: buildTool("query"), export: buildTool("export") };
+    },
+  },
+});
+```
+
+**Limitation:** `execute` must be an inline function — a function expression, arrow function, or method shorthand written directly as the property value. Assigning a variable (`execute: myFn`) or a call result (`execute: makeFn()`) is not detected by the transform; the tool will work on the first workflow step but will not survive replay across step boundaries.
+
 ## What To Read Next
 
 - [Session Context](./session-context.md)

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

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

package/dist/src/compiled/@workflow/core/index.js

@@ -1,2 +1,2 @@
-import{i as e,s as t}from"../../_chunks/workflow/dist-C4EHshZE.js";import{c as n,et as r,nt as i,s as a,tt as o}from"../../_chunks/workflow/symbols-DygIC1sj.js";import{Bt as s,C as c,I as l,R as u,Rt as d,Vt as f,m as p,n as m,x as h,zt as g}from"../../_chunks/workflow/resume-hook-D6dFbxMV.js";import{n as _,t as v}from"../../_chunks/workflow/sleep-kQ0UwHn0.js";function y(e){o(`createHook()`,`https://workflow-sdk.dev/docs/api-reference/workflow/create-hook`,y)}function b(e){o(`createWebhook()`,`https://workflow-sdk.dev/docs/api-reference/workflow/create-webhook`,b)}function x({schema:e}={}){function t(e){o(`defineHook().create()`,`https://workflow-sdk.dev/docs/api-reference/workflow/define-hook`,t)}return{create:t,async resume(t,n){if(!e?.[`~standard`])return await m(t,n);let r=e[`~standard`].validate(n);if(r instanceof Promise&&(r=await r),r.issues){let e=r.issues.map(e=>{let t=e.path?.map(e=>String(typeof e==`object`&&e?e.key:e)).join(`.`);return t?`  at "${t}": ${e.message}`:`  ${e.message}`});throw Error(`Hook payload did not match the defined schema:\n${e.join(`
+import{i as e,s as t}from"../../_chunks/workflow/dist-C4EHshZE.js";import{c as n,et as r,nt as i,s as a,tt as o}from"../../_chunks/workflow/symbols-DygIC1sj.js";import{Bt as s,C as c,I as l,R as u,Rt as d,Vt as f,m as p,n as m,x as h,zt as g}from"../../_chunks/workflow/resume-hook-B2kqAsX6.js";import{n as _,t as v}from"../../_chunks/workflow/sleep-kQ0UwHn0.js";function y(e){o(`createHook()`,`https://workflow-sdk.dev/docs/api-reference/workflow/create-hook`,y)}function b(e){o(`createWebhook()`,`https://workflow-sdk.dev/docs/api-reference/workflow/create-webhook`,b)}function x({schema:e}={}){function t(e){o(`defineHook().create()`,`https://workflow-sdk.dev/docs/api-reference/workflow/define-hook`,t)}return{create:t,async resume(t,n){if(!e?.[`~standard`])return await m(t,n);let r=e[`~standard`].validate(n);if(r instanceof Promise&&(r=await r),r.issues){let e=r.issues.map(e=>{let t=e.path?.map(e=>String(typeof e==`object`&&e?e.key:e)).join(`.`);return t?`  at "${t}": ${e.message}`:`  ${e.message}`});throw Error(`Hook payload did not match the defined schema:\n${e.join(`
 `)}`)}return await m(t,r.value)}}}const S=Symbol.for(`@workflow/setAttributes//unsupportedWorldWarned`);async function C(t,n={}){let r=u.getStore()?.workflowMetadata?.workflowRunId;if(!r)throw new e(`experimental_setAttributes() must be called from a 'use workflow' or 'use step' function. Calling it from plain host code is not supported.`);let i=_(t,n);if(i.length===0)return;let a=await d();if(typeof a.runs.experimentalSetAttributes!=`function`){let e=globalThis;if(!e[S]){e[S]=!0;let t=`name`in a&&typeof a.name==`string`?a.name:``,n=t?` (${t})`:``;console.warn(`[workflow] setAttributes: the current world implementation${n} does not implement experimentalSetAttributes; this call (and any subsequent setAttributes calls in this process) is a no-op. Attributes will become available once the world adapter adds support.`)}return}await a.runs.experimentalSetAttributes(r,i,n.allowReservedAttributes===!0?{allowReservedAttributes:!0}:{})}function w(){let e=u.getStore();return e||r(`getStepMetadata()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-step-metadata`,w),e.stepMetadata}function T(){let e=u.getStore();return e||i(`getWorkflowMetadata()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-workflow-metadata`,T),e.workflowMetadata}function E(e={}){let t=u.getStore();t||i(`getWritable()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-writable`,E);let{namespace:r}=e,o=t.workflowMetadata.workflowRunId,d=l(o,r),m=t.writables??=new Map,_=m.get(d);if(_)return _.writable;let v=c(h(globalThis,t.ops,o,t.encryptionKey),t.encryptionKey),y=new p(o,d),b=g();return t.ops.push(b.promise),s(v.readable,y,b).catch(()=>{}),f(v.writable,b),Object.defineProperty(v.writable,a,{value:d,writable:!1}),Object.defineProperty(v.writable,n,{value:o,writable:!1}),m.set(d,{writable:v.writable,state:b}),v.writable}export{e as FatalError,t as RetryableError,y as createHook,b as createWebhook,x as defineHook,C as experimental_setAttributes,w as getStepMetadata,T as getWorkflowMetadata,E as getWritable,v as sleep};