tardie 0.14.0 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tardie",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "license": "MIT",
   "author": "Clavia, Inc.",
   "description": "A durable agent harness. State is a pure function of the log.",
@@ -16,7 +16,7 @@
     "access": "public"
   },
   "tardigrade": {
-    "sourceTree": "97448ddae8564fb78c339ce7cc9423dfe7e18b73"
+    "sourceTree": "9d578e4ded2cd6f98b5b20d18d9c68df4a7622fa"
   },
   "files": [
     "src",

package/src/agent/components/budget-authority.ts

@@ -3,7 +3,7 @@ import { Schema } from "effect"
 import type { KeyFragment } from "tardie/core/log"
 import { intent, type Transition } from "tardie/core/reconciliation"
 import { handles, type Component } from "tardie/core/actor"
-import { formatActorId, isActorId } from "tardie/core/communication/endpoint"
+import { formatThreadAddress, isThreadAddress } from "tardie/core/communication/endpoint"
 import { BudgetDecision } from "../actor/budget"
 import { budgetRequestDecided, budgetRequestFailed } from "../log/events"
 import { requestBudgetMethod } from "../actor/budget"
@@ -70,7 +70,7 @@ const authorityTransition = (
     turn: String(received.turn ?? ""),
     reason: String(received.reason ?? ""),
     amount,
-    ...(isActorId(received.link?.source) ? { from: formatActorId(received.link.source) } : {}),
+    ...(isThreadAddress(received.link?.source) ? { from: formatThreadAddress(received.link.source) } : {}),
     grant: (granted = amount) => ({ granted }),
     deny: (reason) => ({ denied: true, ...(reason === undefined ? {} : { reason }) })
   }

package/src/agent/components/budget.ts

@@ -13,7 +13,7 @@ import { turnHead, turnView } from "tardie/code/execution/turns"
 import { AGENT_VIEW_ALGEBRA, type AgentComponent, type AgentTool, type AgentView } from "../runtime/composition"
 import type { ToolSpec } from "../inference/request"
 import { Router } from "tardie/core/communication/router"
-import { formatActorId, isActorId, type ActorId } from "tardie/core/communication/endpoint"
+import { formatThreadAddress, isThreadAddress, type ThreadAddress } from "tardie/core/communication/endpoint"
 import type { Link } from "tardie/core/communication/link"
 import { threadCreatedOf } from "tardie/core/thread"
 import { requestBudgetMethod } from "../actor/budget"
@@ -194,8 +194,8 @@ const requestBudgetTool: AgentTool = {
   }
 }
 
-const requestCallId = (child: ActorId, turn: string, request: string): string =>
-  `budget/${formatActorId(child)}/${turn}/${request}`
+const requestCallId = (child: ThreadAddress, turn: string, request: string): string =>
+  `budget/${formatThreadAddress(child)}/${turn}/${request}`
 
 const authorityFor = (
   log: ReadonlyArray<Event>,
@@ -206,17 +206,17 @@ const authorityFor = (
   if ("address" in authority) return authority
   const head = log.find((event) =>
     event.type === "MessageReceived" && String((event as { readonly id?: unknown }).id) === turn
-  ) as { readonly link?: Link<unknown, ActorId> } | undefined
-  return isActorId(head?.link?.source)
+  ) as { readonly link?: Link<unknown, ThreadAddress> } | undefined
+  return isThreadAddress(head?.link?.source)
     ? { address: head.link.source, methods: { requestBudget: requestBudgetMethod } }
     : undefined
 }
 
-const sourceFor = (log: ReadonlyArray<Event>, turn: string): ActorId | undefined => {
+const sourceFor = (log: ReadonlyArray<Event>, turn: string): ThreadAddress | undefined => {
   const head = log.find((event) =>
     event.type === "MessageReceived" && String((event as { readonly id?: unknown }).id) === turn
   ) as { readonly link?: Link<unknown, unknown> } | undefined
-  if (isActorId(head?.link?.target)) return head.link.target
+  if (isThreadAddress(head?.link?.target)) return head.link.target
   return threadCreatedOf(log)?.address
 }
 

package/src/agent/components/compaction.ts

@@ -167,7 +167,7 @@ export const resolvedContextPolicyOf = (policy: Partial<ContextPolicy> = {}): Co
 
 // renderedChars counts the characters a render sends for one event: capped where the render
 // caps, zero for an event the render skips. The guard must measure the request the model sees;
-// a measure over raw event JSON counts tool results the render truncates and lanes the render
+// a measure over raw event JSON counts tool results the render truncates and threads the render
 // never shows, and fires against a size no request ever reaches.
 const renderedChars = (e: Event, policy: ContextPolicy): number => {
   const v = e as Record<string, unknown>

package/src/agent/components/permission-authority.ts

@@ -3,7 +3,7 @@ import { Schema } from "effect"
 import type { KeyFragment } from "tardie/core/log"
 import { intent, type Transition } from "tardie/core/reconciliation"
 import { externallyHandled, handles, type Component } from "tardie/core/actor"
-import { formatActorId, isActorId } from "tardie/core/communication/endpoint"
+import { formatThreadAddress, isThreadAddress } from "tardie/core/communication/endpoint"
 import { PermissionDecision, requestPermissionMethod } from "../actor/permission"
 import { permissionRequestDecided, permissionRequestFailed } from "../log/events"
 
@@ -71,7 +71,7 @@ const authorityTransition = (
     action: String(received.action ?? ""),
     ...(typeof received.resource === "string" ? { resource: received.resource } : {}),
     reason: String(received.reason ?? ""),
-    ...(isActorId(received.link?.source) ? { from: formatActorId(received.link.source) } : {}),
+    ...(isThreadAddress(received.link?.source) ? { from: formatThreadAddress(received.link.source) } : {}),
     grant: () => ({ granted: true }),
     deny: (reason) => ({ denied: true, ...(reason === undefined ? {} : { reason }) })
   }

package/src/agent/index.ts

@@ -140,8 +140,8 @@ export {
 // boundary is a projection of the log rather than a value the driver returns (boundary.ts).
 export { boundaryOf, outputOf, type Boundary } from "./output/boundary"
 
-// The spawn package: a value with no lane in it, so the assembly that mounts it and the host
-// that binds Router and Self per lane cannot disagree about placement (packages/agents.ts).
+// The spawn package: a value with no thread in it, so the assembly that mounts it and the host
+// that binds Router and Self per thread cannot disagree about placement (packages/agents.ts).
 export {
   agentsPackage,
   INLINE_OUTPUT_NAME,

package/src/agent/log/events.ts

@@ -377,7 +377,7 @@ export type Action =
       }
     } & Served)
 
-// agentKeys is the agent lane's dedup fragment, owned beside its alphabet. tr names the tool call's recorded
+// agentKeys is the agent thread's dedup fragment, owned beside its alphabet. tr names the tool call's recorded
 // pair; bdec names the budget request a local decision answers, so a grant and denial for one request
 // cannot both commit. A grant is summed into the ceiling, so a redelivery must also absorb. A
 // decision that carries no callId predates the stamp and lands unkeyed; the fold tolerates it.

package/src/agent/packages/agents.ts

@@ -1,4 +1,4 @@
-import { Clock, Effect } from "effect"
+import { Clock, Effect, Schema } from "effect"
 import { Router } from "tardie/core/communication/router"
 import { Self } from "tardie/core/reconciliation"
 import { EventLog } from "tardie/core/log"
@@ -8,11 +8,19 @@ import { Park } from "tardie/code/execution/errors"
 import { boundaryId } from "tardie/core/communication/message"
 import { linkOf } from "tardie/core/communication/link"
 import { methodEnvelopeOf } from "tardie/core/communication/envelope"
-import { childLineageOf, threadCreatedOf } from "tardie/core/thread"
 import {
-  actorIdOf,
-  formatActorId,
-  type ActorId
+  ChildCreated,
+  childCreated,
+  childLineageOf,
+  ChildPlacement,
+  threadCreatedOf,
+  type ThreadCreated,
+  type ThreadLineage
+} from "tardie/core/thread"
+import {
+  threadAddressOf,
+  formatThreadAddress,
+  type ThreadAddress
 } from "tardie/core/communication/endpoint"
 import { decodeOutput, outputFrom, type OutputContract } from "../output/contract"
 import { modelRefOf } from "../inference/reference"
@@ -40,14 +48,11 @@ import {
 // message id, so a replayed dispatch reaches the same child and is absorbed as a duplicate.
 //
 // The package is a value any consumer mounts: its host privileges are services, not constructor
-// arguments. `Router` sends, `Self` names the calling lane, and `EventLog` supplies its durable
+// arguments. `Router` sends, `Self` names the calling thread, and `EventLog` supplies its durable
 // calls, responses, and creation record.
 //
-// place selects the child's actor address from the call id and parent address. The host resolves
-// that stable identity to current placement when it interprets the resulting link.
-//
 // A plain foreground run parks, the same mechanism `tasks.fire` (`src/packages/tasks.ts`) uses:
-// deliver the brief through a link from this lane, then await the reply row on this lane, host-side
+// deliver the brief through a link from this thread, then await the reply row on this thread, host-side
 // `Park` when it has not landed yet (`src/code/execute.ts`'s proxy is what turns that into a promise
 // that never settles for the code body). It never holds a call open.
 //
@@ -246,19 +251,46 @@ const catalogQueryOf = (args: unknown): AgentCatalogQuery => {
   }
 }
 
-// sibling is the default placement: the child is a facet of the parent's own principal, named `ag.<callId>`. The address selects the target while ThreadCreated records its lineage (spawn.test.ts, "the default placement is the host's own sibling address"; tla/runtime/Thread.tla, CreationFirst).
-const sibling = (callId: string, self: ActorId): ActorId =>
-  actorIdOf(self.actor, `ag.${callId}`)
+// sibling is the default address: the child inherits the parent's actor instance and uses the name `ag.<callId>`. Thread placement remains a separate host decision (spawn.test.ts, "the default address is the host's own sibling"; tla/runtime/Thread.tla, CreationFirst).
+const sibling = (callId: string, self: ThreadAddress): ThreadAddress =>
+  threadAddressOf(self.actor, self.instance, `ag.${callId}`)
+
+const childClaimOf = (
+  placement: unknown,
+  events: ReadonlyArray<{ readonly type: string }>,
+  parent: ThreadCreated,
+  callId: string,
+  source: ThreadAddress
+) => {
+  if (placement !== undefined && !Schema.is(ChildPlacement)(placement)) {
+    return { error: "agents.run placement must be colocated or independent" }
+  }
+  const recorded = events.find(
+    (event) => event.type === "ChildCreated" && (event as { readonly callId?: unknown }).callId === callId
+  )
+  if (recorded !== undefined && !Schema.is(ChildCreated)(recorded)) {
+    throw new Error(`child ${callId} has an invalid creation record`)
+  }
+  const lineage: ThreadLineage = recorded === undefined
+    ? childLineageOf(parent, placement as ChildPlacement | undefined)
+    : {
+        parent: parent.address,
+        depth: recorded.depth,
+        ...(recorded.placement === undefined ? {} : { placement: recorded.placement })
+      }
+  return {
+    recorded,
+    target: recorded?.address ?? sibling(callId, source),
+    lineage
+  }
+}
 
 const inheritedModelsOf = (events: ReadonlyArray<{ readonly type: string }>): ModelPolicy => {
   const resolved = [...events].reverse().find((event) => event.type === "ModelResolved") as { readonly models?: unknown } | undefined
   return resolved?.models === undefined ? DEFAULT_MODEL_POLICY : modelPolicyOf(resolved.models)
 }
 
-export const agentsPackage = (
-  options: SpawnOptions & { readonly place?: (callId: string, self: ActorId) => ActorId } = {}
-): Package<Router | Self | EventLog> => {
-  const place = options.place ?? sibling
+export const agentsPackage = (options: SpawnOptions = {}): Package<Router | Self | EventLog> => {
   const actorNameOf = options.actorNameOf ?? (() => undefined)
   const reserve = options.reserve ?? (async (_callId: string, want: number) => want)
   const shadowOf = options.shadowOf ?? (() => false)
@@ -331,6 +363,7 @@ export const agentsPackage = (
               additionalProperties: false
             },
             budget: { type: "integer", description: "max tool calls before the agent must answer, a whole number of calls; keeps a research agent bounded" },
+            placement: { type: "string", enum: ["colocated", "independent"], description: "place the child relative to this thread's host" },
             escalatable: { type: "boolean", description: "true: at its budget the child may ask its parent's budget authority for more before answering" }
           },
           required: ["text"]
@@ -394,7 +427,7 @@ export const agentsPackage = (
       }),
       run: (args, ctx) =>
         Effect.gen(function* () {
-          // The three cross-lane privileges, read where the work happens: send, identity,
+          // The three cross-thread privileges, read where the work happens: send, identity,
           // observe. A host that binds them serves this method; nothing here closes over one.
           const router = yield* Router
           const source = yield* Self
@@ -402,15 +435,17 @@ export const agentsPackage = (
           const events = yield* log.read
           const created = threadCreatedOf(events)
           if (created === undefined) {
-            return yield* Effect.die(new Error(`thread ${formatActorId(source)} cannot spawn without ThreadCreated`))
+            return yield* Effect.die(new Error(`thread ${formatThreadAddress(source)} cannot spawn without ThreadCreated`))
           }
-          const lineage = childLineageOf(created)
-          const self = formatActorId(source)
+          const self = formatThreadAddress(source)
           const a = args as
-            | { text?: unknown; background?: unknown; output?: unknown; outputSchema?: unknown; model?: unknown; budget?: unknown; escalatable?: unknown }
+            | { text?: unknown; background?: unknown; output?: unknown; outputSchema?: unknown; model?: unknown; budget?: unknown; escalatable?: unknown; placement?: unknown }
             | undefined
           const text = String(a?.text ?? "")
           if (text === "") return { error: "agents.run needs { text }" }
+          const child = childClaimOf(a?.placement, events, created, ctx.callId, source)
+          if ("error" in child) return child
+          const { lineage, recorded: recordedChild, target } = child
           // The contract parameter is `output`, and a near-miss spelling fails silently: no
           // contract means a prose answer, so the caller's field reads come back undefined and
           // the run returns something plausible and wrong. Say so instead.
@@ -454,11 +489,8 @@ export const agentsPackage = (
           // the same way, when the fire named an explicit shared one.
           const shadow = shadowOf()
           const world = worldOf()
-          const target = place(ctx.callId, source)
-          if (a?.background === true) {
-            // A background run uses the same actor protocol. Its budget request can be served while
-            // no code body awaits it, and its terminal is collected later by agents.result.
-            const at = yield* Clock.currentTimeMillis
+          const dispatch = (at: number) => Effect.gen(function* () {
+            if (recordedChild === undefined) yield* log.append([childCreated(ctx.callId, target, lineage, at)])
             yield* router.send(methodEnvelopeOf(linkOf(source, target), { method: "message", id: ctx.callId }, {
               type: "MessageReceived",
               id: ctx.callId,
@@ -474,6 +506,12 @@ export const agentsPackage = (
               from: self,
               at
             }, lineage))
+          })
+          if (a?.background === true) {
+            // A background run uses the same actor protocol. Its budget request can be served while
+            // no code body awaits it, and its terminal is collected later by agents.result.
+            const at = yield* Clock.currentTimeMillis
+            yield* dispatch(at)
             return { dispatched: true, callId: ctx.callId }
           }
           // Foreground runs park on their terminal response. A replay reads that response
@@ -481,21 +519,7 @@ export const agentsPackage = (
           const already = yield* awaitedBoundary(ctx.callId)
           if (already !== undefined) return shape(answerOf(already), ctx.callId, output)
           const at = yield* Clock.currentTimeMillis
-          yield* router.send(methodEnvelopeOf(linkOf(source, target), { method: "message", id: ctx.callId }, {
-            type: "MessageReceived",
-            id: ctx.callId,
-            text,
-            ...(outputDeclaration === undefined ? {} : { output: outputDeclaration }),
-            ...(selectedModel === undefined ? {} : { model: selectedModel }),
-            models,
-            budget,
-            ...(a?.escalatable === true ? { escalatable: true } : {}),
-            ...(actor === undefined ? {} : { actor }),
-            ...(shadow ? { shadow: true } : {}),
-            ...(world === undefined ? {} : { world }),
-            from: self,
-            at
-          }, lineage))
+          yield* dispatch(at)
           return yield* new Park({ callId: ctx.callId, awaiting: boundaryId(ctx.callId, 0) })
         }),
       // Await a run already fired in the background: no delivery, the same reply-or-park read the

package/src/agent/runtime/resume.ts

@@ -7,10 +7,10 @@ type Awaitable<T> = T | Promise<T>
 
 // TurnDriver is the common control surface of the memory host and the durable Bun host.
 export interface TurnDriver {
-  readonly read: (lane: string) => Awaitable<ReadonlyArray<Event>>
+  readonly read: (thread: string) => Awaitable<ReadonlyArray<Event>>
   readonly commitRoot: (address: string, event: Event) => Awaitable<void>
   readonly drive: () => Promise<void>
-  readonly self: (lane: string) => string
+  readonly self: (thread: string) => string
 }
 
 export interface ResumeTurnOptions {
@@ -20,20 +20,20 @@ export interface ResumeTurnOptions {
 // resumeTurn starts a new execution epoch from a failed turn's committed history.
 export const resumeTurn = async (
   host: TurnDriver,
-  lane: string,
+  thread: string,
   turn: string,
   options: ResumeTurnOptions = {}
 ): Promise<Boundary | undefined> => {
-  const before = await host.read(lane)
+  const before = await host.read(thread)
   const boundary = boundaryOf(before, turn)
   if (boundary?.kind !== "failed") {
     throw new Error(`turn "${turn}" cannot resume because its active epoch is not failed`)
   }
   const failedEpoch = turnEpochOf(before, turn)
   await host.commitRoot(
-    host.self(lane),
+    host.self(thread),
     turnResumed({ turn, failedEpoch, epoch: failedEpoch + 1, at: options.at ?? Date.now() })
   )
   await host.drive()
-  return boundaryOf(await host.read(lane), turn)
+  return boundaryOf(await host.read(thread), turn)
 }