@wrongstack/core 0.155.0 → 0.250.0

package/dist/sdd/index.js

@@ -617,6 +617,81 @@ function topologicalSort(graph) {
   return result;
 }
 
+// src/types/errors.ts
+var ERROR_CODES = {
+  // Provider
+  PROVIDER_RATE_LIMITED: "PROVIDER_RATE_LIMITED",
+  PROVIDER_AUTH_FAILED: "PROVIDER_AUTH_FAILED",
+  PROVIDER_OVERLOADED: "PROVIDER_OVERLOADED",
+  PROVIDER_INVALID_REQUEST: "PROVIDER_INVALID_REQUEST",
+  PROVIDER_SERVER_ERROR: "PROVIDER_SERVER_ERROR",
+  PROVIDER_NETWORK_ERROR: "PROVIDER_NETWORK_ERROR",
+  // Agent
+  AGENT_ITERATION_LIMIT: "AGENT_ITERATION_LIMIT",
+  AGENT_ABORTED: "AGENT_ABORTED",
+  AGENT_RUN_FAILED: "AGENT_RUN_FAILED",
+  // SDD (Spec-Driven Development)
+  SDD_VALIDATION_FAILED: "SDD_VALIDATION_FAILED",
+  SDD_PARSE_FAILED: "SDD_PARSE_FAILED",
+  SDD_INVALID_STATE: "SDD_INVALID_STATE",
+  SDD_NOT_READY: "SDD_NOT_READY"};
+var WrongStackError = class extends Error {
+  code;
+  subsystem;
+  severity;
+  recoverable;
+  context;
+  constructor(opts) {
+    super(opts.message, { cause: opts.cause });
+    this.name = "WrongStackError";
+    this.code = opts.code;
+    this.subsystem = opts.subsystem;
+    this.severity = opts.severity ?? "error";
+    this.recoverable = opts.recoverable ?? false;
+    this.context = opts.context;
+  }
+  /**
+   * Render a one-line user-facing description.
+   * Subclasses should override for domain-specific formatting.
+   */
+  describe() {
+    const ctx = this.context ? ` ${formatContext(this.context)}` : "";
+    return `${this.code}: ${this.message}${ctx}`;
+  }
+};
+function formatContext(ctx) {
+  const parts = Object.entries(ctx).filter(([, v]) => v !== void 0).slice(0, 3).map(([k, v]) => `${k}=${String(v)}`);
+  return parts.length > 0 ? `[${parts.join(" ")}]` : "";
+}
+var AgentError = class extends WrongStackError {
+  constructor(opts) {
+    super({
+      message: opts.message,
+      code: opts.code,
+      subsystem: "agent",
+      severity: opts.code === ERROR_CODES.AGENT_ABORTED ? "warning" : "error",
+      recoverable: opts.recoverable ?? opts.code === ERROR_CODES.AGENT_ITERATION_LIMIT,
+      context: opts.context,
+      cause: opts.cause
+    });
+    this.name = "AgentError";
+  }
+};
+var SddError = class extends WrongStackError {
+  constructor(opts) {
+    super({
+      message: opts.message,
+      code: opts.code,
+      subsystem: "sdd",
+      severity: opts.code === ERROR_CODES.SDD_PARSE_FAILED ? "warning" : "error",
+      recoverable: opts.code === ERROR_CODES.SDD_NOT_READY,
+      context: opts.context,
+      cause: opts.cause
+    });
+    this.name = "SddError";
+  }
+};
+
 // src/sdd/task-tracker.ts
 var TaskTracker = class {
   constructor(opts) {
@@ -651,7 +726,10 @@ var TaskTracker = class {
     return this.graph;
   }
   addNode(node) {
-    if (!this.graph) throw new Error("No graph loaded");
+    if (!this.graph) throw new SddError({
+      message: "No graph loaded",
+      code: ERROR_CODES.SDD_INVALID_STATE
+    });
     const now = Date.now();
     const newNode = {
       ...node,
@@ -669,7 +747,10 @@ var TaskTracker = class {
     return newNode;
   }
   addEdge(from, to, type = "depends_on") {
-    if (!this.graph) throw new Error("No graph loaded");
+    if (!this.graph) throw new SddError({
+      message: "No graph loaded",
+      code: ERROR_CODES.SDD_INVALID_STATE
+    });
     this.graph.edges.push({
       id: crypto.randomUUID(),
       from,
@@ -680,9 +761,16 @@ var TaskTracker = class {
     this.persist();
   }
   updateNodeStatus(id, status, reason) {
-    if (!this.graph) throw new Error("No graph loaded");
+    if (!this.graph) throw new SddError({
+      message: "No graph loaded",
+      code: ERROR_CODES.SDD_INVALID_STATE
+    });
     const node = this.graph.nodes.get(id);
-    if (!node) throw new Error(`Node ${id} not found`);
+    if (!node) throw new SddError({
+      message: `Node ${id} not found`,
+      code: ERROR_CODES.SDD_NOT_READY,
+      context: { nodeId: id }
+    });
     const from = node.status;
     const now = Date.now();
     node.status = status;
@@ -705,9 +793,16 @@ var TaskTracker = class {
     this.persist();
   }
   updateNode(id, patch) {
-    if (!this.graph) throw new Error("No graph loaded");
+    if (!this.graph) throw new SddError({
+      message: "No graph loaded",
+      code: ERROR_CODES.SDD_INVALID_STATE
+    });
     const node = this.graph.nodes.get(id);
-    if (!node) throw new Error(`Node ${id} not found`);
+    if (!node) throw new SddError({
+      message: `Node ${id} not found`,
+      code: ERROR_CODES.SDD_NOT_READY,
+      context: { nodeId: id }
+    });
     if (patch.title !== void 0) node.title = patch.title;
     if (patch.description !== void 0) node.description = patch.description;
     if (patch.priority !== void 0) node.priority = patch.priority;
@@ -826,7 +921,12 @@ var TaskTracker = class {
   persist() {
     if (!this.graph) return;
     this.opts.store.saveGraph(this.graph).catch((err) => {
-      this.opts.onPersistError ? this.opts.onPersistError(err) : console.warn("[task-tracker] saveGraph failed:", err instanceof Error ? err.message : String(err));
+      this.opts.onPersistError ? this.opts.onPersistError(err) : console.warn(JSON.stringify({
+        level: "warn",
+        event: "task_tracker.save_graph_failed",
+        message: err instanceof Error ? err.message : String(err),
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      }));
     });
   }
 };
@@ -879,12 +979,14 @@ var TaskFlow = class {
     const analysis = parser.analyze(this.spec);
     this.emit("spec.analyzed", { analysis });
     if (analysis.completeness < 50) {
-      this.emit("error", {
-        phase: "analyzing",
-        error: new Error(`Spec completeness too low: ${analysis.completeness}%`)
+      const err = new SddError({
+        message: `Spec completeness too low: ${analysis.completeness}%`,
+        code: ERROR_CODES.SDD_VALIDATION_FAILED,
+        context: { completeness: analysis.completeness }
       });
+      this.emit("error", { phase: "analyzing", error: err });
       this.setPhase("failed");
-      throw new Error("Spec too incomplete");
+      throw err;
     }
     this.setPhase("generating");
     const generator = new TaskGenerator({ taskTracker: this.opts.tracker });
@@ -892,7 +994,11 @@ var TaskFlow = class {
     return this.graph;
   }
   async execute(ctx) {
-    if (!this.graph) throw new Error("No graph loaded. Call fromSpec first.");
+    if (!this.graph) throw new SddError({
+      message: "No graph loaded. Call fromSpec first.",
+      code: ERROR_CODES.SDD_INVALID_STATE,
+      context: { phase: this.phase }
+    });
     this.setPhase("executing");
     this.stopped = false;
     const pendingTasks = this.getExecutableTasks();
@@ -932,7 +1038,11 @@ var TaskFlow = class {
   }
   async reviewTask(taskId, approved, comment) {
     const task = this.opts.tracker.getNode(taskId);
-    if (!task) throw new Error(`Task ${taskId} not found`);
+    if (!task) throw new SddError({
+      message: `Task ${taskId} not found`,
+      code: ERROR_CODES.SDD_NOT_READY,
+      context: { taskId }
+    });
     if (approved) {
       this.opts.tracker.updateNodeStatus(taskId, "completed", comment);
       this.emit("task.completed", { taskId });
@@ -1246,7 +1356,9 @@ var TaskGraphStore = class {
 // src/utils/expect-defined.ts
 function expectDefined(value, label) {
   if (value === null || value === void 0) {
-    throw new Error("Expected value to be defined");
+    const err = new Error("Expected value to be defined");
+    err.name = "ExpectDefinedError";
+    throw err;
   }
   return value;
 }
@@ -1584,7 +1696,11 @@ var AISpecBuilder = class {
     switch (this.session.phase) {
       case "questioning":
         if (!this.session.spec) {
-          throw new Error("Cannot approve: no spec generated yet.");
+          throw new SddError({
+            message: "Cannot approve: no spec generated yet.",
+            code: ERROR_CODES.SDD_INVALID_STATE,
+            context: { phase: "questioning", sessionId: this.session.id }
+          });
         }
         this.session.phase = "spec_review";
         break;
@@ -1642,7 +1758,11 @@ var AISpecBuilder = class {
    */
   async saveSpec() {
     if (!this.session.spec) {
-      throw new Error("No spec to save.");
+      throw new SddError({
+        message: "No spec to save.",
+        code: ERROR_CODES.SDD_NOT_READY,
+        context: { sessionId: this.session.id }
+      });
     }
     await this.store.save(this.session.spec);
     return this.session.spec;
@@ -1657,17 +1777,30 @@ var AISpecBuilder = class {
     try {
       parsed = JSON.parse(jsonStr);
     } catch (e) {
-      throw new Error(`Invalid JSON for spec: ${e instanceof Error ? e.message : "parse error"}`);
+      throw new SddError({
+        message: "Invalid JSON for spec",
+        code: ERROR_CODES.SDD_PARSE_FAILED,
+        cause: e,
+        context: { detail: e instanceof Error ? e.message : "parse error" }
+      });
     }
     if (!parsed || typeof parsed !== "object") {
-      throw new Error("Spec JSON must be an object.");
+      throw new SddError({
+        message: "Spec JSON must be an object",
+        code: ERROR_CODES.SDD_VALIDATION_FAILED,
+        context: { actualType: typeof parsed }
+      });
     }
     const raw = parsed;
     const now = Date.now();
     const title = String(raw.title ?? this.session.title ?? "Untitled");
     const overview = String(raw.overview ?? "");
     if (!overview || overview === "undefined") {
-      throw new Error("Spec must have an overview.");
+      throw new SddError({
+        message: "Spec must have an overview",
+        code: ERROR_CODES.SDD_VALIDATION_FAILED,
+        context: { field: "overview", title }
+      });
     }
     const rawSections = Array.isArray(raw.sections) ? raw.sections : [];
     const sections = rawSections.filter((s) => s && typeof s === "object").map((s) => ({
@@ -1883,6 +2016,11 @@ function templateToMarkdown(template, title) {
   return lines.join("\n");
 }
 
+// src/utils/string.ts
+function truncate(s, max) {
+  return s.length <= max ? s : `${s.slice(0, max - 1)}\u2026`;
+}
+
 // src/sdd/task-visualizer.ts
 var STATUS_ICON = {
   pending: "\u25CB",
@@ -2033,10 +2171,6 @@ function renderSpecAnalysis(spec, analysis) {
   }
   return lines.join("\n");
 }
-function truncate(str, maxLen) {
-  if (str.length <= maxLen) return str;
-  return str.slice(0, maxLen - 1) + "\u2026";
-}
 
 // src/sdd/critical-path.ts
 function analyzeCriticalPath(graph) {
@@ -2211,9 +2345,11 @@ function computeParallelGroups(graph, blockedByMap) {
 
 // src/utils/assert-never.ts
 function assertNever(x, message) {
-  throw new Error(
+  const err = new Error(
     `Unhandled case: ${JSON.stringify(x)}`
   );
+  err.name = "AssertNeverError";
+  throw err;
 }
 
 // src/sdd/spec-versioning.ts
@@ -3136,21 +3272,40 @@ function makeAgentSubagentRunner(opts) {
       if (budgetError) throw budgetError;
     }
     if (result.status === "failed") {
-      throw result.error instanceof Error ? result.error : new Error(String(result.error ?? "agent failed"));
+      throw result.error instanceof AgentError ? result.error : new AgentError({
+        message: result.error instanceof Error ? result.error.message : String(result.error ?? "agent failed"),
+        code: ERROR_CODES.AGENT_RUN_FAILED,
+        cause: result.error
+      });
     }
     if (result.status === "aborted") {
-      throw new Error("agent aborted");
+      throw new AgentError({
+        message: "agent aborted",
+        code: ERROR_CODES.AGENT_ABORTED
+      });
     }
     if (result.status === "max_iterations") {
-      throw new Error("agent exhausted iteration limit");
+      throw new AgentError({
+        message: "agent exhausted iteration limit",
+        code: ERROR_CODES.AGENT_ITERATION_LIMIT,
+        recoverable: true
+      });
     }
     const usage = ctx.budget.usage();
     const finalText = (result.finalText ?? "").trim();
     if (finalText.length === 0 && usage.toolCalls === 0) {
-      throw new Error("empty response");
+      throw new AgentError({
+        message: "empty response \u2014 agent produced no text and no tool calls",
+        code: ERROR_CODES.AGENT_RUN_FAILED,
+        context: { iterations: result.iterations }
+      });
     }
     if (finalText.length === 0 && lastToolFailed !== null) {
-      throw new Error(`tool failed: ${lastToolFailed}`);
+      throw new AgentError({
+        message: `unrecovered tool failure: ${lastToolFailed} \u2014 agent ended turn without acknowledging the error`,
+        code: ERROR_CODES.AGENT_RUN_FAILED,
+        context: { tool: lastToolFailed, iterations: result.iterations }
+      });
     }
     return {
       result: result.finalText,
@@ -3163,44 +3318,6 @@ function defaultFormatTaskInput(task) {
   return task.description ?? "";
 }
 
-// src/types/errors.ts
-var ERROR_CODES = {
-  // Provider
-  PROVIDER_RATE_LIMITED: "PROVIDER_RATE_LIMITED",
-  PROVIDER_AUTH_FAILED: "PROVIDER_AUTH_FAILED",
-  PROVIDER_OVERLOADED: "PROVIDER_OVERLOADED",
-  PROVIDER_INVALID_REQUEST: "PROVIDER_INVALID_REQUEST",
-  PROVIDER_SERVER_ERROR: "PROVIDER_SERVER_ERROR",
-  PROVIDER_NETWORK_ERROR: "PROVIDER_NETWORK_ERROR"};
-var WrongStackError = class extends Error {
-  code;
-  subsystem;
-  severity;
-  recoverable;
-  context;
-  constructor(opts) {
-    super(opts.message, { cause: opts.cause });
-    this.name = "WrongStackError";
-    this.code = opts.code;
-    this.subsystem = opts.subsystem;
-    this.severity = opts.severity ?? "error";
-    this.recoverable = opts.recoverable ?? false;
-    this.context = opts.context;
-  }
-  /**
-   * Render a one-line user-facing description.
-   * Subclasses should override for domain-specific formatting.
-   */
-  describe() {
-    const ctx = this.context ? ` ${formatContext(this.context)}` : "";
-    return `${this.code}: ${this.message}${ctx}`;
-  }
-};
-function formatContext(ctx) {
-  const parts = Object.entries(ctx).filter(([, v]) => v !== void 0).slice(0, 3).map(([k, v]) => `${k}=${String(v)}`);
-  return parts.length > 0 ? `[${parts.join(" ")}]` : "";
-}
-
 // src/types/provider.ts
 var ProviderError = class extends WrongStackError {
   status;
@@ -3241,7 +3358,7 @@ var ProviderError = class extends WrongStackError {
     const detail = this.body?.message?.trim();
     const reqId = this.body?.requestId ? ` [req ${this.body.requestId.slice(0, 16)}${this.body.requestId.length > 16 ? "\u2026" : ""}]` : "";
     if (detail && detail.length > 0) {
-      return `${head}: ${truncate2(detail, 240)}${reqId}`;
+      return `${head}: ${truncate(detail, 240)}${reqId}`;
     }
     return `${head}${reqId}`;
   }
@@ -3259,9 +3376,6 @@ function describeStatus(status, type) {
   if (type) return `${type} (${status})`;
   return `HTTP ${status}`;
 }
-function truncate2(s, n) {
-  return s.length <= n ? s : `${s.slice(0, n - 1)}\u2026`;
-}
 function providerStatusToCode(status, type) {
   if (status === 0) return ERROR_CODES.PROVIDER_NETWORK_ERROR;
   if (type === "rate_limit_error" || status === 429) return ERROR_CODES.PROVIDER_RATE_LIMITED;
@@ -3275,6 +3389,9 @@ function providerStatusToCode(status, type) {
 
 // src/coordination/coordinator/error-classifier.ts
 function classifySubagentError(err, hints = {}) {
+  if (err instanceof AgentError && err.cause) {
+    return classifySubagentError(err.cause, hints);
+  }
   const cause = err instanceof Error ? { name: err.name, message: err.message, stack: err.stack } : void 0;
   if (err instanceof ProviderError) {
     const baseMessage2 = err.describe();
@@ -3307,7 +3424,7 @@ function classifySubagentError(err, hints = {}) {
   if (/agent exhausted iteration limit$/i.test(baseMessage)) {
     return { kind: "budget_iterations", message: baseMessage, retryable: false, cause };
   }
-  if (/empty response$/i.test(baseMessage)) {
+  if (/empty response/i.test(baseMessage)) {
     return { kind: "empty_response", message: baseMessage, retryable: false, cause };
   }
   if (/^tool failed: /i.test(baseMessage)) {
@@ -3357,11 +3474,11 @@ var HEAVY_BUDGET = {
 };
 var TOOLS = {
   /** Pure read/inspect — safe for analysis and review agents. */
-  read: ["read", "grep", "glob", "search", "tree"],
+  read: ["read", "grep", "glob", "search", "tree", "mailbox"],
   /** Read + structured inspection (logs, diffs, json, dependency audit). */
-  inspect: ["read", "grep", "glob", "search", "tree", "json", "diff", "logs", "audit"],
+  inspect: ["read", "grep", "glob", "search", "tree", "json", "diff", "logs", "audit", "mailbox"],
   /** Read + edit (no shell). For agents that write code/docs but don't run it. */
-  write: ["read", "grep", "glob", "search", "tree", "write", "edit", "replace", "patch"],
+  write: ["read", "grep", "glob", "search", "tree", "write", "edit", "replace", "patch", "mailbox"],
   /** Full build loop: edit + run (lint/format/typecheck/test/bash). */
   build: [
     "read",
@@ -3378,16 +3495,17 @@ var TOOLS = {
     "lint",
     "format",
     "typecheck",
-    "test"
+    "test",
+    "mailbox"
   ],
   /** Version control. */
   vcs: ["read", "grep", "glob", "git", "diff"],
   /** Dependency management + CVE audit. */
-  deps: ["read", "grep", "glob", "install", "outdated", "audit", "json"],
+  deps: ["read", "grep", "glob", "install", "outdated", "audit", "json", "mailbox"],
   /** Documentation authoring. */
-  docs: ["read", "grep", "glob", "search", "tree", "write", "edit", "document"],
+  docs: ["read", "grep", "glob", "search", "tree", "write", "edit", "document", "mailbox"],
   /** Web research. */
-  research: ["read", "grep", "glob", "search", "fetch"]
+  research: ["read", "grep", "glob", "search", "fetch", "mailbox"]
 };
 
 // src/coordination/agents/phase1-discovery.ts
@@ -5800,7 +5918,7 @@ Working rules:
       id: "tech-stack",
       name: "Tech Stack Validator",
       role: "tech-stack",
-      tools: ["search", "fetch", "read", "grep", "glob", "outdated", "audit", "json"],
+      tools: ["search", "fetch", "read", "grep", "glob", "outdated", "audit", "json", "mailbox"],
       prompt: `You are the Tech Stack Validator \u2014 a single-shot validation agent that fires
 before any package, library, or framework choice is committed.
 
@@ -5808,6 +5926,16 @@ Your ONLY job: verify that a technology choice is current, real, and not obsolet
 You are the "this isn't code, this is 10-year-old technology" agent. Intervene
 hard when the LLM hallucinates a version number or suggests dead tech.
 
+## Before you begin
+
+Check the inter-agent mailbox for pending tasks. Other agents or the file-watcher
+may have left assign messages with dependency files to audit:
+- mailbox action=check
+
+If you find an assign message, use the specified file path and packages.
+When done, post results back:
+- mailbox action=send to=<sender> type=result subject="Tech stack audit results" body="..."
+
 ## Critical rules
 
 1. **Verify existence.** Search npm registry (fetch https://registry.npmjs.org/<pkg>/latest)
@@ -5866,11 +5994,11 @@ When APPROVED:
 **Install**: pnpm add <name>@^<major>.<minor>.0`
     },
     budget: {
-      timeoutMs: 6e4,
-      maxIterations: 5,
-      maxToolCalls: 20,
-      maxTokens: 4e4,
-      maxCostUsd: 0.1
+      timeoutMs: 12e4,
+      maxIterations: 10,
+      maxToolCalls: 40,
+      maxTokens: 6e4,
+      maxCostUsd: 0.25
     },
     capability: {
       phase: "meta",
@@ -6911,7 +7039,10 @@ var SddParallelRun = class {
       "\u2022 Do not ask before routine in-project tool use; if a permission gate appears, wait for that flow.",
       "\u2022 Keep output concise \u2014 summarize changes, do not transcribe files."
     ].join("\n");
-    if (!this.coordinator) throw new Error("SDD parallel runner requires a coordinator");
+    if (!this.coordinator) throw new SddError({
+      message: "SDD parallel runner requires a coordinator",
+      code: ERROR_CODES.SDD_INVALID_STATE
+    });
     const coordinator = this.coordinator;
     const spawns = subagentIds.map(
       (subagentId) => coordinator.spawn({
@@ -6923,7 +7054,10 @@ var SddParallelRun = class {
     );
     const spawnResults = await Promise.all(spawns);
     if (!spawnResults.every((r) => Boolean(r.subagentId))) {
-      throw new Error("One or more subagent spawns failed");
+      throw new SddError({
+        message: "One or more subagent spawns failed",
+        code: ERROR_CODES.SDD_INVALID_STATE
+      });
     }
     const assignPromises = tasks.map((task, i) => {
       const spec = {