@runravel/ravel 0.1.0

package/src/control-plane/registry.ts

@@ -0,0 +1,294 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { parseAgentSpec, type AgentSpec } from "../schemas/agent.js";
+import { parseToolsConfig, EMPTY_TOOLS_CONFIG, type ToolsConfig } from "../schemas/tools.js";
+import { parseProcessSpec, type ProcessSpec } from "../schemas/process.js";
+
+/**
+ * The compiled, immutable representation of one agent folder.
+ *
+ * Folder position defines the *escalation/permission tree* (parent ← manager,
+ * children → direct reports), not the execution flow. Execution is driven by
+ * processes and the orchestrator. `id` is a stable, path-derived identifier so
+ * the same folder keeps the same id across recompiles.
+ */
+export interface RegistryNode {
+  /** Stable id derived from the path relative to the org root (POSIX slashes). Root is "". */
+  id: string;
+  /** Absolute path to the agent folder. */
+  dir: string;
+  spec: AgentSpec;
+  tools: ToolsConfig;
+  parentId: string | null;
+  childIds: string[];
+  /** Processes authored at this node's `processes/` directory. */
+  processes: ProcessSpec[];
+  /**
+   * Root-relative path to this node's `plugin.ts`, if present. Compile only
+   * RECORDS the path — it never imports team code. The platform loads it later.
+   */
+  pluginPath?: string;
+}
+
+/** A process plus the node id that owns its execution. */
+export interface RegistryProcess {
+  spec: ProcessSpec;
+  /** Node that authored the process file. */
+  definedAtNodeId: string;
+  /** Node resolved from `spec.owner` that will decompose & dispatch it. */
+  ownerNodeId: string;
+  /** The process file's path, relative to the org root (for the config editor). */
+  path: string;
+}
+
+export interface Diagnostic {
+  /** Path (file or dir) the problem relates to, relative to the org root. */
+  where: string;
+  message: string;
+}
+
+/**
+ * An immutable snapshot of the whole org. The watcher builds a new snapshot on
+ * every change; the lifecycle manager diffs snapshots to drain/spawn agents.
+ * Editing a folder never mutates a running agent directly — it produces a new
+ * snapshot that is swapped in deliberately.
+ */
+export interface RegistrySnapshot {
+  /** Monotonic version assigned by the compiler caller. */
+  version: number;
+  /** Absolute org root path. */
+  root: string;
+  rootId: string;
+  nodes: ReadonlyMap<string, RegistryNode>;
+  /** All processes across the org, with owners resolved. */
+  processes: readonly RegistryProcess[];
+}
+
+export interface CompileResult {
+  ok: boolean;
+  snapshot: RegistrySnapshot | null;
+  diagnostics: Diagnostic[];
+}
+
+const AGENT_FILE = "agent.md";
+const TOOLS_FILE = "tools.json";
+const PROCESS_DIR = "processes";
+const PROCESS_SUFFIX = ".process.md";
+const PLUGIN_FILE = "plugin.ts";
+
+function toNodeId(root: string, dir: string): string {
+  const rel = path.relative(root, dir);
+  return rel.split(path.sep).join("/"); // "" for root
+}
+
+function describeError(err: unknown): string {
+  if (err && typeof err === "object" && "issues" in err) {
+    // ZodError — flatten to a compact, readable list.
+    const issues = (err as { issues: Array<{ path: (string | number)[]; message: string }> }).issues;
+    return issues
+      .map((i) => (i.path.length ? `${i.path.join(".")}: ${i.message}` : i.message))
+      .join("; ");
+  }
+  return err instanceof Error ? err.message : String(err);
+}
+
+/** Is this directory an agent node? (contains an agent.md) */
+async function hasAgentFile(dir: string): Promise<boolean> {
+  try {
+    await fs.access(path.join(dir, AGENT_FILE));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+interface ScanContext {
+  root: string;
+  nodes: Map<string, RegistryNode>;
+  diagnostics: Diagnostic[];
+  /** definedAt + spec, owner resolved in a second pass once all nodes exist. */
+  pendingProcesses: Array<{ spec: ProcessSpec; definedAtNodeId: string; where: string }>;
+}
+
+async function readProcesses(
+  dir: string,
+  ctx: ScanContext,
+  nodeId: string,
+): Promise<ProcessSpec[]> {
+  const procDir = path.join(dir, PROCESS_DIR);
+  let entries: string[];
+  try {
+    entries = (await fs.readdir(procDir)).filter((f) => f.endsWith(PROCESS_SUFFIX));
+  } catch {
+    return []; // no processes/ dir is fine
+  }
+  entries.sort(); // deterministic ordering — stable cache keys downstream
+  const result: ProcessSpec[] = [];
+  for (const file of entries) {
+    const full = path.join(procDir, file);
+    const rel = toNodeId(ctx.root, full);
+    try {
+      const spec = parseProcessSpec(await fs.readFile(full, "utf8"));
+      result.push(spec);
+      ctx.pendingProcesses.push({ spec, definedAtNodeId: nodeId, where: rel });
+    } catch (err) {
+      ctx.diagnostics.push({ where: rel, message: describeError(err) });
+    }
+  }
+  return result;
+}
+
+async function scanNode(
+  dir: string,
+  parentId: string | null,
+  ctx: ScanContext,
+): Promise<string | null> {
+  const id = toNodeId(ctx.root, dir);
+  const relDir = id || ".";
+
+  // Parse agent.md
+  let spec: AgentSpec;
+  try {
+    spec = parseAgentSpec(await fs.readFile(path.join(dir, AGENT_FILE), "utf8"));
+  } catch (err) {
+    ctx.diagnostics.push({ where: path.join(relDir, AGENT_FILE), message: describeError(err) });
+    return null; // node invalid; do not register
+  }
+
+  // Parse tools.json (optional)
+  let tools: ToolsConfig = EMPTY_TOOLS_CONFIG;
+  try {
+    const raw = await fs.readFile(path.join(dir, TOOLS_FILE), "utf8");
+    tools = parseToolsConfig(raw);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+      ctx.diagnostics.push({ where: path.join(relDir, TOOLS_FILE), message: describeError(err) });
+      // Tools invalid is a hard error for the node — running with the wrong
+      // permission surface is unsafe. Drop the node.
+      return null;
+    }
+  }
+
+  const processes = await readProcesses(dir, ctx, id);
+
+  // Detect an optional team plugin (record its path only; never import at compile).
+  let pluginPath: string | undefined;
+  try {
+    await fs.access(path.join(dir, PLUGIN_FILE));
+    pluginPath = toNodeId(ctx.root, path.join(dir, PLUGIN_FILE)); // root-relative
+  } catch {
+    /* no plugin.ts — fine */
+  }
+
+  // Recurse into child folders that contain an agent.md.
+  const childIds: string[] = [];
+  const dirents = await fs.readdir(dir, { withFileTypes: true });
+  const childDirs = dirents
+    .filter((d) => d.isDirectory() && d.name !== PROCESS_DIR && !d.name.startsWith("."))
+    .map((d) => path.join(dir, d.name))
+    .sort(); // deterministic
+
+  // Register this node before recursing so children can reference parentId.
+  ctx.nodes.set(id, { id, dir, spec, tools, parentId, childIds, processes, ...(pluginPath ? { pluginPath } : {}) });
+
+  for (const child of childDirs) {
+    if (await hasAgentFile(child)) {
+      const childId = await scanNode(child, id, ctx);
+      if (childId !== null) childIds.push(childId);
+    }
+  }
+  return id;
+}
+
+/**
+ * Resolve a process's `owner` role string to a node id.
+ * Resolution order (first match wins, case-insensitive): node id, role, name.
+ * The owner must be the defining node or one of its descendants — a process
+ * cannot dispatch work to an unrelated branch of the org.
+ */
+function resolveOwner(
+  ownerRef: string,
+  definedAtNodeId: string,
+  nodes: Map<string, RegistryNode>,
+): { ok: true; nodeId: string } | { ok: false; reason: string } {
+  const needle = ownerRef.trim().toLowerCase();
+  const inScope = (id: string): boolean =>
+    id === definedAtNodeId ||
+    id.startsWith(definedAtNodeId === "" ? "" : `${definedAtNodeId}/`);
+
+  const matches: string[] = [];
+  for (const node of nodes.values()) {
+    if (!inScope(node.id)) continue;
+    const candidates = [node.id, node.spec.role ?? "", node.spec.name].map((s) =>
+      s.toLowerCase(),
+    );
+    if (candidates.includes(needle)) matches.push(node.id);
+  }
+
+  if (matches.length === 0) {
+    return { ok: false, reason: `owner "${ownerRef}" did not resolve to any agent in scope` };
+  }
+  if (matches.length > 1) {
+    return {
+      ok: false,
+      reason: `owner "${ownerRef}" is ambiguous (matched ${matches.join(", ")})`,
+    };
+  }
+  return { ok: true, nodeId: matches[0]! };
+}
+
+/**
+ * Compile an org folder tree into an immutable RegistrySnapshot.
+ *
+ * On any validation error the result is `ok: false` with diagnostics and a
+ * null snapshot — the caller keeps the last-good snapshot live. The `version`
+ * is supplied by the caller (the watcher owns the monotonic counter).
+ */
+export async function compileRegistry(root: string, version: number): Promise<CompileResult> {
+  const absRoot = path.resolve(root);
+  const diagnostics: Diagnostic[] = [];
+
+  if (!(await hasAgentFile(absRoot))) {
+    diagnostics.push({
+      where: ".",
+      message: `org root has no ${AGENT_FILE} — the root folder must define the top-level agent`,
+    });
+    return { ok: false, snapshot: null, diagnostics };
+  }
+
+  const ctx: ScanContext = { root: absRoot, nodes: new Map(), diagnostics, pendingProcesses: [] };
+  const rootId = await scanNode(absRoot, null, ctx);
+
+  if (rootId === null) {
+    return { ok: false, snapshot: null, diagnostics };
+  }
+
+  // Second pass: resolve process owners now that all nodes exist.
+  const processes: RegistryProcess[] = [];
+  for (const pending of ctx.pendingProcesses) {
+    const resolved = resolveOwner(pending.spec.owner, pending.definedAtNodeId, ctx.nodes);
+    if (!resolved.ok) {
+      diagnostics.push({ where: pending.where, message: resolved.reason });
+      continue;
+    }
+    processes.push({
+      spec: pending.spec,
+      definedAtNodeId: pending.definedAtNodeId,
+      ownerNodeId: resolved.nodeId,
+      path: pending.where,
+    });
+  }
+
+  if (diagnostics.length > 0) {
+    return { ok: false, snapshot: null, diagnostics };
+  }
+
+  const snapshot: RegistrySnapshot = {
+    version,
+    root: absRoot,
+    rootId,
+    nodes: ctx.nodes,
+    processes,
+  };
+  return { ok: true, snapshot, diagnostics: [] };
+}

package/src/control-plane/watcher.ts

@@ -0,0 +1,132 @@
+import chokidar, { type FSWatcher, type ChokidarOptions } from "chokidar";
+import { EventEmitter } from "node:events";
+import { compileRegistry, type CompileResult, type RegistrySnapshot, type Diagnostic } from "./registry.js";
+
+export interface WatcherEvents {
+  /** A new valid snapshot was compiled and is now current. */
+  snapshot: (snapshot: RegistrySnapshot) => void;
+  /** A compile failed; the previous snapshot (if any) stays current. */
+  invalid: (diagnostics: Diagnostic[], lastGood: RegistrySnapshot | null) => void;
+}
+
+/**
+ * Watches an org folder and compiles it into versioned snapshots on change.
+ *
+ * Design choices that follow from the architecture:
+ * - The folder is the *authoring source of truth*; this watcher is the
+ *   compile step that turns it into a runtime artifact. Nothing mutates a
+ *   running agent directly.
+ * - Versions are monotonic and owned here, so downstream (lifecycle) can diff.
+ * - A failed compile never clobbers the last-good snapshot — invalid trees are
+ *   surfaced as diagnostics and the running org keeps going.
+ * - Changes are debounced so a multi-file save produces one recompile.
+ */
+export class RegistryWatcher extends EventEmitter {
+  private readonly root: string;
+  private readonly debounceMs: number;
+  private readonly watchOptions: Partial<ChokidarOptions>;
+  private version = 0;
+  private lastGood: RegistrySnapshot | null = null;
+  private watcher: FSWatcher | null = null;
+  private timer: NodeJS.Timeout | null = null;
+  private compiling = false;
+  private pending = false;
+
+  constructor(root: string, opts: { debounceMs?: number; watchOptions?: Partial<ChokidarOptions> } = {}) {
+    super();
+    this.root = root;
+    this.debounceMs = opts.debounceMs ?? 150;
+    // Polling is more reliable than fsevents/inotify under heavy parallel load
+    // (e.g. test workers) and across network/container filesystems. Callers can
+    // opt into it; the default uses the native backend for efficiency.
+    this.watchOptions = opts.watchOptions ?? {};
+  }
+
+  /** Compile once without starting the watcher. Returns the result. */
+  async compileOnce(): Promise<CompileResult> {
+    const result = await compileRegistry(this.root, this.version + 1);
+    if (result.ok && result.snapshot) {
+      this.version = result.snapshot.version;
+      this.lastGood = result.snapshot;
+    }
+    return result;
+  }
+
+  /** Current last-good snapshot, or null if nothing has compiled cleanly yet. */
+  current(): RegistrySnapshot | null {
+    return this.lastGood;
+  }
+
+  /** Start watching. Performs an initial compile, then recompiles on changes. */
+  async start(): Promise<CompileResult> {
+    const initial = await this.compileOnce();
+    this.emitResult(initial);
+
+    this.watcher = chokidar.watch(this.root, {
+      ignoreInitial: true,
+      ignored: (p: string) => /(^|[/\\])(node_modules|\.git|\.businessos)([/\\]|$)/.test(p),
+      awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 50 },
+      ...this.watchOptions,
+    });
+
+    const schedule = () => this.scheduleRecompile();
+    this.watcher.on("add", schedule);
+    this.watcher.on("change", schedule);
+    this.watcher.on("unlink", schedule);
+    this.watcher.on("addDir", schedule);
+    this.watcher.on("unlinkDir", schedule);
+
+    // Wait until the initial scan completes so the watch is actually armed
+    // before we return — otherwise a change made immediately after start() can
+    // race the watcher's setup and be missed.
+    await new Promise<void>((resolve) => {
+      this.watcher!.once("ready", () => resolve());
+    });
+
+    return initial;
+  }
+
+  async stop(): Promise<void> {
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+    await this.watcher?.close();
+    this.watcher = null;
+  }
+
+  private scheduleRecompile(): void {
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = setTimeout(() => void this.recompile(), this.debounceMs);
+  }
+
+  private async recompile(): Promise<void> {
+    // Serialize compiles; coalesce changes that arrive mid-compile into one
+    // follow-up pass so we never miss the latest state.
+    if (this.compiling) {
+      this.pending = true;
+      return;
+    }
+    this.compiling = true;
+    try {
+      const result = await compileRegistry(this.root, this.version + 1);
+      if (result.ok && result.snapshot) {
+        this.version = result.snapshot.version;
+        this.lastGood = result.snapshot;
+      }
+      this.emitResult(result);
+    } finally {
+      this.compiling = false;
+      if (this.pending) {
+        this.pending = false;
+        this.scheduleRecompile();
+      }
+    }
+  }
+
+  private emitResult(result: CompileResult): void {
+    if (result.ok && result.snapshot) {
+      this.emit("snapshot", result.snapshot);
+    } else {
+      this.emit("invalid", result.diagnostics, this.lastGood);
+    }
+  }
+}

package/src/domain/ids.ts

@@ -0,0 +1,17 @@
+import { randomUUID } from "node:crypto";
+
+/** Short, prefixed, sortable-ish id. Prefix communicates the kind at a glance. */
+export function newId(prefix: string): string {
+  return `${prefix}_${randomUUID().slice(0, 12)}`;
+}
+
+/** Injectable clock so time-dependent logic stays testable. */
+export interface Clock {
+  now(): number;
+  iso(): string;
+}
+
+export const systemClock: Clock = {
+  now: () => Date.now(),
+  iso: () => new Date().toISOString(),
+};

package/src/domain/pricing.ts

@@ -0,0 +1,51 @@
+import type { Usage } from "./types.js";
+
+/** Per-model pricing in USD per million tokens (input, output). */
+const PRICING: Record<string, { input: number; output: number }> = {
+  "claude-opus-4-8": { input: 5, output: 25 },
+  "claude-opus-4-7": { input: 5, output: 25 },
+  "claude-sonnet-4-6": { input: 3, output: 15 },
+  "claude-haiku-4-5": { input: 1, output: 5 },
+};
+
+/** Fallback pricing for unknown model ids — assume opus-tier so we never undercount spend. */
+const FALLBACK = { input: 5, output: 25 };
+
+/** Cache multipliers relative to the input rate (5-minute TTL). */
+const CACHE_READ_MULT = 0.1;
+const CACHE_WRITE_MULT = 1.25;
+
+/** Cache-aware cost estimate in USD. */
+export function estimateUsd(
+  model: string,
+  inputTokens: number,
+  outputTokens: number,
+  cacheReadTokens = 0,
+  cacheCreationTokens = 0,
+): number {
+  const p = PRICING[model] ?? FALLBACK;
+  return (
+    (inputTokens * p.input +
+      outputTokens * p.output +
+      cacheReadTokens * p.input * CACHE_READ_MULT +
+      cacheCreationTokens * p.input * CACHE_WRITE_MULT) /
+    1_000_000
+  );
+}
+
+/** Build a cache-aware Usage with cost filled in from the model's pricing. */
+export function usageFor(
+  model: string,
+  inputTokens: number,
+  outputTokens: number,
+  cacheReadTokens = 0,
+  cacheCreationTokens = 0,
+): Usage {
+  return {
+    inputTokens,
+    outputTokens,
+    cacheReadTokens,
+    cacheCreationTokens,
+    usd: estimateUsd(model, inputTokens, outputTokens, cacheReadTokens, cacheCreationTokens),
+  };
+}

package/src/domain/types.ts

@@ -0,0 +1,168 @@
+/**
+ * Core runtime domain types shared across the engine, orchestrator, messaging,
+ * and trust layers. These are deliberately serializable (plain data) so they
+ * can be logged to the audit trail and replayed.
+ */
+
+import type { Budget } from "../schemas/common.js";
+
+/** Token/cost accounting for a single model interaction or an aggregate. */
+export interface Usage {
+  /** Uncached input tokens (full price). */
+  inputTokens: number;
+  outputTokens: number;
+  /** Tokens served from the prompt cache (~0.1× input price). */
+  cacheReadTokens: number;
+  /** Tokens written to the prompt cache (~1.25× input price, 5-min TTL). */
+  cacheCreationTokens: number;
+  /** Estimated cost in USD, cache-aware. */
+  usd: number;
+}
+
+export function emptyUsage(): Usage {
+  return { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0, usd: 0 };
+}
+
+export function addUsage(a: Usage, b: Usage): Usage {
+  return {
+    inputTokens: a.inputTokens + b.inputTokens,
+    outputTokens: a.outputTokens + b.outputTokens,
+    cacheReadTokens: a.cacheReadTokens + b.cacheReadTokens,
+    cacheCreationTokens: a.cacheCreationTokens + b.cacheCreationTokens,
+    usd: a.usd + b.usd,
+  };
+}
+
+/** Total tokens that hit the model this turn, cached or not. */
+export function totalTokens(u: Usage): number {
+  return u.inputTokens + u.outputTokens + u.cacheReadTokens + u.cacheCreationTokens;
+}
+
+/**
+ * A structured handoff from a manager to a worker. Dispatch is via contracts,
+ * not free-form chat — this is the unit of orchestrated work. A task ends when
+ * its definition-of-done is met, its budget is exhausted, or it escalates.
+ */
+export interface TaskContract {
+  id: string;
+  /** Node id of the agent expected to execute this task. */
+  assigneeNodeId: string;
+  /** Node id (or "owner") that issued the contract. */
+  issuerNodeId: string;
+  /** What to accomplish. */
+  goal: string;
+  /** Inputs/context the worker needs. */
+  inputs: Record<string, unknown>;
+  /** Checkable completion criteria. */
+  definitionOfDone: string;
+  /** Hard ceiling for this task. */
+  budget: Budget;
+  /** Optional ISO deadline. */
+  deadline?: string;
+  /** Process run this task belongs to, if any. */
+  runId?: string;
+  /**
+   * Root of the shared per-run workspace. When set, this becomes the agent's
+   * working directory for the task, giving it `shared/` (team-shared files for
+   * the run) and a private `<nodeId>/` subfolder. Source files are staged into
+   * `shared/` once by the orchestrator, so agents hand off artifacts by writing
+   * to `shared/` rather than re-passing them through prompts.
+   */
+  workspaceRoot?: string;
+  /**
+   * Absolute host paths of source files to stage into the assignee's working
+   * directory (legacy / standalone path; runs stage into the shared workspace).
+   */
+  files?: string[];
+}
+
+export type TaskStatus =
+  | "completed"
+  | "budget_exhausted"
+  | "escalated"
+  | "failed"
+  | "aborted"
+  /** Finished, but one or more consequential actions are awaiting human approval. */
+  | "deferred";
+
+/** The structured result a worker returns for a task contract. */
+export interface TaskResult {
+  contractId: string;
+  status: TaskStatus;
+  /** Worker's summary / answer. */
+  summary: string;
+  /** Artifacts produced (file paths, data), keyed by name. */
+  artifacts: Record<string, unknown>;
+  /** Follow-ups the worker surfaced (e.g. needs decision, blocked on X). */
+  followUps: string[];
+  usage: Usage;
+  /** Proposals queued for human approval during this task (deferred actions). */
+  pendingProposalIds?: string[];
+}
+
+/** Direction of an inter-agent message relative to the sender. */
+export type MessageDirection = "down" | "up" | "sideways";
+
+/** A message between agents, delivered via durable per-agent inboxes. */
+export interface AgentMessage {
+  id: string;
+  fromNodeId: string;
+  toNodeId: string;
+  direction: MessageDirection;
+  /** "task" (a contract), "result", or "note" (free-form, rate-limited). */
+  kind: "task" | "result" | "note";
+  subject: string;
+  body: string;
+  /** Higher = more urgent; used for inbox prioritization into context. */
+  priority: number;
+  /** ISO timestamp set at enqueue. */
+  enqueuedAt: string;
+  /** Idempotency: redelivery carries the same id. */
+  payload?: Record<string, unknown>;
+}
+
+/** Decision returned by the human-in-the-loop approval gate. */
+export type PermissionDecision = "allow" | "deny";
+
+/** A pending request for a human to approve a consequential action. */
+export interface ApprovalRequest {
+  id: string;
+  nodeId: string;
+  toolName: string;
+  input: unknown;
+  /** Why the agent wants to do this (model-provided rationale, if any). */
+  rationale?: string;
+  requestedAt: string;
+}
+
+export type ProposalStatus = "pending" | "approved" | "rejected" | "executed" | "failed";
+
+/**
+ * A consequential action an agent wanted to take, recorded for asynchronous
+ * human approval rather than blocking the run. The agent proposes; the run
+ * completes; a human approves on their own schedule; an executor then performs
+ * the action deterministically (no second model call). This is what makes the
+ * platform able to run continuously without a human in the critical path.
+ */
+export interface Proposal {
+  id: string;
+  runId?: string;
+  nodeId: string;
+  /** Team-memory scope key (manager + direct reports share it). For executor team writes. */
+  managerNodeId?: string;
+  /** Bare action/tool name (e.g. "deliver_to_client"). */
+  action: string;
+  input: unknown;
+  /** Model-provided rationale, if any. */
+  rationale?: string;
+  /** Workspace root the executor should act in (matches the agent's cwd). */
+  cwd: string;
+  createdAt: string;
+  status: ProposalStatus;
+  decidedAt?: string;
+  executedAt?: string;
+  /** Executor result on success. */
+  result?: unknown;
+  error?: string;
+}
+

package/src/index.ts

@@ -0,0 +1,35 @@
+/**
+ * Ravel — public API surface.
+ *
+ * The stable entry point for consumers: **team plugins** import the memory,
+ * plugin, and helper types from here instead of deep paths; a **hosting platform**
+ * imports `App` and the engine to embed the runtime. Deep `src/...` imports are not
+ * part of the contract and may change between versions.
+ */
+
+// --- platform / runtime ------------------------------------------------------
+export { App } from "./platform/app.js";
+export type { AppOptions } from "./platform/app.js";
+export { SdkEngine, assembleMcpServers } from "./runtime/sdkEngine.js";
+export { FakeEngine } from "./runtime/fakeEngine.js";
+export type { AgentEngine, EngineRequest, EngineResult, ToolContext, EngineToolUse } from "./runtime/engine.js";
+
+// --- memory ------------------------------------------------------------------
+export { MemoryStore } from "./memory/store.js";
+export type { MemoryScope } from "./memory/store.js";
+export { withLock, lockKey, readJson, json } from "./memory/kv.js";
+export { queueAppend, queueClear, resolveScope, buildGenericMemoryServer, GENERIC_MEMORY_TOOL_NAMES } from "./memory/genericTools.js";
+
+// --- plugins (what a team's plugin.ts builds against) ------------------------
+export { definePlugin, isPluginDefinition } from "./plugins/types.js";
+export type {
+  PluginDefinition,
+  PluginTool,
+  PluginAction,
+  PluginToolCtx,
+  PluginActionCtx,
+  PluginActionResult,
+} from "./plugins/types.js";
+
+// --- trust (executor action contract for gated plugin actions) --------------
+export type { ActionHandler, ActionContext, ActionResult } from "./trust/executor.js";