tardie 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clavia, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,9 +1,183 @@
-# tardie
+<p align="center">
+  <br>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-dark.svg">
+    <img alt="Tardigrade logo: a tardigrade drawn from overlapping circles" src="docs/assets/logo-light.svg" width="170">
+  </picture>
+</p>
 
-Reserved for [tardigrade](https://github.com/clavia-labs/tardigrade), a durable agent harness where state is a pure function of an event log.
+# Tardigrade
 
-The package to install is [`@clavia/tardigrade`](https://www.npmjs.com/package/@clavia/tardigrade), which ships the framework, the HTTP server, the explorer, and the `tdg` command.
+[![npm version](https://img.shields.io/npm/v/tardie.svg)](https://www.npmjs.com/package/tardie)
+
+A durable and modular agent harness built for self-improvement.
+
+### A harness made for self-improvement
+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.
+
+We took inspiration from React. React derives the component tree as a function of state (`UI = f(state)`). Similarly, Tardigrade defines the harness as a set of state transitions derived from the event log, an idea with roots in [Harel's statecharts](https://www.sciencedirect.com/science/article/pii/0167642387900359).
+
+$$\lbrace\mathrm{transitions}\rbrace = f(\mathrm{log})$$
+
+## Why Tardigrade
+
+- **Composable harness.** Add tools, code execution, budgets, compaction, and replies as independent capabilities.
+- **Strongly typed, built on Effect.** Typed services and Layers make each capability's dependencies explicit. A missing service fails during compile.
+- **Crash proof.** A durable host derives unfinished work from the stored log.
+- **Serverless.** All you need is a durable store, no process has to stay alive. Any new invocation reads the log, runs the transitions it owes, and settles.
+- **Inspect and improve every run.** Log as core supports native debugging, replay, and experiments with state forked from any checkpoint.
+
+## Quickstart
+
+Install Tardigrade and run the default agent. Use Bun 1.4 or later.
+
+```bash
+bun add -g tardie
+tdg dev
+```
+
+Start a thread from another shell:
+
+```bash
+tdg run "read this repo and tell me what it does"
+```
+
+Watch the live trajectory at [localhost:4242](http://localhost:4242).
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/voyager-dark.png">
+  <img alt="The voyager: a thread's log, one row per event" src="docs/assets/voyager-light.png">
+</picture>
+
+## Build one
 
 ```bash
-bunx @clavia/tardigrade dev
+bun add tardie
 ```
+
+You can use `npm install tardie` instead. Install `tardie@next` to test a release candidate.
+
+### Create a capability
+
+An agent is made of capabilities. A capability is one value with two halves: what the model is shown (`tools`, `system`), and how the calls that come back are handled (`serve`). This one gives the model a single tool:
+
+```ts
+import type { Capability } from "tardie"
+
+const deploys: Capability = {
+  name: "deploys",
+  tools: () => [
+    {
+      name: "recent_deploys",
+      description: "List recent production deploys",
+      inputSchema: { type: "object", properties: {}, additionalProperties: false }
+    }
+  ],
+  serve: (call, log, answer) => {
+    if (call.name !== "recent_deploys") return undefined
+    return [answer([{ service: "api", revision: "a17c", summary: "Add rate limiting" }])]
+  }
+}
+```
+
+`tools` derives what the model is offered from the log; a constant capability ignores it. `serve` handles a call that comes back: `answer` mints the transition that records the result, and returning `undefined` passes the call to the next capability. Replace the sample result with a call to your deployment API.
+
+The call follows one route:
+
+1. `tools` adds `recent_deploys` to the next model request.
+2. The model selects it and returns a tool call. Tardigrade records `ToolCalled` in the log.
+3. The shared router asks each mounted capability's `serve` to handle the call. `deploys` matches the name and answers.
+4. Tardigrade records `ToolReturned`. The next model request includes the result.
+
+### Compose an agent
+
+Mount the capability beside the built-in parts that this task needs:
+
+```ts
+import { agentOf, budget, codeMode, compaction, reply } from "tardie"
+
+const releaseAnalyst = agentOf([
+  deploys,     // recent_deploys and its handler
+  codeMode,    // durable JavaScript execution
+  budget,      // a per-turn code budget
+  compaction,  // bounded model context
+  reply        // results for parent agents
+])
+```
+
+`agentOf` combines every model-facing part and runtime handler. The model sees `recent_deploys` and `execute` in one request. Policy capabilities react to the same log.
+
+This agent can inspect deployments, analyze results with JavaScript, compact a long investigation, and report to a parent agent. Change the list to create another harness.
+
+A run can follow this path:
+
+```text
+MessageReceived -> recent_deploys -> execute -> TurnCompleted
+```
+
+Each action and result becomes an event that every capability can interpret.
+
+### Run the composition
+
+<details>
+<summary>Bind a model and durable SQLite host</summary>
+
+The three code blocks form one program.
+
+```ts
+import { infer } from "tardie/model"
+import { createBunHost } from "tardie/bun/host"
+
+const model = infer({
+  baseUrl: process.env.MODEL_BASE_URL!,
+  apiKey: process.env.MODEL_API_KEY!,
+  model: process.env.MODEL_ID!
+})
+
+const host = await createBunHost({
+  log: "agents.sqlite",
+  actorFor: () => releaseAnalyst,
+  layersFor: () => model
+})
+
+await host.deliver("bun:main", {
+  type: "MessageReceived",
+  id: "m1",
+  text: "What changed in the deploy?",
+  at: Date.now()
+})
+await host.drive()
+
+const completed = (await host.read("main")).findLast(
+  (event) => event.type === "TurnCompleted"
+)
+console.log(completed)
+await host.close()
+```
+
+The model binding uses the OpenAI-compatible protocol by default. Add `provider: "bedrock"` to the model options for Bedrock.
+
+</details>
+
+## How durability works
+
+Every message, model action, tool result, and checkpoint lands in the log. Reactors read that log and derive keyed transitions.
+
+$$\lbrace\mathrm{transitions}\rbrace = f(\mathrm{log})$$
+
+The host runs transitions with unrecorded keys. It appends the returned events and repeats until the agent rests.
+
+If the process stops during `recent_deploys`, the log still contains its unanswered `ToolCalled`. `host.recover()` derives the same key and input, then runs the handler again.
+
+Effects have at-least-once execution. Each keyed result is recorded once. Providers can use the transition key as an idempotency key.
+
+## Learn more
+
+- [Quickstart](docs/quickstart.md): build the event loop and its agent capabilities from first principles.
+- [HTTP server](docs/how-to/server.md)
+- [CLI](docs/how-to/cli.md)
+- [Why Tardigrade](docs/explanations/why.md): learn what the log-as-state model makes possible.
+
+## Contributing
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md) and run `bun run gate` before finishing a change.

package/package.json

@@ -1,10 +1,58 @@
 {
   "name": "tardie",
-  "version": "0.0.1",
-  "description": "Reserved for tardigrade, a durable agent harness. See @clavia/tardigrade.",
+  "version": "0.1.0",
   "license": "MIT",
+  "author": "Clavia, Inc.",
+  "description": "A durable agent harness. State is a pure function of the log.",
   "homepage": "https://github.com/clavia-labs/tardigrade#readme",
-  "repository": { "type": "git", "url": "git+https://github.com/clavia-labs/tardigrade.git" },
-  "keywords": ["tardigrade", "agent", "event-sourcing", "actor"],
-  "files": ["README.md"]
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clavia-labs/tardigrade.git"
+  },
+  "bugs": {
+    "url": "https://github.com/clavia-labs/tardigrade/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "ui"
+  ],
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "type": "module",
+  "bin": {
+    "tdg": "./src/cli/main.ts"
+  },
+  "exports": {
+    ".": "./src/agent/index.ts",
+    "./package.json": "./package.json",
+    "./core/*": "./src/core/*.ts",
+    "./code": "./src/code/index.ts",
+    "./code/*": "./src/code/*.ts",
+    "./host/*": "./src/host/*.ts",
+    "./client": "./src/client/index.ts",
+    "./client/*": "./src/client/*.ts",
+    "./bun/*": "./src/bun/*.ts",
+    "./server/*": "./src/server/*.ts",
+    "./cli/*": "./src/cli/*.ts",
+    "./model": "./src/model/model.ts",
+    "./model/*": "./src/model/*.ts",
+    "./*": "./src/agent/*.ts"
+  },
+  "dependencies": {
+    "@aws-sdk/client-bedrock-runtime": "^3.1079.0",
+    "@cfworker/json-schema": "^4.1.1",
+    "@effect/platform-bun": "4.0.0-rc.110",
+    "@effect/platform-node-shared": "4.0.0-rc.110",
+    "@effect/sql-sqlite-bun": "4.0.0-rc.110",
+    "@smithy/fetch-http-handler": "^5.6.3",
+    "@smithy/node-http-handler": "^4.11.2",
+    "@tanstack/ai": "0.46.0",
+    "@tanstack/ai-bedrock": "0.2.3",
+    "@tanstack/ai-openai": "0.20.0",
+    "effect": "4.0.0-rc.110"
+  }
 }

package/src/agent/artifact.ts

@@ -0,0 +1,24 @@
+import type { Actor } from "tardie/core/actor"
+
+export const ACTOR_NAME_PATTERN = /^[a-z][a-z0-9-]{0,62}$/u
+
+export const ACTOR_ARTIFACT_VERSION = 1
+
+export interface ActorArtifactManifest {
+  readonly schema: typeof ACTOR_ARTIFACT_VERSION
+  readonly name: string
+  readonly module: string
+  readonly digest: string
+}
+
+export interface ActorDefinition<R = never> {
+  readonly name: string
+  readonly actor: Actor<R>
+}
+
+export const defineActor = <R>(definition: ActorDefinition<R>): ActorDefinition<R> => {
+  if (!ACTOR_NAME_PATTERN.test(definition.name)) {
+    throw new Error(`actor name must match ${String(ACTOR_NAME_PATTERN)}, got ${JSON.stringify(definition.name)}`)
+  }
+  return definition
+}

package/src/agent/boundary.ts

@@ -0,0 +1,34 @@
+import type { Event } from "tardie/core/event"
+import { turnTerminalOf } from "tardie/code/turns"
+
+// Boundary is where a settle left a turn: a terminal, or a park on a budget ask. The
+// platform's call and resume read it to answer the spawning code. Pure over the log, so a
+// re-driven settle reads the same boundary.
+
+export type Boundary =
+  | { readonly kind: "completed"; readonly output: string }
+  | { readonly kind: "failed"; readonly error: string }
+  | { readonly kind: "requesting"; readonly callId: string; readonly reason: string; readonly amount: number }
+
+// boundaryOf returns the turn's boundary, or undefined while it still runs. A terminal wins
+// over a park: a resumed turn that finished reads completed even though it once asked. A park
+// is the last BudgetRequested no grant or denial has answered.
+export const boundaryOf = (log: ReadonlyArray<Event>, turn: string): Boundary | undefined => {
+  const terminal = turnTerminalOf(log, turn)
+  if (terminal !== undefined) {
+    return terminal.type === "TurnCompleted"
+      ? { kind: "completed", output: String((terminal as { output?: unknown }).output) }
+      : { kind: "failed", error: String((terminal as { error?: unknown }).error) }
+  }
+  let pending: Event | undefined
+  for (const e of log) {
+    if (String((e as { turn?: unknown }).turn) !== turn) continue
+    if (e.type === "BudgetRequested") pending = e
+    else if (e.type === "BudgetGranted" || e.type === "BudgetDenied") pending = undefined
+  }
+  if (pending !== undefined) {
+    const p = pending as { callId?: unknown; reason?: unknown; amount?: unknown }
+    return { kind: "requesting", callId: String(p.callId), reason: String(p.reason ?? ""), amount: Number(p.amount ?? 0) }
+  }
+  return undefined
+}

package/src/agent/budget.ts

@@ -0,0 +1,131 @@
+import { Clock, Effect } from "effect"
+import { transition, type Reactor } from "tardie/core/actor"
+import { budgetExhausted } from "./events"
+import type { Event } from "tardie/core/event"
+import { turnHead, turnView } from "tardie/code/turns"
+
+// The budget reactor observes the turn's tool spend and fires BudgetExhausted once when it
+// passes the brief's budget. Detection lives here; enforcement lives with the tools reactor,
+// which reads the wall and refuses the next execute. See docs/agent-budgets.md.
+
+// BudgetPolicy is the ceiling a brief with no stated budget takes, so an unbounded agent is
+// never an accident. A brief that states its own `budget` overrides it per turn; this is what a
+// silent brief gets, and a consumer sets it on the reactor (`budgetReactorFor`) and on the spawn
+// package, which draws the same default for a child (spawn.ts).
+export interface BudgetPolicy {
+  readonly defaultToolBudget: number
+}
+
+export const DEFAULT_BUDGET_POLICY: BudgetPolicy = { defaultToolBudget: 40 }
+
+export const budgetPolicyOf = (policy: Partial<BudgetPolicy> = {}): BudgetPolicy => ({
+  defaultToolBudget: policy.defaultToolBudget ?? DEFAULT_BUDGET_POLICY.defaultToolBudget
+})
+
+// budgetOf returns the turn's budget: the head's `budget` plus every grant the escalation has
+// added, or the policy's default. The budget rides the brief envelope and is read off the raw
+// event. A `BudgetGranted` raises the ceiling, which is what lets a granted turn resume.
+export const budgetOf = (view: ReadonlyArray<Event>, policy: Partial<BudgetPolicy> = {}): number => {
+  const head = turnHead(view) as { budget?: unknown } | undefined
+  const base =
+    typeof head?.budget === "number" && head.budget > 0
+      ? Math.floor(head.budget)
+      : budgetPolicyOf(policy).defaultToolBudget
+  const granted = view.reduce((n, e) => (e.type === "BudgetGranted" ? n + Number((e as { amount?: unknown }).amount ?? 0) : n), 0)
+  return base + granted
+}
+
+// usedOf counts the tool calls the turn has spent. Only `execute` spends: `answer` and
+// `request_budget` are the turn's exits, so they never draw the budget down.
+export const usedOf = (view: ReadonlyArray<Event>): number =>
+  view.filter((e) => e.type === "ToolCalled" && String((e as { name?: unknown }).name) === "execute").length
+
+// escalatableOf reports whether the brief lets this turn escalate at its wall. It rides the
+// envelope like `budget`.
+export const escalatableOf = (view: ReadonlyArray<Event>): boolean =>
+  (turnHead(view) as { escalatable?: unknown } | undefined)?.escalatable === true
+
+// shadowOf reports whether this turn's brief carries the shadow flag. It rides the envelope like
+// `escalatable`: the run's fire sets it once, and every spawn downstream inherits the same
+// reading.
+export const shadowOf = (view: ReadonlyArray<Event>): boolean =>
+  (turnHead(view) as { shadow?: unknown } | undefined)?.shadow === true
+
+// worldOf returns the explicit world label this turn's brief carries, present when its fire
+// named a shared world (docs/worlds.md). It rides the envelope like `shadow` and propagates to
+// every spawn the same way, so a whole family stays on one shared world's facets. It is absent
+// for the anonymous case, where a shadow run's own family.run is its world and needs no
+// propagation.
+export const worldOf = (view: ReadonlyArray<Event>): string | undefined => {
+  const w = (turnHead(view) as { world?: unknown } | undefined)?.world
+  return typeof w === "string" && w !== "" ? w : undefined
+}
+
+// BudgetPhase is the budget state of the current turn, read from the most recent lifecycle
+// marker scanning back. It is pure and scoped to the current turn like `outputSchemaOf`, so an
+// earlier turn's wall does not leak. `exhausted`: the wall is up and the turn may still ask.
+// `denied`: the ask was refused, so the turn must answer. `spending`: a grant reopened the
+// budget, or none was ever spent.
+export type BudgetPhase = "spending" | "exhausted" | "denied"
+
+export const budgetPhase = (trajectory: ReadonlyArray<Event>): BudgetPhase => {
+  for (let i = trajectory.length - 1; i >= 0; i--) {
+    const t = trajectory[i]!.type
+    if (t === "BudgetExhausted") return "exhausted"
+    if (t === "BudgetDenied") return "denied"
+    if (t === "BudgetGranted") return "spending"
+    if (t === "MessageReceived") return "spending"
+  }
+  return "spending"
+}
+
+// budgetSpent reports whether `execute` is withdrawn for this turn: true from the wall until a
+// grant reopens it. The tools gate and the model's tool list both read this one predicate, so
+// they never disagree.
+export const budgetSpent = (trajectory: ReadonlyArray<Event>): boolean => budgetPhase(trajectory) !== "spending"
+
+// canRequestBudget reports whether the model may ask for more: only while the wall is up, no
+// denial has closed it, and the brief made the turn escalatable. A denied turn answers and never
+// asks again.
+export const canRequestBudget = (trajectory: ReadonlyArray<Event>): boolean =>
+  budgetPhase(trajectory) === "exhausted" && escalatableOf(trajectory)
+
+// overBudget reports whether the spend has passed the budget. It is pure and total over the log,
+// so replay re-folds to the same state: it reads only the log and calls no clock and no random
+// source. It is off by exactly one on purpose: `used > budget` fires on the call after the last
+// allowed one, so the agent gets `budget` dispatched calls and the next is refused.
+const overBudget = (log: ReadonlyArray<Event>, policy: BudgetPolicy): boolean => usedOf(log) > budgetOf(log, policy)
+
+// budgetReactorFor derives the wall when the spend has crossed the ceiling and no wall marker
+// stands. The act records `BudgetExhausted` once; the tools reactor reads it and refuses the
+// next `execute`, so enforcement stays where dispatch lives and this reactor only detects. The
+// wall's key is the ceiling it fired at: a grant raises the ceiling, so a second crossing is a
+// new occurrence with a new key, and a redelivered wall absorbs.
+export const budgetReactorFor = (policy: Partial<BudgetPolicy> = {}): Reactor<never> => (log) => {
+  const resolved = budgetPolicyOf(policy)
+  const view = turnView(log)
+  if (view.length === 0 || !overBudget(view, resolved) || budgetPhase(view) !== "spending") return []
+  const head = turnHead(view) as { id?: unknown } | undefined
+  const budget = budgetOf(view, resolved)
+  return [
+    transition({
+      key: `bw:${String(head?.id ?? "")}/${budget}`,
+      input: { turn: head?.id === undefined ? undefined : String(head.id), budget, used: usedOf(view) },
+      act: (input) =>
+        Effect.gen(function* () {
+          const at = yield* Clock.currentTimeMillis
+          return [
+            budgetExhausted({
+              budget: input.budget,
+              used: input.used,
+              ...(input.turn === undefined ? {} : { turn: input.turn }),
+              at
+            })
+          ]
+        })
+    })
+  ]
+}
+
+// budgetReactor is that reactor on the default ceiling.
+export const budgetReactor: Reactor<never> = budgetReactorFor()