tjs-lang 0.8.1 → 0.8.3

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)
@@ -215,3 +229,15 @@ export const llmVision = defineAtom(
   },
   { docs: 'Analyze images using a vision model', timeoutMs: 120000, cost: 150 }
 )
+
+// Every battery atom is IO (embedding/LLM/vector-store network calls).
+for (const atom of [
+  storeVectorize,
+  storeCreateCollection,
+  storeVectorAdd,
+  storeSearch,
+  llmPredictBattery,
+  llmVision,
+]) {
+  atom.effects = 'io'
+}

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,12 +170,28 @@ 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>
 
+/**
+ * Effect classification of an atom.
+ * - `'pure'`: deterministic, no IO, no capability access, no observable side
+ *   effects — safe inside a synchronous predicate (see the predicate verifier).
+ * - `'io'`: touches `ctx.capabilities` (fetch/store/llm/agent/code), or is
+ *   nondeterministic (random/uuid), or has side effects (console). Not allowed
+ *   in a predicate.
+ * Defaults to `'pure'`; effectful atoms must opt into `'io'`. The invariant
+ * "anything touching ctx.capabilities is tagged 'io'" is guarded by a test.
+ */
+export type AtomEffects = 'pure' | 'io'
+
 export interface AtomDef {
   op: OpCode
   inputSchema: any
@@ -179,6 +200,7 @@ export interface AtomDef {
   docs?: string
   timeoutMs?: number
   cost?: number | ((input: any, ctx: RuntimeContext) => number)
+  effects?: AtomEffects
 }
 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -190,6 +212,8 @@ export interface AtomOptions {
   docs?: string
   timeoutMs?: number
   cost?: number | ((input: any, ctx: RuntimeContext) => number)
+  /** Effect class — defaults to `'pure'`; effectful atoms set `'io'`. */
+  effects?: AtomEffects
 }
 
 export interface RunResult {
@@ -1338,6 +1362,7 @@ export function defineAtom<I extends Record<string, any>, O = any>(
     docs = '',
     timeoutMs = 1000,
     cost = 1,
+    effects = 'pure',
   } = typeof options === 'string' ? { docs: options } : options
 
   const exec: AtomExec = async (step: any, ctx: RuntimeContext) => {
@@ -1363,18 +1388,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))
@@ -1430,6 +1462,7 @@ export function defineAtom<I extends Record<string, any>, O = any>(
     docs,
     timeoutMs,
     cost,
+    effects,
     create: (input: I) => ({ op, ...input }),
   }
 }
@@ -1562,8 +1595,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 +1822,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 +3092,7 @@ export const coreAtoms = {
   varsLet,
   varsExport,
   scope,
+  callLocal,
   map,
   filter,
   reduce,
@@ -3029,3 +3131,37 @@ export const coreAtoms = {
   releaseProcedure,
   clearExpiredProcedures,
 }
+
+/**
+ * Effectful core atoms — anything that touches `ctx.capabilities`
+ * (fetch/store/llm/agent/code), is nondeterministic (random/uuid), or has
+ * observable side effects (console). Tagged centrally so the list reads as one
+ * audit surface; a test asserts every capability-touching atom is in here.
+ * Everything else defaults to `effects: 'pure'`.
+ */
+export const EFFECTFUL_CORE_OPS = [
+  'httpFetch',
+  'storeGet',
+  'storeSet',
+  'storeQuery',
+  'storeVectorSearch',
+  'llmPredict',
+  'agentRun',
+  'transpileCode',
+  'runCode',
+  'random',
+  'uuid',
+  'consoleLog',
+  'consoleWarn',
+  'consoleError',
+  'storeProcedure',
+  'releaseProcedure',
+  'clearExpiredProcedures',
+  'cache',
+  'memoize',
+] as const
+
+for (const op of EFFECTFUL_CORE_OPS) {
+  const atom = (coreAtoms as Record<string, AtomDef>)[op]
+  if (atom) atom.effects = 'io'
+}

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 {