babavoss 0.0.1 → 0.0.2

package/src/door/core.ts

@@ -0,0 +1,384 @@
+// The one core both doors stand on: the CLI and the MCP server are
+// projections of it, so the contract never lives in a door's own shape. The
+// index and a call's schemas, read from the manifest; follow, watch and state
+// over a small Api both doors' clients satisfy; the output budget; the closed
+// set of error codes and the one error object. Pure where it can be; the rest
+// reads the state through the Api and writes an over-budget answer to a file.
+import { join } from "node:path";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import type { Manifest, Call } from "../ecs/baba.ts";
+import type { Snapshot } from "../ecs/state.ts";
+import { follow, type StateAnswer } from "../ecs/snapshot.ts";
+import type { Json } from "../kernel/schema.ts";
+import { exampleOf, keyField } from "../ecs/handles.ts";
+
+type O = Record<string, unknown>;
+
+/** The state as a door reaches it: the shell's client and the MCP server's daemon client both are one. */
+export interface Api {
+  describe(): Promise<unknown>;
+  /** An action; `key` is its idempotency key. */
+  fire(name: string, args: unknown, key?: string): Promise<unknown>;
+  read(name: string, args: unknown): Promise<unknown>;
+  /** The state since round `since`, once a round past it has run or after the daemon's wait: a delta, or the whole for -1; `signal` cuts it short. */
+  state(since: number, signal?: AbortSignal): Promise<StateAnswer>;
+}
+
+// ---- errors -----------------------------------------------------------------
+
+/** The closed set of codes, each with whether the same call may succeed if tried again. The shell adds an exit status to each. */
+export const CODES = {
+  failed: false, result: false, down: true, busy: true, timeout: true, unknown: true,
+  usage: false, args: false, noaction: false, noquery: false, name: false, owner: false, noproject: false,
+  entity: false, gone: false, nokey: false,
+} as const satisfies Record<string, boolean>;
+export type Code = keyof typeof CODES;
+
+/** Codes from elsewhere that mean one of ours. */
+const ALIAS: Record<string, Code> = { value: "args", notool: "noaction", notfound: "failed", load: "failed", unauthorized: "down" };
+
+export const codeOf = (code: string): Code => code in CODES ? code as Code : ALIAS[code] ?? "failed";
+
+/** An error of the set, with the call's usage line or its idempotency key when they help. */
+export class DoorError extends Error {
+  constructor(readonly code: Code, msg: string, readonly extra: { usage?: string; key?: string } = {}) { super(msg); }
+}
+
+export interface ErrorBody { code: Code; message: string; usage?: string; retry: boolean; key?: string }
+/** The one error object both doors answer. */
+export interface Failure { error: ErrorBody }
+
+export function failure(code: string, message: string, extra: { usage?: string; key?: string } = {}): Failure {
+  const c = codeOf(code);
+  return { error: { code: c, message, ...(extra.usage && (c === "args" || c === "usage") ? { usage: extra.usage } : {}), retry: CODES[c], ...(extra.key ? { key: extra.key } : {}) } };
+}
+
+/** Anything thrown, as the error body: a DoorError's code, any other error's `code` mapped into the set, else failed. */
+export function errorOf(err: unknown): ErrorBody {
+  const message = err instanceof Error ? err.message : String(err);
+  if (err instanceof DoorError) return failure(err.code, message, err.extra).error;
+  const e = err as { code?: unknown; key?: unknown } | null;
+  const code = typeof e?.code === "string" ? e.code : "failed";
+  return failure(code, message, typeof e?.key === "string" ? { key: e.key } : {}).error;
+}
+
+// ---- the index and a call's schemas ---------------------------------------------
+
+export interface Example { cli: string; mcp: { name: string; args: unknown } }
+export interface IndexCall { name: string; kind: "action" | "query"; system: string; summary: string; example: Example }
+export interface Index {
+  via?: string;
+  round?: number;
+  gen?: number;
+  error?: string;
+  systems: { name: string }[];
+  /** What the baba tells agents: whether it has a context, and its skills by name. */
+  promptware: { context: boolean; skills: string[] };
+  calls: IndexCall[];
+  components: Record<string, { system: string; key?: string; accept?: true }>;
+  resources: string[];
+  counts: { systems: number; actions: number; queries: number; components: number; resources: number; effects: number };
+}
+export interface Schemas { name: string; kind: "action" | "query"; system: string; summary: string; args: Json; result: Json; positional?: string[]; example: Example }
+
+/** What the index carries beside the manifest: where the state is, its round and generation, the last load's error; `prog` spells the CLI ("voss baba"). */
+export interface IndexExtra { via?: string; round?: number; gen?: number; error?: string | null; prog?: string }
+
+const isObj = (v: unknown): v is O => typeof v === "object" && v !== null && !Array.isArray(v);
+const quote = (s: string) => `'${s.replace(/'/g, `'\\''`)}'`;
+
+/**
+ * A call to copy: the CLI as one JSON word, its secrets read from stdin
+ * (`--NAME @-`), never on the command line; the MCP as `call`'s arguments,
+ * a secret as the redaction mark to replace.
+ */
+export function exampleCall(name: string, c: Call, prog = "voss baba"): Example {
+  const ex = exampleOf(c.args);
+  const args = isObj(ex) ? ex : {};
+  const props = (c.args.properties ?? {}) as Record<string, Json>;
+  const secrets = Object.keys(args).filter((k) => props[k]?.format === "secret");
+  const word = Object.fromEntries(Object.entries(args).filter(([k]) => !secrets.includes(k)));
+  const cli = [prog, name, ...(Object.keys(word).length ? [quote(JSON.stringify(word))] : []), ...secrets.map((k) => `--${k} @-`)].join(" ");
+  return { cli, mcp: { name, args } };
+}
+
+const entries = (m: Manifest) => [
+  ...Object.entries(m.actions).map(([name, c]) => ({ name, kind: "action" as const, c })),
+  ...Object.entries(m.queries).map(([name, c]) => ({ name, kind: "query" as const, c })),
+];
+
+/** The index both doors answer: every call with an example, the components with their keys, the resources. */
+export function index(m: Manifest, extra: IndexExtra = {}): Index {
+  return {
+    ...(extra.via !== undefined ? { via: extra.via } : {}),
+    ...(extra.round !== undefined ? { round: extra.round } : {}),
+    ...(extra.gen !== undefined ? { gen: extra.gen } : {}),
+    ...(extra.error ? { error: extra.error } : {}),
+    systems: m.systems.map((c) => ({ name: c.name })),
+    promptware: { context: !!m.promptware.context, skills: Object.keys(m.promptware.skills) },
+    calls: entries(m).map(({ name, kind, c }) => ({ name, kind, system: c.owner, summary: c.summary, example: exampleCall(name, c, extra.prog) })),
+    components: Object.fromEntries(Object.entries(m.components).map(([n, c]) => {
+      const key = keyField(c.schema);
+      return [n, { system: c.owner, ...(key !== null ? { key } : {}), ...(c.accept ? { accept: true } : {}) }];
+    })),
+    resources: Object.keys(m.resources),
+    counts: { systems: m.systems.length, actions: Object.keys(m.actions).length, queries: Object.keys(m.queries).length, components: Object.keys(m.components).length, resources: Object.keys(m.resources).length, effects: Object.keys(m.effects).length },
+  };
+}
+
+/** One call's schemas and example, or null when there is no such action or query. */
+export function schemaOf(m: Manifest, name: string, prog?: string): Schemas | null {
+  const e = entries(m).find((x) => x.name === name);
+  if (!e) return null;
+  const { kind, c } = e;
+  return { name, kind, system: c.owner, summary: c.summary, args: c.args, result: c.result, ...(c.positional ? { positional: c.positional } : {}), example: exampleCall(name, c, prog) };
+}
+
+// ---- the state --------------------------------------------------------------
+
+/** How long follow and watch wait by default, in ms. */
+export const FOLLOW_MS = 30_000;
+/** No round for this long, and no job: the state is quiet, so nothing more is coming for the entity. */
+const QUIET_MS = 1_000;
+/** A follow's changes are told at most once per this. */
+const COALESCE_MS = 250;
+
+/** How a wait ended: the condition held, the time ran out (the last value with `timedOut`), or the entity is gone. */
+export interface Outcome { outcome: "held" | "timedOut" | "gone"; value: unknown }
+
+/** An entity as a row: its components (entity refs expanded when `deep`), its jobs, its last settlement. */
+export function rowOf(snap: Snapshot, m: Manifest | null, e: number, deep = false, seen = new Set<number>()): O | null {
+  const parts = snap.entities[String(e)];
+  if (!parts) return null;
+  seen.add(e);
+  const o: O = { entity: e };
+  for (const [n, v] of Object.entries(parts)) {
+    if (!deep || !m || typeof v !== "object" || v === null) { o[n] = v; continue; }
+    const props = (m.components[n]?.schema.properties ?? {}) as Record<string, Json>;
+    const copy: O = { ...(v as O) };
+    for (const [k, p] of Object.entries(props)) {
+      const id = copy[k];
+      if (p.description === "an entity" && typeof id === "number" && !seen.has(id) && snap.entities[String(id)]) copy[k] = rowOf(snap, m, id, true, new Set(seen));
+    }
+    o[n] = copy;
+  }
+  const jobs = snap.jobs.filter((j) => j.entity === e).map((j) => ({ effect: j.effect, status: j.status, ...(j.attempt ? { attempt: j.attempt } : {}), ...(j.error ? { error: j.error } : {}), ...(j.shape === "source" ? { source: true, phase: j.phase, events: j.events } : {}) }));
+  if (jobs.length) o.jobs = jobs;
+  const settled = snap.settled?.[String(e)];
+  if (settled) o.settled = settled;
+  return o;
+}
+
+/** A missing entity: one that was never made is not found (thrown); one that was is gone, with its last settlement. */
+export function missing(snap: Snapshot, e: number): O {
+  if (snap.next !== undefined && e >= snap.next) throw new DoorError("entity", `no entity ${e}; the state has made ${snap.next - 1}`);
+  return { entity: e, gone: true, ...(snap.settled?.[String(e)] ? { settled: snap.settled[String(e)] } : {}) };
+}
+
+/** The entity whose COMPONENT's key field is VALUE, in `snap`. */
+export function byKey(snap: Snapshot, m: Manifest, component: string, value: unknown): number {
+  const c = m.components[component];
+  if (!c) throw new DoorError("name", `no component ${component}; components: ${Object.keys(m.components).join(", ")}`);
+  const field = keyField(c.schema);
+  if (field === null) throw new DoorError("args", `${component} has no key field, so it is found by entity; state ${component} lists them`);
+  for (const [id, parts] of Object.entries(snap.entities)) {
+    const v = parts[component];
+    if (v === undefined) continue;
+    const key = field === "" ? v : (v as O | null)?.[field];
+    if (key !== undefined && String(key) === String(value)) return Number(id);
+  }
+  throw new DoorError("nokey", `no ${component} with ${field || "key"} ${String(value)}`);
+}
+
+/** A follow condition: COMPONENT, or COMPONENT.field=value. */
+export interface Until { component: string; field?: string; value?: string }
+
+/** COMPONENT or COMPONENT.field=value, parsed. */
+export function parseUntil(until: string): Until {
+  const dot = until.indexOf(".");
+  if (dot < 0) return { component: until };
+  const rest = until.slice(dot + 1);
+  const eq = rest.indexOf("=");
+  if (eq < 0) throw new DoorError("usage", `until takes COMPONENT or COMPONENT.field=value, got ${until}`);
+  return { component: until.slice(0, dot), field: rest.slice(0, eq), value: rest.slice(eq + 1) };
+}
+
+/** A condition parsed and its component checked against the manifest. */
+export function untilOf(m: Manifest, text: string): Until {
+  const u = parseUntil(text);
+  if (!(u.component in m.components)) throw new DoorError("name", `no component ${u.component}; components: ${Object.keys(m.components).join(", ")}`);
+  return u;
+}
+
+/** A field matches a value written as text: equal, or equal as JSON or as a string. */
+export const matches = (field: unknown, v: unknown) =>
+  field === v || (typeof v === "string" && (JSON.stringify(field) === v || String(field) === v)) || JSON.stringify(field) === JSON.stringify(v);
+
+/** A long-poll of the state past `since`, bounded by `ms`: null when no round came in time. */
+async function poll(api: Api, since: number, ms: number): Promise<StateAnswer | null> {
+  try { return await api.state(since, AbortSignal.timeout(Math.max(1, ms))); }
+  catch (err) {
+    const e = err as { name?: unknown; code?: unknown } | null;
+    if (e && (e.name === "TimeoutError" || e.name === "AbortError" || e.code === "timeout")) return null;
+    throw err;
+  }
+}
+
+export interface FollowOptions {
+  /** The condition; without one, until no job runs for it, a round boundary has passed (or a second of quiet), and two snapshots agree. */
+  until?: Until | null;
+  /** How long to wait at most, in ms; 30 s by default. */
+  for?: number;
+  /** Tell each change through `onChange`, at most one per 250 ms. */
+  changes?: boolean;
+  onChange?: (row: O) => void | Promise<void>;
+  /** Asked between polls: true ends the wait as timed out (an interrupt). */
+  stop?: () => boolean;
+}
+
+/** Waits on an entity until the condition holds, the time runs out, or it is gone. */
+export async function followEntity(api: Api, entity: number, o: FollowOptions = {}): Promise<Outcome> {
+  const until = o.until ?? null;
+  const deadline = Date.now() + (o.for ?? FOLLOW_MS);
+  let snap = follow(null, await api.state(-1));
+  const start = snap.round;
+  let lastRound = Date.now();
+  let boundary = false;
+  let prev: string | null = null;
+  let told: string | null = null;
+  let toldAt = 0;
+  let pending = false;
+  const changes = o.changes === true && !!o.onChange;
+  const tell = async (row: O) => { await o.onChange!(row); told = JSON.stringify(row); toldAt = Date.now(); pending = false; };
+  for (;;) {
+    const row = rowOf(snap, null, entity);
+    if (!row) return { outcome: "gone", value: missing(snap, entity) };
+    const text = JSON.stringify(row);
+    if (changes && text !== told) {
+      if (Date.now() - toldAt >= COALESCE_MS) await tell(row); else pending = true;
+    }
+    if (snap.round > start) boundary = true;
+    // A source's job runs for as long as the entity is watched: it is not work the entity waits on.
+    const busy = (row.jobs as { source?: boolean }[] | undefined)?.some((j) => !j.source) ?? false;
+    const holds = until
+      ? until.component in row && (until.field === undefined || matches((row[until.component] as O | undefined)?.[until.field], until.value))
+      : !busy && boundary && prev === text;
+    if (holds) return { outcome: "held", value: row };
+    prev = text;
+    const left = deadline - Date.now();
+    if (left <= 0 || o.stop?.()) return { outcome: "timedOut", value: { ...row, timedOut: true } };
+    let wait = left;
+    if (!until && !busy) wait = Math.min(wait, QUIET_MS);
+    if (pending) wait = Math.min(wait, Math.max(1, COALESCE_MS - (Date.now() - toldAt)));
+    const next = await poll(api, snap.round, wait);
+    if (next && next.round !== snap.round) lastRound = Date.now();
+    if (next) snap = follow(snap, next);
+    // No round for a while and no job: nothing is due, so nothing more can be scheduled for it.
+    else if (!until && !busy && Date.now() - lastRound >= QUIET_MS) boundary = true;
+    if (pending && Date.now() - toldAt >= COALESCE_MS) { const r = rowOf(snap, null, entity); if (r) await tell(r); }
+  }
+}
+
+/** Reads a query, then waits until its answer differs from that first read: {value}, or {value, timedOut} with the last read. */
+export async function watchQuery(api: Api, name: string, args: unknown, o: { for?: number; stop?: () => boolean } = {}): Promise<Outcome> {
+  const deadline = Date.now() + (o.for ?? FOLLOW_MS);
+  const first = await api.read(name, args);
+  const firstText = JSON.stringify(first);
+  let since = (await api.state(-1)).round;
+  let value = first;
+  for (;;) {
+    const left = deadline - Date.now();
+    if (left <= 0 || o.stop?.()) return { outcome: "timedOut", value: { value, timedOut: true } };
+    const snap = await poll(api, since, left);
+    if (!snap) continue;
+    since = snap.round;
+    value = await api.read(name, args);
+    if (JSON.stringify(value) !== firstText) return { outcome: "held", value: { value } };
+  }
+}
+
+export interface StateOptions {
+  /** A component (its rows) or a resource (its value). */
+  component?: string;
+  entity?: number;
+  /** With `component`: the entity whose key field is this. */
+  key?: unknown;
+  /** With `component`: field = value, every one to hold. */
+  where?: Record<string, unknown> | (readonly [string, unknown])[];
+  /** With `component`: at most this many rows, 100 by default, 0 for all; past it, the rest is spilled under `dir` (or cut) and a marker ends the list. */
+  limit?: number;
+  /** The whole state: resources, every entity, the jobs. */
+  all?: boolean;
+  /** Entity refs in a row expanded into their rows. */
+  deep?: boolean;
+  /** Where rows past the limit go. */
+  dir?: string;
+}
+
+/** Reads the state: a summary, all of it, an entity, a component's rows, an entity by key, or a resource's value. */
+export async function stateOf(api: Api, m: Manifest, o: StateOptions = {}): Promise<Outcome> {
+  const snap = follow(null, await api.state(-1));
+  const row = (e: number) => rowOf(snap, m, e, o.deep === true)!;
+  if (o.entity !== undefined) {
+    if (!snap.entities[String(o.entity)]) return { outcome: "gone", value: missing(snap, o.entity) };
+    return { outcome: "held", value: row(o.entity) };
+  }
+  const c = o.component;
+  if (c === undefined || c === "") {
+    if (o.all) return { outcome: "held", value: { round: snap.round, resources: snap.resources, entities: Object.keys(snap.entities).map((id) => row(Number(id))), jobs: snap.jobs } };
+    const components: Record<string, number> = Object.fromEntries(Object.keys(m.components).map((n) => [n, 0]));
+    for (const parts of Object.values(snap.entities)) for (const n of Object.keys(parts)) components[n] = (components[n] ?? 0) + 1;
+    const jobs: Record<string, number> = {};
+    for (const j of snap.jobs) jobs[j.status] = (jobs[j.status] ?? 0) + 1;
+    return { outcome: "held", value: { round: snap.round, entities: Object.keys(snap.entities).length, components, resources: Object.keys(snap.resources), jobs } };
+  }
+  if (c in snap.resources && !(c in m.components)) return { outcome: "held", value: snap.resources[c] };
+  if (!(c in m.components)) throw new DoorError("name", `no component or resource ${c}; components: ${Object.keys(m.components).join(", ")}`);
+  if (o.key !== undefined) return { outcome: "held", value: row(byKey(snap, m, c, o.key)) };
+  const conds = Array.isArray(o.where) ? o.where : Object.entries(o.where ?? {});
+  const limit = o.limit ?? 100;
+  if (!Number.isInteger(limit) || limit < 0) throw new DoorError("usage", `limit takes a whole number, got ${String(o.limit)}`);
+  const rows = Object.entries(snap.entities)
+    .filter(([, parts]) => c in parts && conds.every(([k, v]) => matches((parts[c] as O | null)?.[k], v)))
+    .map(([id]) => row(Number(id)));
+  if (limit === 0 || rows.length <= limit) return { outcome: "held", value: rows };
+  const marker: O = o.dir ? (({ head: _, ...rest }) => rest)(spill(o.dir, `state-${c}`, rows)) : { truncated: true, count: rows.length };
+  return { outcome: "held", value: [...rows.slice(0, limit), marker] };
+}
+
+// ---- the output budget ----------------------------------------------------------
+
+/** The default budget, in characters of JSON. */
+export const BUDGET = 20_000;
+const HEAD = 2_000;
+
+export interface Truncated { truncated: true; bytes: number; count?: number; path: string; head: unknown }
+
+/** The value's first items (an array) or first 2000 characters of its JSON. */
+function headOf(value: unknown, text: string): unknown {
+  if (!Array.isArray(value)) return text.slice(0, HEAD);
+  const items: unknown[] = [];
+  let size = 2;
+  for (const x of value) { size += JSON.stringify(x ?? null).length + 1; if (size > HEAD && items.length) break; items.push(x); if (size > HEAD) break; }
+  return items;
+}
+
+/** Writes `value` whole to `<dir>/<timestamp>-<name>.json`, at once, so the answer that names it never comes before it; answers its marker. */
+export function spill(dir: string, name: string, value: unknown, text = JSON.stringify(value ?? null)): Truncated {
+  const stem = `${new Date().toISOString().replace(/[:.]/g, "-")}-${name.replace(/[^\w.-]+/g, "_") || "answer"}`;
+  mkdirSync(dir, { recursive: true });
+  let path = join(dir, `${stem}.json`);
+  for (let n = 2; existsSync(path); n++) path = join(dir, `${stem}-${n}.json`);
+  writeFileSync(path, text);
+  return { truncated: true, bytes: Buffer.byteLength(text), ...(Array.isArray(value) ? { count: value.length } : {}), path, head: headOf(value, text) };
+}
+
+/** `value` within `limit` characters of JSON, or its marker, the whole written under `dir`; `limit` 0 is no budget, and so is a missing `dir`. */
+export function budget(value: unknown, o: { limit: number; dir?: string; name: string }): unknown {
+  if (!o.dir || o.limit <= 0) return value;
+  const text = JSON.stringify(value ?? null);
+  return text.length <= o.limit ? value : spill(o.dir, o.name, value, text);
+}
+
+/** Whether a value is a budget's marker. */
+export const isTruncated = (v: unknown): v is Truncated => isObj(v) && v.truncated === true && typeof v.path === "string";