opencode-swarm 7.41.0 → 7.42.0

package/dist/summaries/aggregate.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Phase-level aggregation of per-agent work summaries (issue #893, Chunk B).
+ *
+ * Deterministic, cheap rollup that runs in the non-blocking phase-monitor hook: it reads
+ * the agent summaries for a completed phase, unions their decisions/risks/violations, and
+ * surfaces cross-agent contradictions (a constraint one agent observed but another
+ * violated). The result is written as a raw sidecar that the architecture-supervisor
+ * critic reviews in Chunk C. No LLM call here — keeps the hook fast and side-effect-light.
+ */
+import { type PhaseArchitectureSummary } from './schema';
+export interface AggregatePhaseOptions {
+    /** Override the timestamp source (tests). */
+    now?: () => string;
+    /** Word cap for the rollup summary text. */
+    maxPhaseSummaryWords?: number;
+}
+/**
+ * Aggregate all agent summaries for `phase` into a PhaseArchitectureSummary and persist
+ * it as a sidecar. Returns the summary, or null when there are no agent summaries for the
+ * phase (nothing to roll up — the sidecar is not written in that case).
+ */
+export declare function aggregatePhaseSummary(directory: string, phase: number, options?: AggregatePhaseOptions): Promise<PhaseArchitectureSummary | null>;

package/dist/summaries/schema.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Schemas and helpers for the hierarchical architecture-summary system (issue #893).
+ *
+ * Three tiers roll up task -> phase -> project:
+ *  - AgentWorkSummary: short, structured "what I did" emitted by each worker/architect
+ *    at task completion (stored as a `note` evidence entry, payload under metadata).
+ *  - PhaseArchitectureSummary: cheap-model compression of all agent summaries in a phase
+ *    (written as a raw sidecar, like phase-council.json).
+ *  - ArchitectureSupervisorReport: the expensive read-only critic's verdict over the
+ *    compressed summaries (also a raw sidecar so top-level fields survive).
+ *
+ * Caps are enforced by truncation (not rejection) to match the repo's lenient evidence
+ * style; callers use the normalize* helpers before validation and surface a `truncated`
+ * flag in metadata.
+ */
+import { z } from 'zod';
+export declare const SUMMARY_SCHEMA_VERSION = "1.0.0";
+/** Default caps (config can lower these per-feature; schemas use them as hard bounds). */
+export declare const MAX_AGENT_SUMMARY_WORDS = 100;
+export declare const MAX_PHASE_SUMMARY_WORDS = 250;
+export declare const MAX_LIST_ITEMS = 5;
+/** Verdict vocabulary — mirrors the phase-council gate (APPROVE | CONCERNS | REJECT). */
+export declare const SupervisorVerdictSchema: z.ZodEnum<{
+    APPROVE: "APPROVE";
+    REJECT: "REJECT";
+    CONCERNS: "CONCERNS";
+}>;
+export type SupervisorVerdict = z.infer<typeof SupervisorVerdictSchema>;
+/** Count whitespace-delimited words in a string. */
+export declare function countWords(text: string): number;
+/** Truncate to `maxWords`, appending an ellipsis marker when content was dropped. */
+export declare function truncateWords(text: string, maxWords: number): {
+    text: string;
+    truncated: boolean;
+};
+/** Cap an array to `maxItems`, reporting whether anything was dropped. */
+export declare function capArray<T>(items: T[], maxItems: number): {
+    items: T[];
+    truncated: boolean;
+};
+export declare const AgentWorkSummarySchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<"1.0.0">;
+    phase: z.ZodNumber;
+    task_id: z.ZodOptional<z.ZodString>;
+    session_id: z.ZodString;
+    agent: z.ZodString;
+    parent_agent: z.ZodOptional<z.ZodString>;
+    summary: z.ZodString;
+    key_decisions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    constraints_observed: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    constraints_violated: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    assumptions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    risks: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    files_touched: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    evidence_refs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    created_at: z.ZodString;
+    truncated: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type AgentWorkSummary = z.infer<typeof AgentWorkSummarySchema>;
+/**
+ * Raw, pre-validation fields a caller supplies. Caps are applied here, then the result
+ * is validated against AgentWorkSummarySchema. Returns the normalized summary plus a
+ * `truncated` flag aggregated across all fields.
+ */
+export interface AgentWorkSummaryInput {
+    phase: number;
+    task_id?: string;
+    session_id: string;
+    agent: string;
+    parent_agent?: string;
+    summary: string;
+    key_decisions?: string[];
+    constraints_observed?: string[];
+    constraints_violated?: string[];
+    assumptions?: string[];
+    risks?: string[];
+    files_touched?: string[];
+    evidence_refs?: string[];
+    created_at?: string;
+}
+export declare function normalizeAgentWorkSummary(input: AgentWorkSummaryInput, maxSummaryWords?: number): AgentWorkSummary;
+export declare const PhaseArchitectureSummarySchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<"1.0.0">;
+    phase: z.ZodNumber;
+    summary: z.ZodDefault<z.ZodString>;
+    agents_seen: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    tasks_seen: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    key_decisions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    conflicts: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    unresolved_risks: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    constraint_violations: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    evidence_refs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    created_at: z.ZodString;
+}, z.core.$strip>;
+export type PhaseArchitectureSummary = z.infer<typeof PhaseArchitectureSummarySchema>;
+export declare const SupervisorFindingSchema: z.ZodObject<{
+    severity: z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+        critical: "critical";
+    }>;
+    category: z.ZodString;
+    agents: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    tasks: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    evidence_refs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    description: z.ZodString;
+    recommendation: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+export type SupervisorFinding = z.infer<typeof SupervisorFindingSchema>;
+export declare const KnowledgeRecommendationSchema: z.ZodObject<{
+    lesson: z.ZodString;
+    target_agents: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    confidence: z.ZodDefault<z.ZodNumber>;
+    evidence_refs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type KnowledgeRecommendation = z.infer<typeof KnowledgeRecommendationSchema>;
+export declare const ArchitectureSupervisorReportSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<"1.0.0">;
+    phase: z.ZodNumber;
+    verdict: z.ZodEnum<{
+        APPROVE: "APPROVE";
+        REJECT: "REJECT";
+        CONCERNS: "CONCERNS";
+    }>;
+    findings: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        severity: z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+            critical: "critical";
+        }>;
+        category: z.ZodString;
+        agents: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        tasks: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        evidence_refs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        description: z.ZodString;
+        recommendation: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>>;
+    knowledge_recommendations: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        lesson: z.ZodString;
+        target_agents: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        confidence: z.ZodDefault<z.ZodNumber>;
+        evidence_refs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    created_at: z.ZodString;
+}, z.core.$strip>;
+export type ArchitectureSupervisorReport = z.infer<typeof ArchitectureSupervisorReportSchema>;

package/dist/summaries/store.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Persistence for the architecture-summary tiers (issue #893).
+ *
+ * Storage strategy (verified against the evidence system):
+ *  - Per-agent summaries are stored as `note` evidence entries via saveEvidence(), with
+ *    the structured payload under `metadata` (EvidenceBundleSchema parses entries through
+ *    a discriminated union and strips unknown top-level keys, so the payload MUST live in
+ *    metadata).
+ *  - Phase summaries and the supervisor report are written as raw sidecar bundles
+ *    (temp-file + rename), mirroring submit-phase-council-verdicts.ts, so the gate can
+ *    read top-level fields (verdict, phase_number, timestamp) without zod stripping them.
+ */
+import { type AgentWorkSummary, type ArchitectureSupervisorReport, type PhaseArchitectureSummary } from './schema';
+export declare const AGENT_SUMMARY_METADATA_KIND = "agent_summary";
+/**
+ * Persist a per-agent work summary as a `note` evidence entry. The structured payload
+ * lives entirely under metadata so it survives EvidenceBundleSchema validation.
+ * Keyed by the agent's task_id when present, else a synthetic phase-scoped bucket.
+ */
+export declare function writeAgentSummary(directory: string, summary: AgentWorkSummary): Promise<string>;
+export interface ListAgentSummariesFilter {
+    phase?: number;
+    session?: string;
+}
+/**
+ * Scan all evidence bundles and return the agent work summaries matching the filter.
+ * Malformed payloads are skipped (logged, never thrown) so aggregation stays fail-open.
+ */
+export declare function listAgentSummaries(directory: string, filter?: ListAgentSummariesFilter): Promise<AgentWorkSummary[]>;
+export declare function writePhaseArchitectureSummary(directory: string, summary: PhaseArchitectureSummary): string;
+export declare function readPhaseArchitectureSummary(directory: string, phase: number): PhaseArchitectureSummary | null;
+/**
+ * Write the supervisor report as a raw sidecar bundle whose single entry carries
+ * top-level `verdict`, `phase_number`, and `timestamp` — exactly the shape the
+ * phase-complete gate reads via fs.readFileSync + JSON.parse (mirrors phase-council).
+ */
+export declare function writeSupervisorReport(directory: string, report: ArchitectureSupervisorReport): string;
+/** A single raw supervisor entry as read back from the sidecar (untyped JSON). */
+export interface RawSupervisorEntry {
+    type: string;
+    phase_number?: number;
+    timestamp?: string;
+    verdict?: string;
+    findings?: unknown[];
+    knowledge_recommendations?: unknown[];
+}
+/**
+ * Read the supervisor report sidecar raw (no zod), returning the supervisor entry or
+ * null when the file is missing/malformed. This is the read path the gate uses.
+ */
+export declare function readSupervisorReportRaw(directory: string, phase: number): RawSupervisorEntry | null;

package/dist/tools/index.d.ts

@@ -50,9 +50,11 @@ export { skill_inspect } from './skill-inspect';
 export { skill_list } from './skill-list';
 export { spec_write } from './spec-write';
 export { submit_phase_council_verdicts } from './submit-phase-council-verdicts';
+export { summarize_work } from './summarize-work';
 export { createSwarmCommandTool, swarm_command } from './swarm-command';
 export { swarm_memory_propose } from './swarm-memory-propose';
 export { swarm_memory_recall } from './swarm-memory-recall';
+export { write_architecture_supervisor_evidence } from './write-architecture-supervisor-evidence';
 import { suggestPatch } from './suggest-patch';
 export { suggestPatch };
 export type { SuggestPatchArgs } from './suggest-patch';

package/dist/tools/summarize-work.d.ts

@@ -0,0 +1,7 @@
+/**
+ * summarize_work — agents call this at task completion to emit a short structured
+ * summary of what they did (issue #893). Stored as a `note` evidence entry; rolled up
+ * per-phase and reviewed by the architecture-supervisor critic. Advisory: never blocks.
+ */
+import type { tool } from '@opencode-ai/plugin';
+export declare const summarize_work: ReturnType<typeof tool>;

package/dist/tools/tool-names.d.ts

@@ -3,7 +3,7 @@
  * Used for constants and agent setup references.
  */
 /** Union type of all valid tool names */
-export type ToolName = 'diff' | 'diff_summary' | 'syntax_check' | 'placeholder_scan' | 'imports' | 'lint' | 'secretscan' | 'sast_scan' | 'build_check' | 'pre_check_batch' | 'quality_budget' | 'symbols' | 'complexity_hotspots' | 'schema_drift' | 'todo_extract' | 'evidence_check' | 'check_gate_status' | 'completion_verify' | 'submit_council_verdicts' | 'submit_phase_council_verdicts' | 'declare_council_criteria' | 'sbom_generate' | 'checkpoint' | 'pkg_audit' | 'test_runner' | 'test_impact' | 'mutation_test' | 'generate_mutants' | 'detect_domains' | 'gitingest' | 'retrieve_summary' | 'extract_code_blocks' | 'phase_complete' | 'save_plan' | 'update_task_status' | 'lint_spec' | 'write_retro' | 'write_drift_evidence' | 'write_hallucination_evidence' | 'write_mutation_evidence' | 'declare_scope' | 'knowledge_query' | 'doc_scan' | 'doc_extract' | 'curator_analyze' | 'knowledge_add' | 'knowledge_recall' | 'knowledge_remove' | 'co_change_analyzer' | 'search' | 'batch_symbols' | 'suggest_patch' | 'req_coverage' | 'get_approved_plan' | 'repo_map' | 'get_qa_gate_profile' | 'set_qa_gates' | 'web_search' | 'convene_general_council' | 'write_final_council_evidence' | 'skill_generate' | 'skill_list' | 'skill_apply' | 'skill_inspect' | 'skill_improve' | 'spec_write' | 'knowledge_ack' | 'swarm_memory_recall' | 'swarm_memory_propose' | 'swarm_command' | 'lean_turbo_plan_lanes' | 'lean_turbo_acquire_locks' | 'lean_turbo_runner_status' | 'lean_turbo_review' | 'lean_turbo_run_phase' | 'lean_turbo_status';
+export type ToolName = 'diff' | 'diff_summary' | 'syntax_check' | 'placeholder_scan' | 'imports' | 'lint' | 'secretscan' | 'sast_scan' | 'build_check' | 'pre_check_batch' | 'quality_budget' | 'symbols' | 'complexity_hotspots' | 'schema_drift' | 'todo_extract' | 'evidence_check' | 'check_gate_status' | 'completion_verify' | 'submit_council_verdicts' | 'submit_phase_council_verdicts' | 'declare_council_criteria' | 'sbom_generate' | 'checkpoint' | 'pkg_audit' | 'test_runner' | 'test_impact' | 'mutation_test' | 'generate_mutants' | 'detect_domains' | 'gitingest' | 'retrieve_summary' | 'extract_code_blocks' | 'phase_complete' | 'save_plan' | 'update_task_status' | 'lint_spec' | 'write_retro' | 'write_drift_evidence' | 'write_hallucination_evidence' | 'write_mutation_evidence' | 'declare_scope' | 'knowledge_query' | 'doc_scan' | 'doc_extract' | 'curator_analyze' | 'knowledge_add' | 'knowledge_recall' | 'knowledge_remove' | 'co_change_analyzer' | 'search' | 'batch_symbols' | 'suggest_patch' | 'req_coverage' | 'get_approved_plan' | 'repo_map' | 'get_qa_gate_profile' | 'set_qa_gates' | 'web_search' | 'convene_general_council' | 'write_final_council_evidence' | 'skill_generate' | 'skill_list' | 'skill_apply' | 'skill_inspect' | 'skill_improve' | 'spec_write' | 'knowledge_ack' | 'swarm_memory_recall' | 'swarm_memory_propose' | 'swarm_command' | 'summarize_work' | 'write_architecture_supervisor_evidence' | 'lean_turbo_plan_lanes' | 'lean_turbo_acquire_locks' | 'lean_turbo_runner_status' | 'lean_turbo_review' | 'lean_turbo_run_phase' | 'lean_turbo_status';
 /** Readonly array of all tool names */
 export declare const TOOL_NAMES: readonly ToolName[];
 /** Set for O(1) tool name validation */

package/dist/tools/write-architecture-supervisor-evidence.d.ts

@@ -0,0 +1,11 @@
+/**
+ * write_architecture_supervisor_evidence — persists the architecture-supervisor critic's
+ * verdict for a phase (issue #893, Chunk C). The architect dispatches
+ * critic_architecture_supervisor, collects its structured JSON verdict, then calls this
+ * tool to write the raw sidecar that the phase-complete gate (Chunk D) reads.
+ *
+ * Mirrors write_drift_evidence / submit_phase_council_verdicts: the tool persists only —
+ * it does not contact the supervisor.
+ */
+import type { tool } from '@opencode-ai/plugin';
+export declare const write_architecture_supervisor_evidence: ReturnType<typeof tool>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-swarm",
-	"version": "7.41.0",
+	"version": "7.42.0",
 	"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",