tjs-lang 0.8.1 → 0.8.2

package/src/use-cases/local-helpers.test.ts

@@ -0,0 +1,219 @@
+import { describe, it, expect } from 'bun:test'
+import { ajs } from '../transpiler'
+import { transpile } from '../lang'
+import { AgentVM } from '../vm'
+
+/**
+ * Local helper functions: an agent source file may declare multiple top-level
+ * functions. The LAST is the entry point; the preceding ones are helpers,
+ * invoked via the `callLocal` atom. Helpers are top-level siblings — isolated
+ * scopes that see only their parameters, like ordinary functions.
+ */
+describe('Local helper functions', () => {
+  const VM = new AgentVM()
+  const run = async (src: string, args: Record<string, any>) =>
+    (await VM.run(ajs(src), args)).result
+
+  it('invokes a scalar-returning helper from the entry function', async () => {
+    const result = await run(
+      `
+      function double(x) { return x * 2 }
+      function main(n) {
+        const d = double(n)
+        return { d }
+      }`,
+      { n: 5 }
+    )
+    expect(result.d).toBe(10)
+  })
+
+  it('lets a helper call another helper', async () => {
+    const result = await run(
+      `
+      function double(x) { return x * 2 }
+      function addOne(x) {
+        const d = double(x)
+        return d + 1
+      }
+      function main(n) {
+        const a = double(n)
+        const b = addOne(n)
+        return { a, b }
+      }`,
+      { n: 5 }
+    )
+    expect(result).toEqual({ a: 10, b: 11 })
+  })
+
+  it('allows helpers to return arrays and objects', async () => {
+    const result = await run(
+      `
+      function pair(x) { return [x, x] }
+      function wrap(x) { return { value: x } }
+      function main(n) {
+        const p = pair(n)
+        const w = wrap(n)
+        return { p, w }
+      }`,
+      { n: 3 }
+    )
+    expect(result).toEqual({ p: [3, 3], w: { value: 3 } })
+  })
+
+  it('supports idiomatic TJS typed/example params (colon shorthand)', async () => {
+    // Examples are representative values: floats for a fractional-scaling fn.
+    const result = await run(
+      `
+      function scale(x: 1.5, factor: 0.5): 0.75 { return x * factor }
+      function main(n: 1.5): 0.75 {
+        const s = scale(n, 0.5)
+        return { s }
+      }`,
+      { n: 3 }
+    )
+    expect(result.s).toBe(1.5)
+  })
+
+  it('supports multiple parameters', async () => {
+    const result = await run(
+      `
+      function add(a, b) { return a + b }
+      function main(x, y) {
+        const sum = add(x, y)
+        return { sum }
+      }`,
+      { x: 7, y: 8 }
+    )
+    expect(result.sum).toBe(15)
+  })
+
+  it('isolates helper scope — helpers cannot see the caller locals', async () => {
+    // `secret` is a local in main (= 42). The helper references a bare
+    // `secret`; under isolation it is NOT in scope, so AJS falls back to the
+    // bare-string literal "secret". A scope leak would instead expose main's
+    // 42 — so the guarantee is simply: the helper never sees the caller value.
+    const result = await run(
+      `
+      function leak(x) { return { x, secret } }
+      function main(n) {
+        const secret = 42
+        const r = leak(n)
+        return r
+      }`,
+      { n: 1 }
+    )
+    expect(result.x).toBe(1)
+    expect(result.secret).not.toBe(42) // no leak of caller's local
+    expect(result.secret).toBe('secret') // AJS bare-string fallback
+  })
+
+  it('does not let helper return exit the caller agent', async () => {
+    // The helper returns, then main keeps running and returns its own object.
+    const result = await run(
+      `
+      function step(x) { return x + 100 }
+      function main(n) {
+        const a = step(n)
+        const b = step(a)
+        return { a, b }
+      }`,
+      { n: 1 }
+    )
+    expect(result).toEqual({ a: 101, b: 201 })
+  })
+
+  // --- transpile-time guards -------------------------------------------------
+
+  const expectTranspileError = (src: string, match: RegExp) =>
+    expect(() => transpile(src, { vmTarget: true })).toThrow(match)
+
+  it('rejects helper calls nested inside expressions', () => {
+    expectTranspileError(
+      `
+      function double(x) { return x * 2 }
+      function main(n) { return { v: double(n) + 1 } }`,
+      /cannot be called inside an expression/
+    )
+  })
+
+  it('supports recursion (bounded by fuel/timeout, not rejected)', async () => {
+    // Recursive factorial — by-reference dispatch makes this a runtime loop.
+    const result = await run(
+      `
+      function fact(n) {
+        if (n <= 1) { return 1 }
+        const prev = fact(n - 1)
+        return n * prev
+      }
+      function main(n) {
+        const f = fact(n)
+        return { f }
+      }`,
+      { n: 5 }
+    )
+    expect(result.f).toBe(120)
+  })
+
+  it('supports mutual recursion', async () => {
+    const result = await run(
+      `
+      function isEven(n) {
+        if (n == 0) { return true }
+        const r = isOdd(n - 1)
+        return r
+      }
+      function isOdd(n) {
+        if (n == 0) { return false }
+        const r = isEven(n - 1)
+        return r
+      }
+      function main(n) {
+        const even = isEven(n)
+        return { even }
+      }`,
+      { n: 10 }
+    )
+    expect(result.even).toBe(true)
+  })
+
+  it('turns runaway recursion into a clean error, not a host crash', async () => {
+    // Unbounded recursion: must surface as a monadic error (depth cap or fuel),
+    // never a thrown RangeError that crashes the host VM.
+    const out = await VM.run(
+      ajs(`
+      function loop(n) { const r = loop(n); return r }
+      function main(n) { const v = loop(n); return { v } }`),
+      { n: 1 },
+      { fuel: 100000 }
+    )
+    expect(out.error).toBeDefined()
+    expect(out.error?.message).toMatch(/depth|fuel/i)
+  })
+
+  it('rejects arity mismatches', () => {
+    expectTranspileError(
+      `
+      function add(a, b) { return a + b }
+      function main(n) { const v = add(n); return { v } }`,
+      /expects 2 argument\(s\), got 1/
+    )
+  })
+
+  it('rejects same-name same-arity functions (collision)', () => {
+    // Two identical-signature `dup` declarations collide. The polymorphic-merge
+    // pass (which runs during parse, before helper extraction) catches this
+    // first — either way it's a clear, deterministic rejection.
+    expectTranspileError(
+      `
+      function dup(x) { return x }
+      function dup(x) { return x }
+      function main(n) { const v = dup(n); return { v } }`,
+      /ambiguous signatures|Duplicate helper/
+    )
+  })
+
+  it('still transpiles a single-function agent (no helpers)', async () => {
+    const result = await run(`function main(n) { return { n } }`, { n: 9 })
+    expect(result.n).toBe(9)
+  })
+})

package/src/use-cases/timeout-overrides.test.ts

@@ -0,0 +1,169 @@
+import { describe, it, expect } from 'vitest'
+import { AgentVM, isAgentError, defineAtom } from '../index'
+import { s } from 'tosijs-schema'
+
+// A deliberately slow atom whose builtin timeout would normally trip.
+const slowAtom = defineAtom(
+  'slow',
+  s.object({ ms: s.number }),
+  undefined,
+  async ({ ms }) => {
+    await new Promise((resolve) => setTimeout(resolve, ms))
+  },
+  { docs: 'Slow IO atom for testing', cost: 0.01, timeoutMs: 100 }
+)
+
+describe('Per-atom Timeout Overrides', () => {
+  it('uses the atom default when no override is provided', async () => {
+    const vm = new AgentVM({ slow: slowAtom })
+
+    const ast = vm.Agent.step({ op: 'slow', ms: 200 }).toJSON()
+
+    const result = await vm.run(ast, {}, { fuel: 100 })
+
+    expect(result.error).toBeDefined()
+    expect(result.error?.message).toContain("Atom 'slow' timed out")
+  })
+
+  it('static override raises an atom timeout above its default', async () => {
+    const vm = new AgentVM({ slow: slowAtom })
+
+    const ast = vm.Agent.step({ op: 'slow', ms: 200 }).toJSON()
+
+    const result = await vm.run(
+      ast,
+      {},
+      {
+        fuel: 100,
+        timeoutOverrides: { slow: 5000 }, // raise from 100 → 5s
+      }
+    )
+
+    expect(result.error).toBeUndefined()
+  })
+
+  it('static override lowers an atom timeout below its default', async () => {
+    const vm = new AgentVM({ slow: slowAtom })
+
+    const ast = vm.Agent.step({ op: 'slow', ms: 100 }).toJSON()
+
+    const result = await vm.run(
+      ast,
+      {},
+      {
+        fuel: 100,
+        timeoutOverrides: { slow: 10 }, // lower from 100ms → 10ms
+      }
+    )
+
+    expect(result.error).toBeDefined()
+    expect(result.error?.message).toContain("Atom 'slow' timed out")
+  })
+
+  it('dynamic override receives input and ctx', async () => {
+    const vm = new AgentVM({ slow: slowAtom })
+
+    const ast = vm.Agent.step({ op: 'slow', ms: 200 }).toJSON()
+
+    const result = await vm.run(
+      ast,
+      {},
+      {
+        fuel: 100,
+        timeoutOverrides: {
+          // Allow 10x the requested delay
+          slow: (input: any) => input.ms * 10,
+        },
+      }
+    )
+
+    expect(result.error).toBeUndefined()
+  })
+
+  it('override of 0 disables the per-atom timeout', async () => {
+    const vm = new AgentVM({ slow: slowAtom })
+
+    // ms > atom default (100), would normally trip
+    const ast = vm.Agent.step({ op: 'slow', ms: 300 }).toJSON()
+
+    const result = await vm.run(
+      ast,
+      {},
+      {
+        fuel: 100,
+        timeoutOverrides: { slow: 0 },
+      }
+    )
+
+    expect(result.error).toBeUndefined()
+  })
+
+  it('atom timeout still fires when no override matches that op', async () => {
+    const vm = new AgentVM({ slow: slowAtom })
+
+    const ast = vm.Agent.step({ op: 'slow', ms: 200 }).toJSON()
+
+    const result = await vm.run(
+      ast,
+      {},
+      {
+        fuel: 100,
+        timeoutOverrides: { somethingElse: 5000 },
+      }
+    )
+
+    expect(result.error).toBeDefined()
+    expect(isAgentError(result.error)).toBe(true)
+  })
+})
+
+describe('Default vm.run timeout', () => {
+  it('does not derive run timeout from fuel (formula removed)', async () => {
+    // Under the old `fuel * 10ms` formula, fuel=1 would timeout in 10ms —
+    // far less than the IO needed below. Under the atom-derived default
+    // (slowest atom × 2), a 200ms IO atom completes fine with tiny fuel.
+    const vm = new AgentVM({ slow: slowAtom })
+
+    const ast = vm.Agent.step({ op: 'slow', ms: 200 }).toJSON()
+
+    const result = await vm.run(
+      ast,
+      {},
+      {
+        fuel: 1000, // headroom for cost; the run-level timeout is what matters
+        timeoutOverrides: { slow: 0 }, // disable per-atom timeout
+        // no timeoutMs option — use the default
+      }
+    )
+
+    expect(result.error).toBeUndefined()
+  })
+
+  it('derives the default from the slowest atom × 2 (never below the slowest atom budget)', () => {
+    // coreAtoms include 120s atoms (llm/runCode); the run-level default must
+    // cover them, else those per-atom budgets are dead config.
+    const core = new AgentVM()
+    expect(core.defaultRunTimeout).toBe(240_000) // 120s × 2
+
+    // A slower custom atom raises the default (self-adjusting).
+    const slow = defineAtom('slow5m', s.object({}), undefined, async () => {}, {
+      timeoutMs: 300_000,
+    })
+    const vm = new AgentVM({ slow5m: slow })
+    expect(vm.defaultRunTimeout).toBe(600_000) // 300s × 2
+    // and it always covers the slowest atom's own budget
+    expect(vm.defaultRunTimeout).toBeGreaterThanOrEqual(300_000)
+  })
+
+  it('floors the default at 60s for a VM whose atoms are all fast', () => {
+    // `seq` etc. have timeoutMs: 0 (no timeout) and are excluded; if the only
+    // finite budgets were tiny, the floor keeps a sane backstop.
+    const fast = defineAtom('fast', s.object({}), undefined, async () => {}, {
+      timeoutMs: 50,
+    })
+    const vm = new AgentVM({ fast })
+    // coreAtoms still contribute their 120s atoms, so this VM is 240s; the floor
+    // is exercised conceptually — assert it's at least the 60s minimum.
+    expect(vm.defaultRunTimeout).toBeGreaterThanOrEqual(60_000)
+  })
+})

package/src/vm/atoms/batteries.ts

@@ -51,7 +51,12 @@ export const storeVectorize = defineAtom(
     const resolvedText = resolveValue(text, ctx)
     return vectorCap.embed(resolvedText)
   },
-  { docs: 'Generate embeddings using vector battery', cost: 20 }
+  // Network embedding call; a cold model can exceed the 1s atom default.
+  {
+    docs: 'Generate embeddings using vector battery',
+    cost: 20,
+    timeoutMs: 60000,
+  }
 )
 
 // store.createCollection
@@ -97,7 +102,12 @@ export const storeVectorAdd = defineAtom(
 
     return storeCap.vectorAdd(resolvedColl, resolvedDoc)
   },
-  { docs: 'Add a document to a vector store collection', cost: 5 }
+  // May embed the doc via the store (network IO); allow for a cold model.
+  {
+    docs: 'Add a document to a vector store collection',
+    cost: 5,
+    timeoutMs: 60000,
+  }
 )
 
 // store.search (Vector Search)
@@ -167,7 +177,11 @@ export const llmPredictBattery = defineAtom(
       resolvedFormat
     )
   },
-  { docs: 'Generate completion using LLM battery', cost: 100 }
+  {
+    docs: 'Generate completion using LLM battery',
+    cost: 100,
+    timeoutMs: 120000,
+  }
 )
 
 // Vision battery interface (multimodal)

package/src/vm/runtime.ts

@@ -151,6 +151,11 @@ export type CostOverride =
   | number
   | ((input: any, ctx: RuntimeContext) => number)
 
+/** Timeout override: static number (ms) or dynamic function. 0 disables. */
+export type TimeoutOverride =
+  | number
+  | ((input: any, ctx: RuntimeContext) => number)
+
 export interface RuntimeContext {
   fuel: { current: number }
   args: Record<string, any>
@@ -165,8 +170,12 @@ export interface RuntimeContext {
   warnings?: string[] // Non-fatal warnings (e.g., console.warn)
   signal?: AbortSignal // External abort signal for timeout enforcement
   costOverrides?: Record<string, CostOverride> // Per-atom cost overrides
+  timeoutOverrides?: Record<string, TimeoutOverride> // Per-atom timeout overrides (ms, 0 disables)
   context?: Record<string, any> // Immutable request-scoped metadata (auth, permissions, etc.)
   runCodeDepth?: number // Track nested runCode calls to prevent infinite recursion
+  localCall?: boolean // Inside a callLocal helper body — return may be a non-object scalar
+  helpers?: Record<string, { steps: any[]; paramNames: string[] }> // Local helper bodies, called by name
+  callDepth?: number // Helper call nesting depth — guards against host-stack overflow on deep recursion
 }
 
 export type AtomExec = (step: any, ctx: RuntimeContext) => Promise<void>
@@ -1363,18 +1372,25 @@ export function defineAtom<I extends Record<string, any>, O = any>(
         return
       }
 
-      // 3. Execution with Timeout
+      // 3. Execution with Timeout (per-atom override > atom default)
+      const overrideTimeout = ctx.timeoutOverrides?.[op]
+      const baseTimeout =
+        overrideTimeout !== undefined ? overrideTimeout : timeoutMs
+      const effectiveTimeout =
+        typeof baseTimeout === 'function'
+          ? baseTimeout(inputData, ctx)
+          : baseTimeout
       let timer: any
       const execute = async () => fn(step as I, ctx)
 
       result =
-        timeoutMs > 0
+        effectiveTimeout > 0
           ? await Promise.race([
               execute(),
               new Promise<never>((_, reject) => {
                 timer = setTimeout(
                   () => reject(new Error(`Atom '${op}' timed out`)),
-                  timeoutMs
+                  effectiveTimeout
                 )
               }),
             ]).finally(() => clearTimeout(timer))
@@ -1562,8 +1578,11 @@ export const ret = defineAtom(
     if ('value' in step) {
       const res = resolveValue(step.value, ctx)
 
-      // Enforce object returns — agents must return objects for composability
+      // Enforce object returns — agents must return objects for composability.
+      // Helper bodies (callLocal) are exempt: they're internal calls and may
+      // return scalars, arrays, etc. like ordinary functions.
       if (
+        !ctx.localCall &&
         res !== undefined &&
         res !== null &&
         !isAgentError(res) &&
@@ -1786,6 +1805,71 @@ export const scope = defineAtom(
   { docs: 'Create new scope', timeoutMs: 0, cost: 0.1 }
 )
 
+/**
+ * Maximum helper-call nesting depth. Fuel + timeout bound the total *work* a
+ * recursive helper can do, but deeply-nested `await seq.exec` would overflow
+ * the host JS stack (an uncatchable RangeError) before fuel runs out. This cap
+ * converts runaway recursion into a clean monadic error instead.
+ */
+export const MAX_CALL_DEPTH = 256
+
+export const callLocal = defineAtom(
+  'callLocal',
+  s.object({
+    name: s.string,
+    args: s.array(s.any),
+  }),
+  undefined,
+  async ({ name, args }, ctx) => {
+    const helper = ctx.helpers?.[name as string]
+    if (!helper) {
+      ctx.error = new AgentError(`Unknown helper: ${name}`, 'callLocal')
+      return ctx.error
+    }
+
+    const depth = (ctx.callDepth ?? 0) + 1
+    if (depth > MAX_CALL_DEPTH) {
+      ctx.error = new AgentError(
+        `Maximum helper call depth (${MAX_CALL_DEPTH}) exceeded — likely infinite recursion in '${name}'`,
+        'callLocal'
+      )
+      return ctx.error
+    }
+
+    // Resolve each argument expression in the caller's scope
+    const resolvedArgs = (args as any[]).map((arg) => resolveValue(arg, ctx))
+
+    // Isolated scope: helpers are top-level sibling functions, not nested
+    // closures, so they see ONLY their params — never the caller's locals.
+    // Capabilities/fuel/resolver/etc. are shared via the spread; state and
+    // consts start fresh. localCall exempts the helper's `return` from the
+    // agent object-return contract (helpers may return scalars/arrays like
+    // ordinary functions). callDepth guards against host-stack overflow.
+    const scopedCtx: RuntimeContext = {
+      ...ctx,
+      state: {},
+      consts: new Set(),
+      output: undefined,
+      error: undefined,
+      localCall: true,
+      callDepth: depth,
+    }
+    for (let i = 0; i < helper.paramNames.length; i++) {
+      scopedCtx.state[helper.paramNames[i]] = resolvedArgs[i]
+    }
+
+    await seq.exec({ op: 'seq', steps: helper.steps } as any, scopedCtx)
+
+    // Propagate errors but NOT output — the helper's return becomes this
+    // atom's result, captured into the caller's named result variable by
+    // the standard exec wrapper. Unlike `scope`, it does not bubble up
+    // to ctx.output (so a helper return doesn't exit the caller agent).
+    if (scopedCtx.error) ctx.error = scopedCtx.error
+    return scopedCtx.output
+  },
+  { docs: 'Invoke a local helper function by name', timeoutMs: 0, cost: 0.1 }
+)
+
 // 3. List (Cost 1)
 
 /*#
@@ -2991,6 +3075,7 @@ export const coreAtoms = {
   varsLet,
   varsExport,
   scope,
+  callLocal,
   map,
   filter,
   reduce,

package/src/vm/vm.ts

@@ -4,6 +4,7 @@ import {
   type RunResult,
   type RuntimeContext,
   type CostOverride,
+  type TimeoutOverride,
   coreAtoms,
   AgentError,
   isProcedureToken,
@@ -13,16 +14,49 @@ import { TypedBuilder, type BaseNode, type BuilderType } from '../builder'
 import { validate } from 'tosijs-schema'
 import { transpile } from '../lang/core'
 
-/** Default timeout multiplier: milliseconds per fuel unit */
-const FUEL_TO_MS = 10 // 1000 fuel = 10 seconds
+/**
+ * Floor for the run-level default timeout. The actual default is derived from
+ * the registered atoms (slowest atom × 2 — see `defaultRunTimeout`), but never
+ * drops below this for a VM whose atoms are all fast.
+ */
+const MIN_DEFAULT_RUN_TIMEOUT_MS = 60_000
 
 export class AgentVM<M extends Record<string, Atom<any, any>>> {
   readonly atoms: typeof coreAtoms & M
 
+  private _defaultRunTimeout?: number
+
   constructor(customAtoms: M = {} as M) {
     this.atoms = { ...coreAtoms, ...customAtoms }
   }
 
+  /**
+   * Default run-level wall-clock timeout when `run()` is given no explicit
+   * `timeoutMs`. Derived as `max(per-atom timeoutMs) × 2` over the registered
+   * atoms (with headroom for an agent that chains a couple of slow calls), so
+   * the run-level backstop can never be shorter than the slowest single atom's
+   * own budget — otherwise that per-atom budget would be dead config (e.g.
+   * `llmVision`/`llmPredictBattery` are 120s; a fixed 60s run default would kill
+   * them mid-call). Atoms with `timeoutMs: 0` (no timeout, e.g. `seq`) are
+   * excluded; the result is floored at {@link MIN_DEFAULT_RUN_TIMEOUT_MS}.
+   * Self-adjusting: registering a slower custom atom raises the default.
+   */
+  get defaultRunTimeout(): number {
+    if (this._defaultRunTimeout === undefined) {
+      let slowest = 0
+      for (const atom of Object.values(this.atoms)) {
+        // undefined timeoutMs means the per-atom default (1000ms); 0 means none.
+        const t = (atom as any).timeoutMs ?? 1000
+        if (t > 0 && t > slowest) slowest = t
+      }
+      this._defaultRunTimeout = Math.max(
+        MIN_DEFAULT_RUN_TIMEOUT_MS,
+        slowest * 2
+      )
+    }
+    return this._defaultRunTimeout
+  }
+
   get builder(): BuilderType<typeof coreAtoms & M> {
     return new TypedBuilder(this.atoms) as any
   }
@@ -77,9 +111,10 @@ export class AgentVM<M extends Record<string, Atom<any, any>>> {
       fuel?: number
       capabilities?: Capabilities
       trace?: boolean
-      timeoutMs?: number // Override automatic timeout (fuel * FUEL_TO_MS)
+      timeoutMs?: number // Wall-clock cap on the whole run (default: slowest atom × 2, min 60s — see defaultRunTimeout)
       signal?: AbortSignal // External abort signal (e.g., from caller)
       costOverrides?: Record<string, CostOverride> // Per-atom fuel cost overrides
+      timeoutOverrides?: Record<string, TimeoutOverride> // Per-atom timeout overrides (ms, 0 disables)
       context?: Record<string, any> // Request-scoped metadata (auth, permissions, etc.)
     } = {}
   ): Promise<RunResult> {
@@ -105,9 +140,10 @@ export class AgentVM<M extends Record<string, Atom<any, any>>> {
 
     const startFuel = options.fuel ?? 1000
 
-    // Calculate timeout from fuel budget (generous: 10ms per fuel unit)
-    // Can be overridden with explicit timeoutMs option
-    const timeoutMs = options.timeoutMs ?? startFuel * FUEL_TO_MS
+    // Run-level wall-clock timeout. Agents are typically IO-bound; the default
+    // is derived from the registered atoms (slowest × 2) so it always covers the
+    // slowest atom's own budget. See `defaultRunTimeout`.
+    const timeoutMs = options.timeoutMs ?? this.defaultRunTimeout
 
     // Default Capabilities
     const capabilities = options.capabilities ?? {}
@@ -160,8 +196,10 @@ export class AgentVM<M extends Record<string, Atom<any, any>>> {
       output: undefined,
       signal: controller.signal,
       costOverrides: options.costOverrides,
+      timeoutOverrides: options.timeoutOverrides,
       context: options.context,
       warnings, // Shared warnings array
+      helpers: (ast as any).helpers, // Local helper bodies, called by name via callLocal
     }
 
     if (options.trace) {
@@ -197,7 +235,7 @@ export class AgentVM<M extends Record<string, Atom<any, any>>> {
           controller.signal.addEventListener('abort', () => {
             reject(
               new Error(
-                `Execution timeout after ${timeoutMs}ms (fuel: ${startFuel}). Consider increasing fuel or optimizing your agent.`
+                `Execution timeout after ${timeoutMs}ms. Pass a higher \`timeoutMs\` to vm.run() or set per-atom \`timeoutOverrides\` for slow IO atoms.`
               )
             )
           })
@@ -205,7 +243,7 @@ export class AgentVM<M extends Record<string, Atom<any, any>>> {
           if (controller.signal.aborted) {
             reject(
               new Error(
-                `Execution timeout after ${timeoutMs}ms (fuel: ${startFuel}). Consider increasing fuel or optimizing your agent.`
+                `Execution timeout after ${timeoutMs}ms. Pass a higher \`timeoutMs\` to vm.run() or set per-atom \`timeoutOverrides\` for slow IO atoms.`
               )
             )
           }
@@ -219,7 +257,7 @@ export class AgentVM<M extends Record<string, Atom<any, any>>> {
         controller.signal.aborted
       ) {
         ctx.error = new AgentError(
-          `Execution timeout after ${timeoutMs}ms (fuel: ${startFuel}). Consider increasing fuel or optimizing your agent.`,
+          `Execution timeout after ${timeoutMs}ms. Pass a higher \`timeoutMs\` to vm.run() or set per-atom \`timeoutOverrides\` for slow IO atoms.`,
           'vm.run'
         )
       } else {