tardie 0.9.0 → 0.10.0

package/README.md

@@ -13,7 +13,7 @@
 
 # Tardigrade
 
-Tardigrade is a typescript framework for building durable, modular agents that can run at the edge. It is inspired by [React](https://react.dev/)'s declarative approach to building user interfaces.
+Tardigrade is a typescript framework for building durable, modular agents that can run on the cloud. It is inspired by [React](https://react.dev/)'s declarative approach to building user interfaces.
 
 ### Agents that can self-improve
 As models get increasingly smart, they will be capable of writing their own harnesses to improve themselves ([Meta-Harness](https://arxiv.org/abs/2603.28052)). A harness that is too rigid and complex is a bottleneck to this. We need something more composable, and easy to author.
@@ -130,40 +130,46 @@ Mount the component beside the built-in parts that this task needs:
 
 ```ts
 import {
-  actor, agentMethods, agentsPackage, budget, codeMode,
-  compaction, defineActor, fetchPackage, filesPackage, infer,
-  outputValidateOnce, reply, system, workspacePackage
+  actor, agentMethods, agentsPackage, budget, budgetAuthority, caller, codeMode,
+  compaction, fetchPackage, filesPackage, infer,
+  outputValidateOnce, system, workspacePackage
 } from "tardie"
 
 const instructions = system(
   "You are a release analyst. Identify risky changes and recommend the safest next action."
 )
 
-const releaseModel = { provider: "openai", default_model: "gpt-5.2" } as const
+const model = { provider: "openai", default_model: "gpt-5.2" } as const
 
-const releaseAnalyst = defineActor({
+const releaseAnalyst = actor({
+  // name supplies the actor's stable identity.
   name: "release-analyst",
+  // methods declare how the world can communicate with this actor.
   methods: agentMethods,
-  actor: actor(infer([
-    instructions, // the agent's system prompt
-    deploys,     // recent_deploys and its paired handler
-    // budget scopes the tool-call limit to the codeMode subtree.
-    budget([
-      codeMode([
-        filesPackage(),
-        fetchPackage(),
-        agentsPackage(),
-        workspacePackage()
-      ])
-    ]),
-    compaction(), // bounded model context
-    reply,       // results for parent agents
-    outputValidateOnce // validates one structured result without correction
-  ], releaseModel))
+  // components implement those methods and derive transitions from the actor's private log.
+  components: [
+    // infer handles messages as model loops composed by children.
+    infer([
+      instructions, // the agent's system prompt
+      deploys,      // provides recent_deploys tool and its paired handler
+      // budget scopes the tool-call limit to the codeMode subtree
+      budget([
+        codeMode([  // sandboxed code execution
+          filesPackage(),    // access file system
+          fetchPackage(),    // make network fetch
+          agentsPackage(),   // call subagents
+          workspacePackage() // sqlite workspace
+        ])
+      ], { authority: caller() }), // declares authority to grant budget
+      compaction(), // bounded model context
+      outputValidateOnce // validates structured result once without correction
+    ], model),
+    budgetAuthority() // budgetAuthority handles requestBudget for this actor.
+  ]
 })
 ```
 
-`infer` composes the components into an agent loop. Its trailing options select a private provider connection and the default model used through it. `defineActor` gives that loop a stable name and callable interface. `agentMethods` provides a `message` method with `{ text, input?, model? }` input and a string result. `model` is a model ID for that turn; it cannot change the actor's provider connection.
+`infer` composes the components into an agent loop. Its trailing options select a private provider connection and the default model used through it. `actor` binds those components to a stable name and callable interface. `agentMethods` provides `message` and `requestBudget`. Every actor method call is a durable future that remains pending until it receives one completed or failed terminal response. `model` is a model ID for that turn; it cannot change the actor's provider connection.
 
 `compaction(policy?)` bounds model context. The host resolves the selected model's window from its catalog snapshot. Compaction fires at 80 percent and keeps a 50 percent tail unless the actor states other ratios:
 
@@ -178,7 +184,7 @@ When compaction runs, its checkpoint records the applied policy with the summary
 
 `codeMode([...components])` combines code packages behind one `execute` tool. Define a package with `definePackage(...)`. Group packages with `composeComponents(...)`.
 
-`budget([...components], policy?)` limits calls to tools derived by its child components. Components beside the wrapper remain outside that budget.
+`budget([...components], { limit?, authority? })` meters calls to tools derived by its child components and closes that subtree at the limit. Components beside the wrapper remain outside that budget. An authority lets an escalatable child call `requestBudget`; `caller()` selects the actor that sent its current message. `budgetAuthority()` is the local automatic handler. Another actor can keep the same method pending while a service or human decides it.
 
 This agent can inspect deployments and files, fetch sources, delegate research, and analyze results with JavaScript. Change the package list to create another harness.
 

package/examples/quickstart/actor.ts

@@ -1,7 +1,7 @@
 import {
-  actor, agentMethods, agentsPackage, budget, codeMode,
-  compaction, defineActor, fetchPackage, filesPackage, infer,
-  outputValidateOnce, reply, system, workspacePackage
+  actor, agentMethods, agentsPackage, budget, budgetAuthority, caller, codeMode,
+  compaction, fetchPackage, filesPackage, infer,
+  outputValidateOnce, system, workspacePackage
 } from "tardie"
 
 // actorName is the stable name used by build, development, and deployment.
@@ -18,26 +18,27 @@ Delegate independent research when it helps.
 Return a concise answer with concrete findings.
 `.trim()
 
-export default defineActor({
+export default actor({
   name: actorName,
   // methods declares the typed calls this actor accepts.
   methods: agentMethods,
-  // actor carries component and output requirements into the host type.
-  actor: actor(infer([
-    system(actorInstructions),
-    // budget scopes the tool-call limit to the codeMode subtree.
-    budget([
-      // codeMode gives the model one code tool over the package components listed here.
-      codeMode([
-        // codeMode package components grant access to files, HTTP, child agents, and saved results.
-        filesPackage(), fetchPackage(), agentsPackage(), workspacePackage()
-      ])
-    ]),
-    // reply returns a finished turn to the actor that delegated it.
-    reply,
-    // compaction summarizes older context when a long turn outgrows its context window.
-    compaction(),
-    // outputValidateOnce validates one structured result when the endpoint supplies no native guarantee.
-    outputValidateOnce
-  ], actorModel))
+  // components carry implementation and output requirements into the host type.
+  components: [
+    infer([
+      system(actorInstructions),
+      // budget scopes the tool-call limit to the codeMode subtree.
+      budget([
+        // codeMode gives the model one code tool over the package components listed here.
+        codeMode([
+          // codeMode package components grant access to files, HTTP, child agents, and saved results.
+          filesPackage(), fetchPackage(), agentsPackage(), workspacePackage()
+        ])
+      ], { authority: caller() }),
+      // compaction summarizes older context when a long turn outgrows its context window.
+      compaction(),
+      // outputValidateOnce validates one structured result when the endpoint supplies no native guarantee.
+      outputValidateOnce
+    ], actorModel),
+    budgetAuthority()
+  ]
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tardie",
-  "version": "0.9.0",
+  "version": "0.10.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": "c2d12a57747f767777e828e2a314b1262fa17e25"
+    "sourceTree": "9ad5b25bb0b49092e6a3aa93d8c2f35886f769fb"
   },
   "files": [
     "src",
@@ -33,9 +33,27 @@
   "exports": {
     ".": "./src/agent/index.ts",
     "./package.json": "./package.json",
-    "./core/*": "./src/core/*.ts",
-    "./code": "./src/code/index.ts",
-    "./code/*": "./src/code/*.ts",
+    "./actor/*": "./src/agent/actor/*.ts",
+    "./components/*": "./src/agent/components/*.ts",
+    "./inference/*": "./src/agent/inference/*.ts",
+    "./log/*": "./src/agent/log/*.ts",
+    "./output/*": "./src/agent/output/*.ts",
+    "./packages/*": "./src/agent/packages/*.ts",
+    "./runtime/*": "./src/agent/runtime/*.ts",
+    "./core/actor": "./src/core/actor/index.ts",
+    "./core/actor/*": "./src/core/actor/*.ts",
+    "./core/communication": "./src/core/communication/index.ts",
+    "./core/communication/*": "./src/core/communication/*.ts",
+    "./core/log": "./src/core/log/index.ts",
+    "./core/log/*": "./src/core/log/*.ts",
+    "./core/reconciliation": "./src/core/reconciliation/index.ts",
+    "./core/reconciliation/*": "./src/core/reconciliation/*.ts",
+    "./core/thread": "./src/core/thread/index.ts",
+    "./core/thread/*": "./src/core/thread/*.ts",
+    "./code/execution/*": "./src/code/execution/*.ts",
+    "./code/package/*": "./src/code/package/*.ts",
+    "./code/sandbox/*": "./src/code/sandbox/*.ts",
+    "./code/storage/*": "./src/code/storage/*.ts",
     "./host/*": "./src/host/*.ts",
     "./channels": "./src/channels/index.ts",
     "./channels/*": "./src/channels/*.ts",
@@ -48,8 +66,7 @@
     "./server/*": "./src/server/*.ts",
     "./cli/*": "./src/cli/*.ts",
     "./model": "./src/model/model.ts",
-    "./model/*": "./src/model/*.ts",
-    "./*": "./src/agent/*.ts"
+    "./model/*": "./src/model/*.ts"
   },
   "dependencies": {
     "@aws-sdk/client-bedrock-runtime": "^3.1079.0",

package/src/agent/actor/artifact.ts

@@ -0,0 +1,12 @@
+export {
+  ACTOR_NAME_PATTERN
+} from "tardie/core/actor"
+
+export const ACTOR_ARTIFACT_VERSION = 3
+
+export interface ActorArtifactManifest {
+  readonly schema: typeof ACTOR_ARTIFACT_VERSION
+  readonly name: string
+  readonly module: string
+  readonly digest: string
+}

package/src/agent/actor/budget.ts

@@ -0,0 +1,54 @@
+import { Schema } from "effect"
+import { actorMethod } from "tardie/core/actor/method"
+import { budgetRequestReceived } from "../log/events"
+
+const PositiveInteger = Schema.Int.pipe(
+  Schema.check(Schema.makeFilter((value: number) => value > 0, { title: "positive" }))
+)
+
+export const BudgetRequestInput = Schema.Struct({
+  request: Schema.String,
+  turn: Schema.String,
+  reason: Schema.String,
+  amount: PositiveInteger
+}).annotate({ identifier: "BudgetRequestInput" })
+
+export type BudgetRequestInput = typeof BudgetRequestInput.Type
+
+export const BudgetDecision = Schema.Union([
+  Schema.Struct({ granted: PositiveInteger }),
+  Schema.Struct({ denied: Schema.Literal(true), reason: Schema.optionalKey(Schema.String) })
+]).annotate({ identifier: "BudgetDecision" })
+
+export type BudgetDecision = typeof BudgetDecision.Type
+
+// requestBudgetMethod exposes budget negotiation as a unary actor call.
+export const requestBudgetMethod = actorMethod({
+  input: BudgetRequestInput,
+  output: BudgetDecision,
+  event: ({ id, input, at }) => budgetRequestReceived({ id, ...input, at }),
+  state: (events, id) => {
+    const requested = events.some((event) =>
+      event.type === "BudgetRequestReceived" && String((event as { readonly id?: unknown }).id) === id
+    )
+    if (!requested) return undefined
+    const decided = events.find((event) =>
+      event.type === "BudgetRequestDecided" && String((event as { readonly callId?: unknown }).callId) === id
+    ) as { readonly grant?: unknown; readonly reason?: unknown } | undefined
+    const failed = events.find((event) =>
+      event.type === "BudgetRequestFailed" && String((event as { readonly callId?: unknown }).callId) === id
+    ) as { readonly error?: unknown } | undefined
+    if (failed !== undefined) return { status: "failed", error: String(failed.error ?? "budget authority failed") }
+    if (decided === undefined) return { status: "pending" }
+    const grant = Number(decided.grant ?? 0)
+    return grant > 0
+      ? { status: "completed", output: { granted: grant } }
+      : {
+          status: "completed",
+          output: {
+            denied: true as const,
+            ...(typeof decided.reason === "string" && decided.reason !== "" ? { reason: decided.reason } : {})
+          }
+        }
+  }
+})

package/src/agent/{message-method.ts → actor/message.ts}

@@ -1,7 +1,8 @@
 import { Schema } from "effect"
 import { messageReceived } from "tardie/core/communication/message"
-import { boundaryOf } from "./boundary"
-import { actorMethod, actorMethodsOf } from "./method"
+import { boundaryOf } from "../output/boundary"
+import { actorMethod, actorMethodsOf } from "tardie/core/actor/method"
+import { requestBudgetMethod } from "./budget"
 
 export const AgentMessageInput = Schema.Struct({
   text: Schema.String,
@@ -23,16 +24,24 @@ export const agentMessageMethod = actorMethod({
     at
   }),
   state: (events, id) => {
-    const invoked = events.some((event) =>
+    const invoked = events.find((event) =>
       event.type === "MessageReceived" && (event as { readonly id?: unknown }).id === id
-    )
-    if (!invoked) return undefined
+    ) as { readonly output?: unknown } | undefined
+    if (invoked === undefined) return undefined
+    const data = invoked.output === undefined ? undefined : { output: invoked.output }
     const boundary = boundaryOf(events, id)
     if (boundary === undefined) return { status: "pending" }
-    if (boundary.kind === "completed") return { status: "completed", output: boundary.output }
-    if (boundary.kind === "failed") return { status: "failed", error: boundary.error }
-    return { status: "blocked", reason: boundary.reason }
+    if (boundary.kind === "completed") {
+      return { status: "completed", output: boundary.output, ...(data === undefined ? {} : { data }) }
+    }
+    if (boundary.kind === "failed") {
+      return { status: "failed", error: boundary.error, ...(data === undefined ? {} : { data }) }
+    }
+    return { status: "pending" }
   }
 })
 
-export const agentMethods = actorMethodsOf({ message: agentMessageMethod })
+export const agentMethods = actorMethodsOf({
+  message: agentMessageMethod,
+  requestBudget: requestBudgetMethod
+})

package/src/agent/actor/permission.ts

@@ -0,0 +1,51 @@
+import { Schema } from "effect"
+import { actorMethod } from "tardie/core/actor/method"
+import { permissionRequestReceived } from "../log/events"
+
+export const PermissionRequestInput = Schema.Struct({
+  request: Schema.String,
+  turn: Schema.String,
+  tool: Schema.String,
+  action: Schema.String,
+  resource: Schema.optionalKey(Schema.String),
+  reason: Schema.String
+}).annotate({ identifier: "PermissionRequestInput" })
+
+export type PermissionRequestInput = typeof PermissionRequestInput.Type
+
+export const PermissionDecision = Schema.Union([
+  Schema.Struct({ granted: Schema.Literal(true) }),
+  Schema.Struct({ denied: Schema.Literal(true), reason: Schema.optionalKey(Schema.String) })
+]).annotate({ identifier: "PermissionDecision" })
+
+export type PermissionDecision = typeof PermissionDecision.Type
+
+// requestPermissionMethod exposes one-shot tool authorization as a unary actor call.
+export const requestPermissionMethod = actorMethod({
+  input: PermissionRequestInput,
+  output: PermissionDecision,
+  event: ({ id, input, at }) => permissionRequestReceived({ id, ...input, at }),
+  state: (events, id) => {
+    const received = events.some((event) =>
+      event.type === "PermissionRequestReceived" && String((event as { readonly id?: unknown }).id) === id
+    )
+    if (!received) return undefined
+    const decided = events.find((event) =>
+      event.type === "PermissionRequestDecided" && String((event as { readonly callId?: unknown }).callId) === id
+    ) as { readonly granted?: unknown; readonly reason?: unknown } | undefined
+    const failed = events.find((event) =>
+      event.type === "PermissionRequestFailed" && String((event as { readonly callId?: unknown }).callId) === id
+    ) as { readonly error?: unknown } | undefined
+    if (failed !== undefined) return { status: "failed", error: String(failed.error ?? "permission authority failed") }
+    if (decided === undefined) return { status: "pending" }
+    return decided.granted === true
+      ? { status: "completed", output: { granted: true as const } }
+      : {
+          status: "completed",
+          output: {
+            denied: true as const,
+            ...(typeof decided.reason === "string" && decided.reason !== "" ? { reason: decided.reason } : {})
+          }
+        }
+  }
+})

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

@@ -0,0 +1,122 @@
+import type { Event } from "tardie/core/log/event"
+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 { BudgetDecision } from "../actor/budget"
+import { budgetRequestDecided, budgetRequestFailed } from "../log/events"
+import { requestBudgetMethod } from "../actor/budget"
+
+// BudgetRequest describes one durable authority call and supplies its valid decisions.
+export interface BudgetRequest {
+  readonly id: string
+  readonly reason: string
+  readonly amount: number
+  readonly turn: string
+  readonly from?: string
+  readonly grant: (amount?: number) => BudgetDecision
+  readonly deny: (reason?: string) => BudgetDecision
+}
+
+// DecideBudget is the pure local policy implemented by budgetAuthority.
+export type DecideBudget = (request: BudgetRequest) => BudgetDecision
+
+// DEFAULT_BUDGET_DECISION grants the number of tool calls the child requested.
+export const DEFAULT_BUDGET_DECISION: DecideBudget = (request) => request.grant()
+
+export interface BudgetAuthorityOptions {
+  readonly decide?: DecideBudget
+}
+
+// budgetAuthorityKeys owns budget authority calls and their terminal outcomes.
+export const budgetAuthorityKeys: KeyFragment = {
+  prefixes: ["bar:", "ba:"],
+  keyOf: (event) => {
+    const value = event as Record<string, unknown>
+    if (event.type === "BudgetRequestReceived") return `bar:${String(value.id)}`
+    return event.type === "BudgetRequestDecided" || event.type === "BudgetRequestFailed"
+      ? `ba:${String(value.callId)}`
+      : undefined
+  }
+}
+
+const failureMessage = (failure: unknown): string =>
+  failure instanceof Error ? failure.message : String(failure)
+
+const authorityTransition = (
+  log: ReadonlyArray<Event>,
+  decide: DecideBudget
+): Transition<never> | undefined => {
+  const received = log.find((event) =>
+    event.type === "BudgetRequestReceived" &&
+    !log.some((terminal) =>
+      (terminal.type === "BudgetRequestDecided" || terminal.type === "BudgetRequestFailed") &&
+      String((terminal as { readonly callId?: unknown }).callId) === String((event as { readonly id?: unknown }).id)
+    )
+  ) as {
+    readonly id?: unknown
+    readonly turn?: unknown
+    readonly reason?: unknown
+    readonly amount?: unknown
+    readonly link?: { readonly source?: unknown }
+  } | undefined
+  if (received === undefined) return undefined
+
+  const id = String(received.id ?? "")
+  const amount = Number(received.amount ?? 0)
+  const request: BudgetRequest = {
+    id,
+    turn: String(received.turn ?? ""),
+    reason: String(received.reason ?? ""),
+    amount,
+    ...(isActorId(received.link?.source) ? { from: formatActorId(received.link.source) } : {}),
+    grant: (granted = amount) => ({ granted }),
+    deny: (reason) => ({ denied: true, ...(reason === undefined ? {} : { reason }) })
+  }
+
+  try {
+    const proposed = decide(request)
+    if ("granted" in proposed && (!Number.isSafeInteger(proposed.granted) || proposed.granted <= 0)) {
+      throw new Error(`budget grant must be a positive integer, got ${JSON.stringify(proposed.granted)}`)
+    }
+    const decision = Schema.decodeSync(BudgetDecision)(proposed)
+    if ("granted" in decision) {
+      const grant = decision.granted
+      return intent({
+        key: `ba:${id}`,
+        input: { id, grant },
+        events: (input, at) => [budgetRequestDecided({ callId: input.id, grant: input.grant, at })]
+      })
+    }
+    return intent({
+      key: `ba:${id}`,
+      input: { id, reason: decision.reason },
+      events: (input, at) => [budgetRequestDecided({
+        callId: input.id,
+        grant: 0,
+        ...(input.reason === undefined ? {} : { reason: input.reason }),
+        at
+      })]
+    })
+  } catch (failure) {
+    return intent({
+      key: `ba:${id}`,
+      input: { id, error: failureMessage(failure) },
+      events: (input, at) => [budgetRequestFailed({ callId: input.id, error: input.error, at })]
+    })
+  }
+}
+
+// budgetAuthority handles requestBudget with a pure local decision policy.
+export const budgetAuthority = (options: BudgetAuthorityOptions = {}): Component<undefined> => {
+  const decide = options.decide ?? DEFAULT_BUDGET_DECISION
+  return handles(requestBudgetMethod, {
+    name: "budget-authority",
+    keys: budgetAuthorityKeys,
+    derive: (log) => {
+      const transition = authorityTransition(log, decide)
+      return { view: undefined, transitions: transition === undefined ? [] : [transition] }
+    }
+  })
+}