@agentproto/agent-runtime 0.1.0-alpha.0

package/dist/adapters/state-fs.mjs

@@ -0,0 +1,54 @@
+import { readFile, writeFile, stat, mkdir } from 'fs/promises';
+import { resolve } from 'path';
+
+/**
+ * @agentproto/agent-runtime v0.1.0-alpha
+ * MultiAgentRuntime kernel — swappable ports + reference adapters
+ * (file substrate, mention dispatcher, fs state, agent-cli participant).
+ * Transport-specific adapters ship in separate packages.
+ */
+
+var FileStateStore = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  opts;
+  kind = "fs";
+  async read(participantId) {
+    const path = this.pathFor(participantId);
+    try {
+      const raw = await readFile(path, "utf8");
+      return JSON.parse(raw);
+    } catch (err) {
+      if (isNotFound(err)) return Object.freeze({});
+      throw err;
+    }
+  }
+  async write(participantId, state) {
+    await ensureDir(this.opts.dir);
+    const path = this.pathFor(participantId);
+    await writeFile(path, JSON.stringify(state, null, 2), "utf8");
+  }
+  pathFor(participantId) {
+    const safe = participantId.replace(/[^a-zA-Z0-9._-]/g, "_");
+    return resolve(this.opts.dir, `${safe}.json`);
+  }
+};
+async function ensureDir(dir) {
+  try {
+    await stat(dir);
+  } catch (err) {
+    if (isNotFound(err)) {
+      await mkdir(dir, { recursive: true });
+      return;
+    }
+    throw err;
+  }
+}
+function isNotFound(err) {
+  return typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT";
+}
+
+export { FileStateStore };
+//# sourceMappingURL=state-fs.mjs.map
+//# sourceMappingURL=state-fs.mjs.map

package/dist/adapters/state-fs.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/state-fs.ts"],"names":["resolvePath"],"mappings":";;;;;;;;;;AAkBO,IAAM,iBAAN,MAA2C;AAAA,EAGhD,YAA6B,IAAA,EAA6B;AAA7B,IAAA,IAAA,CAAA,IAAA,GAAA,IAAA;AAAA,EAA8B;AAAA,EAA9B,IAAA;AAAA,EAFpB,IAAA,GAAO,IAAA;AAAA,EAIhB,MAAM,KAAK,aAAA,EAA0E;AACnF,IAAA,MAAM,IAAA,GAAO,IAAA,CAAK,OAAA,CAAQ,aAAa,CAAA;AACvC,IAAA,IAAI;AACF,MAAA,MAAM,GAAA,GAAM,MAAM,QAAA,CAAS,IAAA,EAAM,MAAM,CAAA;AACvC,MAAA,OAAO,IAAA,CAAK,MAAM,GAAG,CAAA;AAAA,IACvB,SAAS,GAAA,EAAK;AACZ,MAAA,IAAI,WAAW,GAAG,CAAA,SAAU,MAAA,CAAO,MAAA,CAAO,EAAE,CAAA;AAC5C,MAAA,MAAM,GAAA;AAAA,IACR;AAAA,EACF;AAAA,EAEA,MAAM,KAAA,CACJ,aAAA,EACA,KAAA,EACe;AACf,IAAA,MAAM,SAAA,CAAU,IAAA,CAAK,IAAA,CAAK,GAAG,CAAA;AAC7B,IAAA,MAAM,IAAA,GAAO,IAAA,CAAK,OAAA,CAAQ,aAAa,CAAA;AACvC,IAAA,MAAM,SAAA,CAAU,MAAM,IAAA,CAAK,SAAA,CAAU,OAAO,IAAA,EAAM,CAAC,GAAG,MAAM,CAAA;AAAA,EAC9D;AAAA,EAEQ,QAAQ,aAAA,EAAsC;AAEpD,IAAA,MAAM,IAAA,GAAO,aAAA,CAAc,OAAA,CAAQ,kBAAA,EAAoB,GAAG,CAAA;AAC1D,IAAA,OAAOA,QAAY,IAAA,CAAK,IAAA,CAAK,GAAA,EAAK,CAAA,EAAG,IAAI,CAAA,KAAA,CAAO,CAAA;AAAA,EAClD;AACF;AAEA,eAAe,UAAU,GAAA,EAA4B;AACnD,EAAA,IAAI;AACF,IAAA,MAAM,KAAK,GAAG,CAAA;AAAA,EAChB,SAAS,GAAA,EAAK;AACZ,IAAA,IAAI,UAAA,CAAW,GAAG,CAAA,EAAG;AACnB,MAAA,MAAM,KAAA,CAAM,GAAA,EAAK,EAAE,SAAA,EAAW,MAAM,CAAA;AACpC,MAAA;AAAA,IACF;AACA,IAAA,MAAM,GAAA;AAAA,EACR;AACF;AAEA,SAAS,WAAW,GAAA,EAAuB;AACzC,EAAA,OACE,OAAO,QAAQ,QAAA,IACf,GAAA,KAAQ,QACR,MAAA,IAAU,GAAA,IACT,IAAyB,IAAA,KAAS,QAAA;AAEvC","file":"state-fs.mjs","sourcesContent":["/**\n * Filesystem state store — one JSON file per participant.\n *\n *   <stateDir>/<participantId>.json\n *\n * Missing files read as {}. Writes are full overwrites; callers\n * pass the merged state, the adapter doesn't merge on its own.\n */\n\nimport { readFile, writeFile, mkdir, stat } from \"node:fs/promises\"\nimport { resolve as resolvePath } from \"node:path\"\nimport type { ParticipantId, StateStore } from \"../ports.js\"\n\nexport type FileStateStoreOptions = {\n  /** Directory to hold the per-participant JSON files. */\n  readonly dir: string\n}\n\nexport class FileStateStore implements StateStore {\n  readonly kind = \"fs\"\n\n  constructor(private readonly opts: FileStateStoreOptions) {}\n\n  async read(participantId: ParticipantId): Promise<Readonly<Record<string, unknown>>> {\n    const path = this.pathFor(participantId)\n    try {\n      const raw = await readFile(path, \"utf8\")\n      return JSON.parse(raw) as Record<string, unknown>\n    } catch (err) {\n      if (isNotFound(err)) return Object.freeze({})\n      throw err\n    }\n  }\n\n  async write(\n    participantId: ParticipantId,\n    state: Readonly<Record<string, unknown>>\n  ): Promise<void> {\n    await ensureDir(this.opts.dir)\n    const path = this.pathFor(participantId)\n    await writeFile(path, JSON.stringify(state, null, 2), \"utf8\")\n  }\n\n  private pathFor(participantId: ParticipantId): string {\n    // Sanitize: participant ids are user-controlled. Disallow path traversal.\n    const safe = participantId.replace(/[^a-zA-Z0-9._-]/g, \"_\")\n    return resolvePath(this.opts.dir, `${safe}.json`)\n  }\n}\n\nasync function ensureDir(dir: string): Promise<void> {\n  try {\n    await stat(dir)\n  } catch (err) {\n    if (isNotFound(err)) {\n      await mkdir(dir, { recursive: true })\n      return\n    }\n    throw err\n  }\n}\n\nfunction isNotFound(err: unknown): boolean {\n  return (\n    typeof err === \"object\" &&\n    err !== null &&\n    \"code\" in err &&\n    (err as { code: string }).code === \"ENOENT\"\n  )\n}\n"]}

package/dist/adapters/substrate-file.d.ts

@@ -0,0 +1,39 @@
+import { Substrate, TurnInput, Turn, TurnId } from '../ports.js';
+
+/**
+ * File substrate — append-only markdown journal.
+ *
+ * Each turn is delimited by a header line:
+ *   === TURN id=<id> participant=<pid> ts=<iso> ===
+ *   <body lines…>
+ *
+ * Ids are content-hashed, so re-running an append with the same body
+ * is idempotent at the row level.
+ *
+ * Caveats:
+ *   - `appendFile` does not fsync. A power-loss between buffered write
+ *     and disk flush can lose the most recent turn(s); callers that
+ *     need durability across crashes should layer their own fsync.
+ *   - The parser splits on lines matching `=== TURN ... ===`. Turn
+ *     content containing such a line will corrupt subsequent parses.
+ *     Treat turn content as untrusted? Sanitize before append.
+ */
+
+type FileSubstrateOptions = {
+    /** Absolute path to the journal file. */
+    readonly path: string;
+};
+declare class FileSubstrate implements Substrate {
+    private readonly opts;
+    readonly kind = "file";
+    constructor(opts: FileSubstrateOptions);
+    append(input: TurnInput): Promise<Turn>;
+    read(since?: TurnId): Promise<readonly Turn[]>;
+}
+/**
+ * Reset the journal by truncating it. Useful for tests. Not part of the
+ * Substrate interface — callers must reach for the adapter directly.
+ */
+declare function resetFileSubstrate(path: string): Promise<void>;
+
+export { FileSubstrate, type FileSubstrateOptions, resetFileSubstrate };

package/dist/adapters/substrate-file.mjs

@@ -0,0 +1,113 @@
+import { appendFile, readFile, writeFile, stat, mkdir } from 'fs/promises';
+import { dirname } from 'path';
+import { createHash } from 'crypto';
+
+/**
+ * @agentproto/agent-runtime v0.1.0-alpha
+ * MultiAgentRuntime kernel — swappable ports + reference adapters
+ * (file substrate, mention dispatcher, fs state, agent-cli participant).
+ * Transport-specific adapters ship in separate packages.
+ */
+
+var HEADER_RE = /^=== TURN id=([^\s]+) participant=([^\s]+) ts=([^\s]+) ===$/;
+var FileSubstrate = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  opts;
+  kind = "file";
+  async append(input) {
+    const timestamp = input.timestamp ?? (/* @__PURE__ */ new Date()).toISOString();
+    const id = hashTurnId(input.participantId, timestamp, input.content);
+    const turn = {
+      id,
+      participantId: input.participantId,
+      timestamp,
+      content: input.content,
+      meta: input.meta
+    };
+    await ensureDir(this.opts.path);
+    const block = formatTurnBlock(turn);
+    await appendFile(this.opts.path, block, "utf8");
+    return turn;
+  }
+  async read(since) {
+    let raw;
+    try {
+      raw = await readFile(this.opts.path, "utf8");
+    } catch (err) {
+      if (isNotFound(err)) return [];
+      throw err;
+    }
+    const turns = parseJournal(raw);
+    if (since === void 0) return turns;
+    const cutoff = turns.findIndex((t) => t.id === since);
+    if (cutoff === -1) return turns;
+    return turns.slice(cutoff + 1);
+  }
+};
+async function resetFileSubstrate(path) {
+  await ensureDir(path);
+  await writeFile(path, "", "utf8");
+}
+function formatTurnBlock(turn) {
+  const header = `=== TURN id=${turn.id} participant=${turn.participantId} ts=${turn.timestamp} ===
+`;
+  const body = turn.content.endsWith("\n") ? turn.content : `${turn.content}
+`;
+  return `${header}${body}`;
+}
+function parseJournal(raw) {
+  const lines = raw.split("\n");
+  const turns = [];
+  let current = null;
+  for (const line of lines) {
+    const match = HEADER_RE.exec(line);
+    if (match && match[1] && match[2] && match[3]) {
+      if (current) turns.push(materialise(current));
+      current = { id: match[1], pid: match[2], ts: match[3], buf: [] };
+      continue;
+    }
+    if (current) current.buf.push(line);
+  }
+  if (current) turns.push(materialise(current));
+  return turns;
+}
+function materialise(c) {
+  let body = c.buf.join("\n");
+  while (body.endsWith("\n")) body = body.slice(0, -1);
+  return {
+    id: c.id,
+    participantId: c.pid,
+    timestamp: c.ts,
+    content: body
+  };
+}
+function hashTurnId(pid, ts, content) {
+  const h = createHash("sha256");
+  h.update(pid);
+  h.update("\0");
+  h.update(ts);
+  h.update("\0");
+  h.update(content);
+  return `t_${h.digest("hex").slice(0, 12)}`;
+}
+async function ensureDir(path) {
+  const dir = dirname(path);
+  try {
+    await stat(dir);
+  } catch (err) {
+    if (isNotFound(err)) {
+      await mkdir(dir, { recursive: true });
+      return;
+    }
+    throw err;
+  }
+}
+function isNotFound(err) {
+  return typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT";
+}
+
+export { FileSubstrate, resetFileSubstrate };
+//# sourceMappingURL=substrate-file.mjs.map
+//# sourceMappingURL=substrate-file.mjs.map

package/dist/adapters/substrate-file.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/substrate-file.ts"],"names":[],"mappings":";;;;;;;;;;;AA6BA,IAAM,SAAA,GACJ,6DAAA;AAEK,IAAM,gBAAN,MAAyC;AAAA,EAG9C,YAA6B,IAAA,EAA4B;AAA5B,IAAA,IAAA,CAAA,IAAA,GAAA,IAAA;AAAA,EAA6B;AAAA,EAA7B,IAAA;AAAA,EAFpB,IAAA,GAAO,MAAA;AAAA,EAIhB,MAAM,OAAO,KAAA,EAAiC;AAC5C,IAAA,MAAM,YAAY,KAAA,CAAM,SAAA,IAAA,iBAAa,IAAI,IAAA,IAAO,WAAA,EAAY;AAC5D,IAAA,MAAM,KAAK,UAAA,CAAW,KAAA,CAAM,aAAA,EAAe,SAAA,EAAW,MAAM,OAAO,CAAA;AACnE,IAAA,MAAM,IAAA,GAAa;AAAA,MACjB,EAAA;AAAA,MACA,eAAe,KAAA,CAAM,aAAA;AAAA,MACrB,SAAA;AAAA,MACA,SAAS,KAAA,CAAM,OAAA;AAAA,MACf,MAAM,KAAA,CAAM;AAAA,KACd;AACA,IAAA,MAAM,SAAA,CAAU,IAAA,CAAK,IAAA,CAAK,IAAI,CAAA;AAC9B,IAAA,MAAM,KAAA,GAAQ,gBAAgB,IAAI,CAAA;AAClC,IAAA,MAAM,UAAA,CAAW,IAAA,CAAK,IAAA,CAAK,IAAA,EAAM,OAAO,MAAM,CAAA;AAC9C,IAAA,OAAO,IAAA;AAAA,EACT;AAAA,EAEA,MAAM,KAAK,KAAA,EAA0C;AACnD,IAAA,IAAI,GAAA;AACJ,IAAA,IAAI;AACF,MAAA,GAAA,GAAM,MAAM,QAAA,CAAS,IAAA,CAAK,IAAA,CAAK,MAAM,MAAM,CAAA;AAAA,IAC7C,SAAS,GAAA,EAAK;AACZ,MAAA,IAAI,UAAA,CAAW,GAAG,CAAA,EAAG,OAAO,EAAC;AAC7B,MAAA,MAAM,GAAA;AAAA,IACR;AACA,IAAA,MAAM,KAAA,GAAQ,aAAa,GAAG,CAAA;AAC9B,IAAA,IAAI,KAAA,KAAU,QAAW,OAAO,KAAA;AAChC,IAAA,MAAM,SAAS,KAAA,CAAM,SAAA,CAAU,CAAC,CAAA,KAAM,CAAA,CAAE,OAAO,KAAK,CAAA;AACpD,IAAA,IAAI,MAAA,KAAW,IAAI,OAAO,KAAA;AAC1B,IAAA,OAAO,KAAA,CAAM,KAAA,CAAM,MAAA,GAAS,CAAC,CAAA;AAAA,EAC/B;AACF;AAMA,eAAsB,mBAAmB,IAAA,EAA6B;AACpE,EAAA,MAAM,UAAU,IAAI,CAAA;AACpB,EAAA,MAAM,SAAA,CAAU,IAAA,EAAM,EAAA,EAAI,MAAM,CAAA;AAClC;AAEA,SAAS,gBAAgB,IAAA,EAAoB;AAC3C,EAAA,MAAM,MAAA,GAAS,eAAe,IAAA,CAAK,EAAE,gBAAgB,IAAA,CAAK,aAAa,CAAA,IAAA,EAAO,IAAA,CAAK,SAAS,CAAA;AAAA,CAAA;AAC5F,EAAA,MAAM,IAAA,GAAO,IAAA,CAAK,OAAA,CAAQ,QAAA,CAAS,IAAI,IAAI,IAAA,CAAK,OAAA,GAAU,CAAA,EAAG,IAAA,CAAK,OAAO;AAAA,CAAA;AACzE,EAAA,OAAO,CAAA,EAAG,MAAM,CAAA,EAAG,IAAI,CAAA,CAAA;AACzB;AAEA,SAAS,aAAa,GAAA,EAAqB;AACzC,EAAA,MAAM,KAAA,GAAQ,GAAA,CAAI,KAAA,CAAM,IAAI,CAAA;AAC5B,EAAA,MAAM,QAAgB,EAAC;AACvB,EAAA,IAAI,OAAA,GAAyE,IAAA;AAE7E,EAAA,KAAA,MAAW,QAAQ,KAAA,EAAO;AACxB,IAAA,MAAM,KAAA,GAAQ,SAAA,CAAU,IAAA,CAAK,IAAI,CAAA;AACjC,IAAA,IAAI,KAAA,IAAS,MAAM,CAAC,CAAA,IAAK,MAAM,CAAC,CAAA,IAAK,KAAA,CAAM,CAAC,CAAA,EAAG;AAC7C,MAAA,IAAI,OAAA,EAAS,KAAA,CAAM,IAAA,CAAK,WAAA,CAAY,OAAO,CAAC,CAAA;AAC5C,MAAA,OAAA,GAAU,EAAE,EAAA,EAAI,KAAA,CAAM,CAAC,GAAG,GAAA,EAAK,KAAA,CAAM,CAAC,CAAA,EAAG,IAAI,KAAA,CAAM,CAAC,CAAA,EAAG,GAAA,EAAK,EAAC,EAAE;AAC/D,MAAA;AAAA,IACF;AACA,IAAA,IAAI,OAAA,EAAS,OAAA,CAAQ,GAAA,CAAI,IAAA,CAAK,IAAI,CAAA;AAAA,EACpC;AACA,EAAA,IAAI,OAAA,EAAS,KAAA,CAAM,IAAA,CAAK,WAAA,CAAY,OAAO,CAAC,CAAA;AAC5C,EAAA,OAAO,KAAA;AACT;AAEA,SAAS,YAAY,CAAA,EAKZ;AAEP,EAAA,IAAI,IAAA,GAAO,CAAA,CAAE,GAAA,CAAI,IAAA,CAAK,IAAI,CAAA;AAC1B,EAAA,OAAO,IAAA,CAAK,SAAS,IAAI,CAAA,SAAU,IAAA,CAAK,KAAA,CAAM,GAAG,EAAE,CAAA;AACnD,EAAA,OAAO;AAAA,IACL,IAAI,CAAA,CAAE,EAAA;AAAA,IACN,eAAe,CAAA,CAAE,GAAA;AAAA,IACjB,WAAW,CAAA,CAAE,EAAA;AAAA,IACb,OAAA,EAAS;AAAA,GACX;AACF;AAEA,SAAS,UAAA,CAAW,GAAA,EAAa,EAAA,EAAY,OAAA,EAAyB;AACpE,EAAA,MAAM,CAAA,GAAI,WAAW,QAAQ,CAAA;AAC7B,EAAA,CAAA,CAAE,OAAO,GAAG,CAAA;AACZ,EAAA,CAAA,CAAE,OAAO,IAAM,CAAA;AACf,EAAA,CAAA,CAAE,OAAO,EAAE,CAAA;AACX,EAAA,CAAA,CAAE,OAAO,IAAM,CAAA;AACf,EAAA,CAAA,CAAE,OAAO,OAAO,CAAA;AAChB,EAAA,OAAO,CAAA,EAAA,EAAK,EAAE,MAAA,CAAO,KAAK,EAAE,KAAA,CAAM,CAAA,EAAG,EAAE,CAAC,CAAA,CAAA;AAC1C;AAEA,eAAe,UAAU,IAAA,EAA6B;AACpD,EAAA,MAAM,GAAA,GAAM,QAAQ,IAAI,CAAA;AACxB,EAAA,IAAI;AACF,IAAA,MAAM,KAAK,GAAG,CAAA;AAAA,EAChB,SAAS,GAAA,EAAK;AACZ,IAAA,IAAI,UAAA,CAAW,GAAG,CAAA,EAAG;AACnB,MAAA,MAAM,KAAA,CAAM,GAAA,EAAK,EAAE,SAAA,EAAW,MAAM,CAAA;AACpC,MAAA;AAAA,IACF;AACA,IAAA,MAAM,GAAA;AAAA,EACR;AACF;AAEA,SAAS,WAAW,GAAA,EAAuB;AACzC,EAAA,OACE,OAAO,QAAQ,QAAA,IACf,GAAA,KAAQ,QACR,MAAA,IAAU,GAAA,IACT,IAAyB,IAAA,KAAS,QAAA;AAEvC","file":"substrate-file.mjs","sourcesContent":["/**\n * File substrate — append-only markdown journal.\n *\n * Each turn is delimited by a header line:\n *   === TURN id=<id> participant=<pid> ts=<iso> ===\n *   <body lines…>\n *\n * Ids are content-hashed, so re-running an append with the same body\n * is idempotent at the row level.\n *\n * Caveats:\n *   - `appendFile` does not fsync. A power-loss between buffered write\n *     and disk flush can lose the most recent turn(s); callers that\n *     need durability across crashes should layer their own fsync.\n *   - The parser splits on lines matching `=== TURN ... ===`. Turn\n *     content containing such a line will corrupt subsequent parses.\n *     Treat turn content as untrusted? Sanitize before append.\n */\n\nimport { appendFile, readFile, writeFile, mkdir, stat } from \"node:fs/promises\"\nimport { dirname } from \"node:path\"\nimport { createHash } from \"node:crypto\"\nimport type { Substrate, Turn, TurnInput, TurnId } from \"../ports.js\"\n\nexport type FileSubstrateOptions = {\n  /** Absolute path to the journal file. */\n  readonly path: string\n}\n\nconst HEADER_RE =\n  /^=== TURN id=([^\\s]+) participant=([^\\s]+) ts=([^\\s]+) ===$/\n\nexport class FileSubstrate implements Substrate {\n  readonly kind = \"file\"\n\n  constructor(private readonly opts: FileSubstrateOptions) {}\n\n  async append(input: TurnInput): Promise<Turn> {\n    const timestamp = input.timestamp ?? new Date().toISOString()\n    const id = hashTurnId(input.participantId, timestamp, input.content)\n    const turn: Turn = {\n      id,\n      participantId: input.participantId,\n      timestamp,\n      content: input.content,\n      meta: input.meta,\n    }\n    await ensureDir(this.opts.path)\n    const block = formatTurnBlock(turn)\n    await appendFile(this.opts.path, block, \"utf8\")\n    return turn\n  }\n\n  async read(since?: TurnId): Promise<readonly Turn[]> {\n    let raw: string\n    try {\n      raw = await readFile(this.opts.path, \"utf8\")\n    } catch (err) {\n      if (isNotFound(err)) return []\n      throw err\n    }\n    const turns = parseJournal(raw)\n    if (since === undefined) return turns\n    const cutoff = turns.findIndex((t) => t.id === since)\n    if (cutoff === -1) return turns\n    return turns.slice(cutoff + 1)\n  }\n}\n\n/**\n * Reset the journal by truncating it. Useful for tests. Not part of the\n * Substrate interface — callers must reach for the adapter directly.\n */\nexport async function resetFileSubstrate(path: string): Promise<void> {\n  await ensureDir(path)\n  await writeFile(path, \"\", \"utf8\")\n}\n\nfunction formatTurnBlock(turn: Turn): string {\n  const header = `=== TURN id=${turn.id} participant=${turn.participantId} ts=${turn.timestamp} ===\\n`\n  const body = turn.content.endsWith(\"\\n\") ? turn.content : `${turn.content}\\n`\n  return `${header}${body}`\n}\n\nfunction parseJournal(raw: string): Turn[] {\n  const lines = raw.split(\"\\n\")\n  const turns: Turn[] = []\n  let current: { id: string; pid: string; ts: string; buf: string[] } | null = null\n\n  for (const line of lines) {\n    const match = HEADER_RE.exec(line)\n    if (match && match[1] && match[2] && match[3]) {\n      if (current) turns.push(materialise(current))\n      current = { id: match[1], pid: match[2], ts: match[3], buf: [] }\n      continue\n    }\n    if (current) current.buf.push(line)\n  }\n  if (current) turns.push(materialise(current))\n  return turns\n}\n\nfunction materialise(c: {\n  id: string\n  pid: string\n  ts: string\n  buf: string[]\n}): Turn {\n  // Drop the trailing empty line that appendFile leaves between blocks.\n  let body = c.buf.join(\"\\n\")\n  while (body.endsWith(\"\\n\")) body = body.slice(0, -1)\n  return {\n    id: c.id,\n    participantId: c.pid,\n    timestamp: c.ts,\n    content: body,\n  }\n}\n\nfunction hashTurnId(pid: string, ts: string, content: string): string {\n  const h = createHash(\"sha256\")\n  h.update(pid)\n  h.update(\"\\x00\")\n  h.update(ts)\n  h.update(\"\\x00\")\n  h.update(content)\n  return `t_${h.digest(\"hex\").slice(0, 12)}`\n}\n\nasync function ensureDir(path: string): Promise<void> {\n  const dir = dirname(path)\n  try {\n    await stat(dir)\n  } catch (err) {\n    if (isNotFound(err)) {\n      await mkdir(dir, { recursive: true })\n      return\n    }\n    throw err\n  }\n}\n\nfunction isNotFound(err: unknown): boolean {\n  return (\n    typeof err === \"object\" &&\n    err !== null &&\n    \"code\" in err &&\n    (err as { code: string }).code === \"ENOENT\"\n  )\n}\n"]}

package/dist/adapters/telemetry.d.ts

@@ -0,0 +1,39 @@
+import { TelemetryEvent, Telemetry } from '../ports.js';
+
+/**
+ * Reference Telemetry adapters.
+ *
+ * Wire `RuntimePorts.telemetry` to one of these (or your own
+ * implementation) to receive structured events from each cycle.
+ * Sinks may also be composed via `composeTelemetry()`.
+ */
+
+/** No-op sink. Equivalent to leaving `telemetry` undefined on RuntimePorts. */
+declare const noopTelemetry: Telemetry;
+interface StderrTelemetryOptions {
+    /** Event kinds to include. Omit to emit all kinds. */
+    readonly include?: ReadonlySet<TelemetryEvent["kind"]>;
+    /** Event kinds to suppress. Wins over `include`. */
+    readonly exclude?: ReadonlySet<TelemetryEvent["kind"]>;
+    /** Prefix prepended to every line. Default "agentproto: ". */
+    readonly prefix?: string;
+}
+/**
+ * Human-readable stderr sink — one line per event. Cheaper than wiring
+ * a real exporter; good default for `--verbose` mode.
+ */
+declare function stderrTelemetry(options?: StderrTelemetryOptions): Telemetry;
+/**
+ * In-memory sink — every event pushed onto an array. Intended for
+ * tests; reach into `events` after `runTurn` to assert.
+ */
+declare function arrayTelemetry(): Telemetry & {
+    readonly events: readonly TelemetryEvent[];
+};
+/**
+ * Fan-out — emits every event to all wrapped sinks in order. Useful
+ * for "log to stderr AND export to OTEL" setups.
+ */
+declare function composeTelemetry(...sinks: readonly Telemetry[]): Telemetry;
+
+export { type StderrTelemetryOptions, arrayTelemetry, composeTelemetry, noopTelemetry, stderrTelemetry };

package/dist/adapters/telemetry.mjs

@@ -0,0 +1,76 @@
+/**
+ * @agentproto/agent-runtime v0.1.0-alpha
+ * MultiAgentRuntime kernel — swappable ports + reference adapters
+ * (file substrate, mention dispatcher, fs state, agent-cli participant).
+ * Transport-specific adapters ship in separate packages.
+ */
+
+// src/adapters/telemetry.ts
+var noopTelemetry = {
+  emit() {
+  }
+};
+function stderrTelemetry(options = {}) {
+  const prefix = options.prefix ?? "agentproto: ";
+  return {
+    emit(event) {
+      if (options.exclude?.has(event.kind)) return;
+      if (options.include && !options.include.has(event.kind)) return;
+      process.stderr.write(`${prefix}${formatEvent(event)}
+`);
+    }
+  };
+}
+function arrayTelemetry() {
+  const events = [];
+  return {
+    events,
+    emit(event) {
+      events.push(event);
+    }
+  };
+}
+function composeTelemetry(...sinks) {
+  return {
+    emit(event) {
+      for (const sink of sinks) {
+        try {
+          sink.emit(event);
+        } catch {
+        }
+      }
+    }
+  };
+}
+function formatEvent(event) {
+  switch (event.kind) {
+    case "cycle.started":
+      return `${event.cycleId} cycle.started${event.since !== void 0 ? ` since=${event.since}` : ""}`;
+    case "substrate.read":
+      return `${event.cycleId} substrate.read ${event.substrateKind} turns=${event.turnCount} ${event.durationMs}ms`;
+    case "dispatch.decided":
+      return `${event.cycleId} dispatch.decided ${event.dispatcherKind} selected=[${event.selected.join(",") || "(none)"}] ${event.durationMs}ms`;
+    case "participant.started":
+      return `${event.cycleId} participant.started ${event.participantId} (${event.executorKind})`;
+    case "participant.finished":
+      return `${event.cycleId} participant.finished ${event.participantId} ${event.durationMs}ms content=${event.contentLength}b`;
+    case "participant.failed":
+      return `${event.cycleId} participant.failed ${event.participantId} \u2014 ${event.error}`;
+    case "substrate.appended":
+      return `${event.cycleId} substrate.appended turn=${event.turnId} by=${event.participantId}`;
+    case "state.written":
+      return `${event.cycleId} state.written ${event.participantId}`;
+    case "cycle.idle":
+      return `${event.cycleId} cycle.idle`;
+    case "cycle.finished":
+      return `${event.cycleId} cycle.finished ${event.outcome} appended=${event.turnsAppended} ${event.durationMs}ms`;
+    default: {
+      const _exhaustive = event;
+      return JSON.stringify(_exhaustive);
+    }
+  }
+}
+
+export { arrayTelemetry, composeTelemetry, noopTelemetry, stderrTelemetry };
+//# sourceMappingURL=telemetry.mjs.map
+//# sourceMappingURL=telemetry.mjs.map

package/dist/adapters/telemetry.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/telemetry.ts"],"names":[],"mappings":"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","file":"telemetry.mjs","sourcesContent":["/**\n * Reference Telemetry adapters.\n *\n * Wire `RuntimePorts.telemetry` to one of these (or your own\n * implementation) to receive structured events from each cycle.\n * Sinks may also be composed via `composeTelemetry()`.\n */\n\nimport type { Telemetry, TelemetryEvent } from \"../ports.js\"\n\n/** No-op sink. Equivalent to leaving `telemetry` undefined on RuntimePorts. */\nexport const noopTelemetry: Telemetry = {\n  emit() {\n    // intentionally blank\n  },\n}\n\nexport interface StderrTelemetryOptions {\n  /** Event kinds to include. Omit to emit all kinds. */\n  readonly include?: ReadonlySet<TelemetryEvent[\"kind\"]>\n  /** Event kinds to suppress. Wins over `include`. */\n  readonly exclude?: ReadonlySet<TelemetryEvent[\"kind\"]>\n  /** Prefix prepended to every line. Default \"agentproto: \". */\n  readonly prefix?: string\n}\n\n/**\n * Human-readable stderr sink — one line per event. Cheaper than wiring\n * a real exporter; good default for `--verbose` mode.\n */\nexport function stderrTelemetry(\n  options: StderrTelemetryOptions = {}\n): Telemetry {\n  const prefix = options.prefix ?? \"agentproto: \"\n  return {\n    emit(event) {\n      if (options.exclude?.has(event.kind)) return\n      if (options.include && !options.include.has(event.kind)) return\n      process.stderr.write(`${prefix}${formatEvent(event)}\\n`)\n    },\n  }\n}\n\n/**\n * In-memory sink — every event pushed onto an array. Intended for\n * tests; reach into `events` after `runTurn` to assert.\n */\nexport function arrayTelemetry(): Telemetry & {\n  readonly events: readonly TelemetryEvent[]\n} {\n  const events: TelemetryEvent[] = []\n  return {\n    events,\n    emit(event) {\n      events.push(event)\n    },\n  }\n}\n\n/**\n * Fan-out — emits every event to all wrapped sinks in order. Useful\n * for \"log to stderr AND export to OTEL\" setups.\n */\nexport function composeTelemetry(...sinks: readonly Telemetry[]): Telemetry {\n  return {\n    emit(event) {\n      for (const sink of sinks) {\n        try {\n          sink.emit(event)\n        } catch {\n          // Each sink is independently isolated.\n        }\n      }\n    },\n  }\n}\n\nfunction formatEvent(event: TelemetryEvent): string {\n  switch (event.kind) {\n    case \"cycle.started\":\n      return `${event.cycleId} cycle.started${event.since !== undefined ? ` since=${event.since}` : \"\"}`\n    case \"substrate.read\":\n      return `${event.cycleId} substrate.read ${event.substrateKind} turns=${event.turnCount} ${event.durationMs}ms`\n    case \"dispatch.decided\":\n      return `${event.cycleId} dispatch.decided ${event.dispatcherKind} selected=[${event.selected.join(\",\") || \"(none)\"}] ${event.durationMs}ms`\n    case \"participant.started\":\n      return `${event.cycleId} participant.started ${event.participantId} (${event.executorKind})`\n    case \"participant.finished\":\n      return `${event.cycleId} participant.finished ${event.participantId} ${event.durationMs}ms content=${event.contentLength}b`\n    case \"participant.failed\":\n      return `${event.cycleId} participant.failed ${event.participantId} — ${event.error}`\n    case \"substrate.appended\":\n      return `${event.cycleId} substrate.appended turn=${event.turnId} by=${event.participantId}`\n    case \"state.written\":\n      return `${event.cycleId} state.written ${event.participantId}`\n    case \"cycle.idle\":\n      return `${event.cycleId} cycle.idle`\n    case \"cycle.finished\":\n      return `${event.cycleId} cycle.finished ${event.outcome} appended=${event.turnsAppended} ${event.durationMs}ms`\n    default: {\n      // Forward-compat — render unknown kinds as JSON so a future\n      // kernel version doesn't blank-line the log.\n      const _exhaustive: never = event\n      return JSON.stringify(_exhaustive)\n    }\n  }\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+import { TurnId, Turn, RuntimePorts } from './ports.js';
+export { Dispatcher, DispatcherInput, Lifecycle, ParticipantDescriptor, ParticipantExecuteInput, ParticipantExecuteOutput, ParticipantExecutor, ParticipantId, StateStore, Substrate, Telemetry, TelemetryEvent, TurnInput } from './ports.js';
+export { LoadedManifest, MULTI_AGENT_RUNTIME_KIND, MULTI_AGENT_RUNTIME_SCHEMA, MultiAgentRuntimeManifest, MultiAgentRuntimeManifestSchema, loadManifest, parseManifest, resolveManifestPath } from './manifest.js';
+import 'zod';
+
+/**
+ * Runtime orchestrator. One cycle =
+ *   read substrate → dispatch → execute selected participants → append → fire lifecycle.
+ *
+ * The kernel knows nothing about specific substrates, dispatchers, or
+ * executors — it only routes through the port interfaces. Telemetry,
+ * if wired, receives a structured event at every phase boundary; the
+ * cycleId on each event lets a sink rebuild OTEL-style spans by
+ * grouping.
+ */
+
+type RunTurnOptions = {
+    /** How far back to read from the substrate when building dispatcher input. Default 30. */
+    readonly historyLimit?: number;
+    /** Read turns strictly newer than this id. Default undefined (full snapshot, truncated by historyLimit). */
+    readonly since?: TurnId;
+    /** Abort signal forwarded to participant executors. */
+    readonly signal?: AbortSignal;
+};
+type RunTurnResult = {
+    readonly cycle: "executed" | "idle";
+    readonly selected: readonly string[];
+    readonly turnsAppended: readonly Turn[];
+};
+/**
+ * Run a single dispatcher cycle. Returns synchronously after one round of
+ * dispatch + execute + append. Callers loop for continuous operation.
+ */
+declare function runTurn(ports: RuntimePorts, options?: RunTurnOptions): Promise<RunTurnResult>;
+
+export { type RunTurnOptions, type RunTurnResult, RuntimePorts, Turn, TurnId, runTurn };

package/dist/index.mjs

@@ -0,0 +1,225 @@
+import { randomBytes } from 'crypto';
+import { readFile } from 'fs/promises';
+import { resolve, dirname } from 'path';
+import matter from 'gray-matter';
+import { z } from 'zod';
+
+/**
+ * @agentproto/agent-runtime v0.1.0-alpha
+ * MultiAgentRuntime kernel — swappable ports + reference adapters
+ * (file substrate, mention dispatcher, fs state, agent-cli participant).
+ * Transport-specific adapters ship in separate packages.
+ */
+
+async function runTurn(ports, options = {}) {
+  const historyLimit = options.historyLimit ?? 30;
+  const cycleId = newCycleId();
+  const cycleStart = Date.now();
+  emit(ports.telemetry, {
+    kind: "cycle.started",
+    cycleId,
+    at: nowIso(),
+    ...options.since !== void 0 ? { since: options.since } : {}
+  });
+  const readStart = Date.now();
+  const all = await ports.substrate.read(options.since);
+  const recentTurns = all.slice(-historyLimit);
+  emit(ports.telemetry, {
+    kind: "substrate.read",
+    cycleId,
+    at: nowIso(),
+    substrateKind: ports.substrate.kind,
+    turnCount: recentTurns.length,
+    durationMs: Date.now() - readStart
+  });
+  const dispatchStart = Date.now();
+  const selected = await ports.dispatcher.selectNext({
+    recentTurns,
+    participants: ports.participants
+  });
+  emit(ports.telemetry, {
+    kind: "dispatch.decided",
+    cycleId,
+    at: nowIso(),
+    dispatcherKind: ports.dispatcher.kind,
+    selected,
+    durationMs: Date.now() - dispatchStart
+  });
+  if (selected.length === 0) {
+    await ports.lifecycle?.onIdle?.();
+    emit(ports.telemetry, { kind: "cycle.idle", cycleId, at: nowIso() });
+    emit(ports.telemetry, {
+      kind: "cycle.finished",
+      cycleId,
+      at: nowIso(),
+      outcome: "idle",
+      turnsAppended: 0,
+      durationMs: Date.now() - cycleStart
+    });
+    return { cycle: "idle", selected: [], turnsAppended: [] };
+  }
+  const triggerTurn = recentTurns[recentTurns.length - 1];
+  if (!triggerTurn) {
+    await ports.lifecycle?.onIdle?.();
+    emit(ports.telemetry, { kind: "cycle.idle", cycleId, at: nowIso() });
+    emit(ports.telemetry, {
+      kind: "cycle.finished",
+      cycleId,
+      at: nowIso(),
+      outcome: "idle",
+      turnsAppended: 0,
+      durationMs: Date.now() - cycleStart
+    });
+    return { cycle: "idle", selected: [], turnsAppended: [] };
+  }
+  const appended = [];
+  for (const participantId of selected) {
+    const participant = findParticipant(ports.participants, participantId);
+    if (!participant) {
+      continue;
+    }
+    const executor = ports.executors.get(participant.executor);
+    if (!executor) {
+      continue;
+    }
+    await ports.lifecycle?.onMention?.(participantId, triggerTurn);
+    const state = await ports.state.read(participantId);
+    emit(ports.telemetry, {
+      kind: "participant.started",
+      cycleId,
+      at: nowIso(),
+      participantId,
+      executorKind: participant.executor
+    });
+    const execStart = Date.now();
+    let output;
+    try {
+      output = await executor.executeTurn({
+        participant,
+        recentTurns,
+        triggerTurn,
+        state,
+        signal: options.signal
+      });
+    } catch (err) {
+      emit(ports.telemetry, {
+        kind: "participant.failed",
+        cycleId,
+        at: nowIso(),
+        participantId,
+        executorKind: participant.executor,
+        error: err instanceof Error ? err.message : String(err)
+      });
+      throw err;
+    }
+    emit(ports.telemetry, {
+      kind: "participant.finished",
+      cycleId,
+      at: nowIso(),
+      participantId,
+      executorKind: participant.executor,
+      durationMs: Date.now() - execStart,
+      contentLength: output.content.length
+    });
+    const turn = await ports.substrate.append({
+      participantId,
+      content: output.content,
+      meta: output.meta
+    });
+    appended.push(turn);
+    emit(ports.telemetry, {
+      kind: "substrate.appended",
+      cycleId,
+      at: nowIso(),
+      turnId: turn.id,
+      participantId
+    });
+    if (output.stateUpdate) {
+      await ports.state.write(participantId, output.stateUpdate);
+      emit(ports.telemetry, {
+        kind: "state.written",
+        cycleId,
+        at: nowIso(),
+        participantId
+      });
+    }
+    await ports.lifecycle?.onTurnEnd?.(turn);
+  }
+  emit(ports.telemetry, {
+    kind: "cycle.finished",
+    cycleId,
+    at: nowIso(),
+    outcome: "executed",
+    turnsAppended: appended.length,
+    durationMs: Date.now() - cycleStart
+  });
+  return { cycle: "executed", selected, turnsAppended: appended };
+}
+function findParticipant(participants, id) {
+  for (const p of participants) {
+    if (p.id === id) return p;
+  }
+  return void 0;
+}
+function emit(telemetry, event) {
+  if (!telemetry) return;
+  try {
+    telemetry.emit(event);
+  } catch {
+  }
+}
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function newCycleId() {
+  return `c_${randomBytes(6).toString("hex")}`;
+}
+var MULTI_AGENT_RUNTIME_SCHEMA = "agentruntimes/v1";
+var MULTI_AGENT_RUNTIME_KIND = "MultiAgentRuntime";
+var AdapterConfigSchema = z.object({
+  kind: z.string().min(1)
+}).loose();
+var ParticipantManifestSchema = z.object({
+  id: z.string().min(1),
+  executor: z.string().min(1),
+  displayName: z.string().min(1).optional(),
+  role: z.string().optional(),
+  meta: z.record(z.string(), z.unknown()).optional()
+}).loose();
+var MultiAgentRuntimeManifestSchema = z.object({
+  schema: z.literal(MULTI_AGENT_RUNTIME_SCHEMA),
+  kind: z.literal(MULTI_AGENT_RUNTIME_KIND),
+  id: z.string().min(1),
+  participants: z.array(ParticipantManifestSchema).min(1),
+  substrate: AdapterConfigSchema,
+  dispatcher: AdapterConfigSchema,
+  state: AdapterConfigSchema.optional(),
+  lifecycle: z.object({
+    onTurnEnd: z.boolean().optional(),
+    onMention: z.boolean().optional(),
+    onIdle: z.boolean().optional()
+  }).optional()
+}).loose();
+function parseManifest(source) {
+  const parsed = matter(source);
+  return MultiAgentRuntimeManifestSchema.parse(parsed.data);
+}
+async function loadManifest(path) {
+  const abs = resolve(path);
+  const raw = await readFile(abs, "utf8");
+  const parsed = matter(raw);
+  const manifest = MultiAgentRuntimeManifestSchema.parse(parsed.data);
+  return {
+    manifest,
+    body: parsed.content,
+    path: abs,
+    baseDir: dirname(abs)
+  };
+}
+function resolveManifestPath(loaded, value) {
+  return resolve(loaded.baseDir, value);
+}
+
+export { MULTI_AGENT_RUNTIME_KIND, MULTI_AGENT_RUNTIME_SCHEMA, MultiAgentRuntimeManifestSchema, loadManifest, parseManifest, resolveManifestPath, runTurn };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/runtime.ts","../src/manifest.ts"],"names":["resolvePath"],"mappings":"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","file":"index.mjs","sourcesContent":["/**\n * Runtime orchestrator. One cycle =\n *   read substrate → dispatch → execute selected participants → append → fire lifecycle.\n *\n * The kernel knows nothing about specific substrates, dispatchers, or\n * executors — it only routes through the port interfaces. Telemetry,\n * if wired, receives a structured event at every phase boundary; the\n * cycleId on each event lets a sink rebuild OTEL-style spans by\n * grouping.\n */\n\nimport { randomBytes } from \"node:crypto\"\nimport type {\n  ParticipantDescriptor,\n  RuntimePorts,\n  Telemetry,\n  TelemetryEvent,\n  Turn,\n  TurnId,\n} from \"./ports.js\"\n\nexport type RunTurnOptions = {\n  /** How far back to read from the substrate when building dispatcher input. Default 30. */\n  readonly historyLimit?: number\n  /** Read turns strictly newer than this id. Default undefined (full snapshot, truncated by historyLimit). */\n  readonly since?: TurnId\n  /** Abort signal forwarded to participant executors. */\n  readonly signal?: AbortSignal\n}\n\nexport type RunTurnResult = {\n  readonly cycle: \"executed\" | \"idle\"\n  readonly selected: readonly string[]\n  readonly turnsAppended: readonly Turn[]\n}\n\n/**\n * Run a single dispatcher cycle. Returns synchronously after one round of\n * dispatch + execute + append. Callers loop for continuous operation.\n */\nexport async function runTurn(\n  ports: RuntimePorts,\n  options: RunTurnOptions = {}\n): Promise<RunTurnResult> {\n  const historyLimit = options.historyLimit ?? 30\n  const cycleId = newCycleId()\n  const cycleStart = Date.now()\n\n  emit(ports.telemetry, {\n    kind: \"cycle.started\",\n    cycleId,\n    at: nowIso(),\n    ...(options.since !== undefined ? { since: options.since } : {}),\n  })\n\n  const readStart = Date.now()\n  const all = await ports.substrate.read(options.since)\n  const recentTurns = all.slice(-historyLimit)\n  emit(ports.telemetry, {\n    kind: \"substrate.read\",\n    cycleId,\n    at: nowIso(),\n    substrateKind: ports.substrate.kind,\n    turnCount: recentTurns.length,\n    durationMs: Date.now() - readStart,\n  })\n\n  const dispatchStart = Date.now()\n  const selected = await ports.dispatcher.selectNext({\n    recentTurns,\n    participants: ports.participants,\n  })\n  emit(ports.telemetry, {\n    kind: \"dispatch.decided\",\n    cycleId,\n    at: nowIso(),\n    dispatcherKind: ports.dispatcher.kind,\n    selected,\n    durationMs: Date.now() - dispatchStart,\n  })\n\n  if (selected.length === 0) {\n    await ports.lifecycle?.onIdle?.()\n    emit(ports.telemetry, { kind: \"cycle.idle\", cycleId, at: nowIso() })\n    emit(ports.telemetry, {\n      kind: \"cycle.finished\",\n      cycleId,\n      at: nowIso(),\n      outcome: \"idle\",\n      turnsAppended: 0,\n      durationMs: Date.now() - cycleStart,\n    })\n    return { cycle: \"idle\", selected: [], turnsAppended: [] }\n  }\n\n  const triggerTurn = recentTurns[recentTurns.length - 1]\n  if (!triggerTurn) {\n    // Dispatcher selected someone but there's no recent turn to trigger off.\n    // Treat as idle — dispatchers should not pick speakers from an empty substrate.\n    await ports.lifecycle?.onIdle?.()\n    emit(ports.telemetry, { kind: \"cycle.idle\", cycleId, at: nowIso() })\n    emit(ports.telemetry, {\n      kind: \"cycle.finished\",\n      cycleId,\n      at: nowIso(),\n      outcome: \"idle\",\n      turnsAppended: 0,\n      durationMs: Date.now() - cycleStart,\n    })\n    return { cycle: \"idle\", selected: [], turnsAppended: [] }\n  }\n\n  const appended: Turn[] = []\n\n  for (const participantId of selected) {\n    const participant = findParticipant(ports.participants, participantId)\n    if (!participant) {\n      // Dispatcher hallucinated an unknown participant. Skip rather than crash —\n      // a malformed dispatcher shouldn't take down the loop.\n      continue\n    }\n    const executor = ports.executors.get(participant.executor)\n    if (!executor) {\n      // Manifest declared a participant whose executor isn't registered.\n      // Skip; misconfiguration shows up in logs but the loop survives.\n      continue\n    }\n\n    await ports.lifecycle?.onMention?.(participantId, triggerTurn)\n\n    const state = await ports.state.read(participantId)\n\n    emit(ports.telemetry, {\n      kind: \"participant.started\",\n      cycleId,\n      at: nowIso(),\n      participantId,\n      executorKind: participant.executor,\n    })\n\n    const execStart = Date.now()\n    let output\n    try {\n      output = await executor.executeTurn({\n        participant,\n        recentTurns,\n        triggerTurn,\n        state,\n        signal: options.signal,\n      })\n    } catch (err) {\n      emit(ports.telemetry, {\n        kind: \"participant.failed\",\n        cycleId,\n        at: nowIso(),\n        participantId,\n        executorKind: participant.executor,\n        error: err instanceof Error ? err.message : String(err),\n      })\n      throw err\n    }\n\n    emit(ports.telemetry, {\n      kind: \"participant.finished\",\n      cycleId,\n      at: nowIso(),\n      participantId,\n      executorKind: participant.executor,\n      durationMs: Date.now() - execStart,\n      contentLength: output.content.length,\n    })\n\n    const turn = await ports.substrate.append({\n      participantId,\n      content: output.content,\n      meta: output.meta,\n    })\n    appended.push(turn)\n    emit(ports.telemetry, {\n      kind: \"substrate.appended\",\n      cycleId,\n      at: nowIso(),\n      turnId: turn.id,\n      participantId,\n    })\n\n    if (output.stateUpdate) {\n      await ports.state.write(participantId, output.stateUpdate)\n      emit(ports.telemetry, {\n        kind: \"state.written\",\n        cycleId,\n        at: nowIso(),\n        participantId,\n      })\n    }\n\n    await ports.lifecycle?.onTurnEnd?.(turn)\n  }\n\n  emit(ports.telemetry, {\n    kind: \"cycle.finished\",\n    cycleId,\n    at: nowIso(),\n    outcome: \"executed\",\n    turnsAppended: appended.length,\n    durationMs: Date.now() - cycleStart,\n  })\n\n  return { cycle: \"executed\", selected, turnsAppended: appended }\n}\n\nfunction findParticipant(\n  participants: readonly ParticipantDescriptor[],\n  id: string\n): ParticipantDescriptor | undefined {\n  for (const p of participants) {\n    if (p.id === id) return p\n  }\n  return undefined\n}\n\nfunction emit(telemetry: Telemetry | undefined, event: TelemetryEvent): void {\n  // Sinks throwing must not take down the cycle — observability is\n  // non-load-bearing for the conversation.\n  if (!telemetry) return\n  try {\n    telemetry.emit(event)\n  } catch {\n    // Swallow. Better to lose a metric than to corrupt a turn.\n  }\n}\n\nfunction nowIso(): string {\n  return new Date().toISOString()\n}\n\nfunction newCycleId(): string {\n  // 96-bit random id, base32-ish — short enough to read, wide enough\n  // to be unique within a swarm process's lifetime.\n  return `c_${randomBytes(6).toString(\"hex\")}`\n}\n","/**\n * MultiAgentRuntime manifest schema + loader.\n *\n * The manifest is markdown with YAML frontmatter (matching @agentproto's\n * doctype convention used by ROLE.md, OPERATOR.md, etc.). The frontmatter\n * is the structured contract; the markdown body is human-readable\n * documentation of what the swarm does.\n *\n * Loader is filesystem-bound but parsing is pure — the schema can be used\n * by tests with inline strings via `parseManifest()`.\n */\n\nimport { readFile } from \"node:fs/promises\"\nimport { resolve as resolvePath, dirname } from \"node:path\"\nimport matter from \"gray-matter\"\nimport { z } from \"zod\"\n\nexport const MULTI_AGENT_RUNTIME_SCHEMA = \"agentruntimes/v1\"\nexport const MULTI_AGENT_RUNTIME_KIND = \"MultiAgentRuntime\"\n\nconst AdapterConfigSchema = z\n  .object({\n    kind: z.string().min(1),\n  })\n  .loose()\n\nconst ParticipantManifestSchema = z\n  .object({\n    id: z.string().min(1),\n    executor: z.string().min(1),\n    displayName: z.string().min(1).optional(),\n    role: z.string().optional(),\n    meta: z.record(z.string(), z.unknown()).optional(),\n  })\n  .loose()\n\nexport const MultiAgentRuntimeManifestSchema = z\n  .object({\n    schema: z.literal(MULTI_AGENT_RUNTIME_SCHEMA),\n    kind: z.literal(MULTI_AGENT_RUNTIME_KIND),\n    id: z.string().min(1),\n    participants: z.array(ParticipantManifestSchema).min(1),\n    substrate: AdapterConfigSchema,\n    dispatcher: AdapterConfigSchema,\n    state: AdapterConfigSchema.optional(),\n    lifecycle: z\n      .object({\n        onTurnEnd: z.boolean().optional(),\n        onMention: z.boolean().optional(),\n        onIdle: z.boolean().optional(),\n      })\n      .optional(),\n  })\n  .loose()\n\nexport type MultiAgentRuntimeManifest = z.infer<\n  typeof MultiAgentRuntimeManifestSchema\n>\n\nexport type LoadedManifest = {\n  readonly manifest: MultiAgentRuntimeManifest\n  readonly body: string\n  readonly path: string\n  /** Absolute directory of the manifest file — adapter configs that reference paths resolve relative to this. */\n  readonly baseDir: string\n}\n\nexport function parseManifest(source: string): MultiAgentRuntimeManifest {\n  const parsed = matter(source)\n  return MultiAgentRuntimeManifestSchema.parse(parsed.data)\n}\n\nexport async function loadManifest(path: string): Promise<LoadedManifest> {\n  const abs = resolvePath(path)\n  const raw = await readFile(abs, \"utf8\")\n  const parsed = matter(raw)\n  const manifest = MultiAgentRuntimeManifestSchema.parse(parsed.data)\n  return {\n    manifest,\n    body: parsed.content,\n    path: abs,\n    baseDir: dirname(abs),\n  }\n}\n\n/** Resolve a path string from a manifest field, relative to the manifest's directory. */\nexport function resolveManifestPath(loaded: LoadedManifest, value: string): string {\n  return resolvePath(loaded.baseDir, value)\n}\n"]}