@runravel/ravel 0.1.0

package/src/trust/approval.ts

@@ -0,0 +1,180 @@
+import { EventEmitter } from "node:events";
+import { newId, systemClock, type Clock } from "../domain/ids.js";
+import type { ApprovalRequest, PermissionDecision } from "../domain/types.js";
+import type { PermissionPolicy } from "../schemas/common.js";
+import type { ToolsConfig } from "../schemas/tools.js";
+import type { AuditSink } from "./audit.js";
+import type { ProposalStore } from "./proposals.js";
+
+/** Strip an MCP namespace (`mcp__server__tool`) to the bare tool name. */
+function bareName(toolName: string): string {
+  return toolName.includes("__") ? toolName.split("__").pop()! : toolName;
+}
+
+/**
+ * Read-only built-in tools the runtime auto-exposes so agents can read their
+ * staged files. They are safe and their results are needed inline, so they
+ * default to `auto` — gating a read as a proposal both breaks the agent (it
+ * never gets the content) and has no executor to perform it later. An author
+ * can still override by listing one explicitly in tools.json.
+ */
+export const SAFE_AUTO_TOOLS = ["Read", "Glob", "Grep"];
+
+/**
+ * Resolve the effective permission policy for a tool from an agent's config.
+ * Precedence: an explicit grant (author intent) → the safe read-only set
+ * (`auto`) → the agent's `defaultPolicy`. MCP tools arrive namespaced
+ * (`mcp__<server>__<tool>`); we match the bare name too so a grant for
+ * `deliver_to_client` governs `mcp__office__deliver_to_client`.
+ */
+export function policyForTool(tools: ToolsConfig, toolName: string): PermissionPolicy {
+  const bare = bareName(toolName);
+  const grant = tools.tools.find((t) => t.name === toolName || t.name === bare);
+  if (grant) return grant.policy;
+  if (SAFE_AUTO_TOOLS.includes(bare)) return "auto";
+  return tools.defaultPolicy;
+}
+
+export interface DecideRequest {
+  nodeId: string;
+  toolName: string;
+  input: unknown;
+  policy: PermissionPolicy;
+  rationale?: string;
+  runId?: string;
+  /** Workspace root, recorded on a deferred proposal so the executor can act there. */
+  cwd?: string;
+  /** Team-memory scope, recorded so the executor can perform team-scoped writes. */
+  managerNodeId?: string;
+}
+
+/** Decision plus, in deferred mode, the proposal that was queued for approval. */
+export interface DecideResult {
+  decision: PermissionDecision;
+  proposalId?: string;
+}
+
+export type ApprovalMode = "sync" | "deferred";
+
+/**
+ * The human-in-the-loop gate. Every consequential tool call passes through here.
+ *
+ * Two modes:
+ * - **deferred** (default): `ask` records a Proposal and immediately denies, so
+ *   the agent never blocks — the run completes and a human approves later, out
+ *   of band. This is what lets the platform run continuously.
+ * - **sync**: `ask` blocks until a human resolves it (interactive CLI / tests).
+ *
+ * `auto`/`deny`/dry-run behave identically in both modes.
+ */
+export class ApprovalBroker extends EventEmitter {
+  private readonly waiting = new Map<string, { req: ApprovalRequest; resolve: (d: PermissionDecision) => void }>();
+  private readonly mode: ApprovalMode;
+
+  constructor(
+    private readonly audit: AuditSink,
+    private readonly opts: { dryRun?: boolean; clock?: Clock; mode?: ApprovalMode; proposals?: ProposalStore } = {},
+  ) {
+    super();
+    this.mode = opts.mode ?? "deferred";
+  }
+
+  private get clock(): Clock {
+    return this.opts.clock ?? systemClock;
+  }
+
+  /** Sync-mode: currently-blocking approval requests. (Deferred uses ProposalStore.) */
+  pending(): ApprovalRequest[] {
+    return [...this.waiting.values()].map((w) => w.req);
+  }
+
+  async decide(req: DecideRequest): Promise<DecideResult> {
+    if (this.opts.dryRun) {
+      await this.audit.append("tool.dry_run", {
+        nodeId: req.nodeId,
+        runId: req.runId,
+        data: { tool: req.toolName, input: req.input },
+      });
+      return { decision: "deny" };
+    }
+
+    if (req.policy === "auto") {
+      await this.audit.append("tool.auto_allowed", {
+        nodeId: req.nodeId,
+        runId: req.runId,
+        data: { tool: req.toolName },
+      });
+      return { decision: "allow" };
+    }
+
+    if (req.policy === "deny") {
+      await this.audit.append("tool.denied_by_policy", {
+        nodeId: req.nodeId,
+        runId: req.runId,
+        data: { tool: req.toolName },
+      });
+      return { decision: "deny" };
+    }
+
+    // policy === "ask"
+    return this.mode === "deferred" ? this.defer(req) : this.block(req);
+  }
+
+  /** Deferred: queue a proposal and deny immediately (non-blocking). */
+  private async defer(req: DecideRequest): Promise<DecideResult> {
+    if (!this.opts.proposals) {
+      throw new Error("deferred approval mode requires a ProposalStore");
+    }
+    const proposal = await this.opts.proposals.create({
+      nodeId: req.nodeId,
+      action: bareName(req.toolName),
+      input: req.input,
+      cwd: req.cwd ?? "",
+      ...(req.managerNodeId !== undefined ? { managerNodeId: req.managerNodeId } : {}),
+      ...(req.rationale !== undefined ? { rationale: req.rationale } : {}),
+      ...(req.runId !== undefined ? { runId: req.runId } : {}),
+    });
+    await this.audit.append("proposal.created", {
+      nodeId: req.nodeId,
+      runId: req.runId,
+      data: { proposalId: proposal.id, action: proposal.action, input: req.input },
+    });
+    return { decision: "deny", proposalId: proposal.id };
+  }
+
+  /** Sync: enqueue and block until a human resolves. */
+  private async block(req: DecideRequest): Promise<DecideResult> {
+    const request: ApprovalRequest = {
+      id: newId("apr"),
+      nodeId: req.nodeId,
+      toolName: req.toolName,
+      input: req.input,
+      ...(req.rationale !== undefined ? { rationale: req.rationale } : {}),
+      requestedAt: this.clock.iso(),
+    };
+    await this.audit.append("approval.requested", {
+      nodeId: req.nodeId,
+      runId: req.runId,
+      data: { approvalId: request.id, tool: req.toolName, input: req.input },
+    });
+    const decision = await new Promise<PermissionDecision>((resolve) => {
+      this.waiting.set(request.id, { req: request, resolve });
+      this.emit("requested", request);
+    });
+    return { decision };
+  }
+
+  /** Resolve a pending *sync-mode* approval. No-op if unknown/already resolved. */
+  async resolve(approvalId: string, decision: PermissionDecision): Promise<boolean> {
+    const entry = this.waiting.get(approvalId);
+    if (!entry) return false;
+    this.waiting.delete(approvalId);
+    await this.audit.append("approval.resolved", {
+      nodeId: entry.req.nodeId,
+      data: { approvalId, decision, tool: entry.req.toolName },
+    });
+    entry.resolve(decision);
+    this.emit("resolved", approvalId, decision);
+    return true;
+  }
+}

package/src/trust/audit.ts

@@ -0,0 +1,195 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { systemClock, type Clock } from "../domain/ids.js";
+
+/**
+ * One entry in the append-only audit trail. Every decision, message, tool call,
+ * approval, and lifecycle transition is recorded so a run can be fully
+ * reconstructed and reviewed. This is non-negotiable for a system a business
+ * owner must trust.
+ */
+export interface AuditEvent {
+  /** Monotonic sequence within the sink. */
+  seq: number;
+  at: string;
+  type: string;
+  nodeId?: string;
+  runId?: string;
+  data: Record<string, unknown>;
+}
+
+export interface AuditSink {
+  append(type: string, fields: Omit<Partial<AuditEvent>, "seq" | "at" | "type">): Promise<AuditEvent>;
+  all(): readonly AuditEvent[];
+  /** Rehydrate prior events from durable storage (called once at startup). */
+  load?(): Promise<void>;
+}
+
+/** In-memory audit sink — used in tests and as the dashboard's live buffer. */
+export class InMemoryAudit implements AuditSink {
+  private readonly events: AuditEvent[] = [];
+  private seq = 0;
+  constructor(private readonly clock: Clock = systemClock) {}
+
+  async append(
+    type: string,
+    fields: Omit<Partial<AuditEvent>, "seq" | "at" | "type"> = {},
+  ): Promise<AuditEvent> {
+    const event: AuditEvent = {
+      seq: ++this.seq,
+      at: this.clock.iso(),
+      type,
+      data: {},
+      ...fields,
+    };
+    this.events.push(event);
+    return event;
+  }
+
+  /** Load prior events as-is, preserving their seq and continuing the counter. */
+  hydrate(events: AuditEvent[]): void {
+    for (const e of events) {
+      this.events.push(e);
+      if (e.seq > this.seq) this.seq = e.seq;
+    }
+  }
+
+  all(): readonly AuditEvent[] {
+    return this.events;
+  }
+}
+
+/**
+ * Durable JSONL audit sink that also keeps an in-memory mirror for querying.
+ * Writes are serialized so the file is a faithful, ordered record.
+ */
+/**
+ * Wraps any AuditSink and tees each event to a sink function (e.g. stderr) for
+ * live verbose logging. Persistence/querying delegate to the wrapped sink, so
+ * `-v` adds visibility without changing where the audit trail is stored.
+ */
+export class LoggingAudit implements AuditSink {
+  constructor(
+    private readonly base: AuditSink,
+    private readonly emit: (line: string) => void,
+  ) {}
+
+  async append(
+    type: string,
+    fields: Omit<Partial<AuditEvent>, "seq" | "at" | "type"> = {},
+  ): Promise<AuditEvent> {
+    const event = await this.base.append(type, fields);
+    this.emit(formatEvent(event));
+    return event;
+  }
+
+  load(): Promise<void> {
+    return this.base.load?.() ?? Promise.resolve();
+  }
+
+  all(): readonly AuditEvent[] {
+    return this.base.all();
+  }
+}
+
+/** Compact one-line rendering of an audit event for verbose logs. */
+export function formatEvent(e: AuditEvent): string {
+  const where = [e.nodeId !== undefined ? `node=${e.nodeId || "(root)"}` : "", e.runId ? `run=${e.runId}` : ""]
+    .filter(Boolean)
+    .join(" ");
+  const d = e.data;
+  let detail = "";
+  switch (e.type) {
+    case "process.started":
+      detail = `process="${d["process"]}"`;
+      break;
+    case "process.turn":
+      detail = `turn=${d["turn"]} done=${d["done"]} tasks=${d["taskCount"]}${d["assignees"] ? ` → [${(d["assignees"] as string[]).join(", ")}]` : ""}`;
+      break;
+    case "process.finished":
+      detail = `status=${d["status"]} turns=${d["turns"]}`;
+      break;
+    case "task.started":
+      detail = `goal="${String(d["goal"] ?? "").slice(0, 80)}"`;
+      break;
+    case "task.finished":
+      detail = `status=${d["status"]}${d["summary"] ? ` — ${String(d["summary"]).slice(0, 100).replace(/\s+/g, " ")}` : ""}`;
+      break;
+    case "task.unrouted":
+      detail = `role="${d["role"]}"`;
+      break;
+    case "approval.requested":
+      detail = `tool=${d["tool"]} ⏸ awaiting human`;
+      break;
+    case "approval.resolved":
+      detail = `tool=${d["tool"]} → ${d["decision"]}`;
+      break;
+    case "tool.started":
+    case "tool.auto_allowed":
+    case "tool.denied_by_policy":
+    case "tool.dry_run":
+      detail = `tool=${d["tool"]}`;
+      break;
+    case "message.deadletter":
+      detail = `reason=${d["reason"]}`;
+      break;
+    case "registry.invalid":
+      detail = `${(d["diagnostics"] as string[] | undefined)?.length ?? 0} diagnostic(s)`;
+      break;
+    default:
+      detail = "";
+  }
+  return `· ${e.type}${where ? ` ${where}` : ""}${detail ? ` ${detail}` : ""}`;
+}
+
+export class JsonlAudit implements AuditSink {
+  private readonly mem: InMemoryAudit;
+  private writeChain: Promise<void> = Promise.resolve();
+
+  constructor(
+    private readonly filePath: string,
+    private readonly clock: Clock = systemClock,
+  ) {
+    this.mem = new InMemoryAudit(clock);
+  }
+
+  /** Rehydrate the in-memory mirror from the JSONL file so history survives restarts. */
+  async load(): Promise<void> {
+    let raw: string;
+    try {
+      raw = await fs.readFile(this.filePath, "utf8");
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") return;
+      throw err;
+    }
+    const events: AuditEvent[] = [];
+    for (const line of raw.split("\n")) {
+      if (line.trim()) {
+        try {
+          events.push(JSON.parse(line) as AuditEvent);
+        } catch {
+          /* skip a partially-written trailing line */
+        }
+      }
+    }
+    this.mem.hydrate(events);
+  }
+
+  async append(
+    type: string,
+    fields: Omit<Partial<AuditEvent>, "seq" | "at" | "type"> = {},
+  ): Promise<AuditEvent> {
+    const event = await this.mem.append(type, fields);
+    const line = `${JSON.stringify(event)}\n`;
+    this.writeChain = this.writeChain.then(async () => {
+      await fs.mkdir(path.dirname(this.filePath), { recursive: true });
+      await fs.appendFile(this.filePath, line, "utf8");
+    });
+    await this.writeChain;
+    return event;
+  }
+
+  all(): readonly AuditEvent[] {
+    return this.mem.all();
+  }
+}

package/src/trust/budget.ts

@@ -0,0 +1,64 @@
+import type { Budget } from "../schemas/common.js";
+import { addUsage, emptyUsage, type Usage } from "../domain/types.js";
+import { systemClock, type Clock } from "../domain/ids.js";
+
+export type BudgetLimit = "tokens" | "usd" | "seconds" | "turns";
+
+/**
+ * Tracks consumption against a Budget. The orchestrator and agent runtime check
+ * `exceeded()` before each step and terminate/escalate when a ceiling is hit —
+ * this is the mechanism that makes autonomous work bounded rather than a
+ * perpetual loop. An empty budget ({}), means "no ceilings" and never trips.
+ */
+export class BudgetMeter {
+  private usage: Usage = emptyUsage();
+  private turns = 0;
+  private readonly startedAt: number;
+
+  constructor(
+    private readonly budget: Budget,
+    private readonly clock: Clock = systemClock,
+  ) {
+    this.startedAt = clock.now();
+  }
+
+  recordUsage(u: Usage): void {
+    this.usage = addUsage(this.usage, u);
+  }
+
+  recordTurn(): void {
+    this.turns += 1;
+  }
+
+  elapsedSeconds(): number {
+    return (this.clock.now() - this.startedAt) / 1000;
+  }
+
+  spent(): { usage: Usage; turns: number; seconds: number } {
+    return { usage: this.usage, turns: this.turns, seconds: this.elapsedSeconds() };
+  }
+
+  /** Returns the first limit that has been reached, or null if within budget. */
+  exceeded(): BudgetLimit | null {
+    const b = this.budget;
+    if (b.tokens !== undefined && this.usage.inputTokens + this.usage.outputTokens >= b.tokens) {
+      return "tokens";
+    }
+    if (b.usd !== undefined && this.usage.usd >= b.usd) return "usd";
+    if (b.turns !== undefined && this.turns >= b.turns) return "turns";
+    if (b.seconds !== undefined && this.elapsedSeconds() >= b.seconds) return "seconds";
+    return null;
+  }
+
+  remaining(): Budget {
+    const b = this.budget;
+    const out: Budget = {};
+    if (b.tokens !== undefined) {
+      out.tokens = Math.max(0, b.tokens - (this.usage.inputTokens + this.usage.outputTokens));
+    }
+    if (b.usd !== undefined) out.usd = Math.max(0, b.usd - this.usage.usd);
+    if (b.turns !== undefined) out.turns = Math.max(0, b.turns - this.turns);
+    if (b.seconds !== undefined) out.seconds = Math.max(0, b.seconds - this.elapsedSeconds());
+    return out;
+  }
+}

package/src/trust/emittingAudit.ts

@@ -0,0 +1,32 @@
+import { EventEmitter } from "node:events";
+import type { AuditSink, AuditEvent } from "./audit.js";
+
+/**
+ * Wraps an AuditSink and re-emits each appended event as a structured object on
+ * an `EventEmitter` — the tap the HTTP service subscribes to for its SSE stream.
+ * Unlike `LoggingAudit` (which emits formatted strings for humans), this
+ * preserves the full `AuditEvent`. Persistence/querying delegate to the base.
+ */
+export class EmittingAudit extends EventEmitter implements AuditSink {
+  constructor(private readonly base: AuditSink) {
+    super();
+    this.setMaxListeners(0); // many SSE clients may subscribe
+  }
+
+  async append(
+    type: string,
+    fields: Omit<Partial<AuditEvent>, "seq" | "at" | "type"> = {},
+  ): Promise<AuditEvent> {
+    const event = await this.base.append(type, fields);
+    this.emit("event", event);
+    return event;
+  }
+
+  load(): Promise<void> {
+    return this.base.load?.() ?? Promise.resolve();
+  }
+
+  all(): readonly AuditEvent[] {
+    return this.base.all();
+  }
+}

package/src/trust/executor.ts

@@ -0,0 +1,73 @@
+import type { Proposal } from "../domain/types.js";
+import type { AuditSink } from "./audit.js";
+
+export interface ActionContext {
+  cwd: string;
+  nodeId: string;
+  runId?: string;
+  /** Team-memory scope for team-scoped executor writes (e.g. watchlist). */
+  managerNodeId?: string;
+}
+
+export interface ActionResult {
+  ok: boolean;
+  result?: unknown;
+  error?: string;
+}
+
+export type ActionHandler = (input: unknown, ctx: ActionContext) => Promise<ActionResult>;
+
+/**
+ * Performs approved proposed actions deterministically — no model call. The
+ * other half of the async-gate model: agents *propose*, a human *approves*, and
+ * this executor *does* the thing. Actions are registered by name (the bare tool
+ * name an agent proposed, e.g. "deliver_to_client").
+ */
+export class ActionExecutor {
+  private readonly handlers = new Map<string, ActionHandler>();
+
+  constructor(private readonly audit: AuditSink) {}
+
+  register(action: string, handler: ActionHandler): this {
+    this.handlers.set(action, handler);
+    return this;
+  }
+
+  has(action: string): boolean {
+    return this.handlers.has(action);
+  }
+
+  /** Execute the action a proposal describes. Records the outcome to the audit log. */
+  async execute(proposal: Proposal): Promise<ActionResult> {
+    const handler = this.handlers.get(proposal.action);
+    if (!handler) {
+      const error = `no executor registered for action "${proposal.action}"`;
+      await this.audit.append("proposal.execute_failed", {
+        nodeId: proposal.nodeId,
+        ...(proposal.runId !== undefined ? { runId: proposal.runId } : {}),
+        data: { proposalId: proposal.id, action: proposal.action, error },
+      });
+      return { ok: false, error };
+    }
+
+    const ctx: ActionContext = {
+      cwd: proposal.cwd,
+      nodeId: proposal.nodeId,
+      ...(proposal.runId !== undefined ? { runId: proposal.runId } : {}),
+      ...(proposal.managerNodeId !== undefined ? { managerNodeId: proposal.managerNodeId } : {}),
+    };
+    let result: ActionResult;
+    try {
+      result = await handler(proposal.input, ctx);
+    } catch (err) {
+      result = { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+
+    await this.audit.append(result.ok ? "proposal.executed" : "proposal.execute_failed", {
+      nodeId: proposal.nodeId,
+      ...(proposal.runId !== undefined ? { runId: proposal.runId } : {}),
+      data: { proposalId: proposal.id, action: proposal.action, ...(result.error ? { error: result.error } : {}) },
+    });
+    return result;
+  }
+}

package/src/trust/killswitch.ts

@@ -0,0 +1,73 @@
+/**
+ * Instant stop control. The owner can halt one agent, a whole team (subtree),
+ * or the entire org. Each in-flight run registers an AbortController; killing a
+ * scope aborts every matching run and blocks new runs in that scope until it is
+ * cleared.
+ *
+ * Scope matching is by node-id prefix: scope `"sales"` kills `sales` and
+ * `sales/researcher`; scope `"*"` kills everything.
+ */
+export class KillSwitch {
+  private readonly active = new Map<string, Set<AbortController>>();
+  private readonly killedScopes = new Set<string>();
+
+  private matches(scope: string, nodeId: string): boolean {
+    if (scope === "*") return true;
+    return nodeId === scope || nodeId.startsWith(`${scope}/`);
+  }
+
+  /** Is this node currently under an active kill scope? */
+  isKilled(nodeId: string): boolean {
+    for (const scope of this.killedScopes) {
+      if (this.matches(scope, nodeId)) return true;
+    }
+    return false;
+  }
+
+  /**
+   * Register an in-flight run for a node. Returns an AbortController whose
+   * signal fires if the node's scope is (or becomes) killed. Caller must call
+   * `release` when the run ends.
+   */
+  register(nodeId: string): AbortController {
+    const controller = new AbortController();
+    if (this.isKilled(nodeId)) {
+      controller.abort(new Error(`node ${nodeId} is under an active kill`));
+      return controller;
+    }
+    let set = this.active.get(nodeId);
+    if (!set) {
+      set = new Set();
+      this.active.set(nodeId, set);
+    }
+    set.add(controller);
+    return controller;
+  }
+
+  release(nodeId: string, controller: AbortController): void {
+    this.active.get(nodeId)?.delete(controller);
+  }
+
+  /** Halt a scope: abort all matching in-flight runs and block new ones. */
+  kill(scope: string): number {
+    this.killedScopes.add(scope);
+    let aborted = 0;
+    for (const [nodeId, set] of this.active) {
+      if (!this.matches(scope, nodeId)) continue;
+      for (const controller of set) {
+        controller.abort(new Error(`killed: scope ${scope}`));
+        aborted += 1;
+      }
+    }
+    return aborted;
+  }
+
+  /** Clear a kill scope so the node(s) can run again. */
+  clear(scope: string): void {
+    this.killedScopes.delete(scope);
+  }
+
+  clearAll(): void {
+    this.killedScopes.clear();
+  }
+}