@runravel/ravel 0.1.0

package/src/trust/observability.ts

@@ -0,0 +1,97 @@
+import { addUsage, emptyUsage, type Usage } from "../domain/types.js";
+import type { AuditSink, AuditEvent } from "./audit.js";
+import type { ProposalStore } from "./proposals.js";
+import type { Lifecycle } from "../runtime/lifecycle.js";
+import type { AgentState, AgentActivity } from "../runtime/agent.js";
+
+export interface AgentMetric {
+  nodeId: string;
+  name: string;
+  role: string;
+  state: AgentState;
+  tasksRun: number;
+  usage: Usage;
+  /** What the agent is doing right now (empty when idle). */
+  activity: AgentActivity;
+}
+
+export interface ProcessRunMetric {
+  runId: string;
+  process: string;
+  status: string;
+  turns: number;
+  usage: Usage;
+}
+
+export interface DashboardSnapshot {
+  totalUsage: Usage;
+  agents: AgentMetric[];
+  processRuns: ProcessRunMetric[];
+  /** Deferred actions awaiting an async human decision. */
+  pendingProposals: number;
+  deadLetters: number;
+  eventCount: number;
+}
+
+/**
+ * Derives a live cost/trace view from the append-only audit trail plus the
+ * current lifecycle/approval state. Observability is first-class: the owner can
+ * always see what each agent has spent, what's running, and what's waiting on
+ * them — no separate instrumentation, just a read over the audit log.
+ */
+export class Observer {
+  constructor(
+    private readonly audit: AuditSink,
+    private readonly lifecycle: Lifecycle,
+    private readonly proposals: ProposalStore,
+    private readonly deadLetterCount: () => number = () => 0,
+  ) {}
+
+  snapshot(): DashboardSnapshot {
+    const events = this.audit.all();
+    const perNodeUsage = new Map<string, Usage>();
+    const perNodeTasks = new Map<string, number>();
+    const processRuns: ProcessRunMetric[] = [];
+    let totalUsage = emptyUsage();
+
+    for (const e of events) {
+      if (e.type === "task.finished" && e.nodeId !== undefined) {
+        const u = (e.data["usage"] as Usage | undefined) ?? emptyUsage();
+        perNodeUsage.set(e.nodeId, addUsage(perNodeUsage.get(e.nodeId) ?? emptyUsage(), u));
+        perNodeTasks.set(e.nodeId, (perNodeTasks.get(e.nodeId) ?? 0) + 1);
+        totalUsage = addUsage(totalUsage, u);
+      } else if (e.type === "process.finished") {
+        processRuns.push(this.toProcessMetric(e));
+      }
+    }
+
+    const agents: AgentMetric[] = this.lifecycle.all().map((rt) => ({
+      nodeId: rt.node.id,
+      name: rt.node.spec.name,
+      role: rt.node.spec.role ?? rt.node.spec.name,
+      state: rt.state,
+      tasksRun: perNodeTasks.get(rt.node.id) ?? 0,
+      usage: perNodeUsage.get(rt.node.id) ?? emptyUsage(),
+      activity: rt.activity,
+    }));
+
+    return {
+      totalUsage,
+      agents,
+      processRuns,
+      pendingProposals: this.proposals.pending().length,
+      deadLetters: this.deadLetterCount(),
+      eventCount: events.length,
+    };
+  }
+
+  private toProcessMetric(e: AuditEvent): ProcessRunMetric {
+    return {
+      runId: e.runId ?? "",
+      process: String(e.data["process"] ?? ""),
+      status: String(e.data["status"] ?? ""),
+      turns: Number(e.data["turns"] ?? 0),
+      usage: (e.data["usage"] as Usage | undefined) ?? emptyUsage(),
+    };
+  }
+}

package/src/trust/proposals.ts

@@ -0,0 +1,114 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { EventEmitter } from "node:events";
+import { newId, systemClock, type Clock } from "../domain/ids.js";
+import type { Proposal, ProposalStatus } from "../domain/types.js";
+
+/** Stable hash of a tool input, for de-duping identical pending proposals. */
+function hashInput(input: unknown): string {
+  const stable = JSON.stringify(input, (_k, v) =>
+    v && typeof v === "object" && !Array.isArray(v)
+      ? Object.fromEntries(Object.entries(v as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b)))
+      : v,
+  );
+  return createHash("sha256").update(stable ?? "null").digest("hex").slice(0, 16);
+}
+
+function dedupeKey(p: Pick<Proposal, "runId" | "nodeId" | "action" | "input">): string {
+  return `${p.runId ?? ""}|${p.nodeId}|${p.action}|${hashInput(p.input)}`;
+}
+
+/**
+ * Durable store of proposed consequential actions awaiting human approval.
+ *
+ * - Source of truth is the in-memory map; the JSON file is a serialized mirror
+ *   rewritten on each mutation (volumes are small — a flood is a design smell
+ *   the approval queue is meant to surface, not absorb).
+ * - `create` de-dupes against existing *pending* proposals on
+ *   (runId, nodeId, action, inputHash), so a stray task re-dispatch can't queue
+ *   the same action twice.
+ * - Emits `created` / `updated` so the dashboard and the SSE event stream stay live.
+ */
+export class ProposalStore extends EventEmitter {
+  private readonly byId = new Map<string, Proposal>();
+  private writeChain: Promise<void> = Promise.resolve();
+
+  constructor(
+    private readonly opts: { filePath?: string; clock?: Clock } = {},
+  ) {
+    super();
+  }
+
+  private get clock(): Clock {
+    return this.opts.clock ?? systemClock;
+  }
+
+  /** Load persisted proposals (call once at startup). */
+  async load(): Promise<void> {
+    if (!this.opts.filePath) return;
+    try {
+      const raw = await fs.readFile(this.opts.filePath, "utf8");
+      for (const p of JSON.parse(raw) as Proposal[]) this.byId.set(p.id, p);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+    }
+  }
+
+  /**
+   * Record a proposed action. Returns the existing pending proposal if an
+   * identical one is already queued (idempotent), else a new one.
+   */
+  async create(fields: Omit<Proposal, "id" | "createdAt" | "status">): Promise<Proposal> {
+    const key = dedupeKey(fields);
+    for (const existing of this.byId.values()) {
+      if (existing.status === "pending" && dedupeKey(existing) === key) return existing;
+    }
+    const proposal: Proposal = {
+      ...fields,
+      id: newId("prop"),
+      createdAt: this.clock.iso(),
+      status: "pending",
+    };
+    this.byId.set(proposal.id, proposal);
+    await this.persist();
+    this.emit("created", proposal);
+    return proposal;
+  }
+
+  get(id: string): Proposal | undefined {
+    return this.byId.get(id);
+  }
+
+  list(status?: ProposalStatus): Proposal[] {
+    const all = [...this.byId.values()];
+    return status ? all.filter((p) => p.status === status) : all;
+  }
+
+  pending(): Proposal[] {
+    return this.list("pending");
+  }
+
+  /** Update a proposal's status (and optional result/error). No-op if unknown. */
+  async setStatus(id: string, status: ProposalStatus, patch: Partial<Proposal> = {}): Promise<Proposal | null> {
+    const current = this.byId.get(id);
+    if (!current) return null;
+    const updated: Proposal = { ...current, ...patch, status };
+    if (status === "approved" || status === "rejected") updated.decidedAt = this.clock.iso();
+    if (status === "executed" || status === "failed") updated.executedAt = this.clock.iso();
+    this.byId.set(id, updated);
+    await this.persist();
+    this.emit("updated", updated);
+    return updated;
+  }
+
+  private async persist(): Promise<void> {
+    if (!this.opts.filePath) return;
+    const snapshot = JSON.stringify([...this.byId.values()]);
+    this.writeChain = this.writeChain.then(async () => {
+      await fs.mkdir(path.dirname(this.opts.filePath!), { recursive: true });
+      await fs.writeFile(this.opts.filePath!, snapshot, "utf8");
+    });
+    await this.writeChain;
+  }
+}