@awebai/oats 0.22.0

package/packages/record/test/vectors/validate.mjs

@@ -0,0 +1,391 @@
+#!/usr/bin/env node
+// Turn-record conformance validator (docs/turn-record-sot.md).
+//
+// Dependency-free, Node >= 18. Independent re-implementation of canonical
+// JSON, turn ids, did:key Ed25519 verification, the aweb projection, and the
+// merge rules; the vectors are generated by the Python awid stack, so a green
+// run is a two-language agreement on every byte.
+
+import { createHash, createPublicKey, verify as edVerify } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+// ---------------------------------------------------------- canonical JSON
+
+class CoreNumberError extends Error {}
+
+function canon(v) {
+  if (v === null) return "null";
+  const t = typeof v;
+  if (t === "string") return JSON.stringify(v);
+  if (t === "boolean") return v ? "true" : "false";
+  if (t === "number") {
+    if (!Number.isInteger(v) || Math.abs(v) > Number.MAX_SAFE_INTEGER) {
+      throw new CoreNumberError(`non-integer number in canonical core: ${v}`);
+    }
+    return String(v);
+  }
+  if (Array.isArray(v)) return "[" + v.map(canon).join(",") + "]";
+  if (t === "object") {
+    const keys = Object.keys(v).sort();
+    return "{" + keys.map((k) => JSON.stringify(k) + ":" + canon(v[k])).join(",") + "}";
+  }
+  throw new Error(`unsupported value in canonical core: ${t}`);
+}
+
+function coreString(turn) {
+  const core = {};
+  for (const k of Object.keys(turn)) if (k !== "id" && k !== "sig") core[k] = turn[k];
+  return canon(core);
+}
+
+function turnId(turn) {
+  return "t1:" + createHash("sha256").update(coreString(turn), "utf8").digest("hex");
+}
+
+// ------------------------------------------------------- did:key + ed25519
+
+const B58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+
+function b58decode(s) {
+  let n = 0n;
+  for (const c of s) {
+    const i = B58.indexOf(c);
+    if (i < 0) throw new Error(`invalid base58 char ${c}`);
+    n = n * 58n + BigInt(i);
+  }
+  const bytes = [];
+  while (n > 0n) {
+    bytes.push(Number(n & 0xffn));
+    n >>= 8n;
+  }
+  bytes.reverse();
+  for (const c of s) {
+    if (c === "1") bytes.unshift(0);
+    else break;
+  }
+  return Uint8Array.from(bytes);
+}
+
+function publicKeyFromDid(did) {
+  if (!did.startsWith("did:key:z")) throw new Error(`unsupported did ${did}`);
+  const decoded = b58decode(did.slice("did:key:z".length));
+  if (decoded[0] !== 0xed || decoded[1] !== 0x01 || decoded.length !== 34) {
+    throw new Error(`not an ed25519 did:key: ${did}`);
+  }
+  const SPKI = Buffer.from("302a300506032b6570032100", "hex");
+  return createPublicKey({
+    key: Buffer.concat([SPKI, Buffer.from(decoded.subarray(2))]),
+    format: "der",
+    type: "spki",
+  });
+}
+
+function b64decode(s) {
+  const normalized = s.replaceAll("-", "+").replaceAll("_", "/");
+  const padded = normalized + "=".repeat((4 - (normalized.length % 4)) % 4);
+  return Buffer.from(padded, "base64");
+}
+
+function verifySig(did, payloadUtf8, sigB64) {
+  return edVerify(null, Buffer.from(payloadUtf8, "utf8"), publicKeyFromDid(did), b64decode(sigB64));
+}
+
+// ------------------------------------------------------------- aweb project
+
+function projectSigned(row, kind) {
+  const p = JSON.parse(row.signed_payload);
+  return {
+    v: 1,
+    ts: p.timestamp,
+    from: p.from,
+    to: p.to,
+    thread: "aweb:conv:" + row.conversation_id,
+    kind,
+    body: { subject: p.subject, text: p.body },
+    signature: row.signature,
+    signed_payload: row.signed_payload,
+    provenance: {
+      source: kind === "mail" ? "aweb-mail" : "aweb-chat",
+      fidelity: "projected",
+      origin: { message_id: row.message_id, conversation_id: row.conversation_id },
+    },
+  };
+}
+
+function projectLegacy(row) {
+  const origin = {
+    message_id: row.message_id,
+    conversation_id: row.conversation_id,
+  };
+  for (const k of ["from_did", "from_stable_id", "to_did", "to_stable_id", "priority"]) {
+    if (row[k] !== undefined) origin[k] = row[k];
+  }
+  origin.timestamp_source = "created_at";
+  return {
+    v: 1,
+    ts: row.created_at,
+    from: row.from,
+    to: row.to,
+    thread: "aweb:conv:" + row.conversation_id,
+    kind: "mail",
+    body: { subject: row.subject, text: row.body },
+    provenance: { source: "aweb-mail", fidelity: "projected", origin },
+  };
+}
+
+function checkSignedConsistency(turn) {
+  const p = JSON.parse(turn.signed_payload);
+  const pairs = [
+    [turn.ts, p.timestamp, "ts/timestamp"],
+    [turn.from, p.from, "from"],
+    [turn.to, p.to, "to"],
+    [turn.body.subject, p.subject, "body.subject/subject"],
+    [turn.body.text, p.body, "body.text/body"],
+  ];
+  for (const [a, b, what] of pairs) {
+    if (a !== b) throw new Error(`signed consistency violation on ${what}`);
+  }
+}
+
+function unproject(turn) {
+  const out = {};
+  if (turn.signed_payload !== undefined) {
+    const p = JSON.parse(turn.signed_payload);
+    Object.assign(out, p);
+    out.message_id = turn.provenance.origin.message_id;
+    out.conversation_id = turn.provenance.origin.conversation_id;
+    out.signature = turn.signature;
+    out.signed_payload = turn.signed_payload;
+    if (p.message_id !== undefined && p.message_id !== out.message_id) {
+      throw new Error("signed_payload message_id disagrees with origin");
+    }
+    if (p.conversation_id !== undefined && p.conversation_id !== out.conversation_id) {
+      throw new Error("signed_payload conversation_id disagrees with origin");
+    }
+    return out;
+  }
+  const origin = turn.provenance.origin;
+  out.message_id = origin.message_id;
+  out.conversation_id = origin.conversation_id;
+  for (const k of ["from_did", "from_stable_id", "to_did", "to_stable_id", "priority"]) {
+    if (origin[k] !== undefined) out[k] = origin[k];
+  }
+  out.from = turn.from;
+  out.to = turn.to;
+  out.subject = turn.body.subject;
+  out.body = turn.body.text;
+  if (origin.timestamp_source === "created_at") out.created_at = turn.ts;
+  return out;
+}
+
+// -------------------------------------------------------------- merge rules
+
+function isPrefix(shorter, longer) {
+  if (shorter.length > longer.length) return false;
+  for (let i = 0; i < shorter.length; i++) {
+    if (shorter[i].id !== longer[i].id) return false;
+  }
+  return true;
+}
+
+function mergeStreams(replicas) {
+  const merged = {};
+  for (const replica of Object.values(replicas)) {
+    for (const [stream, copy] of Object.entries(replica.streams)) {
+      const prev = merged[stream];
+      if (!prev) {
+        merged[stream] = copy;
+        continue;
+      }
+      const [a, b] = prev.length <= copy.length ? [prev, copy] : [copy, prev];
+      if (!isPrefix(a, b)) throw new Error(`non-prefix copies of stream ${stream}`);
+      merged[stream] = b;
+    }
+  }
+  return merged;
+}
+
+function effectiveRecord(merged, recordOwner) {
+  const byId = new Map();
+  for (const copy of Object.values(merged)) {
+    for (const turn of copy) if (!byId.has(turn.id)) byId.set(turn.id, turn);
+  }
+  const hidden = new Set();
+  for (const turn of byId.values()) {
+    if (turn.kind !== "tombstone") continue;
+    for (const link of turn.links ?? []) {
+      if (link.rel !== "tombstones") continue;
+      const target = byId.get(link.ref);
+      if (!target) continue;
+      if (turn.from === target.from || turn.from === recordOwner) hidden.add(target.id);
+    }
+  }
+  return { byId, hidden };
+}
+
+// ------------------------------------------------------------------ harness
+
+let failures = 0;
+let checks = 0;
+
+function assert(cond, label) {
+  checks++;
+  if (!cond) {
+    failures++;
+    console.error(`FAIL  ${label}`);
+  }
+}
+
+function assertThrows(fn, label) {
+  checks++;
+  try {
+    fn();
+    failures++;
+    console.error(`FAIL  ${label} (expected rejection, got acceptance)`);
+  } catch {
+    /* expected */
+  }
+}
+
+function load(name) {
+  return JSON.parse(readFileSync(join(HERE, name), "utf8"));
+}
+
+// turn-id-v1
+{
+  const doc = load("turn-id-v1.json");
+  for (const c of doc.cases) {
+    assert(coreString(c.turn) === c.expected_canonical_core, `${c.name}: canonical core bytes`);
+    assert(turnId(c.turn) === c.expected_id, `${c.name}: id`);
+    assert(c.turn.id === c.expected_id, `${c.name}: stored id`);
+    if (c.turn.sig) {
+      assert(
+        verifySig(c.turn.sig.by, coreString(c.turn), c.turn.sig.sig),
+        `${c.name}: envelope sig`,
+      );
+    }
+  }
+  for (const n of doc.negatives) {
+    if (n.reject === "id") {
+      assert(turnId(n.turn) !== n.turn.id, `${n.name}: id mismatch detected`);
+    } else if (n.reject === "sig") {
+      checks++;
+      let ok = false;
+      try {
+        ok = verifySig(n.turn.sig.by, coreString(n.turn), n.turn.sig.sig);
+      } catch {
+        ok = false;
+      }
+      if (ok) {
+        failures++;
+        console.error(`FAIL  ${n.name}: invalid signature accepted`);
+      }
+    } else if (n.reject === "number") {
+      assertThrows(() => coreString(n.turn), `${n.name}: float rejected from core`);
+    } else {
+      assert(false, `${n.name}: unknown negative kind ${n.reject}`);
+    }
+  }
+}
+
+// aweb-projection-v1
+{
+  const doc = load("aweb-projection-v1.json");
+  for (const c of doc.cases) {
+    const expected = c.expected_turn;
+    const projected = expected.signed_payload
+      ? projectSigned(c.row, expected.kind)
+      : projectLegacy(c.row);
+    assert(
+      coreString(projected) === coreString(expected),
+      `${c.name}: independent projection matches expected core bytes`,
+    );
+    assert(turnId(projected) === expected.id, `${c.name}: projected id`);
+
+    if (expected.signed_payload) {
+      assert(
+        expected.signed_payload === c.row.signed_payload,
+        `${c.name}: signed_payload byte-verbatim`,
+      );
+      const p = JSON.parse(expected.signed_payload);
+      assert(
+        verifySig(p.from_did, expected.signed_payload, expected.signature),
+        `${c.name}: source signature verifies against from_did`,
+      );
+      checks++;
+      try {
+        checkSignedConsistency(expected);
+      } catch (e) {
+        failures++;
+        console.error(`FAIL  ${c.name}: ${e.message}`);
+      }
+    }
+
+    const row = unproject(expected);
+    for (const f of c.round_trip_fields) {
+      const want = c.row[f] !== undefined ? c.row[f] : JSON.parse(c.row.signed_payload ?? "{}")[f];
+      assert(
+        JSON.stringify(row[f]) === JSON.stringify(want),
+        `${c.name}: round-trip field ${f}`,
+      );
+    }
+  }
+  for (const n of doc.negatives) {
+    if (n.reject === "consistency") {
+      assert(turnId(n.turn) === n.turn.id, `${n.name}: id itself is valid`);
+      assertThrows(() => checkSignedConsistency(n.turn), `${n.name}: consistency rejected`);
+    } else {
+      assert(false, `${n.name}: unknown negative kind ${n.reject}`);
+    }
+  }
+}
+
+// journal-merge-v1
+{
+  const doc = load("journal-merge-v1.json");
+  const merged = mergeStreams(doc.replicas);
+  for (const [stream, len] of Object.entries(doc.expected.merged_stream_lengths)) {
+    assert(merged[stream]?.length === len, `merge: stream ${stream} length ${len}`);
+  }
+  const { byId, hidden } = effectiveRecord(merged, doc.record_owner);
+  assert(
+    JSON.stringify([...byId.keys()].sort()) === JSON.stringify(doc.expected.union_ids),
+    "merge: union ids",
+  );
+  assert(
+    JSON.stringify([...hidden].sort()) === JSON.stringify([...doc.expected.hidden_ids].sort()),
+    "merge: hidden ids (tombstone dominance + authority)",
+  );
+  const visible = [...byId.keys()].filter((id) => !hidden.has(id)).sort();
+  assert(
+    JSON.stringify(visible) === JSON.stringify(doc.expected.visible_ids),
+    "merge: visible ids",
+  );
+  for (const t of byId.values()) {
+    assert(turnId(t) === t.id, `merge: turn ${t.id.slice(0, 12)}… id recomputes`);
+  }
+  for (const n of doc.negatives) {
+    if (n.reject === "prefix") {
+      assertThrows(
+        () =>
+          mergeStreams({
+            a: { streams: { [n.stream]: n.copy_a } },
+            b: { streams: { [n.stream]: n.copy_b } },
+          }),
+        `${n.name}: non-prefix copies quarantined`,
+      );
+    } else {
+      assert(false, `${n.name}: unknown negative kind ${n.reject}`);
+    }
+  }
+}
+
+if (failures) {
+  console.error(`\n${failures}/${checks} checks failed`);
+  process.exit(1);
+}
+console.log(`ok — ${checks} checks passed`);

package/skills/integration-authoring/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: integration-authoring
+description: >-
+  Route custom OATS capability-package and integration work to the framework's
+  integrations expert. Use when building, adapting, or debugging a reusable
+  capability, new task/messaging/knowledge integration, oats.json manifest,
+  lifecycle hook, or operational command—not merely activating an existing
+  package. Triggers: "custom integration", "capability package", "integrate
+  our tracker", "new messaging integration", "write an oats.json".
+---
+
+# Capability and integration authoring — delegate
+
+A capability package may ship skills, instance instructions, requirements,
+namespaced commands, and approved hooks. An integration is the constrained
+subtype implementing exactly one fundamental layer. Building either requires
+manifest, security, targeting-boundary, collision, and probe discipline; use
+the framework's **integrations-expert** soul rather than improvising.
+
+If the user only wants an existing package, use:
+
+```bash
+oats install <source>            # external acquisition + exact lock; inactive
+oats trust <id>                  # only if commands/hooks exist
+oats use <id> --global|--type <t>|--soul <s>
+```
+
+## 1. Locate the OATS framework repository
+
+Check a local pi package path, then likely locations such as
+`~/oats`; verify with `git -C <dir> remote get-url origin`. Avoid
+pi-managed git clones because updates reset them. If absent, ask where to
+clone `https://github.com/awebai/oats`.
+
+## 2. Spawn the expert against the user's repository
+
+```bash
+node -e "
+import('<framework-repo>/lib/core.mjs').then(m => {
+  const root = '<framework-repo>/agents';
+  const a = m.findAgent(root, 'integrations-expert');
+  const r = m.spawnInstance(root, a, {
+    purpose: '<package-slug>',
+    repo: '<users-workspace-or-repo>',
+    work: 'checkout',
+    task: '<capability intent; layer if any; skills/instructions/commands/hooks; external tools; desired global/group/soul targets; distribution path>',
+  });
+  console.log('window:', r.tmux.window, '| attach:', r.attach);
+})"
+```
+
+The work tree is the user's repository, where a local package belongs under
+`.agents/capabilities/<name>/`. A framework contribution belongs under
+`capabilities/<name>/` in the framework worktree; an independently published
+package uses its own repository.
+
+## 3. Brief the design boundary
+
+Tell the expert:
+
+- whether it is additive or implements exactly one of knowledge/messaging/tasks;
+- external requirements and executable surfaces;
+- intended distribution and version/compatibility;
+- desired config-owned targets and settings; and
+- expected skill/instruction/scaffold collisions.
+
+Targets never belong in the manifest. The expert must test exact pi/Claude
+instance materialization, generated instructions, lock/trust behavior,
+command gating, deterministic hooks, and scaffold ownership as applicable.
+
+## 4. Hand off
+
+Report the tmux window (`tmux attach -t pi-agents`). The expert follows its
+package/integration craft, runs a scaffold-only probe, and leaves acquisition
+and activation commands for the user. Its durable lessons harvest back into
+its soul.

package/skills/oats/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: oats
+description: >-
+  How to operate inside OATS (Open Agent Team Specification): instance layout and
+  lifecycle, status, spawn, retire, doctor, operational capability commands,
+  canonical-vs-generated instructions, or explaining OATS. For configuring
+  deployments (capabilities, layers, agent types, injections) load the
+  oats-config skill. Triggers: "spawn an agent", "what agents are running",
+  "retire this instance", "oats doctor", "oats status", "how does OATS work".
+---
+
+# Operating in OATS
+
+A **soul** is a durable specialized agent. An **instance** is one disposable,
+resumable incarnation. A **capability package** distributes reusable skills,
+instructions, commands, and approved lifecycle hooks. An **integration** is a
+capability selected for one exclusive knowledge, messaging, or tasks layer.
+
+## Instance home
+
+| Path | Meaning |
+|---|---|
+| `TASK.md` | briefing and task |
+| `soul/` | linked canonical soul |
+| `AGENTS.md` | generated canonical soul + active capability instructions |
+| `CLAUDE.md -> AGENTS.md` | compatibility view |
+| `.agents/skills/` | exact runtime skill set |
+| `work/` | all repository work happens here |
+| `instance.json` | repo, branch, capabilities, skills, instruction sources, trust, hooks |
+
+Memory files exist only when the selected knowledge integration creates them.
+Follow their injected protocol.
+
+## Lifecycle and roster
+
+```bash
+oats status [--json]
+oats status --team [--json]   # whole-team roster when config declares team: (all repos in the team scope)
+# with the aweb messaging integration active, `oats aweb roster` adds the
+# cross-machine view: aweb team members, where OATS aliases are instance names
+oats create <name> [--description ...] [--type <agent-type>] [--repo ...] [--work worktree|checkout|attached|workspace]
+# workspace mode = cross-repo coordinator: ./work is the whole team scope; read
+# all member repos, edit none; if a knowledge layer is active, IT defines how
+# soul updates are delivered (see that capability's own instructions)
+oats spawn <agent> [--task ...] [--purpose ...] [--relation child|sibling|parent|unrelated --relative-to <instance>] [--parent <instance>] [--no-launch] [--json]
+# lineage is explicit: agents spawning sub-agents declare their RELATION to the
+# new instance with --relation + --relative-to (--parent X is sugar for
+# --relative-to X --relation child). Without a relation the spawn is
+# operator-origin and appears top-level. Attached-mode spawns are ALWAYS
+# children of the work-tree owner (relation flags are rejected there).
+# when config declares team:, spawn/retire also resolve souls and instances
+# defined in sibling repos of the team scope (unique match wins; the instance
+# homes with its owning repo, works in that repo, resolves that repo's config)
+oats retire <instance> [--delete-branch]
+```
+
+### Spawn relations — choosing how the new instance relates to you
+
+When you spawn, declare what the new instance IS to you — the workspace is
+viewed as clusters of related agents, and the relation is how clusters form:
+
+- **child** (`--relation child --relative-to <you>`, or `--parent <you>`) —
+  the new instance works FOR you and nests under you. Example: a coordinator
+  spawning the developers of its feature.
+- **parent** (`--relation parent --relative-to <you>`) — the new instance
+  oversees YOU: your recorded lineage is re-pointed so it becomes your parent.
+  Example: spawning a maintainer of your own PR — the maintainer sits
+  above you. When it later retires, lineage is spliced automatically: you
+  return to your previous parent (or top-level).
+- **sibling** (`--relation sibling --relative-to <you>`) — a peer at your
+  level, in your cluster. Example: enlisting a peer coordinator in another
+  repo, or an architecture coordinator helping you.
+- **unrelated** (default, no flags) — no link. Example: work with no
+  connection to yours.
+
+Exception: **attached** work mode implies child-of-owner — an attached agent
+shares its owner's work tree and is always that owner's child; relation flags
+are rejected there.
+
+This is judgment, not mandate: every workspace differs, and a soul's own
+explicit relation instructions (in its AGENTS.md or task briefing) take
+precedence over these defaults. When unsure which relation fits, check with
+the human.
+
+Do not spawn on your own judgment. Spawn when the human asks or a documented
+workflow requires it.
+
+### Instance naming
+
+Name an instance for both **who it is** and **what this incarnation does** by
+spawning with `oats spawn <soul> --purpose <descriptive-role>`. OATS constructs
+`<full-soul-name>-<descriptive-role>`; use a short, lowercase kebab-case role
+suffix (for example, `desktop-ux` or `terminal-safety`), not an opaque number
+or generic word. The current spawn command always retains the full soul name,
+so shorten the purpose—not the soul prefix—when the result would be unwieldy.
+Do **not** use `oats create` to name an incarnation: it creates a new persistent
+soul. Never put secrets, user data, or volatile task details in an instance
+name.
+
+To self-retire, first finish memory/commit/reporting requirements, report final
+status, then run `oats retire <own-instance> --self`. Never retire merely to
+clean up; retirement deletes the instance home.
+
+## Canonical versus generated
+
+Edit `soul/AGENTS.md` for durable role instructions. Instance `AGENTS.md` is a
+generated view; marked blocks name their source. Config changes do not mutate
+the committed soul. Preview a fresh composition with:
+
+```bash
+oats doctor /path/to/context --soul <name>
+```
+
+The instance's `.agents/skills/` holds the exact OATS-composed set (kernel +
+soul + active capabilities); `.claude/skills` mirrors it. Harness-ambient
+skills (user-level, packages, work tree) coexist with this set. Duplicate
+names *within* the OATS set fail spawn unless `skill-overrides` explicitly
+chooses a source.
+
+## Configuration
+
+Deployments are configured in scoped `oats-config.yaml` files (laptop /
+workspace / repository) declaring capability packages, exclusive
+knowledge/messaging/tasks layers, agent types, targeting, and injection
+overrides. The CLI is the config author (`oats init`, `oats use`, `oats type`,
+`oats inject eject`). **Load the `oats-config` skill for all configuration
+work** — this skill covers operating, not configuring.
+
+## Commands and doctor
+
+Operational namespaces run only when their package is active in the current
+context/instance:
+
+```bash
+oats okf harvest
+oats linear issue list ...
+```
+
+Package-management commands remain global. Use doctor first when something is
+missing:
+
+```bash
+oats doctor [context] [--soul <name>] [--json]
+```
+
+It shows config chain, acquired/active packages, layer selection, target and
+settings provenance, requirements, trust, skill sources, instruction blocks,
+and—with `--soul`—final composed text.
+
+Infrastructure faults should be reported to the spawner/human, not repaired by
+an instance ad hoc.