opencode-swarm 7.62.0 → 7.63.0

package/dist/hooks/knowledge-validator.d.ts

@@ -30,6 +30,44 @@ export declare function validateSkillPath(p: unknown): boolean;
 /** Validate the optional ActionableDirectiveFields block on a knowledge entry. */
 export declare function validateActionableFields(fields: ActionableDirectiveFields | undefined): ActionableValidationResult;
 export type { ActionableDirectiveFields, DirectivePriority };
+export interface ActionabilityResult {
+    actionable: boolean;
+    /** Present only when not actionable. */
+    reason?: 'missing_predicate' | 'missing_scope' | 'missing_predicate_and_scope';
+}
+/**
+ * Layer 5: an entry is actionable only when it carries at least one
+ * machine-checkable predicate AND at least one scope tag.
+ *
+ *   predicate := forbidden_actions | required_actions | verification_checks
+ *                | verification_predicate
+ *   scope     := applies_to_tools | applies_to_agents
+ *
+ * Plain-prose lessons (no predicate, no scope) are NOT actionable and must be
+ * quarantined rather than activated.
+ */
+export declare function validateActionability(entry: Pick<KnowledgeEntryBase, 'forbidden_actions' | 'required_actions' | 'verification_checks' | 'verification_predicate' | 'applies_to_tools' | 'applies_to_agents'>): ActionabilityResult;
+/** Returns `.swarm/knowledge-unactionable.jsonl` for the given directory. */
+export declare function resolveUnactionablePath(directory: string): string;
+/** One quarantined-unactionable record. */
+export interface UnactionableRecord extends KnowledgeEntryBase {
+    status: 'quarantined_unactionable';
+    unactionable_reason: string;
+    quarantined_at: string;
+}
+/**
+ * Persist an entry that failed the actionability layer to the unactionable
+ * queue (held out of the active store, pending hardening by the skill-improver).
+ * FIFO-capped at 200. Best-effort: throws only on lock failure for tests.
+ *
+ * Flooding tradeoff (Phase 4 review): duplicate prose lessons are NOT deduped
+ * at queue time, so a looping producer can fill the queue with duplicates and
+ * FIFO-evict older legitimate records. Accepted because (a) the cap bounds the
+ * damage at 200 records of plain text, (b) the hardening loop's promotion path
+ * dedups at commit time against the active store, and (c) queue producers are
+ * themselves quota- or phase-bounded. Revisit if telemetry shows real evictions.
+ */
+export declare function appendUnactionable(directory: string, entry: KnowledgeEntryBase, reason: string): Promise<void>;
 export interface QuarantinedEntry extends KnowledgeEntryBase {
     original_status: string;
     quarantine_reason: string;

package/dist/hooks/micro-reflector.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Micro-reflector (Swarm Learning System, Change 6 / Task 5.1).
+ *
+ * The innermost reflection loop: runs when a delegated subagent returns (a
+ * `tool.execute.after` hook on the `Task` tool). It reads the delegate's
+ * transcript and the per-task trajectory slice
+ * (`.swarm/evidence/<taskId>/trajectory.jsonl`), classifies the outcome, and —
+ * ONLY on failure/partial outcomes — calls a cheap, quota-gated LLM to emit
+ * 0–2 candidate insights conforming to the v3 actionability schema. Candidates
+ * are appended to `.swarm/insight-candidates.jsonl`; they are NEVER written
+ * directly to the knowledge store (the meso reflector consumes them at phase
+ * boundary, Task 5.2).
+ *
+ * Budget: the prompt is capped well under ~2k input chars and the model is
+ * asked for ≤512 output. Exactly one LLM call per qualifying return, gated by
+ * the shared skill-improver quota. Fail-open: never throws, never blocks.
+ */
+import type { CuratorLLMDelegate } from './curator.js';
+import type { EnrichmentQuotaOptions } from './knowledge-curator.js';
+import type { ActionableDirectiveFields } from './knowledge-types.js';
+import type { TrajectoryEntry } from './trajectory-logger.js';
+export type MicroOutcome = 'success' | 'failure_test' | 'failure_lint' | 'failure_revert' | 'partial';
+export declare const MICRO_PROMPT_INPUT_CAP = 1800;
+/** One v3-schema candidate insight written to the queue. */
+export interface InsightCandidate extends ActionableDirectiveFields {
+    lesson: string;
+    category: string;
+    tags: string[];
+    source: {
+        kind: 'micro_reflection';
+        task_id?: string;
+        agent: string;
+        outcome: MicroOutcome;
+        trajectory_steps: number;
+    };
+    created_at: string;
+}
+/** Returns `.swarm/insight-candidates.jsonl` for a project directory. */
+export declare function resolveInsightCandidatesPath(directory: string): string;
+/**
+ * Classify the delegate outcome from its transcript + trajectory. Trajectory
+ * tool results are authoritative when present; the transcript provides the
+ * fallback signal. Defaults to 'success' (no reflection) when nothing matches.
+ */
+export declare function classifyOutcome(transcript: string, trajectory: TrajectoryEntry[]): MicroOutcome;
+/** Read a task's trajectory slice. Fail-open: [] when absent/corrupt. */
+export declare function readTaskTrajectory(directory: string, taskId: string): Promise<TrajectoryEntry[]>;
+/** Build the bounded micro-reflection prompt (≤ MICRO_PROMPT_INPUT_CAP chars). */
+export declare function buildMicroPrompt(params: {
+    agent: string;
+    outcome: MicroOutcome;
+    transcript: string;
+    trajectory: TrajectoryEntry[];
+}): string;
+/** Parse the LLM response into validated v3 candidates (allowlist + actionable). */
+export declare function parseMicroCandidates(response: string, meta: {
+    agent: string;
+    outcome: MicroOutcome;
+    taskId?: string;
+    steps: number;
+}): InsightCandidate[];
+export interface MicroReflectionResult {
+    outcome: MicroOutcome;
+    reflected: boolean;
+    candidates: number;
+}
+/** Core micro-reflection. Never throws. */
+export declare function runMicroReflection(params: {
+    directory: string;
+    taskId?: string;
+    agent: string;
+    transcript: string;
+    trajectory: TrajectoryEntry[];
+    llmDelegate?: CuratorLLMDelegate;
+    quota?: EnrichmentQuotaOptions;
+}): Promise<MicroReflectionResult>;
+export interface MicroReflectorInput {
+    tool: unknown;
+    args?: unknown;
+    sessionID?: unknown;
+}
+export interface MicroReflectorOutput {
+    output?: unknown;
+}
+/**
+ * `tool.execute.after` adapter for the `Task` tool. Resolves the delegate, the
+ * transcript, the task id, and the trajectory slice, then runs micro-reflection.
+ * The LLM delegate is provided by the caller (so tests can inject one); when
+ * absent, classification still runs but no LLM call is made.
+ */
+export declare function microReflectorAfter(directory: string, input: MicroReflectorInput, output: MicroReflectorOutput, llmDelegate?: CuratorLLMDelegate, quota?: EnrichmentQuotaOptions): Promise<void>;

package/dist/hooks/phase-complete-directive-gate.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Phase-complete critical-directive gate (Swarm Learning System, Change 2 /
+ * Task 2.4).
+ *
+ * A phase may not complete while a CRITICAL knowledge directive shown during the
+ * phase lacks a terminal outcome, or carries an unremediated violation. A
+ * critical directive is RESOLVED when, within the phase window, it has either:
+ *   - an `applied` outcome dated at/after its latest `violated` (remediation /
+ *     reviewer VERIFIED), OR
+ *   - an `ignored` or `n_a` outcome WITH a reason and no later `violated`.
+ * Otherwise it BLOCKS with one of:
+ *   - 'no_verdict'             — no terminal outcome at all, or
+ *   - 'unremediated_violation' — a violation with no later applied/verified.
+ *
+ * The architect may override specific IDs via `acceptViolations` (logged as an
+ * `override` event with a written justification). Fail-CLOSED: any read error
+ * surfaces as a block, never a silent pass.
+ */
+export type DirectiveBlockReason = 'no_verdict' | 'unremediated_violation';
+export interface DirectiveGateResult {
+    blocked: boolean;
+    unresolved: Array<{
+        id: string;
+        reason: DirectiveBlockReason;
+    }>;
+    overridden: string[];
+    /** True when the gate could not read its inputs (fail-closed → blocked). */
+    failedClosed: boolean;
+}
+/**
+ * Evaluate all critical directives shown during the phase. Fail-closed.
+ */
+export declare function evaluatePhaseCriticalDirectives(params: {
+    directory: string;
+    phaseLabel?: string;
+    acceptViolations?: string[];
+}): Promise<DirectiveGateResult>;
+/**
+ * Record an architect override for accepted critical violations. Each accepted
+ * id is logged as an `override` event with the written justification.
+ */
+export declare function recordDirectiveOverrides(directory: string, ids: string[], justification: string, sessionId: string | undefined): Promise<void>;
+/** Build a structured, human-readable block message for unresolved criticals. */
+export declare function formatDirectiveBlockMessage(unresolved: DirectiveGateResult['unresolved']): string;

package/dist/hooks/phase-directives.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Phase-windowed directive sourcing (Swarm Learning System, Change 2).
+ *
+ * Single source of truth for "which knowledge directives were shown during this
+ * phase". Used by both the reviewer verdict loop (Task 2.1/2.3 — which IDs the
+ * reviewer must verify) and the phase-complete gate (Task 2.4 — which CRITICAL
+ * IDs must reach a terminal outcome before the phase advances).
+ *
+ * The window is defined by the retrieval event's `phase` label: every
+ * `retrieved` event (auto_injection AND delegate_inject) carries the plan phase
+ * label, so a single equality filter gives a consistent set across consumers.
+ * Passing an empty/undefined phase collects directives across all phases (used
+ * only as a permissive fallback).
+ */
+import type { DirectiveToVerify } from '../agents/reviewer-directive-compliance.js';
+import type { KnowledgeEntryBase } from './knowledge-types.js';
+/** Collect the directive IDs surfaced by `retrieved` events in the phase window. */
+export declare function collectPhaseDirectiveIds(directory: string, phaseLabel?: string): Promise<string[]>;
+/** Load all knowledge entries (swarm + hive) indexed by id. */
+export declare function readEntriesById(directory: string): Promise<Map<string, KnowledgeEntryBase>>;
+/**
+ * Resolve the directives the reviewer must verify for a phase: the entries
+ * behind the phase's retrieved IDs, with priority + lesson + verification
+ * predicate. Archived/quarantined entries are excluded. Fail-open: returns [] on
+ * any error.
+ */
+export declare function readPhaseDirectivesToVerify(directory: string, phaseLabel?: string): Promise<DirectiveToVerify[]>;
+/** The CRITICAL directive IDs retrieved during the phase. */
+export declare function readPhaseCriticalDirectiveIds(directory: string, phaseLabel?: string): Promise<string[]>;

package/dist/hooks/reviewer-verdict-parser.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Reviewer DIRECTIVE_COMPLIANCE parsing + reconciliation (Swarm Learning System,
+ * Change 2 / Task 2.3).
+ *
+ * Parses a reviewer's `DIRECTIVE_COMPLIANCE` block (VERIFIED / VIOLATED / N/A
+ * lines) and reconciles it against the set of directives the reviewer was asked
+ * to verify, emitting one receipt event per directive (tagged source:'reviewer'):
+ *
+ *   VERIFIED:<id>  → type:'applied'   (verified === honored)
+ *   VIOLATED:<id>  → type:'violated'  (+ run any verification_predicate)
+ *   N/A:<id>       → type:'n_a'        (neutral)
+ *
+ * Anti-spoofing: verdicts for IDs that were not in the verify-set are dropped.
+ * A CRITICAL directive the reviewer never addressed gets a synthetic
+ * `violated` / `reviewer_omitted` event. Fail-open: never throws.
+ */
+import { type DirectiveToVerify } from '../agents/reviewer-directive-compliance.js';
+export type ReviewerVerdict = 'verified' | 'violated' | 'n_a';
+export interface ParsedReviewerVerdict {
+    id: string;
+    verdict: ReviewerVerdict;
+    /** evidence=... (VERIFIED/VIOLATED) or reason=... (N/A). */
+    evidence?: string;
+}
+/** Parse a reviewer transcript's DIRECTIVE_COMPLIANCE verdict lines. */
+export declare function parseReviewerDirectiveCompliance(text: string): ParsedReviewerVerdict[];
+export interface ReconcileReviewerVerdictsParams {
+    directory: string;
+    transcript: string;
+    directivesToVerify: DirectiveToVerify[];
+    sessionId?: string;
+    taskId?: string;
+    phase?: string;
+    agent?: string;
+}
+export interface ReconcileReviewerVerdictsResult {
+    emitted: Array<{
+        id: string;
+        type: string;
+        source: 'reviewer';
+    }>;
+    omittedCriticals: string[];
+}
+/**
+ * Reconcile reviewer verdicts against the verify-set and emit receipt events.
+ * Runs a directive's verification_predicate when the reviewer reports VIOLATED
+ * and the directive carries one. Never throws.
+ */
+export declare function reconcileReviewerVerdicts(params: ReconcileReviewerVerdictsParams): Promise<ReconcileReviewerVerdictsResult>;
+export interface ReviewerVerdictInput {
+    tool: unknown;
+    args?: unknown;
+    sessionID?: unknown;
+}
+export interface ReviewerVerdictOutput {
+    output?: unknown;
+}
+/**
+ * `tool.execute.after` adapter (Task 2.3). When a reviewer Task returns,
+ * recover the verify-set from the `<directives_to_verify>` block in its prompt
+ * (anti-spoofing), then reconcile the reviewer's DIRECTIVE_COMPLIANCE verdicts
+ * into knowledge events. No-op for non-reviewer delegations. Never throws.
+ */
+export declare function collectReviewerVerdictsAfter(directory: string, input: ReviewerVerdictInput, output: ReviewerVerdictOutput): Promise<void>;

package/dist/hooks/search-knowledge.d.ts

@@ -63,6 +63,35 @@ export interface SearchKnowledgeResult {
     trace_id: string;
     results: RankedEntry[];
 }
+/**
+ * Age of an entry measured in distinct confirming phases (Change 5 / Task 6.2).
+ * A brand-new candidate (no confirmations) is age 0; an entry confirmed across
+ * many phases is "established" and no longer eligible for the cold-start
+ * exploration bonus. Falls back to the raw confirmation count when phase numbers
+ * are absent.
+ */
+declare function entryAgePhases(e: {
+    confirmed_by?: Array<{
+        phase_number?: number;
+    }>;
+}): number;
+/** Clamp the MMR lambda to [0,1], default 0.5. */
+declare function clampLambda(v: number | undefined): number;
+/**
+ * Maximal Marginal Relevance rerank (Change 5, Task 6.1). Greedily selects from
+ * `pool` to fill up to `max` total (counting the already-selected `pinned`),
+ * trading relevance against diversity:
+ *   mmr(c) = λ·relevance(c) − (1−λ)·max_{s∈selected} bigram_jaccard(lesson_c, lesson_s)
+ * Reuses `jaccardBigram` (no second similarity function). Deterministic: ties
+ * break by finalScore, then recency, then id, so a query with uniform paraphrase
+ * distance yields a stable order.
+ */
+declare function mmrRerank<T extends {
+    id: string;
+    finalScore: number;
+    lesson: string;
+    created_at: string;
+}>(pool: T[], pinned: T[], max: number, lambda: number): T[];
 /**
  * Run unified knowledge retrieval. Returns a trace_id (always minted, even when
  * no entries match) and the ranked results. Reading/scoring failures degrade to
@@ -71,4 +100,8 @@ export interface SearchKnowledgeResult {
 export declare function searchKnowledge(params: SearchKnowledgeParams): Promise<SearchKnowledgeResult>;
 export declare const _internals: {
     searchKnowledge: typeof searchKnowledge;
+    mmrRerank: typeof mmrRerank;
+    clampLambda: typeof clampLambda;
+    entryAgePhases: typeof entryAgePhases;
 };
+export {};