tardie 0.3.0 → 0.4.0

package/src/agent/{infer.ts → runtime/infer.ts}

@@ -1,11 +1,11 @@
 import { Cause, Clock, Context, Effect } from "effect"
 import { EventLog } from "tardie/core/event-log"
 import { transition, type Reactor } from "tardie/core/actor"
-import { modelCalled, textReturned, turnFailed } from "./events"
+import { modelCalled, textReturned, turnFailed } from "../events"
 import type { Event } from "tardie/core/event"
-import type { Action } from "./events"
+import type { Action } from "../events"
 import { trajectoryOf, turnEpochOf, turnView } from "tardie/code/turns"
-import type { ContextPolicy } from "./compaction"
+import type { ContextPolicy } from "../components/compaction"
 
 // The infer reactor: the model loop, and nothing else. A think is owed when the current turn
 // has no unanswered tool call and no terminal; serving marks the attempt, does inference, then
@@ -28,9 +28,9 @@ export const DEFAULT_INFER_POLICY: InferPolicy = { giveUpAfter: 3, repairAtMost:
 export interface InferRequest {
   readonly trajectory: ReadonlyArray<Event>
   readonly system: string
-  readonly tools: ReadonlyArray<import("./request").ToolSpec>
+  readonly tools: ReadonlyArray<import("../request").ToolSpec>
   // What the render truncates and where, stated by the assembly so the binding renders against
-  // the same numbers the compaction guard fires on (capability.ts, compactionFor).
+  // the same numbers the compaction guard fires on (components/compaction.ts, compactionFor).
   readonly context?: Partial<ContextPolicy>
 }
 
@@ -111,11 +111,11 @@ const terminated = (slice: ReadonlyArray<Event>): boolean =>
 const terminalKey = (turn: string, epoch: number): string =>
   epoch === 0 ? `tn:${turn}` : `tn:${turn}/${epoch}`
 
-// Render derives what the model is shown over this log: the assembly owns it (capability.ts,
+// Render derives what the model is shown over this log: the assembly owns it (runtime/agent.ts,
 // renderOf).
 export type Render = (log: ReadonlyArray<Event>) => {
   readonly system: string
-  readonly tools: ReadonlyArray<import("./request").ToolSpec>
+  readonly tools: ReadonlyArray<import("../request").ToolSpec>
   readonly context?: Partial<ContextPolicy>
 }
 

package/src/agent/{tools.ts → runtime/tools.ts}

@@ -1,13 +1,13 @@
 import { Clock, Effect } from "effect"
 import { transition, type Reactor, type Transition } from "tardie/core/actor"
-import { budgetRequested, toolReturned } from "./events"
+import { budgetRequested, toolReturned } from "../events"
 import type { Event } from "tardie/core/event"
 import { turnView } from "tardie/code/turns"
-import { budgetSpent } from "./budget"
-import { answerErrors, outputSchemaOf, repairText } from "./contract"
+import { budgetSpent } from "../components/budget"
+import { answerErrors, outputSchemaOf, repairText } from "../contract"
 // The tools reactor: the agent's side of the tool table. The policy here is the same whatever
 // the tools are: the answer contract, the escalation ask, the budget wall, and the unknown-tool
-// error. The work tools themselves come from the mounted capabilities (capability.ts), so an
+// error. The work tools themselves come from the mounted components (runtime/agent.ts), so an
 // agent measured against a fixed tool table mounts `toolList` and keeps every behavior here.
 //
 
@@ -24,7 +24,7 @@ export interface PendingCall {
 export type Answer = (result: unknown) => Transition<never, never>
 
 // Serve returns the transitions one call owes: an empty array while the world still works, and
-// undefined when the call names no tool of its capability.
+// undefined when the call names no derived tool.
 export type Serve<R = never> = (
   call: PendingCall,
   log: ReadonlyArray<Event>,
@@ -79,15 +79,15 @@ const decisionFor = (
 
 // toolsReactorFor derives one transition per pending call, branch by branch. The records each
 // branch appends carry the keys: an answer tr:<callId>, an escalation ask br:<callId>, and
-// whatever key the capability's own dispatch mints. An escalating call with no parental decision
+// whatever key the component's own dispatch mints. An escalating call with no parental decision
 // derives nothing (the turn is durably paused); the decision's arrival re-derives the answer.
-// Every branch here is capability-independent policy; a capability's serve decides only how a
+// Every branch here is component-independent policy; a tool binding decides only how a
 // work call becomes events.
-// toolsReactorFrom is the policy over a routed serve and a derived tool list: the capability
-// assembly's entry (capability.ts), where the tools are a projection of the log.
+// toolsReactorFrom is the policy over a routed serve and a derived tool list: the component
+// assembly's entry (runtime/agent.ts), where the tools are information derived from the log.
 export const toolsReactorFrom = <R = never>(
   serve: Serve<R>,
-  toolsFor: (log: ReadonlyArray<Event>) => ReadonlyArray<{ readonly name: string }>
+  toolsFor: (log: ReadonlyArray<Event>, call: PendingCall) => ReadonlyArray<{ readonly name: string }>
 ): Reactor<R> => (log) => {
   const call = pendingCall(log)
   if (call === undefined) return []
@@ -138,7 +138,7 @@ export const toolsReactorFrom = <R = never>(
     return [answering({ error: repairText(errors.length > 0 ? errors : ["the answer tool was called with no arguments"]) })]
   }
   // The budget gate: the wall on the turn refuses the work and keeps what the model has. It
-  // precedes the serve so a spent turn cannot dispatch, whatever a capability would have done.
+  // precedes the serve so a spent turn cannot dispatch, whatever a component would have done.
   if (budgetSpent(log)) {
     return [
       answering({
@@ -148,7 +148,7 @@ export const toolsReactorFrom = <R = never>(
   }
   const served = serve(call, log, answering)
   if (served === undefined) {
-    return [answering({ error: `unknown tool: ${call.name}. Call one of: ${toolsFor(log).map((t) => t.name).join(", ")}.` })]
+    return [answering({ error: `unknown tool: ${call.name}. Call one of: ${toolsFor(log, call).map((t) => t.name).join(", ")}.` })]
   }
   return served
 }

package/src/agent/spawn.ts

@@ -3,7 +3,7 @@ import { Router } from "tardie/core/router"
 import { Self } from "tardie/core/actor"
 import { Facets } from "tardie/core/facets"
 import type { Package } from "tardie/code/packages"
-import { budgetPolicyOf, type BudgetPolicy } from "./budget"
+import { budgetPolicyOf, type BudgetPolicy } from "./components/budget"
 import { Park } from "tardie/code/errors"
 import { address as addressOf, readAddress } from "tardie/core/router"
 import { replyId } from "tardie/core/message"
@@ -51,7 +51,7 @@ import { replyId } from "tardie/core/message"
 // budget takes the same ceiling the child's own reactor would, and a consumer that moved that
 // ceiling moves both (budget.ts, BudgetPolicy).
 export interface SpawnOptions {
-  readonly agentOf?: () => string | undefined
+  readonly actorNameOf?: () => string | undefined
   readonly reserve?: (callId: string, want: number) => Promise<number>
   readonly shadowOf?: () => boolean
   // The parent's explicit world label, when its own fire named a shared world instead of taking
@@ -71,7 +71,7 @@ export const agentsPackage = (
   options: SpawnOptions & { readonly place?: (callId: string, self: string) => string } = {}
 ): Package<Router | Self | Facets> => {
   const place = options.place ?? sibling
-  const agentOf = options.agentOf ?? (() => undefined)
+  const actorNameOf = options.actorNameOf ?? (() => undefined)
   const reserve = options.reserve ?? (async (_callId: string, want: number) => want)
   const shadowOf = options.shadowOf ?? (() => false)
   const worldOf = options.worldOf ?? (() => undefined)
@@ -156,7 +156,7 @@ export const agentsPackage = (
           if (budget <= 0) return { error: "the run's budget is exhausted; no budget to spawn this agent" }
           // The child works as the same member the parent does: the actor rides every brief in the
           // family, so a run's whole tree resolves connections identically.
-          const actor = agentOf()
+          const actor = actorNameOf()
           // The parent's own shadow reading, never the tool args: an agent cannot set or unset it, so
           // a whole run family is shadow by construction from the fire alone. `world` rides along
           // the same way, when the fire named an explicit shared one.

package/src/agent/turn.ts

@@ -5,28 +5,28 @@ import { send, type Actor } from "tardie/core/actor"
 import type { Router } from "tardie/core/router"
 import type { Self } from "tardie/core/actor"
 import type { Facets } from "tardie/core/facets"
-import type { Infer, InferPolicy } from "./infer"
-import type { BudgetPolicy } from "./budget"
-import type { ContextPolicy } from "./compaction"
+import type { Infer, InferPolicy } from "./runtime/infer"
+import type { BudgetPolicy } from "./components/budget"
+import type { ContextPolicy } from "./components/compaction"
 import type { CodePolicy } from "tardie/code/execute"
 import type { WorkspacePolicy } from "tardie/code/workspace"
 
-export { Infer } from "./infer"
+export { Infer } from "./runtime/infer"
 
 // AgentR is the runtime's needs: Infer for the model, EventLog for settle, Router, Self, and
 // Facets for reply and spawn (the deliver, identity, and observe privileges; core/facets.ts), and
 // KeyValueStore for the spill store code mode writes bounded results to
-// (packages/code/src/spill.ts). Capabilities add their own on top (capability.ts,
-// RequirementsOf).
+// (packages/code/src/spill.ts). Components add their own on top (core/component.ts,
+// ComponentRequirements).
 export type AgentR = Infer | EventLog | Router | Self | Facets | KeyValueStore.KeyValueStore
 export type RlmR = AgentR
 
 // AgentPolicy is every policy value an assembled agent applies, one field per part that applies
 // one, so a caller sets a single number without listing reactors. Each field is itself partial
 // and fills from its own exported default (infer.ts, budget.ts, compaction.ts,
-// packages/code/src/execute.ts). `infer` is the runtime's policy (agentOf takes it); `workspace`
+// packages/code/src/execute.ts). `infer` is the runtime's policy (agentRuntime takes it); `workspace`
 // bounds the workspace package's own read and grep answers (packages/code/src/workspace.ts); the
-// rest ride their capabilities (budgetFor, compactionFor, codeModeFor).
+// rest ride their components (budgetFor, compactionFor, codeModeFor).
 export interface AgentPolicy {
   readonly infer: Partial<InferPolicy>
   readonly budget: Partial<BudgetPolicy>

package/src/client/contract.ts

@@ -323,7 +323,7 @@ export const projection = <Params extends Schema.Struct.Fields, Result extends S
 
 // The two names a projection may not claim. The log is not a projection of itself: `events` is the
 // log read back and `stream` is the same log followed, and both are the platform's own guarantee
-// rather than anything an actor derives (projectionsOf refuses either, the way agentOf refuses a
+// rather than anything an actor derives (projectionsOf refuses either, the way agentRuntime refuses a
 // duplicate tool).
 export const RESERVED_PROJECTIONS: ReadonlyArray<string> = ["events", "stream"]
 

package/src/code/execute.ts

@@ -288,11 +288,11 @@ export interface CodePolicy {
 // The packages arrive as values, and what they need arrives with them: the reactor's environment
 // is the spill store plus the union of the packages' own requirements, so a lane assembled with a
 // service-needing package cannot be run where that service is missing (execute.test.ts, "a
-// package's requirements ride its type"). Which packages are passed is the capability scope: the
+// package's requirements ride its type"). Which packages are passed is the component scope: the
 // code can only name these, and the empty array is the powerless lane (packages.ts, Package).
 // Two packages under one name would make `pkg.name` ambiguous in the body's scope, so a duplicate
-// is a construction-time error, the same reading agentOf takes of two capabilities claiming one
-// tool name (packages/agent/src/capability.ts, agentOf).
+// is a construction-time error, the same reading agentRuntime takes of two components claiming one
+// tool name (packages/agent/src/runtime/agent.ts, agentRuntime).
 export const codeReactorFor = <const P extends ReadonlyArray<Package<never>> | ReadonlyArray<Package<unknown>>>(
   policy: Partial<CodePolicy>,
   packages: P

package/src/code/index.ts

@@ -1,4 +1,4 @@
-// The package root: the reactor and the key fragment a caller assembles an agent from. The
-// subpath exports stay for everything else.
+// The package root exposes the code reactor and its event keys. Agent assemblies adapt these
+// through codeModeFor in packages/agent/src/components/code.ts.
 export { codeReactor } from "./execute"
 export { codeKeys } from "./events"

package/src/code/packages.ts

@@ -91,8 +91,8 @@ export const annotationsOf = (pkg: Package<unknown>, method: string): Required<M
   ...pkg.annotations?.[method]
 })
 
-// Package is one named unit of an actor's world face, the dual of a Capability on its model
-// face (packages/agent/src/capability.ts). A capability declares what the model is offered
+// Package is one named unit of an actor's world face, the dual of an AgentComponent on its model
+// face (packages/agent/src/runtime/agent.ts). A component derives what the model is offered
 // (`tools`, `system`) and what settles its calls (`serve`); a package declares what code is
 // offered (`name`, `description`, `docs`) and what settles its calls (`methods`). Code calls
 // methods as `zohorecruit.insert_record(args)`. The platform binds the methods to providers;
@@ -107,11 +107,11 @@ export const annotationsOf = (pkg: Package<unknown>, method: string): Required<M
 // deliberately outside Package: it belongs to the host boundary and gets its own concept once a
 // consumer exists.
 //
-// Which packages an assembly passes is capability scoping: a task that must never send messages
+// Which packages an assembly passes is component scoping: a task that must never send messages
 // is given no sending package, and the code cannot name what the assembly did not pass. The
 // powerless default is the empty array (execute.ts, codeReactor).
 //
-// `R` is what a package's methods need from the environment, the dual of `Capability<R>` on the
+// `R` is what a package's methods need from the environment, the dual of `AgentComponent<R>` on the
 // model face. A package that reaches for a service names it in its type, and the reactor that
 // runs the package declares the union of what its packages need (execute.ts, codeReactorFor); a
 // package that reaches for nothing is `Package<never>` and runs anywhere.
@@ -136,7 +136,7 @@ export interface Package<R = never> {
 
 // PackageRequirements extracts one package's R, so a mixed list infers the union of what its
 // members need rather than collapsing on the first element's R. It is the package-face twin of
-// RequirementsOf (packages/agent/src/capability.ts), and what makes the environment a code
+// ComponentRequirements (packages/core/src/component.ts), and what makes the environment a code
 // reactor demands a function of the packages it was passed (execute.test.ts, "a package's
 // requirements ride its type").
 export type PackageRequirements<T> = T extends Package<infer R> ? R : never

package/src/core/component.ts

@@ -0,0 +1,102 @@
+import { actor, type Actor, type Reactor, type Transition } from "./actor"
+import type { Event } from "./event"
+import { composeKeys, type KeyFragment } from "./event-log"
+
+// Derivation is one component's reading of a log: information for consumers and transitions
+// for the actor runtime. The information follows tla/Projection.tla, ViewFaithful. The
+// transitions follow tla/Reconcile.tla, NoVoid.
+export interface Derivation<I, R = never> {
+  readonly info: I
+  readonly transitions: ReadonlyArray<Transition<never, R>>
+}
+
+// Component derives information and owed work from the same log. Its key fragment declares how
+// the events its transitions append prove commitment to the actor runtime.
+export interface Component<I, R = never> {
+  readonly name: string
+  readonly keys?: KeyFragment
+  readonly derive: (log: ReadonlyArray<Event>) => Derivation<I, R>
+}
+
+// InfoAlgebra states how independently derived information composes. Callers supply the empty
+// value and combination rule because ordering, collisions, and overrides belong to the
+// information's consumer.
+export interface InfoAlgebra<I> {
+  readonly empty: I
+  readonly combine: (left: I, right: I) => I
+}
+
+// ComponentRuntime interprets composed information as reactors and supplies the key fragments
+// for its protocol. The reactor factory is polymorphic in component requirements because an
+// interpreter may route work whose environment is declared by the component that contributed it.
+export interface ComponentRuntime<I, R = never> {
+  readonly name: string
+  readonly algebra: InfoAlgebra<I>
+  readonly keys: ReadonlyArray<KeyFragment>
+  readonly reactors: <C>(infoOf: (log: ReadonlyArray<Event>) => I) => ReadonlyArray<Reactor<R | C>>
+}
+
+// ComponentRequirements extracts a component's environment so composition carries the union of every
+// member's requirements to the actor that hosts it.
+export type ComponentRequirements<C> = C extends Component<unknown, infer R> ? R : never
+
+// composeComponents derives the algebraic sum of each component's information and concatenates
+// its transitions in component order. The name is explicit because traces and collision errors
+// identify the resulting component with it.
+export const composeComponents = <
+  I,
+  const Cs extends ReadonlyArray<Component<I, never> | Component<I, unknown>>
+>(
+  name: string,
+  algebra: InfoAlgebra<I>,
+  components: Cs
+): Component<I, ComponentRequirements<Cs[number]>> => {
+  const members = components as ReadonlyArray<Component<I, ComponentRequirements<Cs[number]>>>
+  const fragments = members.flatMap((component) => component.keys === undefined ? [] : [component.keys])
+  const keys = fragments.length === 0
+    ? undefined
+    : {
+        prefixes: fragments.flatMap((fragment) => fragment.prefixes),
+        keyOf: composeKeys(...fragments)
+      }
+  return {
+    name,
+    ...(keys === undefined ? {} : { keys }),
+    derive: (log) => {
+      let info = algebra.empty
+      const transitions: Array<Transition<never, ComponentRequirements<Cs[number]>>> = []
+      for (const component of members) {
+        const derived = component.derive(log)
+        info = algebra.combine(info, derived.info)
+        transitions.push(...derived.transitions)
+      }
+      return { info, transitions }
+    }
+  }
+}
+
+// reactorOf exposes a component's owed-work projection to the existing actor reconciler.
+export const reactorOf = <I, R>(component: Component<I, R>): Reactor<R> =>
+  (log) => component.derive(log).transitions
+
+// actorOf composes components under one information runtime and adapts their transitions to the
+// existing actor reconciler. Runtime keys compose beside component keys with the same collision
+// rule as composeKeys.
+export const actorOf = <
+  I,
+  RuntimeR,
+  const Cs extends ReadonlyArray<Component<I, never> | Component<I, unknown>>
+>(
+  runtime: ComponentRuntime<I, RuntimeR>,
+  components: Cs
+): Actor<RuntimeR | ComponentRequirements<Cs[number]>> => {
+  type ComponentR = ComponentRequirements<Cs[number]>
+  type R = RuntimeR | ComponentR
+  const combined = composeComponents(runtime.name, runtime.algebra, components) as Component<I, R>
+  const infoOf = (log: ReadonlyArray<Event>): I => combined.derive(log).info
+  const reactors = runtime.reactors<ComponentR>(infoOf) as ReadonlyArray<Reactor<R>>
+  return actor(
+    [...reactors, reactorOf(combined)],
+    composeKeys(...runtime.keys, ...(combined.keys === undefined ? [] : [combined.keys]))
+  )
+}

package/src/model/model.ts

@@ -4,7 +4,7 @@ import { openaiCompatibleText } from "@tanstack/ai-openai/compatible"
 import * as BedrockRuntime from "@aws-sdk/client-bedrock-runtime"
 import { FetchHttpHandler } from "@smithy/fetch-http-handler"
 import { BedrockConverseTextAdapter, type BEDROCK_CONVERSE_MODELS } from "@tanstack/ai-bedrock"
-import { Infer, type InferRequest } from "tardie/infer"
+import { Infer, type InferRequest } from "tardie"
 import type { Action } from "tardie/events"
 import type { Event } from "tardie/core/event"
 import { assertSupportedBun } from "tardie/core/runtime"
@@ -540,7 +540,7 @@ export const infer = (config: ModelConfig) => {
             fetch: fetcher
           })
     // The actor decides the request, render included; the platform maps it to the wire and
-    // streams it, holding no opinion about tools (tardie, capability.ts).
+    // streams it, holding no opinion about tools (tardie, runtime/agent.ts).
     const req = modelRequest(request.trajectory, request, request.context ?? {})
     const schema = outputSchemaOf(request.trajectory) // the answer parser needs the turn's declared shape
     const stream = adapter.chatStream({

package/src/server/actor.ts

@@ -2,7 +2,8 @@ import { Schema } from "effect"
 import type { Event } from "tardie/core/event"
 import type { Actor } from "tardie/core/actor"
 import {
-  agentOf,
+  actorOf,
+  agentRuntime,
   agentsPackage,
   budget,
   codeModeFor,
@@ -24,7 +25,7 @@ import { inboundOf } from "./projections"
 // mounts what is declared here by name (packages/client/src/contract.ts, apiOf).
 
 // The assembly, one for every lane: code mode with four packages in scope, plus the three policy
-// capabilities. v1 runs this one assembly and forking is the customization path (apps-server-spec.md,
+// components. v1 runs this one assembly and forking is the customization path (apps-server-spec.md,
 // "Explicitly out of scope for v1").
 //
 // What the four packages add up to is what this actor can reach. `agents` fans work out to children
@@ -33,12 +34,15 @@ import { inboundOf } from "./projections"
 // requests to any host. There is no shell: a shell cannot be scoped the way a root or an origin can,
 // and this build has no place to ask an operator whether one command is allowed.
 export const assemblyOf = () =>
-  agentOf([
-    codeModeFor({ packages: [agentsPackage(), workspacePackage(), filesPackage(), fetchPackage()] }),
-    reply,
-    budget,
-    compaction
-  ])
+  actorOf(
+    agentRuntime(),
+    [
+      codeModeFor({ packages: [agentsPackage(), workspacePackage(), filesPackage(), fetchPackage()] }),
+      reply,
+      budget,
+      compaction
+    ]
+  )
 
 // ServerR is what this assembly needs bound. It is read off the assembly rather than restated, so a
 // package added above lands in the host's obligation and a host that binds nothing for it fails to