@heretek-ai/epistemic-swarm 1.0.5 → 1.1.2

package/src/panels.tsx

@@ -68,6 +68,13 @@ const FactoryPanel = (props: PanelProps) => {
               {data().spend.ceilingUSD ? ` / $${data().spend.ceilingUSD}` : ""}
               {data().spend.estimated ? " (estimated)" : ""}
             </text>
+            <Show when={data().tree}>
+              <text>
+                Design tree (round {data().tree.round}): {data().tree.settled} settled · {data().tree.open} open ·{" "}
+                {data().tree.deferred} deferred
+                {data().tree.facts ? ` (${data().tree.facts} for research)` : ""}
+              </text>
+            </Show>
             <Show when={data().halt}>
               <text>HALTED: {data().halt}</text>
             </Show>
@@ -77,6 +84,18 @@ const FactoryPanel = (props: PanelProps) => {
             <Show when={data().pending.length}>
               <text>Waiting on human: {data().pending.join(", ")}</text>
             </Show>
+            <Show when={data().audits?.length}>
+              <text>Audits:</text>
+              <For each={data().audits}>
+                {(audit: any) => (
+                  <text>
+                    {"  "}
+                    {audit.id} · {audit.target} · {audit.status} r{audit.round} · t:{audit.thesis} a:{audit.antithesis}
+                    {audit.tiebreak ? ` x:${audit.tiebreak}` : ""}
+                  </text>
+                )}
+              </For>
+            </Show>
             <text>Phases:</text>
             <For each={data().phases}>
               {(phase: any) => (

package/src/policy.ts

@@ -1,9 +1,11 @@
 // Mechanical enforcement in the host: every write, edit, patch and shell call
 // from any agent passes through core's policy (canonical paths, control files,
-// seat scopes); factory seats additionally stop on STOP or a halted run, run
-// read-only shells under bubblewrap, and get fast gate feedback after edits.
+// seat scopes), and every shell command runs inside the bubblewrap sandbox its
+// decision names (trust/sandbox.ts). Factory seats additionally stop on STOP
+// or a halted run and get fast gate feedback after edits.
 import path from "node:path"
 import {
+  agentSpec,
   bwrapAvailable,
   checkStopFile,
   evaluateRead,
@@ -12,13 +14,13 @@ import {
   formatDiagnostics,
   formatReport,
   loadGatesConfig,
-  readonlyWrap,
   runGates,
+  sandboxArgv,
   seatOf,
   shellQuote,
-  treeFingerprint,
 } from "@heretek-ai/es-core"
 import { Error as ToolError } from "@opencode/plugin/promise/tool"
+import { HOST_WEB_TOOLS } from "./agents.ts"
 import type { Runtime } from "./runtime.ts"
 
 const WRITE_TOOLS = new Set(["write", "edit"])
@@ -48,8 +50,6 @@ const appendContent = (content: unknown, text: string) =>
       : text
 
 export function createPolicyHooks(runtime: Runtime) {
-  const fingerprints = new Map<string, { dir: string; print: string }>()
-
   const before = async (event: { tool: string; agent: string; id: string; input: unknown }) => {
     const seat = seatOf(event.agent)
     const input = (event.input ?? {}) as Record<string, any>
@@ -58,11 +58,17 @@ export function createPolicyHooks(runtime: Runtime) {
       if (stop.stopped)
         deny(`The factory is stopped (.factory/STOP: ${stop.reason}). A human must remove it and resume.`)
     }
-    if (seat && !event.tool.startsWith("es_")) {
+    // A halted run (spend ceiling, runtime cap, drift, STOP) stops every seat
+    // tool except es_status, so no seat keeps spending through its own es_* tools.
+    if (seat && event.tool !== "es_status") {
       const state = await runtime.factory.read().catch(() => undefined)
       if (state?.stage === "HALTED")
         deny(`The factory is halted: ${state.halt?.reason}. Stop and report; a human must resume.`)
     }
+    if (agentSpec(event.agent)?.web === "cached" && (HOST_WEB_TOOLS as readonly string[]).includes(event.tool))
+      deny(
+        `Seat "${event.agent}" gets web facts only through es_research_search and es_research_fetch (cached and citable); ${event.tool} is not available to it.`,
+      )
     const context = await runtime.policy()
     if (WRITE_TOOLS.has(event.tool) && typeof input.path === "string") {
       const decision = evaluateWrite(context, event.agent, input.path)
@@ -80,14 +86,37 @@ export function createPolicyHooks(runtime: Runtime) {
     if (event.tool === "shell" && typeof input.command === "string") {
       const decision = evaluateShell(context, event.agent, input.command, { sandboxAvailable: bwrapAvailable() })
       if (decision.effect === "deny") deny(decision.reason)
-      const cwd =
-        typeof input.workdir === "string"
-          ? path.resolve(runtime.root, input.workdir)
-          : (context.worktree ?? runtime.root)
-      if (decision.effect === "allow" && decision.mode === "readonly-sandbox") {
-        event.input = { ...input, command: readonlyWrap(["sh", "-c", input.command], cwd).map(shellQuote).join(" ") }
-      } else if (decision.effect === "allow" && decision.mode === "readonly-checked") {
-        fingerprints.set(event.id, { dir: cwd, print: await treeFingerprint(cwd) })
+    }
+  }
+
+  /**
+   * The last execute.before hook: re-evaluates the final shell command (a
+   * PreToolUse hook may have rewritten it) and wraps it in its sandbox, so no
+   * later rewrite can run unsandboxed and hook matchers see the plain command.
+   */
+  const sandbox = async (event: { tool: string; agent: string; id: string; input: unknown }) => {
+    const input = (event.input ?? {}) as Record<string, any>
+    if (event.tool === "shell" && typeof input.command === "string") {
+      const context = await runtime.policy()
+      const decision = evaluateShell(context, event.agent, input.command, { sandboxAvailable: bwrapAvailable() })
+      if (decision.effect === "deny") deny(decision.reason)
+      if (decision.effect === "allow" && decision.mode === "sandbox") {
+        const cwd =
+          typeof input.workdir === "string"
+            ? path.resolve(runtime.root, input.workdir)
+            : (context.worktree ?? runtime.root)
+        const argv = sandboxArgv(
+          {
+            kind: decision.kind,
+            root: runtime.root,
+            cwd,
+            stateDir: runtime.stateDir,
+            offline: decision.offline,
+            ...(decision.kind === "programmer" && context.worktree ? { writable: context.worktree } : {}),
+          },
+          ["sh", "-c", input.command],
+        )
+        event.input = { ...input, command: argv.map(shellQuote).join(" ") }
       }
     }
   }
@@ -101,23 +130,6 @@ export function createPolicyHooks(runtime: Runtime) {
     result?: any
   }) => {
     const seat = seatOf(event.agent)
-    const checked = fingerprints.get(event.id)
-    if (checked) {
-      fingerprints.delete(event.id)
-      if ((await treeFingerprint(checked.dir)) !== checked.print) {
-        await runtime.factory
-          .halt(`agent:${event.agent}`, `read-only seat ${event.agent} changed files via the shell`)
-          .catch(() => undefined)
-        if (event.status === "completed")
-          event.result = {
-            ...event.result,
-            content: appendContent(
-              event.result?.content,
-              "VIOLATION: this read-only seat modified the checkout. The factory has been halted.",
-            ),
-          }
-      }
-    }
     if (event.status !== "completed") return
     const input = (event.input ?? {}) as Record<string, any>
     const files =
@@ -157,6 +169,7 @@ export function createPolicyHooks(runtime: Runtime) {
         commands: config.commands.filter((check) => check.kind === "format" || check.kind === "lint"),
       },
       stateDir: runtime.stateDir,
+      sandbox: "required",
     })
     if (report.findings.length || !report.passed)
       event.result = {
@@ -217,5 +230,5 @@ export function createPolicyHooks(runtime: Runtime) {
     for (const key of Object.keys(event.env)) if (/^OPENCODE_(SERVER_)?PASSWORD$/.test(key)) delete event.env[key]
   }
 
-  return { before, after, evaluate, shellEnv }
+  return { before, sandbox, after, evaluate, shellEnv }
 }

package/src/research.ts

@@ -1,63 +1,127 @@
 // Research integration: the configured search provider becomes the host's
-// websearch (results cached content-addressed, so they can be cited), and the
-// host's own webfetch results are cached too.
-import { researchCache, selectProvider } from "@heretek-ai/es-core"
+// websearch, and host web results are cached content-addressed so they can be
+// cited. Caching is for Epistemic Swarm seats in a project that already has a
+// .factory/ directory: the user's own agents get plain results, and no
+// project gains a .factory/ because someone searched the web.
+import { stat } from "node:fs/promises"
+import { factoryLayout, researchCache, seatOf, selectProvider } from "@heretek-ai/es-core"
 import type { Runtime } from "./runtime.ts"
 
+interface SearchHit {
+  readonly url: string
+  readonly title?: string
+  readonly text: string
+}
+
+/** Results the provider returned, waiting for the tool hook (which knows the agent) to cache them. */
+export class PendingSearches {
+  private readonly entries: Array<{ query: string; provider: string; hits: readonly SearchHit[]; at: number }> = []
+  private static readonly TTL_MS = 5 * 60_000
+
+  add(query: string, provider: string, hits: readonly SearchHit[]) {
+    this.prune()
+    this.entries.push({ query, provider, hits, at: Date.now() })
+  }
+
+  /** The oldest unclaimed results for this query (each search is claimed once). */
+  take(query: string) {
+    this.prune()
+    const index = this.entries.findIndex((entry) => entry.query === query)
+    return index < 0 ? undefined : this.entries.splice(index, 1)[0]
+  }
+
+  private prune() {
+    const cutoff = Date.now() - PendingSearches.TTL_MS
+    while (this.entries.length && this.entries[0]!.at < cutoff) this.entries.shift()
+  }
+}
+
+/** Host web results are cached only for an ES seat, in a project that already has .factory/. */
+async function cacheable(runtime: Runtime, agent: string | undefined): Promise<boolean> {
+  if (!seatOf(agent)) return false
+  return stat(factoryLayout(runtime.root).dir).then(
+    (info) => info.isDirectory(),
+    () => false,
+  )
+}
+
 export function registerWebsearch(
   editor: { add(definition: any): void; default: { get(): unknown; set(id: string): void } },
   runtime: Runtime,
+  pending: PendingSearches,
 ) {
-  const provider = selectProvider(runtime.options.searchProvider)
+  const searxng = runtime.config.research?.searxngUrl
+  const env = searxng ? { ...process.env, SEARXNG_URL: searxng } : process.env
+  const provider = selectProvider(runtime.options.searchProvider, env)
   if (!provider) return
-  const cache = researchCache(runtime.root)
   editor.add({
     id: "epistemic-swarm",
-    name: `Epistemic Swarm (${provider.id}, cached)`,
+    name: `Epistemic Swarm (${provider.id})`,
     execute: async (input: { query: string; limit?: number }, context: { signal: AbortSignal }) => {
-      const results = await provider.search(input.query, { limit: input.limit ?? 8, signal: context.signal })
-      const out = []
-      for (const result of results) {
-        const cached = await cache.put({
-          url: result.url,
-          title: result.title,
-          text: result.content ?? result.snippet,
-          provider: provider.id,
-          query: input.query,
-        })
-        out.push({
-          url: result.url,
-          title: result.title,
-          content: `[cached sha256:${cached.meta.sha256}]\n${result.content ?? result.snippet}`,
-          time: {},
-        })
-      }
-      return out
+      const results = await provider.search(input.query, { limit: input.limit ?? 8, signal: context.signal, env })
+      const hits = results.map((result) => ({
+        url: result.url,
+        title: result.title,
+        text: result.content ?? result.snippet,
+      }))
+      pending.add(input.query, provider.id, hits)
+      return hits.map((hit) => ({ url: hit.url, title: hit.title, content: hit.text, time: {} }))
     },
   })
   // Additive: become the default only when nothing else is selected.
   if (editor.default.get() === undefined) editor.default.set("epistemic-swarm")
 }
 
-/** Cache host webfetch results so they can be cited as [VERIFIED: sha256:… "quote"]. */
-export function createWebfetchCache(runtime: Runtime) {
-  const cache = researchCache(runtime.root)
-  return async (event: { tool: string; status: string; input: unknown; result?: any }) => {
+const contentText = (content: unknown): string =>
+  typeof content === "string"
+    ? content
+    : Array.isArray(content)
+      ? content.map((part: any) => part?.text ?? "").join("\n")
+      : ""
+
+const prepend = (result: any, note: string) => {
+  const content = result?.content
+  return {
+    ...result,
+    content: typeof content === "string" ? `${note}\n${content}` : [{ type: "text", text: note }, ...(content ?? [])],
+  }
+}
+
+/**
+ * Cache a seat's host webfetch and websearch results so they can be cited as
+ * [VERIFIED: sha256:… "quote"]. Other agents' results pass through untouched.
+ */
+export function createWebCache(runtime: Runtime, pending: PendingSearches) {
+  const cache = researchCache(runtime.root, runtime.stateDir)
+  return async (event: { tool: string; status: string; agent?: string; input: unknown; result?: any }) => {
+    if (event.tool === "websearch") {
+      const query = (event.input as { query?: string } | undefined)?.query
+      const search = typeof query === "string" ? pending.take(query) : undefined
+      if (!search || event.status !== "completed" || !(await cacheable(runtime, event.agent))) return
+      const lines: string[] = []
+      for (const hit of search.hits) {
+        if (!hit.text?.trim()) continue
+        const cached = await cache.put({
+          url: hit.url,
+          title: hit.title,
+          text: hit.text,
+          provider: search.provider,
+          query: search.query,
+        })
+        lines.push(`[cached sha256:${cached.meta.sha256}] ${hit.url}`)
+      }
+      if (lines.length)
+        event.result = prepend(event.result, `${lines.join("\n")}\n(cite with [VERIFIED: sha256:<hash> "exact words"])`)
+      return
+    }
     if (event.tool !== "webfetch" || event.status !== "completed") return
     const url = (event.input as { url?: string } | undefined)?.url
-    const content = event.result?.content
-    const text =
-      typeof content === "string"
-        ? content
-        : Array.isArray(content)
-          ? content.map((part: any) => part?.text ?? "").join("\n")
-          : ""
-    if (!url || text.trim().length < 40) return
+    const text = contentText(event.result?.content)
+    if (!url || text.trim().length < 40 || !(await cacheable(runtime, event.agent))) return
     const cached = await cache.put({ url, text, provider: "webfetch" })
-    const note = `[cached as sha256:${cached.meta.sha256}; cite with [VERIFIED: sha256:${cached.meta.sha256} "exact words"]]`
-    event.result = {
-      ...event.result,
-      content: typeof content === "string" ? `${note}\n${content}` : [{ type: "text", text: note }, ...(content ?? [])],
-    }
+    event.result = prepend(
+      event.result,
+      `[cached as sha256:${cached.meta.sha256}; cite with [VERIFIED: sha256:${cached.meta.sha256} "exact words"]]`,
+    )
   }
 }

package/src/rpc-def.ts

@@ -1,6 +1,7 @@
-// RPC contract between the server plugin and the TUI. These methods are the
-// TUI half of the human-only channel: no agent tool reaches them, and the TUI
-// only calls them after a human confirms a dialog showing what is approved.
+// RPC contract between the server plugin and the TUI. Previews are shown in
+// the TUI; human-only mutations (approve, trust, resume) happen at a terminal
+// with the passphrase (`es approve`, `es trust`, `es factory resume`), never
+// through an agent tool or RPC. Only lspInstall still mutates via RPC.
 import { Rpc } from "@opencode/plugin/rpc"
 
 const obj = (properties: Record<string, unknown>, required: string[] = []) => ({
@@ -26,25 +27,16 @@ export const EsRpc = Rpc.define({
       input: obj({}),
       output: obj({ summary: str, stage: str, pending: strArray }, ["summary", "stage", "pending"]),
     },
+    /** The effective config (JSON), the files it came from, and load warnings to show once. */
+    configState: {
+      input: obj({}),
+      output: obj({ config: str, sources: strArray, warnings: strArray }, ["config", "sources", "warnings"]),
+    },
     previewApproval: {
       input: obj({ stage: { type: "string", enum: ["frontier", "spec"] } }, ["stage"]),
       output: Preview,
     },
-    approve: {
-      input: obj({ stage: { type: "string", enum: ["frontier", "spec"] }, user: str, token: str }, [
-        "stage",
-        "user",
-        "token",
-      ]),
-      output: obj({ message: str }, ["message"]),
-      errors: { refused: obj({ reason: str }, ["reason"]) },
-    },
     previewTrust: { input: obj({}), output: Preview },
-    trust: {
-      input: obj({ user: str, token: str }, ["user", "token"]),
-      output: obj({ message: str }, ["message"]),
-      errors: { refused: obj({ reason: str }, ["reason"]) },
-    },
     previewResume: { input: obj({}), output: Preview },
     previewLspInstall: { input: obj({ id: str }, ["id"]), output: Preview },
     lspInstall: {
@@ -52,20 +44,6 @@ export const EsRpc = Rpc.define({
       output: obj({ message: str }, ["message"]),
       errors: { refused: obj({ reason: str }, ["reason"]) },
     },
-    resume: {
-      input: obj(
-        {
-          user: str,
-          token: str,
-          acceptControlDrift: { type: "boolean" },
-          raiseCeilingUSD: { type: "number" },
-          extendRuntime: { type: "boolean" },
-        },
-        ["user", "token"],
-      ),
-      output: obj({ message: str }, ["message"]),
-      errors: { refused: obj({ reason: str }, ["reason"]) },
-    },
     factoryState: {
       input: obj({}),
       output: obj(
@@ -81,6 +59,16 @@ export const EsRpc = Rpc.define({
           ]),
           phases: { type: "array" },
           pending: strArray,
+          audits: { type: "array" },
+          tree: obj(
+            Object.fromEntries(
+              ["round", "total", "settled", "open", "deferred", "facts", "frontier"].map((key) => [
+                key,
+                { type: "number" },
+              ]),
+            ),
+            ["round", "total", "settled", "open", "deferred", "facts", "frontier"],
+          ),
         },
         ["stage", "spend", "phases", "pending"],
       ),

package/src/rpc.ts

@@ -1,29 +1,29 @@
-// Server side of the human-only channel. Each mutating method needs a token
-// from a preview made in the last two minutes over the same subject, so the
-// human confirms exactly what the dialog showed (no swap between preview and
-// confirm).
+// Server side of the TUI previews. Human-only mutations (approve, trust,
+// resume) happen at a terminal with the passphrase-sealed key, never via RPC:
+// the TUI previews, then points at `es approve`, `es trust`, `es factory
+// resume`. Only lspInstall still mutates via a preview token.
 import { randomBytes } from "node:crypto"
 import {
   type ApprovalStage,
+  allAudits,
   approvalSubject,
   capabilityLoss,
   commandSetHash,
-  factoryLayout,
+  describeTarget,
   factorySummary,
   type HookEngine,
   hashJson,
   installServer,
   isTrusted,
   loadGatesConfig,
+  readFrontier,
   readIdeas,
   readPlan,
   readResult,
   readScores,
-  recordApproval,
   recordConsent,
-  trustProject,
+  treeCounts,
   verifyControl,
-  writeJson,
 } from "@heretek-ai/es-core"
 import type { Runtime } from "./runtime.ts"
 import { pendingApprovals } from "./tools.ts"
@@ -36,7 +36,7 @@ interface Ticket {
 
 const TTL_MS = 120_000
 
-export function createRpcHandlers(runtime: Runtime, notify: () => Promise<void>, hooks?: HookEngine) {
+export function createRpcHandlers(runtime: Runtime, _notify: () => Promise<void>, hooks?: HookEngine) {
   const tickets = new Map<string, Ticket>()
   const issue = (kind: string, subject: unknown) => {
     const token = randomBytes(12).toString("hex")
@@ -75,14 +75,21 @@ export function createRpcHandlers(runtime: Runtime, notify: () => Promise<void>,
     status: async () => {
       const state = await runtime.factory.read()
       return {
-        summary: factorySummary(state),
+        summary: await runtime.factory.summary(state),
         stage: state?.stage ?? "NONE",
         pending: (await pendingApprovals(runtime.root)).map((item) => item.stage),
       }
     },
+    configState: async () => ({
+      config: JSON.stringify(runtime.config),
+      sources: [...runtime.configSources],
+      warnings: [...runtime.warnings],
+    }),
     factoryState: async () => {
       const state = await runtime.factory.read()
+      const frontier = await readFrontier(runtime.root).catch(() => undefined)
       return {
+        ...(frontier ? { tree: treeCounts(frontier) } : {}),
         stage: state?.stage ?? "NONE",
         ...(state?.runId ? { runId: state.runId } : {}),
         ...(state?.halt ? { halt: state.halt.reason } : {}),
@@ -101,6 +108,15 @@ export function createRpcHandlers(runtime: Runtime, notify: () => Promise<void>,
           qa: Object.fromEntries(Object.entries(phase.qa).filter(([, verdict]) => verdict !== undefined)),
         })),
         pending: (await pendingApprovals(runtime.root)).map((item) => item.stage),
+        audits: (state ? allAudits(state) : []).map((audit) => ({
+          id: audit.id,
+          target: describeTarget(audit.target),
+          status: audit.status,
+          round: audit.round,
+          thesis: audit.thesis?.verdict ?? "-",
+          antithesis: audit.antithesis?.verdict ?? "-",
+          ...(audit.tiebreak ? { tiebreak: audit.tiebreak.verdict } : {}),
+        })),
       }
     },
     lspState: async () => {
@@ -189,31 +205,6 @@ export function createRpcHandlers(runtime: Runtime, notify: () => Promise<void>,
         }
       }
     },
-    approve: async (input: unknown, context: any) => {
-      const { stage, user, token } = input as { stage: ApprovalStage; user: string; token: string }
-      try {
-        redeem(token, `approve:${stage}`, (await approvalSubject(runtime.root, stage)).subject)
-        const record = await recordApproval(runtime.root, {
-          stage,
-          channel: "tui",
-          approvedBy: user,
-          stateDir: runtime.stateDir,
-        })
-        await writeJson(
-          factoryLayout(runtime.root).pending,
-          (await pendingApprovals(runtime.root)).filter((item) => item.stage !== stage),
-        )
-        if (stage === "frontier") {
-          const state = await runtime.factory.read()
-          if (!state) await runtime.factory.begin(`human:${user}`)
-          if ((await runtime.factory.read())?.stage === "GRILL") await runtime.factory.beginResearch(`human:${user}`)
-        }
-        await notify()
-        return { message: `Approved ${stage} as ${record.approvedBy}.` }
-      } catch (error) {
-        return refused(context, error)
-      }
-    },
     previewTrust: async () => {
       const subject = await trustSubject()
       const trusted =
@@ -227,27 +218,6 @@ export function createRpcHandlers(runtime: Runtime, notify: () => Promise<void>,
         token: issue("trust", subject.key),
       }
     },
-    trust: async (input: unknown, context: any) => {
-      const { user, token } = input as { user: string; token: string }
-      try {
-        const subject = await trustSubject()
-        redeem(token, "trust", subject.key)
-        await trustProject(runtime.root, subject.gates.hash, subject.gates.lines, {
-          approvedBy: user,
-          stateDir: runtime.stateDir,
-        })
-        if (subject.hooks.hash)
-          await trustProject(runtime.root, subject.hooks.hash, subject.hooks.lines, {
-            approvedBy: user,
-            stateDir: runtime.stateDir,
-            kind: "hooks",
-          })
-        await hooks?.refresh()
-        return { message: `Trusted ${subject.lines.length} command/hook line(s).` }
-      } catch (error) {
-        return refused(context, error)
-      }
-    },
     previewLspInstall: async (input: unknown) => {
       const { id } = input as { id: string }
       const server = (await runtime.lsp.settings()).servers.find((item) => item.id === id)
@@ -306,26 +276,5 @@ export function createRpcHandlers(runtime: Runtime, notify: () => Promise<void>,
         token: issue("resume", state.halt),
       }
     },
-    resume: async (input: unknown, context: any) => {
-      const { user, token, acceptControlDrift, raiseCeilingUSD, extendRuntime } = input as {
-        user: string
-        token: string
-        acceptControlDrift?: boolean
-        raiseCeilingUSD?: number
-        extendRuntime?: boolean
-      }
-      try {
-        redeem(token, "resume", (await runtime.factory.read())?.halt)
-        const state = await runtime.factory.resume(user, {
-          ...(acceptControlDrift ? { acceptControlDrift } : {}),
-          ...(raiseCeilingUSD ? { raiseCeilingUSD } : {}),
-          ...(extendRuntime ? { extendRuntime } : {}),
-        })
-        await notify()
-        return { message: `Resumed at ${state.stage}.` }
-      } catch (error) {
-        return refused(context, error)
-      }
-    },
   }
 }