@agentproto/agent-runtime 0.1.0-alpha.0

package/ARCHITECTURE.md

@@ -0,0 +1,301 @@
+# Architecture — @agentproto/agent-runtime
+
+A small port/adapter kernel for running swarms of agents over swappable
+conversation substrates. The kernel is transport-agnostic — it knows
+nothing about specific chat servers, dispatchers, or executors; it only
+routes through port interfaces.
+
+## The one cycle
+
+```
+                ┌───────────────────┐
+                │   substrate.read  │   1. snapshot recent turns
+                └─────────┬─────────┘
+                          │
+                          ▼
+            ┌───────────────────────────┐
+            │  dispatcher.selectNext()  │   2. decide who speaks next
+            └─────────────┬─────────────┘
+                          │ participantIds[]
+              ┌───────────┴───────────┐
+              │                       │
+              ▼                       ▼
+   ┌──────────────────┐    ┌──────────────────┐
+   │   state.read(p)  │    │ executor.execute │   3. produce reply
+   └────────┬─────────┘    │       Turn       │
+            │              └────────┬─────────┘
+            └──────────► input ─────┘
+                                    │
+                                    ▼
+                       ┌────────────────────────┐
+                       │   substrate.append()   │   4. write reply turn
+                       └────────────┬───────────┘
+                                    │
+                                    ▼
+                         ┌─────────────────────┐
+                         │   state.write(p)    │   5. persist state diff
+                         └──────────┬──────────┘
+                                    │
+                                    ▼
+                       ┌────────────────────────┐
+                       │  lifecycle.onTurnEnd   │   6. fire hooks
+                       └────────────────────────┘
+```
+
+`runTurn(ports, opts)` executes one cycle. Callers loop it for
+continuous operation. The kernel has no concept of "running" — it's
+strictly synchronous-per-cycle. Long-running behavior lives in the
+caller (the `agentproto run-swarm` verb wraps it in a `do-while`).
+
+## Ports
+
+### `Substrate`
+
+The conversation store. Append-only, oldest-first read semantics.
+
+```ts
+interface Substrate {
+  readonly kind: string
+  append(turn: TurnInput): Promise<Turn>
+  read(since?: TurnId): Promise<readonly Turn[]>
+}
+```
+
+Reference adapter: `FileSubstrate` — a markdown journal at a path. Each
+turn is delimited by `=== TURN id=… participant=… ts=… ===`.
+
+Other implementations: chat servers (Slack, Discord), MCP-bridged
+threads, REST APIs. Ship as plugin packages.
+
+**`since` contract:** if `since` is provided but not in the window the
+adapter fetched, the adapter SHOULD throw (telling the caller to raise
+its fetch window) rather than silently returning everything — otherwise
+the dispatcher's cursor can re-fire on already-handled turns.
+
+### `Dispatcher`
+
+Decides which participants speak next, given the recent turns and the
+participant roster.
+
+```ts
+interface Dispatcher {
+  readonly kind: string
+  selectNext(input: DispatcherInput): Promise<readonly ParticipantId[]>
+}
+```
+
+Reference adapter: `MentionDispatcher` — selects participants whose
+`displayName` is `@-mentioned` in the most recent turn. Tracks an
+in-memory cursor so it doesn't re-fire on the same trigger across
+cycles.
+
+Other implementations: round-robin, topic-routed, LLM-decided. The
+dispatcher is the pluggable "who speaks next?" decision.
+
+### `ParticipantExecutor`
+
+Produces a turn for a given participant when the dispatcher selects
+them.
+
+```ts
+interface ParticipantExecutor {
+  readonly kind: string
+  executeTurn(input: ParticipantExecuteInput): Promise<ParticipantExecuteOutput>
+}
+```
+
+Reference adapter: `AgentCliParticipant` — spawns a CLI binary (`claude
+--print`, `hermes -p`, etc.), pipes the assembled prompt over stdin,
+returns parsed stdout as the turn body.
+
+Other implementations: in-process LLM SDK calls, server-side delegation
+(e.g. MCP `run_operator`), webhook-driven external workers.
+
+Each participant in the manifest declares an `executor` kind; the
+runtime keeps one executor instance per kind, shared across
+participants of that kind.
+
+### `StateStore`
+
+Per-participant scratch state, persisted across turns.
+
+```ts
+interface StateStore {
+  readonly kind: string
+  read(participantId: ParticipantId): Promise<Readonly<Record<string, unknown>>>
+  write(participantId: ParticipantId, state: Readonly<Record<string, unknown>>): Promise<void>
+}
+```
+
+Reference adapter: `FileStateStore` — one JSON file per participant.
+
+The state is what the executor returns in `stateUpdate`; the kernel
+writes it after the substrate append. Useful for executors that
+maintain working memory between turns (counters, scratchpads,
+operator-context summaries).
+
+### `Lifecycle` (optional)
+
+Sparse hooks fired at the edges of a cycle. Adapters opt in by
+implementing some/all callbacks.
+
+```ts
+interface Lifecycle {
+  onTurnEnd?(turn: Turn): Promise<void> | void
+  onMention?(target: ParticipantId, byTurn: Turn): Promise<void> | void
+  onIdle?(): Promise<void> | void
+}
+```
+
+Useful for: domain hooks where the caller needs to react to a turn
+(e.g. mirror it elsewhere). For structured observability of every
+phase boundary, use the `Telemetry` port below instead.
+
+### `Telemetry` (optional)
+
+A single sink for structured per-phase events:
+
+```ts
+interface Telemetry {
+  emit(event: TelemetryEvent): void
+}
+```
+
+Every event carries `cycleId` + `at`; sinks group on cycleId to
+rebuild OTEL-style spans. Event kinds emitted per cycle:
+`cycle.started`, `substrate.read`, `dispatch.decided`,
+`participant.started`/`finished`/`failed`, `substrate.appended`,
+`state.written`, `cycle.idle`, `cycle.finished`.
+
+Reference adapters in
+`@agentproto/agent-runtime/adapters/telemetry`:
+
+- `noopTelemetry` — silent default
+- `stderrTelemetry({ prefix?, include?, exclude? })` — one human-readable line per event
+- `arrayTelemetry()` — in-memory, for tests
+- `composeTelemetry(...sinks)` — fan-out
+
+Wire your own (OTEL exporter, JSON-lines log, metrics counter, …) by
+implementing the interface. Sinks that throw are isolated — kernel
+never crashes a cycle on a telemetry failure.
+
+## Composition
+
+`RuntimePorts` is the tuple the kernel runs against:
+
+```ts
+type RuntimePorts = {
+  substrate: Substrate
+  dispatcher: Dispatcher
+  state: StateStore
+  lifecycle?: Lifecycle
+  participants: readonly ParticipantDescriptor[]
+  executors: ReadonlyMap<string, ParticipantExecutor>
+}
+```
+
+Built by the caller. The reference path is `@agentproto/cli`'s
+`run-swarm` verb — it reads a manifest, looks up each `kind` in the
+runtime registry (`@agentproto/cli/registry/runtime`), and builds the
+ports tuple. The kernel itself never matches `kind` strings; that
+happens in the wiring layer.
+
+## Manifest
+
+Markdown with YAML frontmatter (the same doctype convention
+`@agentproto` uses elsewhere):
+
+```yaml
+---
+schema: agentruntimes/v1
+kind: MultiAgentRuntime
+id: my-swarm
+participants:
+  - id: reviewer
+    executor: agent-cli
+    displayName: Reviewer
+    role: ../.claude/agents/reviewer.md
+substrate:
+  kind: file
+  path: ./conversation.md
+dispatcher:
+  kind: mention
+state:
+  kind: fs
+  dir: ./state
+---
+
+Free-form documentation of what this swarm does.
+```
+
+Each adapter block (`substrate`, `dispatcher`, `state`) carries a
+`kind` plus arbitrary host-extension fields. The validating zod schema
+(`manifest.ts`) uses `.loose()` on the adapter blocks — the kind's
+factory reads its own typed fields off the block at build time.
+
+## Extension points
+
+### Adding a new substrate / dispatcher / executor / state store
+
+Implement the relevant port interface. Then register through
+`@agentproto/cli/registry/runtime`:
+
+```ts
+// in your-plugin/src/index.ts
+import { registerSubstrate } from "@agentproto/cli/registry/runtime"
+import { MySubstrate } from "./my-substrate.js"
+
+registerSubstrate("my-kind", (cfg, ctx) => {
+  return new MySubstrate({
+    foo: typeof cfg.foo === "string" ? cfg.foo : "default",
+    // …
+  })
+})
+```
+
+Users wire it via `--plugin <your-package>` on `agentproto run-swarm`,
+or by listing it under `plugins[]` in `~/.agentproto/config.json`.
+
+### Adapter context
+
+Each factory receives an `AdapterContext`:
+
+```ts
+interface AdapterContext {
+  readonly baseDir: string                          // manifest's dir
+  registerCleanup(fn: () => Promise<void> | void): void
+}
+```
+
+`registerCleanup` is the place to register teardown for adapters that
+hold disposable resources (MCP clients, sockets, child processes). The
+CLI calls every registered callback in order when the swarm shuts down.
+
+## Invariants
+
+- **The kernel never matches `kind` strings.** It dispatches off the
+  port interface (`substrate.append()`, `executor.executeTurn()`, etc.)
+  and looks executors up in the `executors` map. Kind resolution
+  happens in the wiring layer (the CLI), never in `runtime.ts`.
+- **A single cycle is synchronous-per-step.** Substrate append, state
+  write, lifecycle hooks run sequentially within a cycle. Concurrency
+  across multiple selected participants is intentionally **not**
+  provided by the kernel — adapters can parallelise internally if they
+  want, but the contract is one-by-one.
+- **Failure recovery is the caller's job.** `runTurn` propagates
+  exceptions. The CLI's run-loop catches them and continues; a library
+  user is free to do anything else.
+
+## What is intentionally NOT in scope
+
+- **Tool / effector binding.** The kernel doesn't model "this
+  participant has these tools available." Executors handle that
+  themselves — the agent-cli executor passes whatever flags the CLI
+  needs; an in-process executor wires tools directly. If structured
+  binding becomes useful later, it'd go in `ParticipantDescriptor.meta`
+  or via a future `Effector` port.
+- **Routing across substrates / federation.** One swarm = one
+  substrate. Federation (one operator participating in many
+  conversations) is the caller's composition concern.
+- **Persistence schemas beyond `StateStore`.** Auditing, tracing,
+  evaluation runs — all live outside the kernel.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agentproto contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# @agentproto/agent-runtime
+
+MultiAgentRuntime kernel — a small port/adapter framework for running
+swarms of agents over swappable conversation substrates.
+
+**Status:** alpha.
+
+## What this is
+
+A composition primitive, not a product. The kernel knows nothing
+about specific transports, dispatchers, or executors — it only routes
+through port interfaces. Mode (local file journal, hosted chat,
+MCP-bridged thread, …) is decided entirely by the adapters the caller
+wires in.
+
+## Ports
+
+| Port                  | What it does                                                        |
+| --------------------- | ------------------------------------------------------------------- |
+| `Substrate`           | Append-only conversation store. `append(turn)` + `read(since?)`.    |
+| `Dispatcher`          | Decides which participants speak next given recent turns.           |
+| `ParticipantExecutor` | Produces a turn for a given participant on demand.                  |
+| `StateStore`          | Per-participant scratch state across turns.                         |
+| `Lifecycle`           | Optional hooks: `onTurnEnd`, `onMention`, `onIdle`.                 |
+| `EffectorBinding`     | Optional per-participant tool / MCP bindings (consumer-supplied).   |
+
+A `RuntimePorts` is a tuple of these. `runTurn(ports, options)` runs
+one dispatcher cycle:
+
+```
+read substrate → dispatch → execute selected participants → append → fire lifecycle
+```
+
+Loop it for continuous operation.
+
+## Reference adapters
+
+Shipped in this package under `@agentproto/agent-runtime/adapters/*`:
+
+| Adapter                                              | Kind         | Notes                                              |
+| ---------------------------------------------------- | ------------ | -------------------------------------------------- |
+| `substrate-file`                                     | `file`       | Append-only markdown journal at a given path.      |
+| `dispatcher-mention`                                 | `mention`    | Selects participants @-mentioned in the trigger.   |
+| `state-fs`                                           | `fs`         | One JSON file per participant.                     |
+| `participant-agent-cli`                              | `agent-cli`  | Spawns a CLI binary (`claude --print`, etc.).      |
+
+## Manifest
+
+A `MultiAgentRuntime` manifest is markdown with YAML frontmatter:
+
+```yaml
+---
+schema: agentruntimes/v1
+kind: MultiAgentRuntime
+id: my-swarm
+participants:
+  - id: reviewer
+    executor: agent-cli
+    displayName: Reviewer
+    role: ../.claude/agents/reviewer.md
+substrate:
+  kind: file
+  path: ./conversation.md
+dispatcher:
+  kind: mention
+state:
+  kind: fs
+  dir: ./state
+---
+
+Free-form documentation of what this swarm does.
+```
+
+`@agentproto/cli`'s `run-swarm` verb loads such manifests, resolves
+each `kind` string through its adapter registry, and runs cycles in a
+loop. Third-party adapters register through `@agentproto/cli/registry/runtime`.
+
+## Extending
+
+Implement any of the ports and ship it as your own package. To plug
+into the CLI, export a module that calls `registerSubstrate` /
+`registerDispatcher` / `registerExecutor` from
+`@agentproto/cli/registry/runtime` at load time, then point users at
+it with `--plugin <your-module-id>` or via `~/.agentproto/config.json`.
+
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for the port-by-port walk,
+cycle diagram, and invariants.
+
+## License
+
+MIT.

package/dist/adapters/dispatcher-mention.d.ts

@@ -0,0 +1,38 @@
+import { Dispatcher, DispatcherInput, ParticipantId } from '../ports.js';
+
+/**
+ * Type sidecar for `mention-parser.mjs`. The implementation file is
+ * vanilla JavaScript so runtime profiles can stamp its source into
+ * Claude Code hooks at build time; this `.d.mts` keeps the TS-side
+ * type contract crisp.
+ */
+
+declare function textContainsMention(text: string, name: string): boolean
+
+/**
+ * Mention dispatcher — selects participants whose displayName is
+ * @-mentioned in the most recent turn.
+ *
+ * Skip rules:
+ *   - never re-select the participant who authored the trigger turn
+ *     (otherwise they'd reply to themselves indefinitely)
+ *   - never dispatch on a trigger we already processed (in-memory cursor —
+ *     prevents the loop from re-firing on the same @mention every poll
+ *     when the kernel's own reply isn't yet visible in the next read).
+ *     Per-dispatcher-instance state; a fresh swarm process starts with
+ *     no cursor and naturally responds to the latest unhandled mention
+ *     exactly once.
+ *   - if no mentions match any known participant, return [] (idle)
+ *
+ * The parser itself lives in `../util/mention-parser.mjs` (vanilla JS)
+ * so runtime profiles can stamp the same implementation into Claude
+ * Code hooks at build time without depending on the TS build pipeline.
+ */
+
+declare class MentionDispatcher implements Dispatcher {
+    readonly kind = "mention";
+    private lastProcessedTriggerId;
+    selectNext(input: DispatcherInput): Promise<readonly ParticipantId[]>;
+}
+
+export { MentionDispatcher, textContainsMention };

package/dist/adapters/dispatcher-mention.mjs

@@ -0,0 +1,45 @@
+/**
+ * @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/util/mention-parser.mjs
+function textContainsMention(text, name) {
+  if (text.includes(`@${name}`)) return true;
+  if (name.includes(" ")) {
+    const firstName = name.split(" ")[0]?.trim();
+    if (!firstName) return false;
+    const regex = new RegExp(`@${firstName}(?!\\w)`, "i");
+    return regex.test(text);
+  }
+  return false;
+}
+
+// src/adapters/dispatcher-mention.ts
+var MentionDispatcher = class {
+  kind = "mention";
+  lastProcessedTriggerId;
+  async selectNext(input) {
+    const trigger = input.recentTurns[input.recentTurns.length - 1];
+    if (!trigger) return [];
+    if (trigger.id === this.lastProcessedTriggerId) return [];
+    const text = trigger.content;
+    const selected = [];
+    for (const p of input.participants) {
+      if (p.id === trigger.participantId) continue;
+      if (textContainsMention(text, p.displayName)) {
+        selected.push(p.id);
+      }
+    }
+    if (selected.length > 0) {
+      this.lastProcessedTriggerId = trigger.id;
+    }
+    return selected;
+  }
+};
+
+export { MentionDispatcher, textContainsMention };
+//# sourceMappingURL=dispatcher-mention.mjs.map
+//# sourceMappingURL=dispatcher-mention.mjs.map

package/dist/adapters/dispatcher-mention.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/util/mention-parser.mjs","../../src/adapters/dispatcher-mention.ts"],"names":[],"mappings":";;;;;;;;AAuBO,SAAS,mBAAA,CAAoB,MAAM,IAAA,EAAM;AAC9C,EAAA,IAAI,KAAK,QAAA,CAAS,CAAA,CAAA,EAAI,IAAI,CAAA,CAAE,GAAG,OAAO,IAAA;AACtC,EAAA,IAAI,IAAA,CAAK,QAAA,CAAS,GAAG,CAAA,EAAG;AACtB,IAAA,MAAM,YAAY,IAAA,CAAK,KAAA,CAAM,GAAG,CAAA,CAAE,CAAC,GAAG,IAAA,EAAK;AAC3C,IAAA,IAAI,CAAC,WAAW,OAAO,KAAA;AACvB,IAAA,MAAM,QAAQ,IAAI,MAAA,CAAO,CAAA,CAAA,EAAI,SAAS,WAAW,GAAG,CAAA;AACpD,IAAA,OAAO,KAAA,CAAM,KAAK,IAAI,CAAA;AAAA,EACxB;AACA,EAAA,OAAO,KAAA;AACT;;;ACJO,IAAM,oBAAN,MAA8C;AAAA,EAC1C,IAAA,GAAO,SAAA;AAAA,EACR,sBAAA;AAAA,EAER,MAAM,WAAW,KAAA,EAA2D;AAC1E,IAAA,MAAM,UAAU,KAAA,CAAM,WAAA,CAAY,KAAA,CAAM,WAAA,CAAY,SAAS,CAAC,CAAA;AAC9D,IAAA,IAAI,CAAC,OAAA,EAAS,OAAO,EAAC;AACtB,IAAA,IAAI,OAAA,CAAQ,EAAA,KAAO,IAAA,CAAK,sBAAA,SAA+B,EAAC;AACxD,IAAA,MAAM,OAAO,OAAA,CAAQ,OAAA;AAErB,IAAA,MAAM,WAA4B,EAAC;AACnC,IAAA,KAAA,MAAW,CAAA,IAAK,MAAM,YAAA,EAAc;AAClC,MAAA,IAAI,CAAA,CAAE,EAAA,KAAO,OAAA,CAAQ,aAAA,EAAe;AACpC,MAAA,IAAI,mBAAA,CAAoB,IAAA,EAAM,CAAA,CAAE,WAAW,CAAA,EAAG;AAC5C,QAAA,QAAA,CAAS,IAAA,CAAK,EAAE,EAAE,CAAA;AAAA,MACpB;AAAA,IACF;AAEA,IAAA,IAAI,QAAA,CAAS,SAAS,CAAA,EAAG;AACvB,MAAA,IAAA,CAAK,yBAAyB,OAAA,CAAQ,EAAA;AAAA,IACxC;AACA,IAAA,OAAO,QAAA;AAAA,EACT;AACF","file":"dispatcher-mention.mjs","sourcesContent":["/**\n * Canonical @-mention parser.\n *\n * Lives as raw JavaScript (no types) because it's consumed in two\n * places that don't share a build:\n *\n *   1. The kernel imports `textContainsMention` from this file as a\n *      normal ESM module (the dispatcher in `adapters/dispatcher-mention.ts`).\n *\n *   2. Runtime profiles inline this file's source into Claude Code\n *      hooks at profile-build time, because `.claude/` has no\n *      module-resolution at hook-execution time. The build script\n *      reads this file as text and stamps it into the hook template.\n *\n * Two cases:\n *   1. Literal `@<name>` substring (case-sensitive, full name).\n *   2. For multi-word names, also `@<firstName>` with non-word\n *      boundary (case-insensitive).\n *\n * Edit here only — both consumers stay in sync via build pipelines.\n */\n\n/** @param {string} text @param {string} name @returns {boolean} */\nexport function textContainsMention(text, name) {\n  if (text.includes(`@${name}`)) return true\n  if (name.includes(\" \")) {\n    const firstName = name.split(\" \")[0]?.trim()\n    if (!firstName) return false\n    const regex = new RegExp(`@${firstName}(?!\\\\w)`, \"i\")\n    return regex.test(text)\n  }\n  return false\n}\n","/**\n * Mention dispatcher — selects participants whose displayName is\n * @-mentioned in the most recent turn.\n *\n * Skip rules:\n *   - never re-select the participant who authored the trigger turn\n *     (otherwise they'd reply to themselves indefinitely)\n *   - never dispatch on a trigger we already processed (in-memory cursor —\n *     prevents the loop from re-firing on the same @mention every poll\n *     when the kernel's own reply isn't yet visible in the next read).\n *     Per-dispatcher-instance state; a fresh swarm process starts with\n *     no cursor and naturally responds to the latest unhandled mention\n *     exactly once.\n *   - if no mentions match any known participant, return [] (idle)\n *\n * The parser itself lives in `../util/mention-parser.mjs` (vanilla JS)\n * so runtime profiles can stamp the same implementation into Claude\n * Code hooks at build time without depending on the TS build pipeline.\n */\n\nimport type {\n  Dispatcher,\n  DispatcherInput,\n  ParticipantId,\n  TurnId,\n} from \"../ports.js\"\nimport { textContainsMention } from \"../util/mention-parser.mjs\"\n\nexport class MentionDispatcher implements Dispatcher {\n  readonly kind = \"mention\"\n  private lastProcessedTriggerId: TurnId | undefined\n\n  async selectNext(input: DispatcherInput): Promise<readonly ParticipantId[]> {\n    const trigger = input.recentTurns[input.recentTurns.length - 1]\n    if (!trigger) return []\n    if (trigger.id === this.lastProcessedTriggerId) return []\n    const text = trigger.content\n\n    const selected: ParticipantId[] = []\n    for (const p of input.participants) {\n      if (p.id === trigger.participantId) continue\n      if (textContainsMention(text, p.displayName)) {\n        selected.push(p.id)\n      }\n    }\n\n    if (selected.length > 0) {\n      this.lastProcessedTriggerId = trigger.id\n    }\n    return selected\n  }\n}\n\n// Re-exported so callers writing their own adapters can detect\n// mentions with identical semantics.\nexport { textContainsMention }\n"]}

package/dist/adapters/participant-agent-cli.d.ts

@@ -0,0 +1,32 @@
+import { ParticipantExecutor, ParticipantExecuteInput, ParticipantExecuteOutput } from '../ports.js';
+export { parseClaudeJsonOutput } from '@agentproto/cli-exec';
+
+/**
+ * Agent-CLI participant — spawns a CLI binary, pipes the assembled prompt
+ * over stdin, and uses captured stdout as the turn content.
+ *
+ * Works for any CLI that supports a one-shot "read prompt from stdin,
+ * print response to stdout" mode (claude-code's `--print`, hermes' `-p`,
+ * etc.).
+ */
+
+type AgentCliParticipantOptions = {
+    /** Executable to invoke. Examples: "claude", "hermes", "goose". */
+    readonly command: string;
+    /** Static args. The prompt is fed over stdin, not as an argument. */
+    readonly args?: readonly string[];
+    /** Working directory. Defaults to process.cwd(). */
+    readonly cwd?: string;
+    /** Hard timeout in ms. Default 90000. */
+    readonly timeoutMs?: number;
+    /** Optional output parser — if returns null, content falls back to raw stdout. */
+    readonly parseOutput?: (stdout: string) => string | null;
+};
+declare class AgentCliParticipant implements ParticipantExecutor {
+    private readonly opts;
+    readonly kind = "agent-cli";
+    constructor(opts: AgentCliParticipantOptions);
+    executeTurn(input: ParticipantExecuteInput): Promise<ParticipantExecuteOutput>;
+}
+
+export { AgentCliParticipant, type AgentCliParticipantOptions };

package/dist/adapters/participant-agent-cli.mjs

@@ -0,0 +1,72 @@
+import { readFile } from 'fs/promises';
+import matter from 'gray-matter';
+import { spawnWithStdin } from '@agentproto/cli-exec';
+export { parseClaudeJsonOutput } from '@agentproto/cli-exec';
+
+/**
+ * @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 AgentCliParticipant = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  opts;
+  kind = "agent-cli";
+  async executeTurn(input) {
+    const prompt = await assemblePrompt(input);
+    const stdout = await spawnWithStdin({
+      command: this.opts.command,
+      args: this.opts.args ?? [],
+      cwd: this.opts.cwd ?? process.cwd(),
+      timeoutMs: this.opts.timeoutMs ?? 9e4,
+      stdin: prompt,
+      signal: input.signal
+    });
+    const parsed = this.opts.parseOutput?.(stdout) ?? null;
+    const content = parsed ?? stdout.trimEnd();
+    return { content };
+  }
+};
+async function assemblePrompt(input) {
+  const roleText = input.participant.role ? await loadRole(input.participant.role) : "";
+  const transcript = input.recentTurns.map((t) => `[${t.participantId}] ${t.content}`).join("\n\n");
+  return [
+    roleText && `# Your role
+
+${roleText}`,
+    `# Recent conversation
+
+${transcript}`,
+    `# Your turn
+
+You are ${input.participant.displayName}. The latest message in the conversation triggered you (most likely because it mentions you). Read the transcript above and reply in character. Keep it conversational unless the trigger asks for detailed work. Output only your reply \u2014 no preamble, no role labels, no quotes around the response.`
+  ].filter(Boolean).join("\n\n");
+}
+var ROLE_FILE_EXTENSIONS = [".md", ".markdown", ".txt"];
+async function loadRole(roleField) {
+  if (!looksLikeRoleFile(roleField)) return roleField;
+  try {
+    const raw = await readFile(roleField, "utf8");
+    const parsed = matter(raw);
+    return parsed.content.trim();
+  } catch (err) {
+    const code = err.code;
+    process.stderr.write(
+      `agent-cli participant: role path '${roleField}' not readable (${code ?? "unknown"}); using the literal string as inline role text.
+`
+    );
+    return roleField;
+  }
+}
+function looksLikeRoleFile(s) {
+  const lower = s.toLowerCase();
+  return ROLE_FILE_EXTENSIONS.some((ext) => lower.endsWith(ext));
+}
+
+export { AgentCliParticipant };
+//# sourceMappingURL=participant-agent-cli.mjs.map
+//# sourceMappingURL=participant-agent-cli.mjs.map

package/dist/adapters/participant-agent-cli.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/participant-agent-cli.ts"],"names":[],"mappings":";;;;;;;;;;;;AAmCO,IAAM,sBAAN,MAAyD;AAAA,EAG9D,YAA6B,IAAA,EAAkC;AAAlC,IAAA,IAAA,CAAA,IAAA,GAAA,IAAA;AAAA,EAAmC;AAAA,EAAnC,IAAA;AAAA,EAFpB,IAAA,GAAO,WAAA;AAAA,EAIhB,MAAM,YACJ,KAAA,EACmC;AACnC,IAAA,MAAM,MAAA,GAAS,MAAM,cAAA,CAAe,KAAK,CAAA;AACzC,IAAA,MAAM,MAAA,GAAS,MAAM,cAAA,CAAe;AAAA,MAClC,OAAA,EAAS,KAAK,IAAA,CAAK,OAAA;AAAA,MACnB,IAAA,EAAM,IAAA,CAAK,IAAA,CAAK,IAAA,IAAQ,EAAC;AAAA,MACzB,GAAA,EAAK,IAAA,CAAK,IAAA,CAAK,GAAA,IAAO,QAAQ,GAAA,EAAI;AAAA,MAClC,SAAA,EAAW,IAAA,CAAK,IAAA,CAAK,SAAA,IAAa,GAAA;AAAA,MAClC,KAAA,EAAO,MAAA;AAAA,MACP,QAAQ,KAAA,CAAM;AAAA,KACf,CAAA;AACD,IAAA,MAAM,MAAA,GAAS,IAAA,CAAK,IAAA,CAAK,WAAA,GAAc,MAAM,CAAA,IAAK,IAAA;AAClD,IAAA,MAAM,OAAA,GAAU,MAAA,IAAU,MAAA,CAAO,OAAA,EAAQ;AACzC,IAAA,OAAO,EAAE,OAAA,EAAQ;AAAA,EACnB;AACF;AAEA,eAAe,eACb,KAAA,EACiB;AACjB,EAAA,MAAM,QAAA,GAAW,MAAM,WAAA,CAAY,IAAA,GAC/B,MAAM,QAAA,CAAS,KAAA,CAAM,WAAA,CAAY,IAAI,CAAA,GACrC,EAAA;AAEJ,EAAA,MAAM,UAAA,GAAa,KAAA,CAAM,WAAA,CACtB,GAAA,CAAI,CAAC,CAAA,KAAM,CAAA,CAAA,EAAI,CAAA,CAAE,aAAa,KAAK,CAAA,CAAE,OAAO,CAAA,CAAE,CAAA,CAC9C,KAAK,MAAM,CAAA;AAEd,EAAA,OAAO;AAAA,IACL,QAAA,IAAY,CAAA;;AAAA,EAAkB,QAAQ,CAAA,CAAA;AAAA,IACtC,CAAA;;AAAA,EAA4B,UAAU,CAAA,CAAA;AAAA,IACtC,CAAA;;AAAA,QAAA,EAA0B,KAAA,CAAM,YAAY,WAAW,CAAA,2SAAA;AAAA,GACzD,CACG,MAAA,CAAO,OAAO,CAAA,CACd,KAAK,MAAM,CAAA;AAChB;AAKA,IAAM,oBAAA,GAAuB,CAAC,KAAA,EAAO,WAAA,EAAa,MAAM,CAAA;AAExD,eAAe,SAAS,SAAA,EAAoC;AAC1D,EAAA,IAAI,CAAC,iBAAA,CAAkB,SAAS,CAAA,EAAG,OAAO,SAAA;AAC1C,EAAA,IAAI;AACF,IAAA,MAAM,GAAA,GAAM,MAAM,QAAA,CAAS,SAAA,EAAW,MAAM,CAAA;AAI5C,IAAA,MAAM,MAAA,GAAS,OAAO,GAAG,CAAA;AACzB,IAAA,OAAO,MAAA,CAAO,QAAQ,IAAA,EAAK;AAAA,EAC7B,SAAS,GAAA,EAAK;AAKZ,IAAA,MAAM,OAAQ,GAAA,CAA8B,IAAA;AAC5C,IAAA,OAAA,CAAQ,MAAA,CAAO,KAAA;AAAA,MACb,CAAA,kCAAA,EAAqC,SAAS,CAAA,gBAAA,EAAmB,IAAA,IAAQ,SAAS,CAAA;AAAA;AAAA,KACpF;AACA,IAAA,OAAO,SAAA;AAAA,EACT;AACF;AAEA,SAAS,kBAAkB,CAAA,EAAoB;AAC7C,EAAA,MAAM,KAAA,GAAQ,EAAE,WAAA,EAAY;AAC5B,EAAA,OAAO,qBAAqB,IAAA,CAAK,CAAC,QAAQ,KAAA,CAAM,QAAA,CAAS,GAAG,CAAC,CAAA;AAC/D","file":"participant-agent-cli.mjs","sourcesContent":["/**\n * Agent-CLI participant — spawns a CLI binary, pipes the assembled prompt\n * over stdin, and uses captured stdout as the turn content.\n *\n * Works for any CLI that supports a one-shot \"read prompt from stdin,\n * print response to stdout\" mode (claude-code's `--print`, hermes' `-p`,\n * etc.).\n */\n\nimport { readFile } from \"node:fs/promises\"\nimport matter from \"gray-matter\"\nimport { spawnWithStdin } from \"@agentproto/cli-exec\"\nimport type {\n  ParticipantExecuteInput,\n  ParticipantExecuteOutput,\n  ParticipantExecutor,\n} from \"../ports.js\"\n\n// Re-exported for back-compat: the JSON-envelope parser now lives in the shared\n// @agentproto/cli-exec package alongside the spawn helper.\nexport { parseClaudeJsonOutput } from \"@agentproto/cli-exec\"\n\nexport type AgentCliParticipantOptions = {\n  /** Executable to invoke. Examples: \"claude\", \"hermes\", \"goose\". */\n  readonly command: string\n  /** Static args. The prompt is fed over stdin, not as an argument. */\n  readonly args?: readonly string[]\n  /** Working directory. Defaults to process.cwd(). */\n  readonly cwd?: string\n  /** Hard timeout in ms. Default 90000. */\n  readonly timeoutMs?: number\n  /** Optional output parser — if returns null, content falls back to raw stdout. */\n  readonly parseOutput?: (stdout: string) => string | null\n}\n\nexport class AgentCliParticipant implements ParticipantExecutor {\n  readonly kind = \"agent-cli\"\n\n  constructor(private readonly opts: AgentCliParticipantOptions) {}\n\n  async executeTurn(\n    input: ParticipantExecuteInput\n  ): Promise<ParticipantExecuteOutput> {\n    const prompt = await assemblePrompt(input)\n    const stdout = await spawnWithStdin({\n      command: this.opts.command,\n      args: this.opts.args ?? [],\n      cwd: this.opts.cwd ?? process.cwd(),\n      timeoutMs: this.opts.timeoutMs ?? 90000,\n      stdin: prompt,\n      signal: input.signal,\n    })\n    const parsed = this.opts.parseOutput?.(stdout) ?? null\n    const content = parsed ?? stdout.trimEnd()\n    return { content }\n  }\n}\n\nasync function assemblePrompt(\n  input: ParticipantExecuteInput\n): Promise<string> {\n  const roleText = input.participant.role\n    ? await loadRole(input.participant.role)\n    : \"\"\n\n  const transcript = input.recentTurns\n    .map((t) => `[${t.participantId}] ${t.content}`)\n    .join(\"\\n\\n\")\n\n  return [\n    roleText && `# Your role\\n\\n${roleText}`,\n    `# Recent conversation\\n\\n${transcript}`,\n    `# Your turn\\n\\nYou are ${input.participant.displayName}. The latest message in the conversation triggered you (most likely because it mentions you). Read the transcript above and reply in character. Keep it conversational unless the trigger asks for detailed work. Output only your reply — no preamble, no role labels, no quotes around the response.`,\n  ]\n    .filter(Boolean)\n    .join(\"\\n\\n\")\n}\n\n// File extensions we treat as a path-to-role-file. Anything else is\n// inline role text — even strings that contain `/`, which are common\n// in normal sentences (\"I am an AI/ML reviewer\").\nconst ROLE_FILE_EXTENSIONS = [\".md\", \".markdown\", \".txt\"]\n\nasync function loadRole(roleField: string): Promise<string> {\n  if (!looksLikeRoleFile(roleField)) return roleField\n  try {\n    const raw = await readFile(roleField, \"utf8\")\n    // Strip optional YAML frontmatter — lets a Claude Code agent\n    // definition file (.claude/agents/*.md) double as a swarm role\n    // without ferrying the agent's metadata into the prompt.\n    const parsed = matter(raw)\n    return parsed.content.trim()\n  } catch (err) {\n    // The string had a role-file extension but the file isn't readable\n    // — surface a hint on stderr so authors don't silently get the\n    // literal path as a prompt. Still fall back to inline so the swarm\n    // doesn't crash on a typo.\n    const code = (err as NodeJS.ErrnoException).code\n    process.stderr.write(\n      `agent-cli participant: role path '${roleField}' not readable (${code ?? \"unknown\"}); using the literal string as inline role text.\\n`\n    )\n    return roleField\n  }\n}\n\nfunction looksLikeRoleFile(s: string): boolean {\n  const lower = s.toLowerCase()\n  return ROLE_FILE_EXTENSIONS.some((ext) => lower.endsWith(ext))\n}\n"]}

package/dist/adapters/state-fs.d.ts

@@ -0,0 +1,25 @@
+import { StateStore, ParticipantId } from '../ports.js';
+
+/**
+ * Filesystem state store — one JSON file per participant.
+ *
+ *   <stateDir>/<participantId>.json
+ *
+ * Missing files read as {}. Writes are full overwrites; callers
+ * pass the merged state, the adapter doesn't merge on its own.
+ */
+
+type FileStateStoreOptions = {
+    /** Directory to hold the per-participant JSON files. */
+    readonly dir: string;
+};
+declare class FileStateStore implements StateStore {
+    private readonly opts;
+    readonly kind = "fs";
+    constructor(opts: FileStateStoreOptions);
+    read(participantId: ParticipantId): Promise<Readonly<Record<string, unknown>>>;
+    write(participantId: ParticipantId, state: Readonly<Record<string, unknown>>): Promise<void>;
+    private pathFor;
+}
+
+export { FileStateStore, type FileStateStoreOptions };