@taicho-ai/contracts 0.1.0

package/README.md

@@ -0,0 +1,4 @@
+# @taicho-ai/contracts
+
+Runtime schemas and shared domain types for Taicho libraries. This package owns no I/O, model,
+telemetry, or UI behavior.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@taicho-ai/contracts",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --target bun",
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "description": "Shared runtime schemas and domain types for taicho (agents, briefs, traces, artifacts, teams).",
+  "license": "MIT",
+  "homepage": "https://taicho.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taicho-ai/taicho.git",
+    "directory": "packages/contracts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/agent.ts

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import { DEFAULT_TEAM_ID } from "./team";
+
+/** Agent identity — canonical form lives in agents/<id>/agent.md frontmatter. */
+const AgentObject = z.object({
+  id: z.string().regex(/^[a-z][a-z0-9-]*$/),
+  role: z.string(),                       // one-line capability description (shown in discovery)
+  identity: z.string(),                   // body of agent.md — the SOUL
+  // Capability allowlist. Built-in tool names (e.g. "delegate_task", "run_command") grant those
+  // tools. MCP capabilities are opt-in the SAME way (Plan 08 security hardening): "mcp:<server>"
+  // grants every tool that connected server exposes; "mcp:<server>/<tool>" grants exactly one.
+  // Anything NOT listed is not exposed to the agent — MCP tools included (no blanket grant).
+  tools: z.array(z.string()).default([]),
+  // Plan 22: the teams this agent sits on (was a single `team`). An agent may belong to MANY teams and
+  // declares them HERE — its own frontmatter is the single source of truth for membership, so
+  // teams/<id>/team.md deliberately carries no member list. This holds only EXPLICIT memberships: the
+  // universal `default` team is implicit (every agent belongs; the derived index adds it), so an empty
+  // list ⇒ default-only. A pre-Plan-22 `team: news` is migrated to `teams: [news]` at parse (below).
+  teams: z.array(z.string()).default([]),
+  // Visibility + delegation ACLs. Each entry is "*", an exact agent id, or (Plan 19) "team:<id>",
+  // which matches every member of that team. Additive: no existing agent id contains a colon.
+  canSee: z.array(z.string()).default(["*"]),        // org visibility ACL
+  canDelegateTo: z.array(z.string()).default(["*"]),
+  budgets: z.object({
+    maxIterationsPerRun: z.number().int().positive().default(30),
+    maxWorkItemsPerRequest: z.number().int().positive().default(20),
+    maxTokensPerRun: z.number().int().positive().optional(),
+    maxCostPerRunUsd: z.number().positive().optional(),
+    // Plan 04 Phase 3: how many background tasks this agent may have RUNNING at once (config
+    // disposes the concurrency the model proposes via dispatch_task). Undefined ⇒ unbounded;
+    // extra dispatches sit in the persistent queue (status "queued") until a slot frees.
+    maxConcurrentRuns: z.number().int().positive().optional(),
+  }).prefault({}),
+  isRoot: z.boolean().default(false),
+  created: z.string().datetime(),
+});
+
+/** Parse an agent, migrating the legacy single `team: <id>` into `teams: [<id>]` so a pre-Plan-22
+ *  agent.md still loads (files are canon; boot reindex then re-serializes it in the new shape). */
+export const AgentDef = z.preprocess((raw) => {
+  if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+    const o = raw as Record<string, unknown>;
+    if (o.teams === undefined && "team" in o)
+      o.teams = o.team == null || o.team === "" ? [] : [o.team];
+    if ("team" in o) delete o.team;
+  }
+  return raw;
+}, AgentObject);
+export type AgentDef = z.infer<typeof AgentDef>;
+
+/** An agent's EFFECTIVE membership: the universal `default` team plus its explicit teams, deduped, with
+ *  default FIRST. This is what the ACL matches against and what the derived agent_teams index stores, so
+ *  `team:default` matches everyone and membersOf("default") is the whole squad. Kept out of the file —
+ *  agent.md lists only explicit teams — so a squad with no explicit teams looks byte-identical to before. */
+export function effectiveTeams(agent: { teams: string[] }): string[] {
+  const out = [DEFAULT_TEAM_ID];
+  for (const t of agent.teams) if (t !== DEFAULT_TEAM_ID && !out.includes(t)) out.push(t);
+  return out;
+}

package/src/annotation.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import { VerificationVerdict } from "./trace";
+
+/** Feedback attached to a SPECIFIC artifact version. Because the store is immutable-per-version, an
+ *  annotation always pins to a concrete handle ("id@vN") — the feedback is anchored to the exact bytes
+ *  it was written about. The author may be the human captain, a producing/reviewing agent, or the
+ *  delegation checker (Plan 06): a verification verdict is an annotation like any other — it rides in
+ *  the optional `verdict` field, so machine feedback and human feedback converge on ONE shape and ONE
+ *  revision path.
+ *
+ *  An OPEN annotation is the input to a REVISION run: run.ts surfaces open annotations under each input
+ *  artifact handed to a child, the reviser addresses them and saves a NEW version linked back via
+ *  `parents`, and (optionally) resolves the annotation against that revision. Mirrors schemas/policy.ts
+ *  (a small typed record with a stable id + status lifecycle). */
+export const AnnotationKind = z.enum(["feedback", "verification", "approval"]);
+export type AnnotationKind = z.infer<typeof AnnotationKind>;
+
+export const AnnotationStatus = z.enum(["open", "addressed", "dismissed"]);
+export type AnnotationStatus = z.infer<typeof AnnotationStatus>;
+
+export const Annotation = z.object({
+  id: z.string(),                             // ann_xxxx
+  target: z.string(),                         // the artifact handle this annotates — always "id@vN" (a concrete version)
+  author: z.string(),                         // "human" | agentId | "checker" — provenance of the feedback
+  kind: AnnotationKind.default("feedback"),
+  body: z.string(),                           // the feedback text (for a verdict: the reasons, human-readable)
+  verdict: VerificationVerdict.optional(),    // Plan 06 hook: a verification verdict IS an annotation
+  status: AnnotationStatus.default("open"),
+  resolvedBy: z.string().optional(),          // the revision handle "id@vN" that addressed this
+  created: z.string().datetime(),
+});
+export type Annotation = z.infer<typeof Annotation>;
+
+/** A short, collision-resistant annotation id. Mirrors coaching's `pol_`/`ex_` id shape. */
+export function mkAnnotationId(): string {
+  return `ann_${crypto.randomUUID().slice(0, 8)}`;
+}

package/src/artifact.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+
+/** Where an artifact's bytes live. PAYLOAD-AGNOSTIC — the store never interprets the body:
+ *  - `file`   — local bytes on disk under artifacts/<id>/ (path is absolute).
+ *  - `external` — a locator into a system an MCP server fronts (a Notion page, a ClickUp task, a
+ *    URL). Forcing a copy into artifacts/ would be wrong there; the envelope (provenance, versioning,
+ *    summary, handle-based hand-off) works identically either way. See reference §5b. */
+export const ArtifactLocation = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("file"), path: z.string() }),
+  z.object({ kind: z.literal("external"), uri: z.string() }),
+]);
+export type ArtifactLocation = z.infer<typeof ArtifactLocation>;
+
+/** A structured hand-off artifact — the ENVELOPE only; the body is opaque bytes (or an external
+ *  ref). Addressable by a stable logical `id` (a slug shared across versions), versioned and
+ *  IMMUTABLE-PER-VERSION (a revision is a new version, never an overwrite). Provenance (producer
+ *  agent + run) and lineage (`parents`) give a hand-off graph. Mirrors schemas/knowledge.ts. */
+export const Artifact = z.object({
+  id: z.string(),                                                     // stable logical id (slug), shared across versions
+  version: z.number().int().positive().default(1),                   // increments per revision; (id,version) is immutable
+  title: z.string(),
+  type: z.string().default("document"),                              // FREE-FORM tag, never an enforced taxonomy
+  role: z.enum(["output", "input", "resource"]).default("output"),   // §3c: one store, role-tagged
+  producer: z.string(),                                              // agentId that produced it (provenance)
+  runId: z.string(),                                                 // run that produced it (provenance)
+  parents: z.array(z.string()).default([]),                          // parent artifact handles (lineage)
+  summary: z.string().optional(),                                    // summary-first read; never the whole body
+  location: ArtifactLocation,                                        // local file OR external ref (payload-agnostic)
+  created: z.string().datetime(),
+});
+export type Artifact = z.infer<typeof Artifact>;
+
+/** Parse a handle: "id" (⇒ latest version) or "id@vN" (⇒ that version). Malformed suffixes fall
+ *  back to treating the whole thing as an id (no version), so a stray "@" never throws. */
+export function parseHandle(handle: string): { id: string; version?: number } {
+  const at = handle.lastIndexOf("@v");
+  if (at <= 0) return { id: handle };
+  const v = Number(handle.slice(at + 2));
+  if (!Number.isInteger(v) || v <= 0) return { id: handle };
+  return { id: handle.slice(0, at), version: v };
+}
+
+/** The canonical addressable handle for a specific version: "id@vN". */
+export function artifactHandle(a: { id: string; version: number }): string {
+  return `${a.id}@v${a.version}`;
+}

package/src/brief.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+
+/** Delegation brief — sender writes goal+context; receiver supplies its own identity & policies. */
+export const Brief = z.object({
+  to: z.string(),
+  goal: z.string(),
+  context: z.string().optional(),
+  criteria: z.string().optional(),         // acceptance criteria the output must meet (rides into the prompt + drives the checker)
+  from: z.string(),                        // sending agent id
+  fromRun: z.string(),
+});
+export type Brief = z.infer<typeof Brief>;

package/src/index.ts

@@ -0,0 +1,11 @@
+export * from "./agent";
+export * from "./annotation";
+export * from "./artifact";
+export * from "./brief";
+export * from "./knowledge";
+export * from "./plan";
+export * from "./policy";
+export * from "./schedule";
+export * from "./skill";
+export * from "./team";
+export * from "./trace";

package/src/knowledge.ts

@@ -0,0 +1,35 @@
+import { z } from "zod";
+
+/** A typed, directed edge from one knowledge node to another (stored in the source node's frontmatter). */
+export const KbEdge = z.object({
+  to: z.string(),                                   // target node id
+  rel: z.string().default("relates_to"),            // relates_to|depends_on|part_of|contradicts|derived_from|<free>
+  weight: z.number().default(1),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+export type KbEdge = z.infer<typeof KbEdge>;
+
+/** Plan 19: the squad-wide scope was spelled "deck" through Plan 18. Accept the legacy value when
+ *  parsing an existing kb/nodes/*.md and normalize it to "squad", so a workspace written by an older
+ *  taicho still loads. `reconcileKbScope` (store/knowledge.ts, called at boot) rewrites those files
+ *  once; this preprocess is what keeps them readable until it does. Ph8 adds "team" to the enum. */
+export const KbScope = z
+  .preprocess((v) => (v === "deck" ? "squad" : v), z.enum(["squad"]))
+  .default("squad");
+
+/** A squad-shared knowledge node — one file per node at kb/nodes/<kb_id>.md
+ *  (YAML frontmatter = the node minus `content`, body = the content). Mirrors schemas/policy.ts. */
+export const KbNode = z.object({
+  id: z.string(),                                   // kb_xxxx
+  kind: z.string().default("fact"),                 // fact|entity|decision|doc|... (open vocab)
+  title: z.string(),
+  summary: z.string().optional(),
+  content: z.string(),                              // body of the .md
+  source: z.string().optional(),                    // provenance: "agentId:runId" / url
+  scope: KbScope,
+  edges: z.array(KbEdge).default([]),               // outgoing typed edges
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  created: z.string().datetime(),
+  updated: z.string().datetime().optional(),
+});
+export type KbNode = z.infer<typeof KbNode>;

package/src/plan.ts

@@ -0,0 +1,113 @@
+import { z } from "zod";
+
+/** Plan 18. A plan separates STRUCTURE from STATE, because they answer different questions and change
+ *  at wildly different rates:
+ *
+ *    · a plan VERSION (v1, v2, …) is an immutable snapshot of the item SET — the intent. Minted only
+ *      when the shape changes: an item added, removed, reworded, reordered. That is a replan, and it
+ *      deserves a version. (This is store/artifacts.ts.)
+ *    · an item TRANSITION is an append-only line in plans/<id>/events.jsonl. Ticking a box appends; it
+ *      never mints a version. (This is store/annotations.ts.)
+ *
+ *  Current state is fold(events) over the latest version — the same ledger-is-truth, cache-is-derived
+ *  discipline that already governs ledger.jsonl → thread.jsonl. Had every tick minted a version, a
+ *  twelve-item plan with three transitions each would produce thirty-six versions of an object whose
+ *  shape never changed, and "when did this agent change its mind?" would be buried under bookkeeping. */
+
+export const PlanItemStatus = z.enum([
+  "pending",
+  "in_progress",
+  "done",
+  "failed",
+  "blocked",
+  "interrupted", // the process died while this item's bound run was in flight (boot reconcile)
+  "dropped",     // the agent abandoned it on purpose; requires a note
+]);
+export type PlanItemStatus = z.infer<typeof PlanItemStatus>;
+
+/** Terminal for the purposes of "is this item still open". `dropped` counts as settled. */
+export const TERMINAL_ITEM_STATUS: ReadonlySet<PlanItemStatus> = new Set<PlanItemStatus>([
+  "done", "failed", "blocked", "interrupted", "dropped",
+]);
+
+/** An item id is stable ACROSS versions. That is what lets an event logged against v1 still resolve
+ *  after a replan mints v2 — the fold matches on item id, not on position. */
+export const PlanItem = z.object({
+  id: z.string().regex(/^[a-z0-9][a-z0-9_-]*$/, "lowercase, digits, underscore, hyphen"),
+  text: z.string(),
+  assignee: z.string().optional(), // the agent or team this item is meant for
+});
+export type PlanItem = z.infer<typeof PlanItem>;
+
+export const Plan = z.object({
+  id: z.string(),                              // p_<slug>
+  version: z.number().int().positive(),
+  owner: z.string(),                           // the agent whose plan this is
+  goal: z.string(),
+  items: z.array(PlanItem),
+  parents: z.array(z.string()).default([]),    // lineage: ["p_ship@v1"] — a replan's provenance
+  producer: z.string(),
+  runId: z.string(),
+  created: z.string().datetime(),
+});
+export type Plan = z.infer<typeof Plan>;
+
+/** One line per transition. The LATEST line for an item wins the fold. */
+export const PlanEvent = z.object({
+  item: z.string(),
+  status: PlanItemStatus,
+  /** Who wrote it. An `engine` event is the truth about what a run actually did; a `model` event is a
+   *  claim. Both are recorded — a model trying to mark a failed delegation `done` is exactly the
+   *  behaviour you want visible in a trace, not silently swallowed. */
+  by: z.enum(["model", "engine"]),
+  runId: z.string(),                           // the run that wrote the event
+  /** The child run (or background taskId) this item is bound to. Once set, ONLY the engine may set the
+   *  item's terminal status: the checkbox reflects what happened, not what the model claims. */
+  boundRunId: z.string().optional(),
+  note: z.string().optional(),                 // e.g. a failed verdict's reasons
+  /** A recorded-but-refused attempt: the model tried to set a terminal status on an engine-owned item.
+   *  The fold SKIPS these — otherwise the attempt would be the last line for that item and would win,
+   *  which is precisely the lie the engine-owns rule exists to prevent. It stays in the log because a
+   *  model marking a failed delegation `done` is a fact worth having. */
+  rejected: z.boolean().optional(),
+  ts: z.string().datetime(),
+});
+export type PlanEvent = z.infer<typeof PlanEvent>;
+
+/** An item with its folded state — what the panel renders and what the model is shown. */
+export interface FoldedItem extends PlanItem {
+  status: PlanItemStatus;
+  boundRunId?: string;
+  note?: string;
+  /** When this item last changed, for elapsed-in-state. */
+  updated?: string;
+}
+
+export interface PlanState {
+  plan: Plan;
+  handle: string;
+  items: FoldedItem[];
+  counts: { total: number; done: number; open: number; failed: number };
+}
+
+export const planHandle = (p: { id: string; version: number }): string => `${p.id}@v${p.version}`;
+
+/** `p_ship` (latest) or `p_ship@v2` (a concrete version). Mirrors schemas/artifact.ts parseHandle. */
+export function parsePlanHandle(handle: string): { id: string; version?: number } {
+  const at = handle.lastIndexOf("@v");
+  if (at < 0) return { id: handle };
+  const v = Number(handle.slice(at + 2));
+  return Number.isInteger(v) && v > 0 ? { id: handle.slice(0, at), version: v } : { id: handle };
+}
+
+/** A stable id from a goal. Deterministic, so re-stating the same goal continues the same plan rather
+ *  than forking a second one the agent then has to reconcile against. */
+export function planIdForGoal(goal: string): string {
+  const slug = goal
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40)
+    .replace(/-+$/g, "");
+  return `p_${slug || "plan"}`;
+}

package/src/policy.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+
+/** A coaching note — one file per note under agents/<id>/policies/. */
+export const PolicyNote = z.object({
+  id: z.string(),                          // pol_xxxx
+  agent: z.string(),
+  when: z.string(),                        // condition, enforced at retrieval
+  do: z.string(),                          // instruction
+  scope: z.enum(["agent", "global"]).default("agent"),
+  status: z.enum(["proposed", "approved", "rejected", "superseded"]),
+  supersedes: z.string().optional(),       // id of the note this replaces
+  taughtBy: z.string(),
+  fromRun: z.string().optional(),          // run id the coaching came from
+  created: z.string().datetime(),
+  expanded: z.array(z.string()).default([]), // write-time paraphrases for recall
+});
+export type PolicyNote = z.infer<typeof PolicyNote>;
+
+/** Approved output bound to a request pattern. */
+export const Exemplar = z.object({
+  id: z.string(),                          // ex_xxxx
+  agent: z.string(),
+  pattern: z.string(),                     // request pattern this answers
+  artifact: z.string(),                    // artifact HANDLE ("id" ⇒ latest, or "id@vN") — resolves via the
+                                           // artifact store (store/artifacts.ts), NOT a raw filesystem path.
+                                           // Plan 01 Ph4c: keying on the stable, versioned, relocatable id
+                                           // (never an absolute path) is what lets an exemplar survive a
+                                           // revision/workspace move — same addressing as delegate hand-off.
+  mode: z.enum(["serve", "imitate"]).default("imitate"),
+  status: z.enum(["proposed", "approved", "rejected", "superseded"]),
+  taughtBy: z.string(),
+  created: z.string().datetime(),
+});
+export type Exemplar = z.infer<typeof Exemplar>;

package/src/schedule.ts

@@ -0,0 +1,55 @@
+/** Plan 04 Phase 6 — a Schedule fires an UNATTENDED run on a schedule (cron-style) or a trigger
+ *  (a file watch), driving the goal through the headless `executeRun` path (Plan 03's seam). A
+ *  schedule persists to `schedules/<id>.json` (files are canon) so it survives restarts and is
+ *  reconciled/armed on boot.
+ *
+ *  APPROVALS: a scheduled run is unattended — there is no captain watching an approval card — so the
+ *  approval channel is restricted to `reject` (the safe default: decline every privileged action) or
+ *  `approve` (scripted/trusted only). `prompt` is meaningless with no stdin and is not allowed here. */
+import { z } from "zod";
+
+/** Unattended approval modes only. `reject` = the safe default (decline privileged tools); `approve`
+ *  = trusted/scripted (approve everything). No `prompt` — nobody is there to answer. */
+export const ScheduleApprove = z.enum(["reject", "approve"]);
+export type ScheduleApprove = z.infer<typeof ScheduleApprove>;
+
+/** What makes a schedule due:
+ *  - `cron`  — a 5-field cron expression, evaluated in **UTC** (deterministic; no DST ambiguity).
+ *  - `interval` — fire every `everyMs` milliseconds.
+ *  - `watch` — fire when the file/dir at `path` changes (its mtime moves). Polled on each tick. */
+export const Trigger = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("cron"), expr: z.string().min(1) }),
+  z.object({ kind: z.literal("interval"), everyMs: z.number().int().positive() }),
+  z.object({ kind: z.literal("watch"), path: z.string().min(1) }),
+]);
+export type Trigger = z.infer<typeof Trigger>;
+
+export const Schedule = z.object({
+  id: z.string().min(1),
+  goal: z.string().min(1),
+  agent: z.string().min(1).default("root"),
+  trigger: Trigger,
+  approve: ScheduleApprove.default("reject"),
+  enabled: z.boolean().default(true),
+  created: z.string(),
+  updated: z.string(),
+  // Mutable scheduling state, advanced by the runner on each fire and persisted so cadence survives
+  // a restart. `nextDueAt` is the next computed fire time (cron/interval); `lastMtimeMs` the last-seen
+  // mtime (watch). `lastRunId`/`lastStatus` record the outcome of the most recent fire.
+  runCount: z.number().int().nonnegative().default(0),
+  lastRunAt: z.string().optional(),
+  lastRunId: z.string().optional(),
+  lastStatus: z.string().optional(),
+  nextDueAt: z.string().optional(),
+  lastMtimeMs: z.number().optional(),
+});
+export type Schedule = z.infer<typeof Schedule>;
+
+/** The fields a caller supplies to create a schedule (the rest are defaulted / assigned). */
+export interface ScheduleSpec {
+  id?: string;
+  goal: string;
+  agent?: string;
+  trigger: Trigger;
+  approve?: ScheduleApprove;
+}

package/src/skill.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+
+/** A reusable procedure document — one file per skill at skills/<id>.md
+ *  (YAML frontmatter = the skill minus `body`, body = the procedure). Mirrors schemas/policy.ts. */
+export const Skill = z.object({
+  id: z.string(),                                        // skill_xxxx
+  name: z.string(),                                      // short, unique; used by use_skill + display
+  description: z.string(),                               // WHEN to use it — drives discovery + injection
+  tags: z.array(z.string()).default([]),
+  status: z.enum(["active", "draft"]).default("active"), // only `active` are injected/usable
+  body: z.string(),                                      // the procedure (markdown)
+  created: z.string().datetime(),
+  updated: z.string().datetime().optional(),
+});
+export type Skill = z.infer<typeof Skill>;

package/src/team.ts

@@ -0,0 +1,87 @@
+import { z } from "zod";
+
+/** Plan 22: the universal team. Every agent belongs to `default` — it IS the squad, expressed as a
+ *  team. It is seeded on boot, cannot be deleted, and is IMPLICIT: an agent never has to list it in its
+ *  own `teams:` frontmatter (the derived index adds it). Root leads it. Explicit teams (news, trading…)
+ *  are additive overlays on top; joining one never removes an agent from default. */
+export const DEFAULT_TEAM_ID = "default";
+
+/** A team's tool policy, applied in toolsForAgent to every member.
+ *  `grant` ADDS to a member's own toolset; `deny` REMOVES from it and wins over the member's own grant.
+ *  A `deny` list that intersects DEFAULT_WORKER_TOOLS is rejected when the team loads (store/teams.ts):
+ *  Plan 14's capability FLOOR — a worker can always produce and hand off an artifact — is not a team's
+ *  to punch through. `grant` may name privileged tools; that is safe precisely because teams are
+ *  captain-authored files and there is deliberately no create_team tool. */
+export const TeamTools = z
+  .object({
+    grant: z.array(z.string()).default([]),
+    deny: z.array(z.string()).default([]),
+  })
+  .prefault({});
+export type TeamTools = z.infer<typeof TeamTools>;
+
+/** Plan 19: a team is a functional group within the squad — news, trading, programming.
+ *
+ *  Canonical form is teams/<id>/team.md: YAML frontmatter (this schema minus `charterBody`) plus a
+ *  markdown body that becomes the team's standing instruction, injected into every member's system
+ *  prompt as a context-tier section. Mirrors agents/<id>/agent.md exactly.
+ *
+ *  MEMBERSHIP IS NOT HERE. An agent declares `team: <id>` in its own frontmatter — one source of truth —
+ *  and a team's roster is derived by grouping the registry. Listing members here too would let the two
+ *  drift. `lead` names an agent that must itself declare this team; a mismatch is a boot error. */
+export const TeamDef = z.object({
+  id: z.string().regex(/^[a-z][a-z0-9-]*$/),
+  /** One line, shown in root's roster in place of the members it stands for. */
+  charter: z.string(),
+  /** Optional. Present ⇒ delegate_task(to:"<id>") routes to this agent, which then delegates within
+   *  its team; it costs one delegation level and one model call. Absent ⇒ the engine routes to the
+   *  best-ranked member directly, for free. Leadless is the right default. */
+  lead: z.string().optional(),
+  tools: TeamTools,
+  /** Body of team.md — the team's standing instruction. Culture is configuration. */
+  charterBody: z.string().default(""),
+  created: z.string().datetime(),
+});
+export type TeamDef = z.infer<typeof TeamDef>;
+
+/** A member's effective toolset: its own grant, minus the team's `deny`, plus the team's `grant`.
+ *
+ *  `deny` wins over BOTH the member's own grant and the team's own `grant` — a team that lists a tool in
+ *  both is unambiguous rather than order-dependent. The DEFAULT_WORKER_TOOLS floor is protected earlier,
+ *  when the team file loads (store/teams.ts assertPolicyRespectsFloor), so nothing here can strip a
+ *  worker's ability to produce and hand off an artifact. */
+export function effectiveTools(agentTools: string[], policy?: TeamTools): string[] {
+  if (!policy || (!policy.grant.length && !policy.deny.length)) return agentTools;
+  const denied = new Set(policy.deny);
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const t of [...agentTools, ...policy.grant])
+    if (!denied.has(t) && !seen.has(t)) { seen.add(t); out.push(t); }
+  return out;
+}
+
+/** Fold several teams' tool policies into one (Plan 22: an agent may sit on many teams). Grants union,
+ *  denies union — and since effectiveTools lets deny win over grant, a tool ANY of the agent's teams
+ *  denies is denied for it, even if another grants it. The DEFAULT_WORKER_TOOLS floor is protected
+ *  per-team at load (assertPolicyRespectsFloor), so the union can never strip a worker's artifact tools. */
+export function mergeTeamPolicies(policies: (TeamTools | undefined)[]): TeamTools {
+  const grant: string[] = [];
+  const deny: string[] = [];
+  for (const p of policies) {
+    if (!p) continue;
+    for (const g of p.grant) if (!grant.includes(g)) grant.push(g);
+    for (const d of p.deny) if (!deny.includes(d)) deny.push(d);
+  }
+  return { grant, deny };
+}
+
+/** The ACL grammar's team production (core/registry.ts). An entry in canSee/canDelegateTo is `"*"`,
+ *  an exact agent id, or `team:<id>`. No existing id contains a colon, so this is purely additive. */
+export const TEAM_ACL_PREFIX = "team:";
+
+export const teamAclEntry = (teamId: string): string => `${TEAM_ACL_PREFIX}${teamId}`;
+
+/** The team named by an ACL entry, or null when the entry is `"*"` or an exact agent id. */
+export function parseTeamAcl(entry: string): string | null {
+  return entry.startsWith(TEAM_ACL_PREFIX) ? entry.slice(TEAM_ACL_PREFIX.length) : null;
+}

package/src/trace.ts

@@ -0,0 +1,73 @@
+import { z } from "zod";
+
+export const CoachingLedger = z.object({
+  retrieved: z.array(z.string()),          // policy ids
+  applied: z.array(z.string()),
+  skipped: z.array(z.object({ id: z.string(), reason: z.string() })),
+  knowledge: z.array(z.string()).default([]), // kb node ids injected into context (default keeps old traces parseable)
+  skills: z.array(z.string()).default([]), // skill ids injected into context (default keeps old traces parseable)
+});
+
+/** An independent checker's judgement of a delegated output against its acceptance criteria. */
+export const VerificationVerdict = z.object({
+  pass: z.boolean(),
+  reasons: z.array(z.string()).default([]),   // when pass=false, the unmet criteria; may be empty on pass
+});
+export type VerificationVerdict = z.infer<typeof VerificationVerdict>;
+
+/** One criteria→verdict record for a delegation that carried acceptance criteria. A failed initial
+ *  verdict followed by a retry yields two records (retried:false, then retried:true). */
+export const VerificationRecord = z.object({
+  criteria: z.string(),
+  verdict: VerificationVerdict,
+  runId: z.string(),                          // the child run whose output was checked
+  retried: z.boolean().default(false),
+  tokens: z.number().default(0),              // the checker call's own spend (advisory; not a hard budget)
+  costUsd: z.number().nullable().default(0),  // null on a subscription checker (no measurable USD) — never a fabricated 0
+  costNote: z.string().optional(),            // "subscription" when the checker ran on an unpriced subscription model
+  checkerError: z.boolean().optional(),       // Plan 20: the checker itself never ran (outage/cancel) — the verdict means "unverified", not a judged fail
+});
+export type VerificationRecord = z.infer<typeof VerificationRecord>;
+
+/** One file per run under runs/<agent>/. Written by agents, read by humans + coaching flow only. */
+export const RunTrace = z.object({
+  id: z.string(),                          // <agent>/<date>-run<n>
+  agent: z.string(),
+  task: z.string(),
+  triggeredBy: z.string(),                 // "user" | run id of delegating run
+  ledger: CoachingLedger,
+  toolCalls: z.array(z.object({ tool: z.string(), count: z.number() })),
+  artifacts: z.array(z.string()),          // artifact references (handles/paths) THIS run produced
+  // Hand-off graph (parent-side, mirrors delegatedOut): what flowed across this run's delegation
+  // edges. inputArtifacts = handles handed DOWN to children; outputArtifacts = handles received UP.
+  // Defaults keep pre-Plan-01 traces parseable.
+  inputArtifacts: z.array(z.string()).default([]),
+  outputArtifacts: z.array(z.string()).default([]),
+  delegatedOut: z.array(z.string()),       // run ids
+  verification: z.array(VerificationRecord).default([]), // criteria→verdict records for this run's delegations (default keeps old traces parseable)
+  outcome: z.enum(["completed", "blocked", "failed", "interrupted"]),
+  tokens: z.number().default(0),
+  // Plan 05: peak estimated context size (system + messages, chars/4) actually sent to the model this
+  // run — post-compaction. Advisory (a gate estimate, not billed tokens). Default keeps old traces parseable.
+  contextTokens: z.number().default(0),
+  costUsd: z.number().nullable().default(0),
+  costNote: z.string().optional(),
+  // This run's OWN delegation-checker (Plan 06) spend, kept separate from `tokens`/`costUsd` (the
+  // primary loop) because the verifier call creates NO child trace. /costs adds these to the run's
+  // own-spend sum so verifier tokens/USD surface exactly ONCE (no child double-count). USD is 0 for a
+  // subscription/unmeasurable run (mirrors costUsd:null there) — never a fabricated price. Defaults
+  // keep pre-Plan-09 traces parseable.
+  verifierTokens: z.number().default(0),
+  verifierCostUsd: z.number().default(0),
+  model: z.string().optional(),           // resolved model id — the /costs "by provider" dimension (default keeps old traces parseable)
+  aggregate: z.object({ tokens: z.number(), costUsd: z.number().nullable() }).optional(),
+  // Plan 18: the agent's plan handle at run end, and how many transitions this run wrote. Both OPTIONAL
+  // (not .default(0)) so every trace written before this plan parses AND so the hand-built RunTrace
+  // fixtures across the suite need no edit — absent simply means "this run had no plan".
+  plan: z.string().optional(),
+  planEvents: z.number().optional(),
+  notes: z.array(z.string()).default([]),
+  durationMs: z.number().default(0),
+  started: z.string().datetime(),
+});
+export type RunTrace = z.infer<typeof RunTrace>;