toolnexus 0.18.1 → 0.20.0

package/src/agents/home.ts

@@ -234,9 +234,11 @@ export function startAgent(a: Agent, run: AgentRunOptions, hb: HeartbeatOptions)
         })
       }
     }
-    cancel = runtime.clock.setTimeout(beat, hb.everyMs) // self-reschedule → one live timer
+    // keepAlive:false — a heartbeat is housekeeping and must never be the reason
+    // a host process stays up.
+    cancel = runtime.clock.setTimeout(beat, hb.everyMs, { keepAlive: false }) // self-reschedule → one live timer
   }
-  cancel = runtime.clock.setTimeout(beat, hb.everyMs)
+  cancel = runtime.clock.setTimeout(beat, hb.everyMs, { keepAlive: false })
 
   return {
     runtime,

package/src/agents/loop.ts

@@ -177,6 +177,33 @@ export async function runGated(
   }
 }
 
+/**
+ * The spec fields a Loop drive CANNOT honour, named rather than dropped silently.
+ *
+ * A `Loop` is one client run: it has no runtime, so it has no handle tree to spawn a `team`
+ * into, no §10 suspension ledger for `waitFor`, and no per-agent metric sink routing. Those
+ * fields are honoured by `Agent.run` / `AgentRuntime` only. `uses.tools` is not honoured either
+ * — a Loop is handed its toolkit by the caller.
+ *
+ * Returns a FIXED CANONICAL vocabulary — `"tools"`, `"team"`, `"waitFor"`, `"onMetric"` —
+ * identical in all seven ports, exactly as the `limit` strings are, and NOT this language's own
+ * spelling of the field. Empty ⇒ nothing is lost.
+ * Additive and advisory: a Loop never refuses to run because of it (that would be breaking).
+ */
+export function loopUnsupported(spec: {
+  uses?: { tools?: unknown[] }
+  team?: unknown[]
+  waitFor?: unknown
+  onMetric?: unknown
+}): string[] {
+  const out: string[] = []
+  if (spec.uses?.tools && spec.uses.tools.length > 0) out.push("tools")
+  if (spec.team && spec.team.length > 0) out.push("team")
+  if (spec.waitFor) out.push("waitFor")
+  if (spec.onMetric) out.push("onMetric")
+  return out
+}
+
 /** A live execution of an Agent. Its only verbs are `run` and reading state. */
 export class Loop {
   #status: Outcome["status"] | "idle" | "running" = "idle"
@@ -234,10 +261,21 @@ export class Loop {
   /** Applies a per-call model override via `requestParams` (`model` is not in the
    *  forbidden set — the client forbids only messages/tools/stream). */
   #clientOptions(opts: LoopRunOptions): ClientOptions {
+    const spec = this.agent.spec
     const base: ClientOptions = {
       ...this.options,
-      systemPrompt: this.agent.spec.soul ?? this.options.systemPrompt,
-      hooks: guardedHooks(this.agent.spec.guardrails, this.agent.spec.hooks ?? this.options.hooks),
+      // CALLER-WINS (ADR 0024 / issue #87). A `systemPrompt` the caller put on the client
+      // options is an explicit instruction for THIS drive; the soul is the agent's default.
+      // js used to let the soul override it, which python and csharp never did.
+      systemPrompt: this.options.systemPrompt ?? spec.soul,
+      // The spec's model and turn ceiling become Loop DEFAULTS — the same spec drives both
+      // doors. `ClientOptions.model` is REQUIRED in js, so "the caller did not choose" is
+      // spelled the way the runtime already spells it: absent, or the `"inherit"` sentinel.
+      model: !this.options.model || this.options.model === "inherit"
+        ? (spec.model && spec.model !== "inherit" ? spec.model : this.options.model)
+        : this.options.model,
+      maxTurns: this.options.maxTurns ?? spec.budget?.maxTurns,
+      hooks: guardedHooks(spec.guardrails, spec.hooks ?? this.options.hooks),
     }
     if (!opts.model) return base
     return { ...base, requestParams: { ...(base.requestParams ?? {}), model: opts.model } }

package/src/agents/runtime.ts

@@ -15,7 +15,17 @@
  * identical per-handle transition traces against `examples/subagent-*` fixtures.
  */
 import type { PromptInput } from "../content.js"
-import { createClient, InMemoryConversationStore, type ClientStyle, type ConversationStore, type Hooks, type MetricEvent } from "../client.js"
+import {
+  createClient,
+  createInProcessFetch,
+  InMemoryConversationStore,
+  type ClientStyle,
+  type ConversationStore,
+  type Hooks,
+  type InProcessRequest,
+  type InProcessResponse,
+  type MetricEvent,
+} from "../client.js"
 import { runGated, type Completion } from "./loop.js"
 import { createToolkit, type Toolkit } from "../toolkit.js"
 import { defineTool } from "../native.js"
@@ -29,16 +39,23 @@ import type { Answer, Request, Tool, ToolResult } from "../types.js"
 export interface Clock {
   /** Current time in ms (epoch or virtual). */
   now(): number
-  /** Schedule `fn` after `ms`; returns a cancel function. */
-  setTimeout(fn: () => void, ms: number): () => void
+  /** Schedule `fn` after `ms`; returns a cancel function.
+   *
+   * `keepAlive` defaults to TRUE, and the default is the important half: a timer
+   * that cannot hold the event loop open never fires when it is the only thing
+   * left to do — which is precisely a deadline whose promise nothing else will
+   * settle. Background housekeeping that should never hold a process open (a
+   * heartbeat) passes `false` explicitly. A host's own Clock may ignore the
+   * option; it then behaves as that host's timers always have. */
+  setTimeout(fn: () => void, ms: number, opts?: { keepAlive?: boolean }): () => void
 }
 
-/** The real clock (default). Timers are unref'd so they never hold the process open. */
+/** The real clock (default). See `Clock.setTimeout` for why `keepAlive` defaults to true. */
 export const systemClock: Clock = {
   now: () => Date.now(),
-  setTimeout(fn, ms) {
+  setTimeout(fn, ms, opts) {
     const t = setTimeout(fn, ms)
-    ;(t as { unref?: () => void }).unref?.()
+    if (opts?.keepAlive === false) (t as { unref?: () => void }).unref?.()
     return () => clearTimeout(t)
   },
 }
@@ -118,6 +135,63 @@ export interface InboxItem {
 
 export type HandleState = "idle" | "running" | "suspended" | "closed"
 
+/**
+ * The §7D AGENT status vocabulary, as a value. It is a DIFFERENT, larger closed set than the
+ * §8 CLIENT vocabulary (`RUN_STATUSES` = done/pending/incomplete): only this one contains
+ * `"timeout"`, and `"timeout"` here means a `wait()` DEADLINE expired while the child keeps
+ * running — never that an LLM call timed out. Two fields are called `status`; they are not
+ * interchangeable (ADR 0027 D2.1).
+ */
+export const TASK_STATUSES = [
+  "done", "pending", "incomplete", "interrupted", "closed", "timeout", "error",
+] as const
+
+/**
+ * The CLOSED `limit` vocabulary (addendum A14). A value NAMES THE BUDGET FIELD that stopped the
+ * run, spelled exactly as `Budget` spells it, plus the two non-budget stops `completion` and
+ * `timeout`. Identical in all seven ports, like the `loopUnsupported` strings — "which limit
+ * stopped me" is only answerable if the answer is the same word everywhere.
+ *
+ * A port's INTERNAL pool/dimension name is an implementation detail and must never leak into
+ * the field; `canonicalLimit` is the boundary that enforces that here.
+ */
+export const TASK_LIMITS = [
+  "maxTurns", "maxTokens", "maxToolCalls", "maxWallMs", "maxChildren", "maxConcurrent", "maxDepth",
+  "completion", "timeout",
+] as const
+
+export type TaskLimit = (typeof TASK_LIMITS)[number]
+
+/** Map anything the internals produce onto the closed vocabulary; unknown ⇒ undefined, never a
+ *  leaked internal name. */
+export function canonicalLimit(limit: string | undefined): TaskLimit | undefined {
+  return limit && (TASK_LIMITS as readonly string[]).includes(limit) ? (limit as TaskLimit) : undefined
+}
+
+/**
+ * NAMED CONSTANTS for the two closed vocabularies. Every `TaskResult` construction site in this
+ * file spells its status and limit through these, never as a string literal, so a rename cannot
+ * silently desync the two fields — which is exactly how `status:"timeout"` came to ship with an
+ * empty `limit` in three of the seven ports (addendum A18).
+ */
+export const S: Readonly<Record<TaskStatus, TaskStatus>> = Object.freeze({
+  done: "done", pending: "pending", incomplete: "incomplete", interrupted: "interrupted",
+  closed: "closed", timeout: "timeout", error: "error",
+})
+
+export const L: Readonly<Record<TaskLimit, TaskLimit>> = Object.freeze({
+  maxTurns: "maxTurns", maxTokens: "maxTokens", maxToolCalls: "maxToolCalls", maxWallMs: "maxWallMs",
+  maxChildren: "maxChildren", maxConcurrent: "maxConcurrent", maxDepth: "maxDepth",
+  completion: "completion", timeout: "timeout",
+})
+
+/**
+ * THE INVARIANT `S`/`L` exist to protect (addendum A18): a LIMIT stop (`incomplete`, `timeout`)
+ * names its limit; every other status carries none. It is asserted by the suite, not exported —
+ * a predicate that exists so our own tests can state a rule is not public API (A19b, ADR 0019).
+ * Ports copy the PREDICATE, not an export.
+ */
+
 export type TaskStatus =
   | "done"
   | "pending"      // §10 durable suspension — resume via runtime.resume(answer)
@@ -135,8 +209,23 @@ export interface TaskResult {
   /** Present iff status === "pending". `data.path` carries the suspended handle's
    * id path (§10 agent-escalation addendum) — never a field grafted on Request. */
   pending?: Request
+  /** Cumulative LLM round trips for this handle's SUBTREE — never per-run, never reset. */
   turns: number
+  /**
+   * Cumulative TREE total: this handle's own spend plus every descendant's, on EVERY status
+   * (ADR 0025 D1). It was already the tree total on four of the seven status branches; this
+   * gives the field one meaning. `parent.totalTokens >= child.totalTokens` always holds.
+   */
   totalTokens: number
+  /** This handle's OWN accumulated spend, excluding children. */
+  ownTokens: number
+  /**
+   * WHICH limit stopped the run, as a value to branch on rather than prose to match. Drawn from
+   * the CLOSED, cross-port `TASK_LIMITS` vocabulary (addendum A14) — it names the `Budget` field,
+   * or `completion` / `timeout`. Absent otherwise. A stop you cannot explain to a user is a bug,
+   * not a state.
+   */
+  limit?: TaskLimit
 }
 
 /** Uniform verb failure — returned, never thrown (only the root throws to the host). */
@@ -206,6 +295,8 @@ export class Handle {
   readonly deadline?: number
   /** Total tokens attributed to this handle (own turns + descendant roll-up). */
   usageTotal = 0
+  /** Tokens spent by THIS handle's own turns, excluding descendants (ADR 0025 D1). */
+  ownTokens = 0
   /** Total tool calls attributed to this handle (own + descendant roll-up). */
   toolCallsTotal = 0
   /** LLM round trips run by this handle itself (never reset — resume grows it). */
@@ -270,8 +361,16 @@ export interface RuntimeOptions {
   registry: Record<string, AgentDef>
   /** LLM endpoint. Omit for hermetic runs against an injected `fetch` mock. */
   llm?: { baseUrl?: string; style?: ClientStyle; apiKey?: string; model?: string }
-  /** HTTP transport for LLM requests (§8 Gap 2) — the hermetic-test seam. */
+  /** HTTP transport for LLM requests (§8 Gap 2) — the hermetic-test seam.
+   * Mutually exclusive with `inProcess` — `new AgentRuntime(...)` throws if both are set. */
   fetch?: typeof fetch
+  /** A model running IN THIS PROCESS (ADR 0030): the semantic counterpart to
+   * `fetch`, so a host whose model is a plain function never has to build its own
+   * `fetch`-shaped adapter. Internally this is turned into a `createInProcessFetch`
+   * adapter and wrapped by the SAME global turn gate as `fetch` — there is no second
+   * code path. Mutually exclusive with `fetch` and with `llm` — `new AgentRuntime(...)`
+   * throws if more than one of `fetch`/`inProcess` is set. */
+  inProcess?: (request: InProcessRequest) => InProcessResponse | Promise<InProcessResponse>
   /** Time source for every timer/timeout/deadline. Default: the system clock. */
   clock?: Clock
   /** The ONE ConversationStore for all handles (conversation id = handle id).
@@ -324,6 +423,20 @@ export class AgentRuntime {
   private readonly turnQueue: GateWaiter[] = []
 
   constructor(opts: RuntimeOptions) {
+    if (opts.fetch && opts.inProcess) {
+      throw new Error("toolnexus/agents: RuntimeOptions.fetch and RuntimeOptions.inProcess are mutually exclusive — set one, not both")
+    }
+    if (opts.llm && opts.inProcess) {
+      throw new Error(
+        "toolnexus/agents: RuntimeOptions.llm and RuntimeOptions.inProcess are mutually exclusive — an in-process model has no wire endpoint to point llm at",
+      )
+    }
+    if (opts.inProcess) {
+      // Reuse the SAME adapter createInProcessClient builds on (ADR 0030) — the
+      // runtime's in-process wiring is a CALLER of that export, not a second copy
+      // of the request/response assembly.
+      opts = { ...opts, fetch: createInProcessFetch(opts.inProcess) }
+    }
     this.opts = opts
     this.registry = opts.registry
     this.clock = opts.clock ?? systemClock
@@ -418,11 +531,11 @@ export class AgentRuntime {
     if (opts?.by && h.parent !== opts.by) {
       return Promise.resolve({
         text: `wait refused: only the spawner may wait on ${h.id}`,
-        isError: true, status: "error", turns: h.turnsTotal, totalTokens: h.usageTotal,
+        isError: true, status: S.error, turns: h.turnsTotal, totalTokens: h.usageTotal, ownTokens: h.ownTokens,
       })
     }
     if (h.state === "closed") {
-      return Promise.resolve(h.lastResult ?? { text: "closed", isError: true, status: "closed", turns: h.turnsTotal, totalTokens: h.usageTotal })
+      return Promise.resolve(h.lastResult ?? { text: "closed", isError: true, status: S.closed, turns: h.turnsTotal, totalTokens: h.usageTotal, ownTokens: h.ownTokens })
     }
     if (h.state === "suspended") return Promise.resolve(this.pendingResult(h))
     if (h.state === "idle" && h.lastResult && !this.isQueued(h)) return Promise.resolve(h.lastResult)
@@ -440,7 +553,7 @@ export class AgentRuntime {
         cancel = this.clock.setTimeout(() => {
           const i = h.waiters.indexOf(finish)
           if (i >= 0) h.waiters.splice(i, 1)
-          finish({ text: `wait timeout after ${opts.timeoutMs}ms (child still ${h.state})`, isError: true, status: "timeout", turns: h.turnsTotal, totalTokens: h.usageTotal })
+          finish({ text: `wait timeout after ${opts.timeoutMs}ms (child still ${h.state})`, isError: true, status: S.timeout, limit: L.timeout, turns: h.turnsTotal, totalTokens: h.usageTotal, ownTokens: h.ownTokens })
         }, opts.timeoutMs)
       }
     })
@@ -496,7 +609,7 @@ export class AgentRuntime {
     await h.def.onClose?.(h, reason)
     const prev = h.state
     h.state = "closed"
-    const final: TaskResult = { text: "closed", isError: true, status: "closed", turns: h.turnsTotal, totalTokens: h.usageTotal }
+    const final: TaskResult = { text: "closed", isError: true, status: S.closed, turns: h.turnsTotal, totalTokens: h.usageTotal, ownTokens: h.ownTokens }
     for (const w of h.waiters.splice(0)) w(final)
     this.t(`${h.id}: ${prev}→closed (${reason})`)
   }
@@ -527,16 +640,19 @@ export class AgentRuntime {
    * REATTACHES to the existing child by task key — never spawns a duplicate.
    * The root alone may throw to the host.
    */
-  async resume(answer: Answer): Promise<void> {
+  async resume(answer: Answer): Promise<TaskResult> {
     const leaf = this.deepestSuspended(this.root)
     if (!leaf) throw new Error("no suspended handle to resume")
     this.t(`${leaf.id}: resume with Answer(ok=${answer.ok}) at checkpoint (turns so far: ${leaf.turnsTotal})`)
-    await this.resumeSuspended(leaf, answer, { inline: false })
+    // The value is the settled result of the TOPMOST handle the cascade re-ran — what the host
+    // would have got from `Agent.run` had the suspension never happened (ADR 0025 D3).
+    let topmost = await this.resumeSuspended(leaf, answer, { inline: false })
     for (let p = leaf.parent; p && p !== this.root; p = p.parent) {
       if (p.state !== "suspended") break
       this.t(`${p.id}: cascade resume (reattaching delegated work)`)
-      await this.resumeSuspended(p, undefined, { inline: false })
+      topmost = await this.resumeSuspended(p, undefined, { inline: false })
     }
+    return topmost
   }
 
   private deepestSuspended(h: Handle): Handle | null {
@@ -580,25 +696,28 @@ export class AgentRuntime {
   // ---- budgets (live ancestor-chain enforcement + roll-up ledger) --------
 
   /** Walk the LIVE ancestor chain; name the first exhausted pool, if any. */
-  private poolLimit(h: Handle): string | undefined {
+  private poolLimit(h: Handle): TaskLimit | undefined {
     const now = this.clock.now()
     for (let a: Handle | null = h; a; a = a.parent) {
-      if (a.pool.tokens <= 0) return "maxTokens"
-      if (a.pool.toolCalls <= 0) return "maxToolCalls"
-      if (a.deadline !== undefined && now >= a.deadline) return "maxWallMs"
+      if (a.pool.tokens <= 0) return L.maxTokens
+      if (a.pool.toolCalls <= 0) return L.maxToolCalls
+      if (a.deadline !== undefined && now >= a.deadline) return L.maxWallMs
     }
     return undefined
   }
 
   /** Lifetime turn cap on the handle itself (turns never reset across resumes). */
-  private turnCap(h: Handle): string | undefined {
-    return h.turnsTotal >= h.eff.maxTurns ? "maxTurns" : undefined
+  private turnCap(h: Handle): TaskLimit | undefined {
+    return h.turnsTotal >= h.eff.maxTurns ? L.maxTurns : undefined
   }
 
   /** A limit stop is LOUD: settle an incomplete result (never silent, never a throw). */
-  private settleRefused(h: Handle, limit: string): string {
+  private settleRefused(h: Handle, limit: TaskLimit): string {
+    // `limit` here is already a Budget field name (`poolLimit`/`turnCap` return them verbatim);
+    // `canonicalLimit` below is the guard that keeps it that way if either ever changes.
     const text = `budget exhausted (${limit}); partial work preserved`
-    const r: TaskResult = { text, isError: true, status: "incomplete", turns: h.turnsTotal, totalTokens: h.usageTotal }
+    // The exhausted pool is COMPUTED here and used to be discarded into prose. `limit` carries it.
+    const r: TaskResult = { text, isError: true, status: S.incomplete, turns: h.turnsTotal, totalTokens: h.usageTotal, ownTokens: h.ownTokens, limit }
     h.lastResult = r
     for (const w of h.waiters.splice(0)) w(r)
     return text
@@ -606,6 +725,7 @@ export class AgentRuntime {
 
   /** Usage roll-up IS the budget ledger: every ancestor's pool drains live. */
   private rollUp(h: Handle, tokens: number, toolCalls: number): void {
+    h.ownTokens += tokens // own figure: outside the ancestor walk, by construction
     for (let a: Handle | null = h; a; a = a.parent) {
       a.usageTotal += tokens
       a.toolCallsTotal += toolCalls
@@ -728,7 +848,7 @@ export class AgentRuntime {
 
   private pendingResult(h: Handle): TaskResult {
     const req = h.pendingRequest
-    return { text: req?.prompt ?? "", isError: false, status: "pending", pending: req, turns: h.turnsTotal, totalTokens: h.usageTotal }
+    return { text: req?.prompt ?? "", isError: false, status: S.pending, pending: req, turns: h.turnsTotal, totalTokens: h.usageTotal, ownTokens: h.ownTokens }
   }
 
   /** The escalation seam: this handle's §10 interpreter authority, with the
@@ -801,7 +921,7 @@ export class AgentRuntime {
         h.checkpoint = { input }
         h.drained = [] // drained items ride the checkpointed input, not the inbox
         this.t(`${h.id}: running→suspended (pending "${stamped.kind}")`)
-        result = { text: r.text, isError: false, status: "pending", pending: stamped, turns: r.turns, totalTokens: r.usage.totalTokens }
+        result = { text: r.text, isError: false, status: S.pending, pending: stamped, turns: h.turnsTotal, totalTokens: h.usageTotal, ownTokens: h.ownTokens }
       } else if (r.status === "incomplete") {
         h.state = "idle"
         h.drained = []
@@ -810,13 +930,17 @@ export class AgentRuntime {
         // generic sentence. Reading `limit` is how the runtime tells them apart.
         result = {
           text: r.limit === "completion" ? r.text : "hit maxTurns without a final answer",
-          isError: true, status: "incomplete", turns: r.turns, totalTokens: r.usage.totalTokens,
+          isError: true, status: S.incomplete, turns: h.turnsTotal, totalTokens: h.usageTotal, ownTokens: h.ownTokens,
+          // The LATENT instance golang found: forwarding the client's `limit` straight through
+          // would hand a host `incomplete` with an empty limit whenever the client omits it.
+          // The `?? L.maxTurns` is what makes the invariant hold by construction, not by luck.
+          limit: canonicalLimit(r.limit) ?? L.maxTurns,
         }
       } else {
         h.state = "idle"
         h.drained = []
         this.t(`${h.id}: running→idle (done, turns=${r.turns}, tokens=${r.usage.totalTokens})`)
-        result = { text: r.text, isError: false, status: "done", turns: r.turns, totalTokens: r.usage.totalTokens }
+        result = { text: r.text, isError: false, status: S.done, turns: h.turnsTotal, totalTokens: h.usageTotal, ownTokens: h.ownTokens }
       }
     } catch (e) {
       const aborted = h.abort?.signal.aborted ?? false
@@ -828,8 +952,9 @@ export class AgentRuntime {
       this.t(`${h.id}: running→idle (${aborted ? "interrupted; inbox intact" : `error: ${msg}`})`)
       result = {
         text: msg, isError: true,
-        status: closing ? "closed" : aborted ? "interrupted" : "error",
-        turns: h.turnsTotal, totalTokens: h.usageTotal,
+        // None of these three is a limit stop, so none carries a `limit` (A18).
+        status: closing ? S.closed : aborted ? S.interrupted : S.error,
+        turns: h.turnsTotal, totalTokens: h.usageTotal, ownTokens: h.ownTokens,
       }
     } finally {
       this.releaseChildSlot(h)
@@ -904,7 +1029,7 @@ export class AgentRuntime {
           } else if (existing.state === "running") {
             r = await rt.wait(existing, { by: parent })
           } else {
-            r = existing.lastResult ?? { text: `no recorded result for ${existing.id}`, isError: true, status: "error", turns: existing.turnsTotal, totalTokens: existing.usageTotal }
+            r = existing.lastResult ?? { text: `no recorded result for ${existing.id}`, isError: true, status: S.error, turns: existing.turnsTotal, totalTokens: existing.usageTotal, ownTokens: existing.ownTokens }
           }
         } else {
           const spawned = rt.spawn(parent, name)