babavoss 0.0.1 → 0.0.2

package/src/mcp/daemon.ts

@@ -0,0 +1,61 @@
+// The MCP server's way to the running voss: where it listens, its token, and
+// the API calls the tools need. The server is a client of the daemon only; it
+// never starts a baba of its own.
+import { join } from "node:path";
+import { realpath } from "node:fs/promises";
+import type { Project } from "../baba/project.ts";
+import type { Described } from "../baba/node.ts";
+import type { StateAnswer } from "../ecs/snapshot.ts";
+import { daemon as shellDaemon } from "../shell/client.ts";
+
+export class ApiError extends Error {
+  constructor(readonly code: string, msg: string) { super(msg); }
+}
+
+export interface Daemon {
+  base: string;
+  describe(since?: number, signal?: AbortSignal): Promise<Described>;
+  fire(name: string, args: unknown, key?: string): Promise<unknown>;
+  read(name: string, args: unknown): Promise<unknown>;
+  state(since?: number, signal?: AbortSignal): Promise<StateAnswer>;
+}
+
+/** The daemon's base URL: $VOSS_URL, else the way the shell finds it, through ROOT/address. */
+export async function findBase(rootDir: string): Promise<string | null> {
+  if (process.env.VOSS_URL) return process.env.VOSS_URL.replace(/\/+$/, "");
+  return (await shellDaemon(rootDir))?.base ?? null;
+}
+
+const same = async (a: string, b: string) => a === b || (await realpath(a).catch(() => a)) === (await realpath(b).catch(() => b));
+
+/** The daemon's state for `project`, or why there is none. */
+export async function daemonFor(project: Project, rootDir: string): Promise<Daemon> {
+  const base = await findBase(rootDir);
+  if (!base) throw new ApiError("down", "no running voss found: start `voss gui` or `voss service install`, or set VOSS_URL");
+  const token = process.env.VOSS_TOKEN ?? (await Bun.file(join(rootDir, "http-token")).text().catch(() => "")).trim();
+  if (!token) throw new ApiError("unauthorized", `no token in ${join(rootDir, "http-token")}`);
+  const headers = { authorization: `Bearer ${token}`, "content-type": "application/json" };
+  const name = encodeURIComponent(project.name);
+
+  const answer = async (r: Response) => {
+    const j = await r.json().catch(() => ({})) as { value?: unknown; error?: { code: string; message: string } };
+    if (!r.ok || j.error) throw new ApiError(j.error?.code ?? "failed", j.error?.message ?? r.statusText);
+    return j;
+  };
+  const post = async (path: string, body: unknown, signal?: AbortSignal) =>
+    (await answer(await fetch(`${base}/api/${path}`, { method: "POST", headers, body: JSON.stringify(body ?? {}), signal }))).value;
+
+  let known: { projects?: { name: string; dir: string }[] };
+  try { known = await answer(await fetch(`${base}/api/projects`, { headers, signal: AbortSignal.timeout(3000) })) as typeof known; }
+  catch (err) { throw err instanceof ApiError ? err : new ApiError("down", `voss at ${base} does not answer: ${err instanceof Error ? err.message : String(err)}`); }
+  const entry = known.projects?.find((p) => p.name === project.name);
+  if (!entry || !(await same(entry.dir, project.dir))) throw new ApiError("noproject", `voss at ${base} does not run ${project.name} from ${project.dir}`);
+
+  return {
+    base,
+    describe: async (since = 0, signal) => await answer(await fetch(`${base}/api/describe/${name}${since ? `?since=${since}` : ""}`, { headers, signal })) as unknown as Described,
+    fire: (n, args, key) => post(`fire/${name}/${encodeURIComponent(n)}${key ? `?key=${encodeURIComponent(key)}` : ""}`, args),
+    read: (n, args) => post(`read/${name}/${encodeURIComponent(n)}`, args),
+    state: (since = 0, signal) => post(`state/${name}`, { since }, signal) as Promise<StateAnswer>,
+  };
+}

package/src/mcp/main.ts

@@ -0,0 +1,208 @@
+// `voss baba mcp`: the baba as an MCP server over stdio, a client of the
+// running voss. By default six fixed tools, the CLI's operations over the one
+// core (door/core.ts): `manifest` teaches the contract, `call` and `read` use
+// it, `follow`, `watch` and `state` read the state. With VOSS_MCP_TOOLS=1,
+// one tool per action and query too. Resources are the baba's context and the
+// answers over the budget; prompts are the skills. A reload in the daemon
+// refreshes them and tells the client.
+import { join, basename } from "node:path";
+import { readFile } from "node:fs/promises";
+import type { Project } from "../baba/project.ts";
+import { defaultHarness, type Manifest } from "../ecs/baba.ts";
+import { readManifest } from "../baba/node.ts";
+import { serveRpc, RpcError, NO_METHOD, PARAMS } from "./rpc.ts";
+import { daemonFor, type Daemon } from "./daemon.ts";
+import { follow as whole } from "../ecs/snapshot.ts";
+import { toolsOf, callName, promptsOf, promptText, type Tools } from "./tools.ts";
+import { BUDGET, DoorError, budget, errorOf, index, schemaOf, followEntity, watchQuery, stateOf, untilOf, byKey, isTruncated, type Outcome } from "../door/core.ts";
+
+const VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
+const empty: Manifest = { systems: [], promptware: { context: null, skills: {}, hooks: [] }, harness: defaultHarness, components: {}, resources: {}, effects: {}, actions: {}, queries: {}, tick: null };
+
+const log = (l: string) => process.stderr.write(`voss mcp: ${l}\n`);
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+type O = Record<string, unknown>;
+
+export async function runMcp(project: Project, rootDir: string): Promise<number> {
+  let daemon: Daemon;
+  try { daemon = await daemonFor(project, rootDir); }
+  catch (err) { log(err instanceof Error ? err.message : String(err)); return 1; }
+  const version = ((await import("../../package.json")) as { version: string }).version;
+  const perCall = process.env.VOSS_MCP_TOOLS === "1";
+
+  let gen = 0;
+  let m: Manifest = empty;
+  let down: string | null = null;
+  let loadError: string | null = null;
+  let tools: Tools = toolsOf(m, { perCall });
+  // Down, the contract is the one the last load wrote, as the CLI's is.
+  const take = async (d: { gen: number; manifest: Manifest | null; error: string | null }) => {
+    gen = d.gen;
+    m = d.manifest ?? (await readManifest(project)) ?? empty;
+    loadError = d.error;
+    down = d.manifest ? null : `${project.name} is not running${d.error ? `: ${d.error}` : ""}`;
+    tools = toolsOf(m, { perCall });
+  };
+  await take(await daemon.describe());
+  if (down) log(down);
+
+  // Answers over the budget, kept for this session as resources.
+  const outDir = join(project.baba, ".voss", "out");
+  const outs = new Map<string, string>();
+
+  const peer = serveRpc(Bun.stdin.stream(), (l) => { process.stdout.write(l); }, handle);
+
+  /** A marker of an answer over the budget, kept as a resource. */
+  const keep = (t: { path: string }): string => {
+    const file = basename(t.path);
+    outs.set(file, t.path);
+    peer.notify("notifications/resources/list_changed");
+    return `baba://out/${file}`;
+  };
+
+  /** A value as a tool's answer, within the budget; `isError` for a wait that did not hold. */
+  function answer(tool: string, value: unknown, structured: boolean, isError = false): O {
+    if (Array.isArray(value) && isTruncated(value.at(-1))) {
+      const t = value.at(-1) as { path: string };
+      value = [...value.slice(0, -1), { ...t, resource: keep(t) }];
+    }
+    const v = budget(value, { limit: BUDGET, dir: outDir, name: tool });
+    if (isTruncated(v)) return { content: [{ type: "text", text: JSON.stringify({ ...v, resource: keep(v) }) }], ...(isError ? { isError } : {}) };
+    return {
+      content: [{ type: "text", text: JSON.stringify(v ?? null) }],
+      ...(structured && typeof v === "object" && v !== null && !Array.isArray(v) ? { structuredContent: v } : {}),
+      ...(isError ? { isError } : {}),
+    };
+  }
+  const waited = (tool: string, r: Outcome) => answer(tool, r.value, true, r.outcome !== "held");
+  const failed = (err: unknown): O => ({ content: [{ type: "text", text: JSON.stringify({ error: errorOf(err) }) }], isError: true });
+
+  const secs = (a: O) => typeof a.for === "number" && a.for >= 0 ? 1000 * Math.min(a.for, 600) : undefined;
+  const str = (v: unknown) => typeof v === "string" && v ? v : undefined;
+  const live = () => { if (down) throw new DoorError("down", down); };
+
+  async function call(name: string, a: O): Promise<O> {
+    try {
+      if (name === "manifest") {
+        const n = str(a.name);
+        if (n) {
+          const c = callName(m, n);
+          const v = c && schemaOf(m, c.name);
+          if (!v) throw new DoorError("noaction", `no action or query ${n}`);
+          return answer(name, v, true);
+        }
+        const v = index(m, { via: down ? "down" : daemon.base, gen, error: loadError });
+        const system = str(a.system);
+        return answer(name, system ? { ...v, calls: v.calls.filter((c) => c.system === system) } : v, true);
+      }
+      live();
+      if (name === "follow") {
+        let e = a.entity;
+        if (e === undefined && str(a.component) && (typeof a.key === "string" || typeof a.key === "number")) e = byKey(whole(null, await daemon.state(-1)), m, a.component as string, a.key);
+        if (typeof e !== "number" || !Number.isInteger(e)) throw new DoorError("args", "follow takes an entity, a whole number, or a component and its key");
+        const until = str(a.until) ? untilOf(m, a.until as string) : null;
+        return waited(name, await followEntity(daemon, e, { until, for: secs(a) }));
+      }
+      if (name === "watch") {
+        const n = str(a.name) ?? str(a.query);
+        const q = n ? callName(m, n) : null;
+        if (!q || q.kind !== "query") throw new DoorError("noquery", `no query ${String(n)}; queries: ${Object.keys(m.queries).join(", ")}`);
+        return waited(name, await watchQuery(daemon, q.name, a.args ?? {}, { for: secs(a) }));
+      }
+      if (name === "state") {
+        const r = await stateOf(daemon, m, {
+          component: str(a.component),
+          entity: typeof a.entity === "number" ? a.entity : undefined,
+          key: typeof a.key === "string" || typeof a.key === "number" ? a.key : undefined,
+          where: typeof a.where === "object" && a.where !== null ? a.where as O : undefined,
+          limit: typeof a.limit === "number" && a.limit > 0 ? a.limit : undefined,
+          all: a.all === true, deep: a.deep === true, dir: outDir,
+        });
+        return waited(name, r);
+      }
+      if (name === "call" || name === "read") {
+        const n = String(a.name ?? "");
+        const c = callName(m, n);
+        if (!c) throw new DoorError(name === "read" ? "noquery" : "noaction", `no ${name === "read" ? "query" : "action or query"} ${n}; \`manifest\` lists them`);
+        if (name === "read" && c.kind !== "query") throw new DoorError("noquery", `${n} is an action; \`call\` fires it`);
+        const args = a.args ?? {};
+        const v = c.kind === "query" ? await daemon.read(c.name, args) : await daemon.fire(c.name, args, str(a.key));
+        return answer(name, v, false);
+      }
+      const t = tools.targets.get(name);
+      if (!t) throw new DoorError("noaction", `no tool ${name}; tools/list names them`);
+      // `_key` on an action's tool is the idempotency key, not an arg.
+      const { _key, ...rest } = a as { _key?: unknown } & O;
+      const v = t.kind === "action" ? await daemon.fire(t.name, rest, typeof _key === "string" ? _key : undefined) : await daemon.read(t.name, rest);
+      return answer(name, v, true);
+    } catch (err) {
+      return failed(err);
+    }
+  }
+
+  async function handle(method: string, p: O): Promise<unknown> {
+    switch (method) {
+      case "initialize": {
+        const asked = typeof p.protocolVersion === "string" && VERSIONS.includes(p.protocolVersion) ? p.protocolVersion : VERSIONS[0];
+        return {
+          protocolVersion: asked,
+          capabilities: { tools: { listChanged: perCall }, resources: { listChanged: true }, prompts: {} },
+          serverInfo: { name: project.name, version },
+          instructions: `${project.title}: the baba of ${project.dir}. \`manifest\` lists every call with an example; \`manifest\` with a name gives its schemas. \`call\` fires an action or reads a query by name, \`read\` reads a query; an action that starts work answers an entity to give \`follow\`. \`watch\` waits for a query's answer to change, \`state\` reads the state.`,
+        };
+      }
+      case "ping": return {};
+      case "tools/list": return { tools: tools.tools };
+      case "tools/call": {
+        if (typeof p.name !== "string") throw new RpcError(PARAMS, "tools/call takes a name");
+        return call(p.name, (typeof p.arguments === "object" && p.arguments !== null ? p.arguments : {}) as O);
+      }
+      case "resources/list": return {
+        resources: [
+          ...(m.promptware.context ? [{ uri: "baba://context", name: "context", description: "what the baba tells agents", mimeType: "text/markdown" }] : []),
+          ...[...outs.keys()].map((f) => ({ uri: `baba://out/${f}`, name: f, description: "an answer over the output budget", mimeType: "application/json" })),
+        ],
+      };
+      case "resources/read": {
+        const uri = String(p.uri ?? "");
+        const context = uri === "baba://context" ? m.promptware.context : null;
+        if (context) return { contents: [{ uri, mimeType: "text/markdown", text: context }] };
+        const out = uri.startsWith("baba://out/") ? outs.get(basename(uri.slice(11))) : undefined;
+        if (out) return { contents: [{ uri, mimeType: "application/json", text: await readFile(out, "utf8") }] };
+        throw new RpcError(-32002, `no resource ${uri}`, { uri });
+      }
+      case "resources/templates/list": return { resourceTemplates: [] };
+      case "prompts/list": return { prompts: promptsOf(m).map(({ name, description }) => ({ name, description })) };
+      case "prompts/get": {
+        const pr = promptsOf(m).find((x) => x.name === p.name);
+        const text = pr && promptText(m, pr.skill, tools.generic);
+        if (!pr || !text) throw new RpcError(PARAMS, `no prompt ${String(p.name)}`);
+        return { description: pr.description, messages: [{ role: "user", content: { type: "text", text } }] };
+      }
+    }
+    throw new RpcError(NO_METHOD, `no method ${method}`);
+  }
+
+  // Reload: the daemon answers describe past a generation when it moves, or after a while as it is.
+  const stop = new AbortController();
+  void (async () => {
+    while (!stop.signal.aborted) {
+      try {
+        const asked = Date.now();
+        const d = await daemon.describe(gen, stop.signal);
+        if (d.gen === gen) { if (Date.now() - asked < 1000) await sleep(1000); continue; }
+        await take(d);
+        log(`generation ${gen}${down ? `: ${down}` : ""}`);
+        // The six never change; only the per-call list does.
+        if (perCall) peer.notify("notifications/tools/list_changed");
+        peer.notify("notifications/resources/list_changed");
+      } catch {
+        if (!stop.signal.aborted) await sleep(2000);
+      }
+    }
+  })();
+
+  await peer.done;
+  stop.abort();
+  return 0;
+}

package/src/mcp/rpc.ts

@@ -0,0 +1,64 @@
+// JSON-RPC 2.0 as stdio MCP speaks it: one JSON object per line, both ways.
+// A request gets one answer, in any order; a notification gets none. The
+// handler throws an RpcError for a protocol error; anything else it throws
+// is an internal error.
+
+export class RpcError extends Error {
+  constructor(readonly code: number, msg: string, readonly data?: unknown) { super(msg); }
+}
+
+export const PARSE = -32700, INVALID = -32600, NO_METHOD = -32601, PARAMS = -32602, INTERNAL = -32603;
+
+type Id = string | number | null;
+export type Handler = (method: string, params: Record<string, unknown>) => Promise<unknown>;
+
+export interface Peer {
+  /** A notification to the client. */
+  notify(method: string, params?: Record<string, unknown>): void;
+  /** Resolves when the input closes and every request is answered. */
+  done: Promise<void>;
+}
+
+/** Reads lines from `input`, answers each through `write`, one line each. */
+export function serveRpc(input: ReadableStream<Uint8Array>, write: (line: string) => void, handle: Handler, notified: (method: string, params: Record<string, unknown>) => void = () => {}): Peer {
+  const send = (o: unknown) => write(JSON.stringify(o) + "\n");
+  const error = (id: Id, code: number, message: string, data?: unknown) => send({ jsonrpc: "2.0", id, error: { code, message, ...(data === undefined ? {} : { data }) } });
+  const pending = new Set<Promise<void>>();
+
+  function one(msg: unknown): void {
+    if (typeof msg !== "object" || msg === null || Array.isArray(msg)) { error(null, INVALID, "not a request"); return; }
+    const m = msg as { jsonrpc?: unknown; id?: Id; method?: unknown; params?: unknown };
+    if (m.method === undefined && ("result" in m || "error" in m)) return;   // an answer to us: we ask nothing
+    const isRequest = "id" in m;
+    if (m.jsonrpc !== "2.0" || typeof m.method !== "string") { if (isRequest) error(m.id ?? null, INVALID, "not a JSON-RPC 2.0 request"); return; }
+    const params = (typeof m.params === "object" && m.params !== null ? m.params : {}) as Record<string, unknown>;
+    if (!isRequest) { notified(m.method, params); return; }
+    const id = m.id as Id;
+    const p = handle(m.method, params)
+      .then((result) => send({ jsonrpc: "2.0", id, result: result ?? {} }))
+      .catch((err) => err instanceof RpcError ? error(id, err.code, err.message, err.data) : error(id, INTERNAL, err instanceof Error ? err.message : String(err)))
+      .finally(() => pending.delete(p));
+    pending.add(p);
+  }
+
+  const done = (async () => {
+    const decoder = new TextDecoder();
+    let buf = "";
+    const line = (l: string) => {
+      if (!l.trim()) return;
+      let msg: unknown;
+      try { msg = JSON.parse(l); } catch { error(null, PARSE, "not JSON"); return; }
+      if (Array.isArray(msg)) { for (const x of msg) one(x); return; }
+      one(msg);
+    };
+    for await (const chunk of input) {
+      buf += decoder.decode(chunk, { stream: true });
+      let nl: number;
+      while ((nl = buf.indexOf("\n")) >= 0) { line(buf.slice(0, nl)); buf = buf.slice(nl + 1); }
+    }
+    line(buf + decoder.decode());
+    while (pending.size) await Promise.all([...pending]);
+  })();
+
+  return { notify: (method, params) => send({ jsonrpc: "2.0", method, ...(params ? { params } : {}) }), done };
+}

package/src/mcp/tools.ts

@@ -0,0 +1,125 @@
+// The contract as MCP tools. Pure: a manifest in, the tool list out. By
+// default six fixed tools, the same operations the CLI has over the one core
+// (door/core.ts): `manifest`, `call`, `read`, `follow`, `watch`, `state`. The
+// contract is not in the tool list, since harnesses do not reliably pick up a
+// changed one; `manifest` teaches it. With VOSS_MCP_TOOLS=1, one tool per
+// action and query too, `<system>_<name>`, with its summary and schemas.
+import type { Manifest } from "../ecs/baba.ts";
+
+/** A JSON Schema, as the manifest carries it. */
+type Obj = Record<string, unknown>;
+
+export interface Tool { name: string; description: string; inputSchema: Obj; outputSchema?: Obj }
+
+/** What a per-call tool stands for. */
+export interface Target { kind: "action" | "query"; name: string; system: string }
+
+export interface Tools { tools: Tool[]; targets: Map<string, Target>; generic: boolean }
+
+/** The promptware's threshold for describing the contract as `call`/`read`; the server itself is generic unless VOSS_MCP_TOOLS=1. */
+
+/** How an agent learns the contract: said in every tool that takes a call's name. */
+const LEARN = "`manifest` lists every call with an example; `manifest` with a name gives its schemas.";
+
+/** `<system>_<name>`; a name that already starts with its system's, as voss's own do (`promptware-sync`), is not prefixed twice: `promptware_sync`. */
+export const toolName = (system: string, name: string) => name.startsWith(`${system}-`) ? `${system}_${name.slice(system.length + 1)}` : `${system}_${name}`;
+
+const isObj = (v: unknown): v is Obj => typeof v === "object" && v !== null && !Array.isArray(v);
+
+/** An args schema as MCP takes it: always an object schema. */
+function objectSchema(j: unknown): Obj {
+  if (isObj(j) && j.type === "object") return j;
+  if (isObj(j) && j.type === undefined && isObj(j.properties)) return { ...j, type: "object" };
+  return { type: "object", properties: {} };
+}
+
+/** An action's tool also takes `_key`: an idempotency key, so a retry answers the same. */
+const withKey = (j: Obj): Obj => ({ ...j, properties: { ...(isObj(j.properties) ? j.properties : {}), _key: { type: "string", description: "an idempotency key: a retry with the same key answers the same" } } });
+
+const forSecs: Obj = { type: "number", minimum: 0, maximum: 600, description: "seconds to wait at most; 30 by default" };
+
+/** The six: the same operations as the CLI's, whatever the baba declares. */
+export const genericTools: Tool[] = [
+  {
+    name: "manifest",
+    description: `The contract. With nothing, the index: every action and query with its kind, system, summary and an example to copy, the components with their key fields, the resources, where the state is. \`system\` narrows the calls; \`name\` answers that one call's args and result schemas and its example. ${LEARN}`,
+    inputSchema: { type: "object", properties: { system: { type: "string" }, name: { type: "string" } }, additionalProperties: false },
+  },
+  {
+    name: "call",
+    description: `Call an action by name with its args (a query's name reads it). A \`key\` makes a retry answer the same. An action that starts work answers the entity to \`follow\`. ${LEARN}`,
+    inputSchema: { type: "object", properties: { name: { type: "string" }, args: { type: "object" }, key: { type: "string", description: "an idempotency key: a retry with the same key answers the same" } }, required: ["name"], additionalProperties: false },
+  },
+  {
+    name: "read",
+    description: `Read a query by name with its args. ${LEARN}`,
+    inputSchema: { type: "object", properties: { name: { type: "string" }, args: { type: "object" } }, required: ["name"], additionalProperties: false },
+  },
+  {
+    name: "follow",
+    description: "Wait on an entity, by `entity` or by `component` and its `key`, and answer its row: until it has COMPONENT, or COMPONENT.field=value holds, or (without `until`) until no job runs for it and the state has moved past it; bounded by `for`. A timed-out answer carries `timedOut`, a gone entity `gone`; both are errors.",
+    inputSchema: { type: "object", properties: { entity: { type: "integer", minimum: 1, description: "an entity" }, component: { type: "string", description: "with key: a component with a key field" }, key: { type: ["string", "number"], description: "the entity whose component's key field is this" }, until: { type: "string", description: "COMPONENT, or COMPONENT.field=value" }, for: forSecs }, additionalProperties: false },
+  },
+  {
+    name: "watch",
+    description: `Read a query, then wait until its answer differs from that first read, bounded by \`for\`; answers {value}, or {value, timedOut: true} with the last read. ${LEARN}`,
+    inputSchema: { type: "object", properties: { name: { type: "string", description: "the query's name" }, args: { type: "object", description: "the query's args" }, for: forSecs }, required: ["name"], additionalProperties: false },
+  },
+  {
+    name: "state",
+    description: "Read the state. With nothing, a summary: entities per component, the resources, jobs per status, the round; `all` the whole of it. With `entity`, that entity; with `component`, its rows filtered by `where` (field: value), at most `limit`, or with `key` the one whose key field it is; a resource's name as `component` answers its value.",
+    inputSchema: { type: "object", properties: { component: { type: "string" }, entity: { type: "integer", minimum: 1 }, key: { type: ["string", "number"] }, where: { type: "object", additionalProperties: true }, limit: { type: "integer", minimum: 1, description: "100 by default" }, all: { type: "boolean" }, deep: { type: "boolean", description: "entity refs expanded into their rows" } }, additionalProperties: false },
+  },
+];
+
+/** Every action and query, in manifest order. */
+export function calls(m: Manifest): (Target & { summary: string; args: Obj; result: Obj })[] {
+  return [
+    ...Object.entries(m.actions).map(([name, c]) => ({ kind: "action" as const, name, system: c.owner, summary: c.summary, args: c.args, result: c.result })),
+    ...Object.entries(m.queries).map(([name, c]) => ({ kind: "query" as const, name, system: c.owner, summary: c.summary, args: c.args, result: c.result })),
+  ];
+}
+
+/** The six, and with `perCall` one tool per action and query before them. */
+export function toolsOf(m: Manifest, opts: { perCall?: boolean } = {}): Tools {
+  const generic = opts.perCall !== true;
+  const targets = new Map<string, Target>();
+  if (generic) return { tools: genericTools, targets, generic };
+  const all = calls(m);
+  const tools: Tool[] = all.map((c) => {
+    const name = toolName(c.system, c.name);
+    targets.set(name, { kind: c.kind, name: c.name, system: c.system });
+    return {
+      name,
+      description: c.summary || `${c.kind} of ${c.system}`,
+      inputSchema: c.kind === "action" ? withKey(objectSchema(c.args)) : objectSchema(c.args),
+      ...(isObj(c.result) && c.result.type === "object" ? { outputSchema: c.result } : {}),
+    };
+  });
+  return { tools: [...tools, ...genericTools], targets, generic };
+}
+
+/** An action's or query's name from itself or its per-call tool's name. */
+export function callName(m: Manifest, n: string): { kind: "action" | "query"; name: string } | null {
+  for (const c of calls(m)) if (c.name === n || toolName(c.system, c.name) === n) return { kind: c.kind, name: c.name };
+  return null;
+}
+
+/** One prompt per skill, by its name. */
+export function promptsOf(m: Manifest): { name: string; description: string; skill: string }[] {
+  return Object.entries(m.promptware.skills).map(([k, sk]) => ({ name: k, description: sk.description, skill: k }));
+}
+
+/** A skill's prompt text: its body, then the tools it uses. */
+export function promptText(m: Manifest, skill: string, generic: boolean): string | null {
+  const sk = m.promptware.skills[skill];
+  if (!sk) return null;
+  const uses = (sk.uses ?? []).map((n) => {
+    const c = m.actions[n] ?? m.queries[n];
+    if (!c) return `- ${n}`;
+    const kind = n in m.actions ? "action" : "query";
+    const tool = generic ? `${kind === "query" ? "read" : "call"} {"name":"${n}"}` : toolName(c.owner, n);
+    return `- ${tool}: ${c.summary || `${kind} of ${c.owner}`}`;
+  });
+  return uses.length ? `${sk.body.trimEnd()}\n\nCalls:\n${uses.join("\n")}\n` : sk.body;
+}

package/src/prompt/evals.ts

@@ -0,0 +1,42 @@
+// The golden interpretation of a piece of promptware: situations a fresh
+// reader must decide from the text alone. Authored as givens, each with the
+// cases under it: when (the moment of decision) and then (the right move, a
+// few words). A situation the text never mentions, decided by what the text
+// conveys, is the point: the text gives the principle, the cases sample what
+// follows from it. Owned by the author through git; the trials system scores
+// readers against it and never writes it. Under the hood each case is one
+// flat record, given carried along, so the reader and the judge see one list.
+export interface InterpretationCase { id: string; when: string; then: string }
+export interface InterpretationGiven { given: string; cases: InterpretationCase[] }
+export interface InterpretationQuestion { id: string; given: string; when: string; then: string }
+export interface InterpretationSuite { questions: InterpretationQuestion[] }
+
+/** Givens with their cases, flattened: one record per case, in order. */
+export function interpretation(givens: InterpretationGiven[]): InterpretationSuite {
+  const questions: InterpretationQuestion[] = [];
+  const ids = new Set<string>();
+  for (const g of givens) {
+    if (!g.given.trim()) throw new Error("interpretation: a given is empty");
+    if (!g.cases.length) throw new Error(`interpretation: no cases under ${JSON.stringify(g.given)}`);
+    for (const c of g.cases) {
+      if (!/^[a-z][a-z0-9-]*$/.test(c.id)) throw new Error(`interpretation: an id is lowercase words joined by dashes: ${JSON.stringify(c.id)}`);
+      if (ids.has(c.id)) throw new Error(`interpretation: two cases are named ${c.id}`);
+      ids.add(c.id);
+      if (!c.when.trim() || !c.then.trim()) throw new Error(`interpretation ${c.id}: a when and a then`);
+      questions.push({ id: c.id, given: g.given.trim(), when: c.when.trim(), then: c.then.trim() });
+    }
+  }
+  if (!questions.length) throw new Error("interpretation: at least one situation");
+  return { questions };
+}
+
+/** The flat records back as givens with their cases, consecutive records of one given together: how a surface draws them. */
+export function givensOf(questions: readonly InterpretationQuestion[]): InterpretationGiven[] {
+  const out: InterpretationGiven[] = [];
+  for (const q of questions) {
+    const last = out[out.length - 1];
+    if (last && last.given === q.given) last.cases.push({ id: q.id, when: q.when, then: q.then });
+    else out.push({ given: q.given, cases: [{ id: q.id, when: q.when, then: q.then }] });
+  }
+  return out;
+}