opencode-swarm 5.1.1 → 5.1.4

package/README.md

@@ -1,9 +1,9 @@
 <p align="center">
-  <img src="https://img.shields.io/badge/version-5.0.0-blue" alt="Version">
+  <img src="https://img.shields.io/badge/version-5.1.4-blue" alt="Version">
   <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
   <img src="https://img.shields.io/badge/opencode-plugin-purple" alt="OpenCode Plugin">
-  <img src="https://img.shields.io/badge/agents-8-orange" alt="Agents">
-  <img src="https://img.shields.io/badge/tests-876-brightgreen" alt="Tests">
+  <img src="https://img.shields.io/badge/agents-7-orange" alt="Agents">
+  <img src="https://img.shields.io/badge/tests-1027-brightgreen" alt="Tests">
 </p>
 
 <h1 align="center">🐝 OpenCode Swarm</h1>
@@ -341,7 +341,7 @@ bunx opencode-swarm uninstall --clean
 - **Context injection budget** — `max_injection_tokens` config controls how much context is injected into system prompts. Priority-ordered: phase → task → decisions → agent context. Lower-priority items dropped when budget exhausted.
 - **Enhanced `/swarm agents`** — Agent count summary, `⚡ custom limits` indicator for profiled agents, guardrail profiles section.
 - **Packaging smoke tests** — CI-safe `dist/` validation (8 tests).
-- **208 new tests** — 876 total tests across 39 files (up from 668 in v4.6.0).
+- **151 new tests** — 1027 total tests across 44 files (up from 876 in v4.6.0).
 
 ### v4.6.0 — Agent Guardrails
 - **Circuit breaker** — Two-layer protection against runaway agents. Soft warning at 50% of limits, hard block at 100%. Prevents infinite loops and runaway API costs.
@@ -422,6 +422,8 @@ All features are opt-in via configuration. See [Installation Guide](docs/install
 | `/swarm reset --confirm` | Clear swarm state files (with safety gate) |
 | `/swarm evidence [task]` | View evidence bundles for a task or all tasks |
 | `/swarm archive [--dry-run]` | Archive old evidence bundles with retention policy |
+| `/swarm benchmark` | Run performance benchmarks and display metrics |
+| `/swarm retrieve [id]` | Retrieve auto-summarized tool outputs by ID |
 
 ---
 
@@ -508,9 +510,7 @@ Override limits for specific agents that need more (or less) room:
 
 Profiles merge with base config — only specified fields are overridden.
 
-> **Built-in Architect Defaults:** The architect agent automatically receives higher limits
-> (600 tool calls, 90 min duration, 8 consecutive errors, 0.7 warning threshold) without any
-> configuration. These built-in defaults can be overridden via a `profiles.architect` entry.
+> **Architect is exempt/unlimited by default:** The architect agent has no guardrail limits by default. To override, add a `profiles.architect` entry in your guardrails config.
 
 ### Disable Guardrails
 
@@ -564,7 +564,7 @@ bun test
 bun test tests/unit/config/schema.test.ts
 ```
 
-876 unit tests across 39 files covering config, tools, agents, hooks, commands, state, guardrails, evidence, and plan schemas. Uses Bun's built-in test runner — zero additional test dependencies.
+1027 unit tests across 44 files covering config, tools, agents, hooks, commands, state, guardrails, evidence, and plan schemas. Uses Bun's built-in test runner — zero additional test dependencies.
 
 ## Troubleshooting
 

package/dist/commands/benchmark.d.ts

@@ -0,0 +1 @@
+export declare function handleBenchmarkCommand(directory: string, args: string[]): Promise<string>;

package/dist/commands/index.d.ts

@@ -1,6 +1,7 @@
 import type { AgentDefinition } from '../agents';
 export { handleAgentsCommand } from './agents';
 export { handleArchiveCommand } from './archive';
+export { handleBenchmarkCommand } from './benchmark';
 export { handleConfigCommand } from './config';
 export { handleDiagnoseCommand } from './diagnose';
 export { handleEvidenceCommand } from './evidence';
@@ -8,6 +9,7 @@ export { handleExportCommand } from './export';
 export { handleHistoryCommand } from './history';
 export { handlePlanCommand } from './plan';
 export { handleResetCommand } from './reset';
+export { handleRetrieveCommand } from './retrieve';
 export { handleStatusCommand } from './status';
 /**
  * Creates a command.execute.before handler for /swarm commands.

package/dist/commands/retrieve.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Handles the /swarm retrieve command.
+ * Loads full tool output from .swarm/summaries/{id}.json and returns it.
+ */
+export declare function handleRetrieveCommand(directory: string, args: string[]): Promise<string>;

package/dist/config/schema.d.ts

@@ -120,6 +120,14 @@ export declare const EvidenceConfigSchema: z.ZodObject<{
     auto_archive: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
 export type EvidenceConfig = z.infer<typeof EvidenceConfigSchema>;
+export declare const SummaryConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    threshold_bytes: z.ZodDefault<z.ZodNumber>;
+    max_summary_chars: z.ZodDefault<z.ZodNumber>;
+    max_stored_bytes: z.ZodDefault<z.ZodNumber>;
+    retention_days: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type SummaryConfig = z.infer<typeof SummaryConfigSchema>;
 export declare const GuardrailsProfileSchema: z.ZodObject<{
     max_tool_calls: z.ZodOptional<z.ZodNumber>;
     max_duration_minutes: z.ZodOptional<z.ZodNumber>;
@@ -262,6 +270,13 @@ export declare const PluginConfigSchema: z.ZodObject<{
         max_bundles: z.ZodDefault<z.ZodNumber>;
         auto_archive: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
+    summaries: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        threshold_bytes: z.ZodDefault<z.ZodNumber>;
+        max_summary_chars: z.ZodDefault<z.ZodNumber>;
+        max_stored_bytes: z.ZodDefault<z.ZodNumber>;
+        retention_days: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type PluginConfig = z.infer<typeof PluginConfigSchema>;
 export type { AgentName, PipelineAgentName, QAAgentName, } from './constants';

package/dist/hooks/index.d.ts

@@ -1,10 +1,11 @@
 export { createAgentActivityHooks } from './agent-activity';
 export { createCompactionCustomizerHook } from './compaction-customizer';
 export { createContextBudgetHandler } from './context-budget';
-export { createDelegationTrackerHook } from './delegation-tracker';
 export { createDelegationGateHook } from './delegation-gate';
+export { createDelegationTrackerHook } from './delegation-tracker';
 export { extractCurrentPhase, extractCurrentPhaseFromPlan, extractCurrentTask, extractCurrentTaskFromPlan, extractDecisions, extractIncompleteTasks, extractIncompleteTasksFromPlan, extractPatterns, } from './extractors';
 export { createGuardrailsHooks } from './guardrails';
 export { createPipelineTrackerHook } from './pipeline-tracker';
 export { createSystemEnhancerHook } from './system-enhancer';
+export { createToolSummarizerHook, resetSummaryIdCounter, } from './tool-summarizer';
 export { composeHandlers, estimateTokens, readSwarmFileAsync, safeHook, validateSwarmPath, } from './utils';

package/dist/hooks/tool-summarizer.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Tool Output Summarizer Hook
+ *
+ * Intercepts oversized tool outputs in tool.execute.after,
+ * stores the full content to .swarm/summaries/, and replaces
+ * the output with a compact summary containing a retrieval ID.
+ */
+import type { SummaryConfig } from '../config/schema';
+/**
+ * Reset the summary ID counter. Used for testing.
+ */
+export declare function resetSummaryIdCounter(): void;
+/**
+ * Creates a tool.execute.after hook that summarizes oversized tool outputs.
+ *
+ * @param config - Summary configuration including enabled, thresholds, and limits
+ * @param directory - Base directory for storing full outputs
+ * @returns Async hook function for tool.execute.after
+ */
+export declare function createToolSummarizerHook(config: SummaryConfig, directory: string): (input: {
+    tool: string;
+    sessionID: string;
+    callID: string;
+}, output: {
+    title: string;
+    output: string;
+    metadata: unknown;
+}) => Promise<void>;

package/dist/index.js

@@ -13623,6 +13623,13 @@ var EvidenceConfigSchema = exports_external.object({
   max_bundles: exports_external.number().min(10).max(1e4).default(1000),
   auto_archive: exports_external.boolean().default(false)
 });
+var SummaryConfigSchema = exports_external.object({
+  enabled: exports_external.boolean().default(true),
+  threshold_bytes: exports_external.number().min(1024).max(1048576).default(20480),
+  max_summary_chars: exports_external.number().min(100).max(5000).default(1000),
+  max_stored_bytes: exports_external.number().min(10240).max(104857600).default(10485760),
+  retention_days: exports_external.number().min(1).max(365).default(7)
+});
 var GuardrailsProfileSchema = exports_external.object({
   max_tool_calls: exports_external.number().min(0).max(1000).optional(),
   max_duration_minutes: exports_external.number().min(0).max(480).optional(),
@@ -13716,7 +13723,8 @@ var PluginConfigSchema = exports_external.object({
   hooks: HooksConfigSchema.optional(),
   context_budget: ContextBudgetConfigSchema.optional(),
   guardrails: GuardrailsConfigSchema.optional(),
-  evidence: EvidenceConfigSchema.optional()
+  evidence: EvidenceConfigSchema.optional(),
+  summaries: SummaryConfigSchema.optional()
 });
 
 // src/config/loader.ts
@@ -15014,6 +15022,282 @@ async function handleArchiveCommand(directory, args) {
 `);
 }
 
+// src/state.ts
+var swarmState = {
+  activeToolCalls: new Map,
+  toolAggregates: new Map,
+  activeAgent: new Map,
+  delegationChains: new Map,
+  pendingEvents: 0,
+  agentSessions: new Map
+};
+function startAgentSession(sessionId, agentName, staleDurationMs = 7200000) {
+  const now = Date.now();
+  const staleIds = [];
+  for (const [id, session] of swarmState.agentSessions) {
+    if (now - session.lastToolCallTime > staleDurationMs) {
+      staleIds.push(id);
+    }
+  }
+  for (const id of staleIds) {
+    swarmState.agentSessions.delete(id);
+  }
+  const sessionState = {
+    agentName,
+    startTime: now,
+    lastToolCallTime: now,
+    toolCallCount: 0,
+    consecutiveErrors: 0,
+    recentToolCalls: [],
+    warningIssued: false,
+    warningReason: "",
+    hardLimitHit: false,
+    lastSuccessTime: now,
+    delegationActive: false
+  };
+  swarmState.agentSessions.set(sessionId, sessionState);
+}
+function getAgentSession(sessionId) {
+  return swarmState.agentSessions.get(sessionId);
+}
+function ensureAgentSession(sessionId, agentName) {
+  const now = Date.now();
+  let session = swarmState.agentSessions.get(sessionId);
+  if (session) {
+    if (agentName && agentName !== session.agentName) {
+      session.agentName = agentName;
+      session.startTime = now;
+      session.toolCallCount = 0;
+      session.consecutiveErrors = 0;
+      session.recentToolCalls = [];
+      session.warningIssued = false;
+      session.warningReason = "";
+      session.hardLimitHit = false;
+      session.lastSuccessTime = now;
+      session.delegationActive = false;
+    }
+    session.lastToolCallTime = now;
+    return session;
+  }
+  startAgentSession(sessionId, agentName ?? "unknown");
+  session = swarmState.agentSessions.get(sessionId);
+  if (!session) {
+    throw new Error(`Failed to create guardrail session for ${sessionId}`);
+  }
+  return session;
+}
+
+// src/commands/benchmark.ts
+var CI = {
+  review_pass_rate: 70,
+  test_pass_rate: 80,
+  max_agent_error_rate: 20,
+  max_hard_limit_hits: 1
+};
+async function handleBenchmarkCommand(directory, args) {
+  let cumulative = args.includes("--cumulative");
+  if (args.includes("--ci-gate"))
+    cumulative = true;
+  const mode = cumulative ? "cumulative" : "in-memory";
+  const agentMap = new Map;
+  for (const [, s] of swarmState.agentSessions) {
+    const e = agentMap.get(s.agentName) || {
+      toolCalls: 0,
+      hardLimits: 0,
+      warnings: 0
+    };
+    e.toolCalls += s.toolCallCount;
+    if (s.hardLimitHit)
+      e.hardLimits++;
+    if (s.warningIssued)
+      e.warnings++;
+    agentMap.set(s.agentName, e);
+  }
+  const agentHealth = Array.from(agentMap.entries()).map(([a, v]) => ({
+    agent: a,
+    ...v
+  }));
+  const toolPerf = [];
+  for (const [, a] of swarmState.toolAggregates) {
+    const successRate = a.count ? a.successCount / a.count * 100 : 0;
+    toolPerf.push({
+      tool: a.tool,
+      calls: a.count,
+      successRate: Math.round(successRate * 10) / 10,
+      avg: a.count ? Math.round(a.totalDuration / a.count) : 0
+    });
+  }
+  toolPerf.sort((a, b) => b.calls - a.calls);
+  let delegationCount = 0;
+  for (const c of swarmState.delegationChains.values())
+    delegationCount += c.length;
+  let quality;
+  if (cumulative) {
+    let reviewPasses = 0, reviewFails = 0, testPasses = 0, testFails = 0, additions = 0, deletions = 0;
+    for (const tid of await listEvidenceTaskIds(directory)) {
+      const b = await loadEvidence(directory, tid);
+      if (!b)
+        continue;
+      for (const e of b.entries) {
+        if (e.type === "review") {
+          if (e.verdict === "approved")
+            reviewPasses++;
+          else if (e.verdict === "rejected")
+            reviewFails++;
+        } else if (e.type === "test") {
+          testPasses += e.tests_passed;
+          testFails += e.tests_failed;
+        } else if (e.type === "diff") {
+          additions += e.additions;
+          deletions += e.deletions;
+        }
+      }
+    }
+    const totalReviews = reviewPasses + reviewFails, totalTests = testPasses + testFails;
+    quality = {
+      reviewPassRate: totalReviews ? Math.round(reviewPasses / totalReviews * 1000) / 10 : null,
+      testPassRate: totalTests ? Math.round(testPasses / totalTests * 1000) / 10 : null,
+      totalReviews,
+      testsPassed: testPasses,
+      testsFailed: testFails,
+      additions,
+      deletions
+    };
+  }
+  let ciGate;
+  if (args.includes("--ci-gate")) {
+    let totalCalls = 0, totalFailures = 0;
+    for (const [, a] of swarmState.toolAggregates) {
+      totalCalls += a.count;
+      totalFailures += a.failureCount;
+    }
+    const agentErrorRate = totalCalls ? totalFailures / totalCalls * 100 : 0;
+    let maxHardLimits = 0;
+    for (const v of agentMap.values())
+      if (v.hardLimits > maxHardLimits)
+        maxHardLimits = v.hardLimits;
+    const checks3 = [
+      {
+        name: "Review pass rate",
+        value: quality?.reviewPassRate ?? 0,
+        threshold: CI.review_pass_rate,
+        operator: ">=",
+        passed: (quality?.reviewPassRate ?? 0) >= CI.review_pass_rate
+      },
+      {
+        name: "Test pass rate",
+        value: quality?.testPassRate ?? 0,
+        threshold: CI.test_pass_rate,
+        operator: ">=",
+        passed: (quality?.testPassRate ?? 0) >= CI.test_pass_rate
+      },
+      {
+        name: "Agent error rate",
+        value: Math.round(agentErrorRate * 10) / 10,
+        threshold: CI.max_agent_error_rate,
+        operator: "<=",
+        passed: agentErrorRate <= CI.max_agent_error_rate
+      },
+      {
+        name: "Hard limit hits",
+        value: maxHardLimits,
+        threshold: CI.max_hard_limit_hits,
+        operator: "<=",
+        passed: maxHardLimits <= CI.max_hard_limit_hits
+      }
+    ];
+    ciGate = { passed: checks3.every((c) => c.passed), checks: checks3 };
+  }
+  const lines = [
+    `## Swarm Benchmark (mode: ${mode})`,
+    "",
+    "### Agent Health"
+  ];
+  if (!agentHealth.length)
+    lines.push("No agent sessions recorded");
+  else
+    for (const { agent, toolCalls, hardLimits, warnings } of agentHealth) {
+      const parts = [`${toolCalls} tool calls`];
+      if (warnings > 0)
+        parts.push(`${warnings} warning${warnings > 1 ? "s" : ""}`);
+      parts.push(hardLimits ? `${hardLimits} hard limit hit${hardLimits > 1 ? "s" : ""}` : "0 hard limits");
+      lines.push(`- ${hardLimits ? "\u26A0\uFE0F" : "\u2705"} **${agent}**: ${parts.join(", ")}`);
+    }
+  lines.push("", "### Tool Performance");
+  if (!toolPerf.length)
+    lines.push("No tool data recorded");
+  else {
+    lines.push("| Tool | Calls | Success Rate | Avg Duration |", "|------|-------|-------------|-------------|");
+    for (const { tool, calls, successRate, avg } of toolPerf)
+      lines.push(`| ${tool} | ${calls} | ${successRate}% | ${avg}ms |`);
+  }
+  lines.push("", "### Delegations", delegationCount ? `Total: ${delegationCount} delegations` : "No delegations recorded", "");
+  if (quality) {
+    lines.push("### Quality Signals");
+    if (!quality.totalReviews && !quality.testsPassed && !quality.additions)
+      lines.push("No evidence data found");
+    else {
+      if (quality.reviewPassRate !== null)
+        lines.push(`- Review pass rate: ${quality.reviewPassRate}% (${quality.totalReviews}) ${quality.reviewPassRate >= 70 ? "\u2705" : "\u274C"}`);
+      else
+        lines.push("- Review pass rate: N/A (no reviews)");
+      if (quality.testPassRate !== null)
+        lines.push(`- Test pass rate: ${quality.testPassRate}% (${quality.testsPassed}/${quality.testsPassed + quality.testsFailed}) ${quality.testPassRate >= 80 ? "\u2705" : "\u274C"}`);
+      else
+        lines.push("- Test pass rate: N/A (no tests)");
+      lines.push(`- Code churn: +${quality.additions} / -${quality.deletions} lines`);
+    }
+    lines.push("");
+  }
+  if (ciGate) {
+    lines.push("### CI Gate", ciGate.passed ? "\u2705 PASSED" : "\u274C FAILED");
+    for (const c of ciGate.checks)
+      lines.push(`- ${c.name}: ${c.value}% ${c.operator} ${c.threshold}% ${c.passed ? "\u2705" : "\u274C"}`);
+    lines.push("");
+  }
+  const json2 = {
+    mode,
+    timestamp: new Date().toISOString(),
+    agent_health: agentHealth.map((a) => ({
+      agent: a.agent,
+      tool_calls: a.toolCalls,
+      hard_limit_hits: a.hardLimits,
+      warnings: a.warnings
+    })),
+    tool_performance: toolPerf.map((t) => ({
+      tool: t.tool,
+      calls: t.calls,
+      success_rate: t.successRate,
+      avg_duration_ms: t.avg
+    })),
+    delegations: delegationCount
+  };
+  if (quality)
+    json2.quality = {
+      review_pass_rate: quality.reviewPassRate,
+      test_pass_rate: quality.testPassRate,
+      total_reviews: quality.totalReviews,
+      total_tests_passed: quality.testsPassed,
+      total_tests_failed: quality.testsFailed,
+      additions: quality.additions,
+      deletions: quality.deletions
+    };
+  if (ciGate)
+    json2.ci_gate = {
+      passed: ciGate.passed,
+      checks: ciGate.checks.map((c) => ({
+        name: c.name,
+        value: c.value,
+        threshold: c.threshold,
+        operator: c.operator,
+        passed: c.passed
+      }))
+    };
+  lines.push("[BENCHMARK_JSON]", JSON.stringify(json2, null, 2), "[/BENCHMARK_JSON]");
+  return lines.join(`
+`);
+}
+
 // src/commands/config.ts
 import * as os2 from "os";
 import * as path4 from "path";
@@ -15724,6 +16008,17 @@ async function handleResetCommand(directory, args) {
       results.push(`- \u274C Failed to delete ${filename}`);
     }
   }
+  try {
+    const summariesPath = validateSwarmPath(directory, "summaries");
+    if (fs2.existsSync(summariesPath)) {
+      fs2.rmSync(summariesPath, { recursive: true, force: true });
+      results.push("- \u2705 Deleted summaries/ directory");
+    } else {
+      results.push("- \u23ED\uFE0F summaries/ not found (skipped)");
+    }
+  } catch {
+    results.push("- \u274C Failed to delete summaries/");
+  }
   return [
     "## Swarm Reset Complete",
     "",
@@ -15734,6 +16029,112 @@ async function handleResetCommand(directory, args) {
 `);
 }
 
+// src/summaries/manager.ts
+import { mkdirSync as mkdirSync2, readdirSync as readdirSync2, renameSync as renameSync2, rmSync as rmSync3, statSync as statSync3 } from "fs";
+import * as path6 from "path";
+var SUMMARY_ID_REGEX = /^S\d+$/;
+function sanitizeSummaryId(id) {
+  if (!id || id.length === 0) {
+    throw new Error("Invalid summary ID: empty string");
+  }
+  if (/\0/.test(id)) {
+    throw new Error("Invalid summary ID: contains null bytes");
+  }
+  for (let i = 0;i < id.length; i++) {
+    if (id.charCodeAt(i) < 32) {
+      throw new Error("Invalid summary ID: contains control characters");
+    }
+  }
+  if (id.includes("..") || id.includes("../") || id.includes("..\\")) {
+    throw new Error("Invalid summary ID: path traversal detected");
+  }
+  if (!SUMMARY_ID_REGEX.test(id)) {
+    throw new Error(`Invalid summary ID: must match pattern ^S\\d+$, got "${id}"`);
+  }
+  return id;
+}
+async function storeSummary(directory, id, fullOutput, summaryText, maxStoredBytes) {
+  const sanitizedId = sanitizeSummaryId(id);
+  const outputBytes = Buffer.byteLength(fullOutput, "utf8");
+  if (outputBytes > maxStoredBytes) {
+    throw new Error(`Summary fullOutput size (${outputBytes} bytes) exceeds maximum (${maxStoredBytes} bytes)`);
+  }
+  const relativePath = path6.join("summaries", `${sanitizedId}.json`);
+  const summaryPath = validateSwarmPath(directory, relativePath);
+  const summaryDir = path6.dirname(summaryPath);
+  const entry = {
+    id: sanitizedId,
+    summaryText,
+    fullOutput,
+    timestamp: Date.now(),
+    originalBytes: outputBytes
+  };
+  const entryJson = JSON.stringify(entry);
+  mkdirSync2(summaryDir, { recursive: true });
+  const tempPath = path6.join(summaryDir, `${sanitizedId}.json.tmp.${Date.now()}.${process.pid}`);
+  try {
+    await Bun.write(tempPath, entryJson);
+    renameSync2(tempPath, summaryPath);
+  } catch (error49) {
+    try {
+      rmSync3(tempPath, { force: true });
+    } catch {}
+    throw error49;
+  }
+}
+async function loadFullOutput(directory, id) {
+  const sanitizedId = sanitizeSummaryId(id);
+  const relativePath = path6.join("summaries", `${sanitizedId}.json`);
+  validateSwarmPath(directory, relativePath);
+  const content = await readSwarmFileAsync(directory, relativePath);
+  if (content === null) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(content);
+    if (typeof parsed.fullOutput === "string") {
+      return parsed.fullOutput;
+    }
+    warn(`Summary entry ${sanitizedId} missing valid fullOutput field`);
+    return null;
+  } catch (error49) {
+    warn(`Summary entry validation failed for ${sanitizedId}: ${error49 instanceof Error ? error49.message : String(error49)}`);
+    return null;
+  }
+}
+
+// src/commands/retrieve.ts
+async function handleRetrieveCommand(directory, args) {
+  const summaryId = args[0];
+  if (!summaryId) {
+    return [
+      "## Swarm Retrieve",
+      "",
+      "Usage: `/swarm retrieve <id>`",
+      "",
+      "Example: `/swarm retrieve S1`",
+      "",
+      "Retrieves the full output that was replaced by a summary."
+    ].join(`
+`);
+  }
+  try {
+    const fullOutput = await loadFullOutput(directory, summaryId);
+    if (fullOutput === null) {
+      return `## Summary Not Found
+
+No stored output found for ID \`${summaryId}\`.
+
+Use a valid summary ID (e.g., S1, S2, S3).`;
+    }
+    return fullOutput;
+  } catch (error49) {
+    return `## Retrieve Failed
+
+${error49 instanceof Error ? error49.message : String(error49)}`;
+  }
+}
+
 // src/hooks/extractors.ts
 function extractCurrentPhase(planContent) {
   if (!planContent) {
@@ -15982,8 +16383,10 @@ var HELP_TEXT = [
   "- `/swarm evidence [taskId]` \u2014 Show evidence bundles",
   "- `/swarm archive [--dry-run]` \u2014 Archive old evidence bundles",
   "- `/swarm diagnose` \u2014 Run health check on swarm state",
+  "- `/swarm benchmark [--cumulative] [--ci-gate]` \u2014 Show performance metrics",
   "- `/swarm export` \u2014 Export plan and context as JSON",
-  "- `/swarm reset --confirm` \u2014 Clear swarm state files"
+  "- `/swarm reset --confirm` \u2014 Clear swarm state files",
+  "- `/swarm retrieve <id>` \u2014 Retrieve full output from a summary"
 ].join(`
 `);
 function createSwarmCommandHandler(directory, agents) {
@@ -16022,12 +16425,18 @@ function createSwarmCommandHandler(directory, agents) {
       case "diagnose":
         text = await handleDiagnoseCommand(directory, args);
         break;
+      case "benchmark":
+        text = await handleBenchmarkCommand(directory, args);
+        break;
       case "export":
         text = await handleExportCommand(directory, args);
         break;
       case "reset":
         text = await handleResetCommand(directory, args);
         break;
+      case "retrieve":
+        text = await handleRetrieveCommand(directory, args);
+        break;
       default:
         text = HELP_TEXT;
         break;
@@ -16038,71 +16447,6 @@ function createSwarmCommandHandler(directory, agents) {
   };
 }
 
-// src/state.ts
-var swarmState = {
-  activeToolCalls: new Map,
-  toolAggregates: new Map,
-  activeAgent: new Map,
-  delegationChains: new Map,
-  pendingEvents: 0,
-  agentSessions: new Map
-};
-function startAgentSession(sessionId, agentName, staleDurationMs = 7200000) {
-  const now = Date.now();
-  const staleIds = [];
-  for (const [id, session] of swarmState.agentSessions) {
-    if (now - session.lastToolCallTime > staleDurationMs) {
-      staleIds.push(id);
-    }
-  }
-  for (const id of staleIds) {
-    swarmState.agentSessions.delete(id);
-  }
-  const sessionState = {
-    agentName,
-    startTime: now,
-    lastToolCallTime: now,
-    toolCallCount: 0,
-    consecutiveErrors: 0,
-    recentToolCalls: [],
-    warningIssued: false,
-    warningReason: "",
-    hardLimitHit: false,
-    lastSuccessTime: now,
-    delegationActive: false
-  };
-  swarmState.agentSessions.set(sessionId, sessionState);
-}
-function getAgentSession(sessionId) {
-  return swarmState.agentSessions.get(sessionId);
-}
-function ensureAgentSession(sessionId, agentName) {
-  const now = Date.now();
-  let session = swarmState.agentSessions.get(sessionId);
-  if (session) {
-    if (agentName && agentName !== session.agentName) {
-      session.agentName = agentName;
-      session.startTime = now;
-      session.toolCallCount = 0;
-      session.consecutiveErrors = 0;
-      session.recentToolCalls = [];
-      session.warningIssued = false;
-      session.warningReason = "";
-      session.hardLimitHit = false;
-      session.lastSuccessTime = now;
-      session.delegationActive = false;
-    }
-    session.lastToolCallTime = now;
-    return session;
-  }
-  startAgentSession(sessionId, agentName ?? "unknown");
-  session = swarmState.agentSessions.get(sessionId);
-  if (!session) {
-    throw new Error(`Failed to create guardrail session for ${sessionId}`);
-  }
-  return session;
-}
-
 // src/hooks/agent-activity.ts
 function createAgentActivityHooks(config2, directory) {
   if (config2.hooks?.agent_activity === false) {
@@ -16171,8 +16515,8 @@ async function doFlush(directory) {
     const activitySection = renderActivitySection();
     const updated = replaceOrAppendSection(existing, "## Agent Activity", activitySection);
     const flushedCount = swarmState.pendingEvents;
-    const path6 = `${directory}/.swarm/context.md`;
-    await Bun.write(path6, updated);
+    const path7 = `${directory}/.swarm/context.md`;
+    await Bun.write(path7, updated);
     swarmState.pendingEvents = Math.max(0, swarmState.pendingEvents - flushedCount);
   } catch (error49) {
     warn("Agent activity flush failed:", error49);
@@ -16322,36 +16666,6 @@ function createContextBudgetHandler(config2) {
     }
   };
 }
-// src/hooks/delegation-tracker.ts
-function createDelegationTrackerHook(config2) {
-  return async (input, _output) => {
-    if (!input.agent || input.agent === "") {
-      const session2 = swarmState.agentSessions.get(input.sessionID);
-      if (session2) {
-        session2.delegationActive = false;
-      }
-      return;
-    }
-    const agentName = input.agent;
-    const previousAgent = swarmState.activeAgent.get(input.sessionID);
-    swarmState.activeAgent.set(input.sessionID, agentName);
-    const session = ensureAgentSession(input.sessionID, agentName);
-    session.delegationActive = true;
-    if (config2.hooks?.delegation_tracker === true && previousAgent && previousAgent !== agentName) {
-      const entry = {
-        from: previousAgent,
-        to: agentName,
-        timestamp: Date.now()
-      };
-      if (!swarmState.delegationChains.has(input.sessionID)) {
-        swarmState.delegationChains.set(input.sessionID, []);
-      }
-      const chain = swarmState.delegationChains.get(input.sessionID);
-      chain?.push(entry);
-      swarmState.pendingEvents++;
-    }
-  };
-}
 // src/hooks/delegation-gate.ts
 function createDelegationGateHook(config2) {
   const enabled = config2.hooks?.delegation_gate !== false;
@@ -16416,6 +16730,38 @@ Split into smaller, atomic tasks for better results.]`;
 ${originalText}`;
   };
 }
+// src/hooks/delegation-tracker.ts
+function createDelegationTrackerHook(config2) {
+  return async (input, _output) => {
+    if (!input.agent || input.agent === "") {
+      const session2 = swarmState.agentSessions.get(input.sessionID);
+      if (session2) {
+        session2.delegationActive = false;
+      }
+      swarmState.activeAgent.set(input.sessionID, ORCHESTRATOR_NAME);
+      ensureAgentSession(input.sessionID, ORCHESTRATOR_NAME);
+      return;
+    }
+    const agentName = input.agent;
+    const previousAgent = swarmState.activeAgent.get(input.sessionID);
+    swarmState.activeAgent.set(input.sessionID, agentName);
+    const session = ensureAgentSession(input.sessionID, agentName);
+    session.delegationActive = true;
+    if (config2.hooks?.delegation_tracker === true && previousAgent && previousAgent !== agentName) {
+      const entry = {
+        from: previousAgent,
+        to: agentName,
+        timestamp: Date.now()
+      };
+      if (!swarmState.delegationChains.has(input.sessionID)) {
+        swarmState.delegationChains.set(input.sessionID, []);
+      }
+      const chain = swarmState.delegationChains.get(input.sessionID);
+      chain?.push(entry);
+      swarmState.pendingEvents++;
+    }
+  };
+}
 // src/hooks/guardrails.ts
 function createGuardrailsHooks(config2) {
   if (config2.enabled === false) {
@@ -16432,8 +16778,19 @@ function createGuardrailsHooks(config2) {
       if (strippedAgent === ORCHESTRATOR_NAME) {
         return;
       }
+      const existingSession = swarmState.agentSessions.get(input.sessionID);
+      if (existingSession) {
+        const sessionAgent = stripKnownSwarmPrefix(existingSession.agentName);
+        if (sessionAgent === ORCHESTRATOR_NAME) {
+          return;
+        }
+      }
       const agentName = swarmState.activeAgent.get(input.sessionID);
       const session = ensureAgentSession(input.sessionID, agentName);
+      const resolvedName = stripKnownSwarmPrefix(session.agentName);
+      if (resolvedName === ORCHESTRATOR_NAME) {
+        return;
+      }
       const agentConfig = resolveGuardrailsConfig(config2, session.agentName);
       if (session.hardLimitHit) {
         throw new Error("\uD83D\uDED1 CIRCUIT BREAKER: Agent blocked. Hard limit was previously triggered. Stop making tool calls and return your progress summary.");
@@ -16762,6 +17119,7 @@ function createSystemEnhancerHook(config2, directory) {
               }
             }
           }
+          tryInject("[SWARM HINT] Large tool outputs may be auto-summarized. Use /swarm retrieve <id> to get the full content if needed.");
           return;
         }
         const userScoringConfig = config2.context_budget?.scoring;
@@ -16887,6 +17245,154 @@ ${activitySection}`;
   }
   return contextSummary;
 }
+// src/summaries/summarizer.ts
+var HYSTERESIS_FACTOR = 1.25;
+function detectContentType(output, toolName) {
+  const trimmed = output.trim();
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+    try {
+      JSON.parse(trimmed);
+      return "json";
+    } catch {}
+  }
+  const codeToolNames = ["read", "cat", "grep", "bash"];
+  const lowerToolName = toolName.toLowerCase();
+  const toolSegments = lowerToolName.split(/[.\-_/]/);
+  if (codeToolNames.some((name) => toolSegments.includes(name))) {
+    return "code";
+  }
+  const codePatterns = [
+    "function ",
+    "const ",
+    "import ",
+    "export ",
+    "class ",
+    "def ",
+    "return ",
+    "=>"
+  ];
+  const startsWithShebang = trimmed.startsWith("#!");
+  if (codePatterns.some((pattern) => output.includes(pattern)) || startsWithShebang) {
+    return "code";
+  }
+  const sampleSize = Math.min(1000, output.length);
+  let nonPrintableCount = 0;
+  for (let i = 0;i < sampleSize; i++) {
+    const charCode = output.charCodeAt(i);
+    if (charCode < 32 && charCode !== 9 && charCode !== 10 && charCode !== 13) {
+      nonPrintableCount++;
+    }
+  }
+  if (sampleSize > 0 && nonPrintableCount / sampleSize > 0.1) {
+    return "binary";
+  }
+  return "text";
+}
+function shouldSummarize(output, thresholdBytes) {
+  const byteLength = Buffer.byteLength(output, "utf8");
+  return byteLength >= thresholdBytes * HYSTERESIS_FACTOR;
+}
+function formatBytes(bytes) {
+  const units = ["B", "KB", "MB", "GB"];
+  let unitIndex = 0;
+  let size = bytes;
+  while (size >= 1024 && unitIndex < units.length - 1) {
+    size /= 1024;
+    unitIndex++;
+  }
+  const formatted = unitIndex === 0 ? size.toString() : size.toFixed(1);
+  return `${formatted} ${units[unitIndex]}`;
+}
+function createSummary(output, toolName, summaryId, maxSummaryChars) {
+  const contentType = detectContentType(output, toolName);
+  const lineCount = output.split(`
+`).length;
+  const byteSize = Buffer.byteLength(output, "utf8");
+  const formattedSize = formatBytes(byteSize);
+  const headerLine = `[SUMMARY ${summaryId}] ${formattedSize} | ${contentType} | ${lineCount} lines`;
+  const footerLine = `\u2192 Use /swarm retrieve ${summaryId} for full content`;
+  const overhead = headerLine.length + 1 + footerLine.length + 1;
+  const maxPreviewChars = maxSummaryChars - overhead;
+  let preview;
+  switch (contentType) {
+    case "json": {
+      try {
+        const parsed = JSON.parse(output.trim());
+        if (Array.isArray(parsed)) {
+          preview = `[ ${parsed.length} items ]`;
+        } else if (typeof parsed === "object" && parsed !== null) {
+          const keys = Object.keys(parsed).slice(0, 3);
+          preview = `{ ${keys.join(", ")}${Object.keys(parsed).length > 3 ? ", ..." : ""} }`;
+        } else {
+          const lines = output.split(`
+`).filter((line) => line.trim().length > 0).slice(0, 3);
+          preview = lines.join(`
+`);
+        }
+      } catch {
+        const lines = output.split(`
+`).filter((line) => line.trim().length > 0).slice(0, 3);
+        preview = lines.join(`
+`);
+      }
+      break;
+    }
+    case "code": {
+      const lines = output.split(`
+`).filter((line) => line.trim().length > 0).slice(0, 5);
+      preview = lines.join(`
+`);
+      break;
+    }
+    case "text": {
+      const lines = output.split(`
+`).filter((line) => line.trim().length > 0).slice(0, 5);
+      preview = lines.join(`
+`);
+      break;
+    }
+    case "binary": {
+      preview = `[Binary content - ${formattedSize}]`;
+      break;
+    }
+    default: {
+      const lines = output.split(`
+`).filter((line) => line.trim().length > 0).slice(0, 5);
+      preview = lines.join(`
+`);
+    }
+  }
+  if (preview.length > maxPreviewChars) {
+    preview = preview.substring(0, maxPreviewChars - 3) + "...";
+  }
+  return `${headerLine}
+${preview}
+${footerLine}`;
+}
+
+// src/hooks/tool-summarizer.ts
+var nextSummaryId = 1;
+function createToolSummarizerHook(config2, directory) {
+  if (config2.enabled === false) {
+    return async () => {};
+  }
+  return async (input, output) => {
+    if (typeof output.output !== "string" || output.output.length === 0) {
+      return;
+    }
+    if (!shouldSummarize(output.output, config2.threshold_bytes)) {
+      return;
+    }
+    const summaryId = `S${nextSummaryId++}`;
+    const summaryText = createSummary(output.output, input.tool, summaryId, config2.max_summary_chars);
+    try {
+      await storeSummary(directory, summaryId, output.output, summaryText, config2.max_stored_bytes);
+      output.output = summaryText;
+    } catch (error49) {
+      warn(`Tool output summarization failed for ${summaryId}: ${error49 instanceof Error ? error49.message : String(error49)}`);
+    }
+  };
+}
 // node_modules/@opencode-ai/plugin/node_modules/zod/v4/classic/external.js
 var exports_external2 = {};
 __export(exports_external2, {
@@ -17616,10 +18122,10 @@ function mergeDefs2(...defs) {
 function cloneDef2(schema) {
   return mergeDefs2(schema._zod.def);
 }
-function getElementAtPath2(obj, path6) {
-  if (!path6)
+function getElementAtPath2(obj, path7) {
+  if (!path7)
     return obj;
-  return path6.reduce((acc, key) => acc?.[key], obj);
+  return path7.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject2(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -17978,11 +18484,11 @@ function aborted2(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues2(path6, issues) {
+function prefixIssues2(path7, issues) {
   return issues.map((iss) => {
     var _a2;
     (_a2 = iss).path ?? (_a2.path = []);
-    iss.path.unshift(path6);
+    iss.path.unshift(path7);
     return iss;
   });
 }
@@ -18150,7 +18656,7 @@ function treeifyError2(error49, _mapper) {
     return issue3.message;
   };
   const result = { errors: [] };
-  const processError = (error50, path6 = []) => {
+  const processError = (error50, path7 = []) => {
     var _a2, _b;
     for (const issue3 of error50.issues) {
       if (issue3.code === "invalid_union" && issue3.errors.length) {
@@ -18160,7 +18666,7 @@ function treeifyError2(error49, _mapper) {
       } else if (issue3.code === "invalid_element") {
         processError({ issues: issue3.issues }, issue3.path);
       } else {
-        const fullpath = [...path6, ...issue3.path];
+        const fullpath = [...path7, ...issue3.path];
         if (fullpath.length === 0) {
           result.errors.push(mapper(issue3));
           continue;
@@ -18192,8 +18698,8 @@ function treeifyError2(error49, _mapper) {
 }
 function toDotPath2(_path) {
   const segs = [];
-  const path6 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
-  for (const seg of path6) {
+  const path7 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
+  for (const seg of path7) {
     if (typeof seg === "number")
       segs.push(`[${seg}]`);
     else if (typeof seg === "symbol")
@@ -29389,7 +29895,7 @@ Use these as DOMAIN values when delegating to @sme.`;
 });
 // src/tools/file-extractor.ts
 import * as fs3 from "fs";
-import * as path6 from "path";
+import * as path7 from "path";
 var EXT_MAP = {
   python: ".py",
   py: ".py",
@@ -29467,12 +29973,12 @@ var extract_code_blocks = tool({
       if (prefix) {
         filename = `${prefix}_${filename}`;
       }
-      let filepath = path6.join(targetDir, filename);
-      const base = path6.basename(filepath, path6.extname(filepath));
-      const ext = path6.extname(filepath);
+      let filepath = path7.join(targetDir, filename);
+      const base = path7.basename(filepath, path7.extname(filepath));
+      const ext = path7.extname(filepath);
       let counter = 1;
       while (fs3.existsSync(filepath)) {
-        filepath = path6.join(targetDir, `${base}_${counter}${ext}`);
+        filepath = path7.join(targetDir, `${base}_${counter}${ext}`);
         counter++;
       }
       try {
@@ -29596,6 +30102,8 @@ var OpenCodeSwarm = async (ctx) => {
   const delegationGateHandler = createDelegationGateHook(config3);
   const guardrailsConfig = GuardrailsConfigSchema.parse(config3.guardrails ?? {});
   const guardrailsHooks = createGuardrailsHooks(guardrailsConfig);
+  const summaryConfig = SummaryConfigSchema.parse(config3.summaries ?? {});
+  const toolSummarizerHook = createToolSummarizerHook(summaryConfig, ctx.directory);
   log("Plugin initialized", {
     directory: ctx.directory,
     maxIterations: config3.max_iterations,
@@ -29609,7 +30117,8 @@ var OpenCodeSwarm = async (ctx) => {
       commands: true,
       agentActivity: config3.hooks?.agent_activity !== false,
       delegationTracker: config3.hooks?.delegation_tracker === true,
-      guardrails: guardrailsConfig.enabled
+      guardrails: guardrailsConfig.enabled,
+      toolSummarizer: summaryConfig.enabled
     }
   });
   return {
@@ -29653,14 +30162,20 @@ var OpenCodeSwarm = async (ctx) => {
       }
       const session = swarmState.agentSessions.get(input.sessionID);
       const activeAgent = swarmState.activeAgent.get(input.sessionID);
-      if (session && activeAgent && activeAgent !== ORCHESTRATOR_NAME && session.delegationActive === false) {
-        swarmState.activeAgent.set(input.sessionID, ORCHESTRATOR_NAME);
-        ensureAgentSession(input.sessionID, ORCHESTRATOR_NAME);
+      if (session && activeAgent && activeAgent !== ORCHESTRATOR_NAME) {
+        const stripActive = stripKnownSwarmPrefix(activeAgent);
+        if (stripActive !== ORCHESTRATOR_NAME) {
+          const staleDelegation = !session.delegationActive || Date.now() - session.lastToolCallTime > 60000;
+          if (staleDelegation) {
+            swarmState.activeAgent.set(input.sessionID, ORCHESTRATOR_NAME);
+            ensureAgentSession(input.sessionID, ORCHESTRATOR_NAME);
+          }
+        }
       }
       await guardrailsHooks.toolBefore(input, output);
       await safeHook(activityHooks.toolBefore)(input, output);
     },
-    "tool.execute.after": composeHandlers(activityHooks.toolAfter, guardrailsHooks.toolAfter),
+    "tool.execute.after": composeHandlers(activityHooks.toolAfter, guardrailsHooks.toolAfter, toolSummarizerHook),
     "chat.message": safeHook(delegationHandler)
   };
 };

package/dist/summaries/index.d.ts

@@ -0,0 +1,2 @@
+export { cleanupSummaries, listSummaries, loadFullOutput, storeSummary, } from './manager';
+export { createSummary, detectContentType, HYSTERESIS_FACTOR, shouldSummarize, } from './summarizer';

package/dist/summaries/manager.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Validate and sanitize summary ID.
+ * Must match regex ^S\d+$ (e.g., S1, S2, S99)
+ * Rejects: empty string, null bytes, control characters, path traversal, non-matching patterns
+ * @throws Error with descriptive message on failure
+ */
+export declare function sanitizeSummaryId(id: string): string;
+/**
+ * Store a summary entry to .swarm/summaries/{id}.json.
+ * Performs atomic write via temp file + rename.
+ * @throws Error if summary ID is invalid or size limit would be exceeded
+ */
+export declare function storeSummary(directory: string, id: string, fullOutput: string, summaryText: string, maxStoredBytes: number): Promise<void>;
+/**
+ * Load fullOutput from a summary entry.
+ * Returns null if file doesn't exist or validation fails.
+ */
+export declare function loadFullOutput(directory: string, id: string): Promise<string | null>;
+/**
+ * List all summary IDs that have summary entries.
+ * Returns sorted array of valid summary IDs.
+ * Returns empty array if summaries directory doesn't exist.
+ */
+export declare function listSummaries(directory: string): Promise<string[]>;
+/**
+ * Delete summaries older than retentionDays.
+ * Returns array of deleted summary IDs.
+ */
+export declare function cleanupSummaries(directory: string, retentionDays: number): Promise<string[]>;

package/dist/summaries/summarizer.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Summarization engine for tool outputs.
+ * Provides content type detection, summarization decision logic, and structured summary creation.
+ */
+/**
+ * Hysteresis factor to prevent churn for outputs near the threshold.
+ * An output must be 25% larger than the threshold to be summarized.
+ */
+export declare const HYSTERESIS_FACTOR = 1.25;
+/**
+ * Content type classification for tool outputs.
+ */
+type ContentType = 'json' | 'code' | 'text' | 'binary';
+/**
+ * Heuristic-based content type detection.
+ * @param output - The tool output string to analyze
+ * @param toolName - The name of the tool that produced the output
+ * @returns The detected content type: 'json', 'code', 'text', or 'binary'
+ */
+export declare function detectContentType(output: string, toolName: string): ContentType;
+/**
+ * Determines whether output should be summarized based on size and hysteresis.
+ * Uses hysteresis to prevent repeated summarization decisions for outputs near the threshold.
+ * @param output - The tool output string to check
+ * @param thresholdBytes - The threshold in bytes
+ * @returns true if the output should be summarized
+ */
+export declare function shouldSummarize(output: string, thresholdBytes: number): boolean;
+/**
+ * Creates a structured summary string from tool output.
+ * @param output - The full tool output string
+ * @param toolName - The name of the tool that produced the output
+ * @param summaryId - Unique identifier for this summary
+ * @param maxSummaryChars - Maximum characters allowed for the preview
+ * @returns Formatted summary string
+ */
+export declare function createSummary(output: string, toolName: string, summaryId: string, maxSummaryChars: number): string;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-swarm",
-	"version": "5.1.1",
+	"version": "5.1.4",
 	"description": "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",