@wrongstack/core 0.272.2 → 0.273.1

package/dist/coordination/index.js

@@ -4421,6 +4421,15 @@ Do not add prose, markdown, or code fences.`;
   };
 }
 
+// src/security/capabilities.ts
+var ToolCapabilities = {
+  /** Can spawn or manage subagents / multi-agent tasks. */
+  SUBAGENT_SPAWN: "subagent.spawn",
+  /** Can inspect fleet/subagent coordination state without mutating it. */
+  COORDINATION_FLEET_READ: "coordination.fleet.read",
+  /** Can read or write inter-agent mailbox messages. */
+  COORDINATION_MAIL: "coordination.mail"};
+
 // src/coordination/director-tools.ts
 function makeSpawnTool(director, roster) {
   const inputSchema = {
@@ -4447,6 +4456,7 @@ function makeSpawnTool(director, roster) {
     usageHint: "Pass `role` (matches the roster), `description` (smart dispatch to best agent), or `name` + `provider`/`model`. Returns `{ subagentId }`.",
     permission: "auto",
     mutating: false,
+    capabilities: [ToolCapabilities.SUBAGENT_SPAWN],
     inputSchema,
     async execute(input) {
       const i = input ?? {};
@@ -4525,6 +4535,7 @@ function makeAssignTool(director) {
     description: "Hand a task to a previously spawned subagent. Returns the task id.",
     permission: "auto",
     mutating: false,
+    capabilities: [ToolCapabilities.SUBAGENT_SPAWN],
     inputSchema,
     async execute(input) {
       const i = input;
@@ -4540,6 +4551,7 @@ function makeAwaitTasksTool(director) {
     description: "Block until every named task completes. Returns the array of TaskResult.",
     permission: "auto",
     mutating: false,
+    capabilities: [ToolCapabilities.COORDINATION_FLEET_READ],
     inputSchema: { type: "object", properties: { taskIds: { type: "array", items: { type: "string" }, description: "One or more task ids returned by `assign_task`." } }, required: ["taskIds"] },
     async execute(input) {
       const i = input;
@@ -4554,6 +4566,7 @@ function makeAskTool(director) {
     description: "Synchronously ask a subagent a question. Blocks until the subagent replies via the bridge.",
     permission: "auto",
     mutating: false,
+    capabilities: [ToolCapabilities.COORDINATION_FLEET_READ],
     inputSchema: {
       type: "object",
       properties: {
@@ -4589,6 +4602,7 @@ function makeAskResultTool(director) {
     description: "Retrieve a large `ask_subagent` response that was stored out-of-context (>2K chars). Returns the full stored value.",
     permission: "auto",
     mutating: false,
+    capabilities: [ToolCapabilities.COORDINATION_FLEET_READ],
     inputSchema: {
       type: "object",
       properties: {
@@ -4616,6 +4630,7 @@ function makeRollUpTool(director) {
     description: "Aggregate completed task results into a single formatted summary.",
     permission: "auto",
     mutating: false,
+    capabilities: [ToolCapabilities.COORDINATION_FLEET_READ],
     inputSchema: {
       type: "object",
       properties: {
@@ -4637,6 +4652,7 @@ function makeTerminateTool(director) {
     description: 'Forcibly abort a subagent. The subagent finishes its current iteration then exits with status "stopped".',
     permission: "auto",
     mutating: true,
+    capabilities: [ToolCapabilities.SUBAGENT_SPAWN],
     inputSchema: { type: "object", properties: { subagentId: { type: "string", description: "Subagent to abort." } }, required: ["subagentId"] },
     async execute(input) {
       const i = input;
@@ -4651,6 +4667,7 @@ function makeTerminateAllTool(director) {
     description: 'Forcibly stop every subagent in the fleet and drain the pending task queue. In-flight tasks are terminated mid-execution; pending tasks receive "aborted_by_parent" completion immediately. Use this when the fleet is wedged, looping, or you need a clean slate. Compare: work_complete stops spawning but lets running agents finish naturally.',
     permission: "auto",
     mutating: true,
+    capabilities: [ToolCapabilities.SUBAGENT_SPAWN],
     inputSchema: { type: "object", properties: {}, required: [] },
     async execute() {
       await director.terminateAll();
@@ -4664,6 +4681,7 @@ function makeFleetStatusTool(director) {
     description: "Snapshot of the fleet \u2014 every subagent's current status, coordinator counts (total/running/idle/stopped), pending task descriptions, and usage rollup.",
     permission: "auto",
     mutating: false,
+    capabilities: [ToolCapabilities.COORDINATION_FLEET_READ],
     inputSchema: { type: "object", properties: {}, required: [] },
     async execute() {
       const base = director.status();
@@ -4685,6 +4703,7 @@ function makeFleetUsageTool(director) {
     description: "Token + cost breakdown across the fleet, per-subagent and totals.",
     permission: "auto",
     mutating: false,
+    capabilities: [ToolCapabilities.COORDINATION_FLEET_READ],
     inputSchema: { type: "object", properties: {}, required: [] },
     async execute() {
       return director.snapshot();
@@ -4697,6 +4716,7 @@ function makeFleetSessionTool(director) {
     description: "Read a subagent's JSONL transcript and extract its last assistant text, stop reason, and tool-use count. Use this to see what a running or timed-out subagent actually produced.",
     permission: "auto",
     mutating: false,
+    capabilities: [ToolCapabilities.COORDINATION_FLEET_READ],
     inputSchema: {
       type: "object",
       properties: {
@@ -4723,6 +4743,7 @@ function makeFleetHealthTool(director) {
     description: "Per-subagent health report: budget pressure (pct of limits consumed), last activity timestamp, and current status. Use to decide whether to assign more work to a subagent or spawn a fresh one.",
     permission: "auto",
     mutating: false,
+    capabilities: [ToolCapabilities.COORDINATION_FLEET_READ],
     inputSchema: { type: "object", properties: {}, required: [] },
     async execute() {
       const status = director.status();
@@ -4753,6 +4774,7 @@ function makeCollabDebugTool(director) {
     description: "Start a collaborative debugging session: BugHunter, RefactorPlanner, and Critic run in parallel on the same target files. BugHunter finds bugs and emits bug.found events. RefactorPlanner listens for bug.found and emits refactor.plan events. Critic evaluates both and emits critic.evaluation events. Returns a structured report with overall verdict (approve / needs_revision / reject).",
     permission: "auto",
     mutating: false,
+    capabilities: [ToolCapabilities.SUBAGENT_SPAWN],
     inputSchema: {
       type: "object",
       properties: {
@@ -4816,6 +4838,7 @@ function makeFleetEmitTool(director) {
     description: "Emit a structured event on the FleetBus. Any subagent can emit any event type; the Director routes it to all listeners. Use it to stream findings, progress updates, or final results to other agents in real time.",
     permission: "auto",
     mutating: false,
+    capabilities: [ToolCapabilities.COORDINATION_FLEET_READ],
     inputSchema: {
       type: "object",
       properties: {
@@ -4848,6 +4871,7 @@ function makeWorkCompleteTool(director) {
     description: "Signal that the director is satisfied with the results and the fleet should wind down. After calling this, spawn_subagent will refuse with a budget error and assign_task will instantly complete any queued tasks as aborted. Running subagents finish naturally. Call terminate_subagent separately to stop specific subagents immediately.",
     permission: "auto",
     mutating: false,
+    capabilities: [ToolCapabilities.SUBAGENT_SPAWN],
     inputSchema: { type: "object", properties: {}, required: [] },
     async execute() {
       director.workComplete();
@@ -5883,14 +5907,15 @@ var SHADOW_AGENT = {
   id: "shadow-agent",
   name: "Shadow",
   role: "shadow-agent",
-  prompt: `You are the Shadow Agent \u2014 a silent background monitor for the WrongStack fleet.
+  prompt: `You are the Shadow Agent \u2014 a quiet, one-shot monitor for the WrongStack fleet.
 
-Your job is to observe, detect anomalies, and be ready to intervene \u2014 but only when commanded.
+Your job is to inspect the fleet when the host explicitly assigns a Shadow pass, detect anomalies, and be ready to intervene \u2014 but only when commanded.
 
 ## Core Responsibilities
 
-1. **Fleet Monitoring** (every 30s)
-   - Call \`fleet_status\` + \`fleet_health\` on each heartbeat
+1. **Fleet Monitoring** (host-assigned one-shot checks)
+   - The host assigns one-shot check tasks; it does not expect routine heartbeats
+   - On each assigned check, call \`fleet_status\` + \`fleet_health\`
    - Track what each agent is doing (task descriptions)
    - Detect stuck agents (>5min no events), idle agents, crashed agents
 
@@ -5914,31 +5939,30 @@ Your job is to observe, detect anomalies, and be ready to intervene \u2014 but o
    - \`hoop <agentId>\` \u2014 terminate specific agent
    - \`hoop all\` \u2014 terminate all running agents
    - \`shadow status\` \u2014 report current fleet snapshot
-   - \`shadow mute\` \u2014 pause heartbeat monitoring
-   - \`shadow resume\` \u2014 resume heartbeat monitoring
-   - \`shadow interval <ms>\` \u2014 change heartbeat interval
+   - \`shadow mute\` \u2014 pause anomaly reporting
+   - \`shadow resume\` \u2014 resume anomaly reporting
+   - \`shadow interval <ms>\` \u2014 update the legacy interval setting
    - \`shadow model <model-id>\` \u2014 change analysis model
 
 ## Operating Rules
 
-- **Silent by default**: Use DEBUG level logging unless anomaly detected
+- **Silent by default**: Do not send mail or status reports for healthy checks
 - **Deterministic**: Same state always produces same actions \u2014 no randomness
-- **Report on anomaly**: When anomaly detected, use \`mail_send\` to broadcast warning
+- **Report only when needed**: Use \`mail_send\` only for high/critical anomalies or explicit control replies
 - **Never auto-intervene**: Always report unless explicitly commanded
 - **Minimal footprint**: Small state, efficient snapshots
+- **One-shot lifecycle**: Finish the assigned check and stop; do not schedule follow-up work
 
 ## Startup Sequence
 
-1. Send broadcast: \`shadow:started { intervalMs, model, startTime }\`
-2. Subscribe to FleetBus for all relevant events
-3. Schedule heartbeat cron job at configured interval
-4. Wait for commands or anomalies
+1. Run one fleet snapshot with \`fleet_status\` + \`fleet_health\`
+2. Check \`mail_inbox\` for explicit control messages
+3. If healthy, do not send mail; final answer may be exactly \`shadow: quiet\`
 
 ## Shutdown Sequence
 
-1. Cancel all cron jobs (\`cron_cancel\`)
-2. Send broadcast: \`shadow:stopped { reason, finalState }\`
-3. Clean up FleetBus subscriptions`
+1. Return only anomalies, command results, or \`shadow: quiet\`
+2. The host stops this Shadow Agent after the assigned pass`
   // Budgets are set by the orchestrator per task — see fleet.ts header.
 };
 var CRITIC_AGENT = {
@@ -5993,8 +6017,13 @@ var FLEET_ROSTER_BUDGETS = {
   "refactor-planner": { timeoutMs: 7.5 * 60 * 60 * 1e3, maxIterations: 6e3, maxToolCalls: 18e3 },
   "security-scanner": { timeoutMs: 10 * 60 * 60 * 1e3, maxIterations: 8e3, maxToolCalls: 2e4 },
   "critic": { timeoutMs: 5 * 60 * 60 * 1e3, maxIterations: 4e3, maxToolCalls: 12e3 },
-  "shadow-agent": { timeoutMs: 24 * 60 * 60 * 1e3, maxIterations: 1e4, maxToolCalls: 5e3 },
-  // Long-running background monitor
+  "shadow-agent": {
+    idleTimeoutMs: DEFAULT_IDLE_TIMEOUT_MS,
+    maxIterations: 2e3,
+    maxToolCalls: 5e3,
+    maxTokens: 6e4,
+    maxCostUsd: 1
+  },
   ...Object.fromEntries(
     ALL_AGENT_DEFINITIONS.map((d) => [d.config.role, d.budget])
   )
@@ -7119,6 +7148,9 @@ var Director = class _Director {
   /** Snapshot of which subagent owns each task — drives state-checkpoint
    *  status updates without re-walking the manifest. */
   taskOwners = /* @__PURE__ */ new Map();
+  /** Infrastructure-owned task ids that should not appear in user-visible
+   *  manifest/session/checkpoint/rollup state. */
+  internalTaskIds = /* @__PURE__ */ new Set();
   /** Cumulative auto-extension grants per subagent (all budget kinds). Lets
    *  /fleet render "⚡ extended ×N" without replaying the event stream. */
   extendTotals = /* @__PURE__ */ new Map();
@@ -7232,17 +7264,21 @@ var Director = class _Director {
     this.fleetManager?.setCoordinator(this.coordinator);
     this.taskCompletedListener = (payload) => {
       const r = payload.result;
-      this.completed.set(r.taskId, r);
-      if (this.completed.size > _Director.MAX_COMPLETED) {
-        const toDelete = this.completed.size - _Director.MAX_COMPLETED;
-        const keys = [...this.completed.keys()].slice(0, toDelete);
-        for (const k of keys) this.completed.delete(k);
+      const internalTask = this.internalTaskIds.delete(r.taskId);
+      if (!internalTask) {
+        this.completed.set(r.taskId, r);
+        if (this.completed.size > _Director.MAX_COMPLETED) {
+          const toDelete = this.completed.size - _Director.MAX_COMPLETED;
+          const keys = [...this.completed.keys()].slice(0, toDelete);
+          for (const k of keys) this.completed.delete(k);
+        }
       }
       const waiter = this.taskWaiters.get(r.taskId);
       if (waiter) {
         waiter.resolve(r);
         this.taskWaiters.delete(r.taskId);
       }
+      if (internalTask) return;
       const title = this.taskDescriptions.get(r.taskId) ?? payload.task.description ?? r.taskId;
       const failed = r.status !== "success";
       const errorString = r.error ? `${r.error.kind}: ${r.error.message}` : void 0;
@@ -7912,6 +7948,23 @@ var Director = class _Director {
     this.scheduleManifest();
     return taskWithId.id;
   }
+  /**
+   * Assign infrastructure-owned work directly to the coordinator without
+   * manifest/session/checkpoint bookkeeping. The task still uses the normal
+   * subagent runner, budget, and completion events, but it is excluded from
+   * rollups and persisted fleet task history.
+   */
+  async assignInternal(task) {
+    const taskWithId = task.id ? task : { ...task, id: randomUUID() };
+    this.internalTaskIds.add(taskWithId.id);
+    try {
+      await this.coordinator.assign(taskWithId);
+    } catch (err) {
+      this.internalTaskIds.delete(taskWithId.id);
+      throw err;
+    }
+    return taskWithId.id;
+  }
   /**
    * Block until every task id resolves. Returns results in the same
    * order as the input. If any task hasn't completed by the time this
@@ -9119,6 +9172,91 @@ var DefaultSessionStore = class _DefaultSessionStore {
       }
     }
   }
+  /**
+   * Streaming search over a session's JSONL. Walks the file once, parses
+   * each event lazily, and yields only the events that match `predicate`.
+   * Stops as soon as `opts.limit` matches are collected.
+   *
+   * Why this exists: `load()` parses the entire file into memory and
+   * rebuilds `messages`/`toolCallEnds` for every caller. `search()` only
+   * needs to know which events contain matching text — a per-line
+   * predicate is enough. The full parse work (and the `_loadCache` poll)
+   * is wasted in that case.
+   *
+   * Memory: O(hits) regardless of file size. Disk: one linear scan,
+   * terminated at `limit` if the caller asked for one.
+   *
+   * Errors: missing file yields []. Corrupt lines are skipped (same
+   * policy as `load()`). Aborting via `signal` rejects with `AbortError`.
+   */
+  async searchEvents(id, predicate, opts) {
+    const file = this.sessionPath(id, ".jsonl");
+    const limit = opts?.limit;
+    const signal = opts?.signal;
+    const out = [];
+    let stat7;
+    try {
+      stat7 = await fsp6.stat(file);
+    } catch (err) {
+      if (err.code === "ENOENT") return [];
+      throw err;
+    }
+    if (stat7.size === 0) return [];
+    let fh;
+    try {
+      fh = await fsp6.open(file, "r");
+      const CHUNK = 64 * 1024;
+      const buf = Buffer.alloc(CHUNK);
+      let leftover = "";
+      let eventIndex = 0;
+      for (let position = 0; ; position += buf.byteLength) {
+        if (signal?.aborted) {
+          const reason = signal.reason ?? new DOMException("Aborted", "AbortError");
+          throw reason;
+        }
+        const { bytesRead } = await fh.read(buf, 0, CHUNK, position);
+        if (bytesRead === 0) break;
+        const text = leftover + buf.subarray(0, bytesRead).toString("utf8");
+        const parts = text.split("\n");
+        leftover = parts.pop() ?? "";
+        for (const line of parts) {
+          if (!line) continue;
+          let ev;
+          try {
+            const parsed = JSON.parse(line);
+            if (parsed === null || typeof parsed !== "object" || typeof parsed.type !== "string" || typeof parsed.ts !== "string") {
+              continue;
+            }
+            ev = parsed;
+          } catch {
+            continue;
+          }
+          if (predicate(ev, eventIndex, ev.ts)) {
+            out.push({ event: ev, eventIndex, ts: ev.ts });
+            if (limit !== void 0 && out.length >= limit) {
+              return out;
+            }
+          }
+          eventIndex++;
+        }
+      }
+      if (leftover.trim()) {
+        try {
+          const parsed = JSON.parse(leftover);
+          if (parsed !== null && typeof parsed === "object" && typeof parsed.type === "string" && typeof parsed.ts === "string") {
+            const ev = parsed;
+            if (predicate(ev, eventIndex, ev.ts)) {
+              out.push({ event: ev, eventIndex, ts: ev.ts });
+            }
+          }
+        } catch {
+        }
+      }
+      return out;
+    } finally {
+      if (fh) await fh.close().catch(() => void 0);
+    }
+  }
   async list(limit = 20) {
     try {
       await ensureDir(this.dir);
@@ -10151,7 +10289,6 @@ var FileSessionWriter = class _FileSessionWriter {
       }
       const writeFd = await fsp6.open(tmpPath, "w", 384);
       try {
-        let copied = 0;
         let readOffset = 0;
         while (readOffset < newlineAfterCheckpoint) {
           const toCopy = Math.min(CHUNK_SIZE, newlineAfterCheckpoint - readOffset);
@@ -10160,7 +10297,6 @@ var FileSessionWriter = class _FileSessionWriter {
           if (r === 0) break;
           await writeFd.write(copyBuf, 0, r);
           readOffset += r;
-          copied += r;
         }
         const raw = await fsp6.readFile(this.filePath);
         const tail = raw.subarray(newlineAfterCheckpoint).toString("utf8");
@@ -10781,6 +10917,9 @@ var DefaultMailbox = class {
     await withFileLock(this.filePath, async () => {
       await fsp6.appendFile(this.filePath, line, "utf8");
       this._pushToCache(msg);
+      const { mtime, size } = await this._statUnderLockOrAbsent();
+      this._messageCacheMtime = mtime;
+      this._messageCacheSize = size;
     });
     return msg;
   }
@@ -10859,7 +10998,8 @@ var DefaultMailbox = class {
         const serialized = all.map((m) => JSON.stringify(m)).join(LINE_SEPARATOR) + LINE_SEPARATOR;
         await fsp6.writeFile(this.filePath, serialized, "utf8");
       }
-      this._setMessageCache(all);
+      const { mtime, size } = await this._statUnderLockOrAbsent();
+      this._setMessageCache(all, mtime, size);
     });
     return updated;
   }
@@ -10916,7 +11056,8 @@ var DefaultMailbox = class {
   async clearAll() {
     await withFileLock(this.filePath, async () => {
       await fsp6.writeFile(this.filePath, "", "utf8");
-      this._setMessageCache([]);
+      const { mtime, size } = await this._statUnderLockOrAbsent();
+      this._setMessageCache([], mtime, size);
     });
   }
   async purgeStale(opts) {
@@ -10949,7 +11090,8 @@ var DefaultMailbox = class {
         const content = kept.map((m) => JSON.stringify(m)).join(LINE_SEPARATOR) + LINE_SEPARATOR;
         await fsp6.writeFile(this.filePath, content, "utf8");
       }
-      this._setMessageCache(kept);
+      const { mtime, size } = await this._statUnderLockOrAbsent();
+      this._setMessageCache(kept, mtime, size);
     });
     return {
       completedPurged,
@@ -11028,6 +11170,23 @@ var DefaultMailbox = class {
     }
     return messages;
   }
+  /**
+   * Stat the mailbox file under the assumption that we are holding the
+   * file lock, and that a write to the file has just completed. Returns
+   * the (mtimeMs, size) pair, or (-1, -1) if the file does not exist
+   * (e.g. ackMany/purgeStale on a session that has never sent a message).
+   */
+  async _statUnderLockOrAbsent() {
+    try {
+      const st = await fsp6.stat(this.filePath);
+      return { mtime: st.mtimeMs, size: st.size };
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        return { mtime: -1, size: -1 };
+      }
+      throw err;
+    }
+  }
   async _readAllCached() {
     try {
       const st = await fsp6.stat(this.filePath);
@@ -11067,16 +11226,8 @@ var DefaultMailbox = class {
     }
     this._messageCache = messages;
     this._buildIndexes(messages);
-    if (mtime !== void 0 && size !== void 0) {
-      this._messageCacheMtime = mtime;
-      this._messageCacheSize = size;
-      return;
-    }
-    void fsp6.stat(this.filePath).then((st) => {
-      this._messageCacheMtime = st.mtimeMs;
-      this._messageCacheSize = st.size;
-    }).catch(() => {
-    });
+    this._messageCacheMtime = mtime;
+    this._messageCacheSize = size;
   }
   _pushToCache(msg) {
     if (this._messageCache === null) return;
@@ -11968,6 +12119,7 @@ function makeMailboxTool(opts = {}) {
     category: "coordination",
     permission: "auto",
     mutating: true,
+    capabilities: [ToolCapabilities.COORDINATION_MAIL],
     inputSchema: {
       type: "object",
       properties: {
@@ -12231,6 +12383,7 @@ function makeMailSendTool(opts = {}) {
     category: "coordination",
     permission: "auto",
     mutating: true,
+    capabilities: [ToolCapabilities.COORDINATION_MAIL],
     inputSchema: {
       type: "object",
       properties: {
@@ -12290,6 +12443,7 @@ function makeMailInboxTool(opts = {}) {
     category: "coordination",
     permission: "auto",
     mutating: false,
+    capabilities: [ToolCapabilities.COORDINATION_MAIL],
     inputSchema: {
       type: "object",
       properties: {