opencode-swarm 7.43.1 → 7.44.0

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

@@ -0,0 +1,193 @@
+/**
+ * Event-sourced knowledge lifecycle for opencode-swarm.
+ *
+ * `.swarm/knowledge-events.jsonl` is an append-only, immutable log of every
+ * meaningful knowledge interaction (retrieval, receipt, outcome, archival).
+ * It is the authoritative history: per-entry counters
+ * (`retrieval_outcomes.*`) become *derived rollups* recomputed deterministically
+ * from this log via {@link recomputeCounters}.
+ *
+ * Design contracts:
+ * - Append-only. We never rewrite or delete lines. OS-level atomic append is
+ *   used (same pattern as `appendKnowledge` in knowledge-store.ts) — no lock is
+ *   needed for append-only writes.
+ * - Fail-open. Event recording is telemetry; it must never break tool or hook
+ *   execution. Use {@link recordKnowledgeEvent} (swallows + warns) on hot paths;
+ *   {@link appendKnowledgeEvent} throws and is intended for tests / callers that
+ *   want explicit error handling.
+ * - `.swarm/` containment (AGENTS.md invariant 4): the path is derived from the
+ *   `directory` argument injected by `createSwarmTool` / hook constructors — never
+ *   from the process working directory.
+ */
+import type { KnowledgeApplicationRecord } from './knowledge-types.js';
+/** Current event-log record schema version. Bump when the on-disk shape changes. */
+export declare const KNOWLEDGE_EVENT_SCHEMA_VERSION = 1;
+/**
+ * Soft cap on `.swarm/knowledge-events.jsonl` line count. Enforced FIFO after
+ * each append: oldest lines are trimmed when total exceeds the cap. Sized for
+ * months of activity on a typical project (~5k retrieval/receipt events).
+ */
+export declare const MAX_EVENT_LOG_ENTRIES = 5000;
+/** Retrieval modes that surface knowledge to an agent. */
+export type RetrievalEventMode = 'manual' | 'auto_injection' | 'coder_context' | 'review_context' | 'curator';
+/** A retrieval: a query returned a ranked set of knowledge entries. */
+export interface RetrievedEvent {
+    type: 'retrieved';
+    schema_version?: number;
+    event_id: string;
+    trace_id: string;
+    timestamp: string;
+    session_id: string;
+    phase?: string;
+    task_id?: string;
+    agent: string;
+    query: string;
+    retrieval_mode: RetrievalEventMode;
+    result_ids: string[];
+    /** id → 1-based rank in the result list. */
+    ranks: Record<string, number>;
+    /** id → final score. */
+    scores: Record<string, number>;
+    score_breakdown?: Record<string, unknown>;
+}
+/** A receipt: an agent explicitly considered a specific knowledge entry. */
+export interface ReceiptEvent {
+    type: 'acknowledged' | 'applied' | 'ignored' | 'contradicted' | 'violated';
+    schema_version?: number;
+    event_id: string;
+    trace_id: string;
+    knowledge_id: string;
+    timestamp: string;
+    session_id: string;
+    phase?: string;
+    task_id?: string;
+    agent: string;
+    reason?: string;
+    evidence?: {
+        files?: string[];
+        commands?: string[];
+        tests?: string[];
+        summary?: string;
+    };
+}
+/** An outcome: a task/phase succeeded or failed, optionally attributed to an entry. */
+export interface OutcomeEvent {
+    type: 'outcome';
+    schema_version?: number;
+    event_id: string;
+    trace_id?: string;
+    knowledge_id?: string;
+    timestamp: string;
+    task_id?: string;
+    phase?: string;
+    outcome: 'success' | 'failure' | 'partial';
+    evidence_summary: string;
+}
+/** An audit tombstone: an entry was archived / quarantined / purged. */
+export interface ArchivedEvent {
+    type: 'archived';
+    schema_version?: number;
+    event_id: string;
+    timestamp: string;
+    entry_id: string;
+    actor: string;
+    reason: string;
+    mode: 'archive' | 'quarantine' | 'purge';
+    evidence?: string;
+    previous_status?: string;
+}
+export type KnowledgeEvent = RetrievedEvent | ReceiptEvent | OutcomeEvent | ArchivedEvent;
+export type KnowledgeEventType = KnowledgeEvent['type'];
+/**
+ * Event shape accepted by {@link appendKnowledgeEvent} / {@link recordKnowledgeEvent}.
+ * `event_id` and `timestamp` are optional on input — they are filled in on write.
+ * Distributes over the union so each variant keeps its required discriminant
+ * fields.
+ */
+export type KnowledgeEventInput = KnowledgeEvent extends infer T ? T extends KnowledgeEvent ? Omit<T, 'event_id' | 'timestamp'> & {
+    event_id?: string;
+    timestamp?: string;
+} : never : never;
+/** Receipt event verbs that reference a single knowledge_id. */
+export declare const RECEIPT_EVENT_TYPES: ReadonlySet<string>;
+/** Returns `.swarm/knowledge-events.jsonl` for the given project directory. */
+export declare function resolveKnowledgeEventsPath(directory: string): string;
+/** Generate a fresh trace id. One per retrieval; receipts reference it. */
+export declare function newTraceId(): string;
+/** Generate a fresh event id. Unique per appended event. */
+export declare function newEventId(): string;
+/**
+ * Append one event to the log, filling in event_id / timestamp if absent.
+ * Returns the fully-populated event that was written.
+ *
+ * Throws on I/O failure — callers on hot paths should prefer
+ * {@link recordKnowledgeEvent}, which swallows errors.
+ */
+export declare function appendKnowledgeEvent(directory: string, event: KnowledgeEventInput): Promise<KnowledgeEvent>;
+/**
+ * Fail-open variant of {@link appendKnowledgeEvent} for hot paths (hooks, tool
+ * execution). Never throws; logs a warning and returns null on failure.
+ */
+export declare function recordKnowledgeEvent(directory: string, event: KnowledgeEventInput): Promise<KnowledgeEvent | null>;
+/**
+ * Read all events from the log. Skips corrupted JSONL lines (logging a warning
+ * for each) and returns an empty array when the file does not exist — mirrors
+ * `readKnowledge` in knowledge-store.ts.
+ */
+export declare function readKnowledgeEvents(directory: string): Promise<KnowledgeEvent[]>;
+/**
+ * Derived per-entry counters. This is the rollup shape recomputed from the
+ * event log; it maps onto the v2 `RetrievalOutcome` counter fields plus the v3
+ * `contradicted_count`.
+ */
+export interface CounterRollup {
+    shown_count: number;
+    acknowledged_count: number;
+    applied_explicit_count: number;
+    ignored_count: number;
+    violated_count: number;
+    contradicted_count: number;
+    succeeded_after_shown_count: number;
+    failed_after_shown_count: number;
+    /**
+     * Count of partial outcomes. Tracked separately so it surfaces in
+     * diagnostics but never contributes to `computeOutcomeSignal` (partial is
+     * deliberately ambiguous — it neither rewards nor penalizes).
+     */
+    partial_after_shown_count: number;
+    last_applied_at?: string;
+    last_acknowledged_at?: string;
+}
+/**
+ * Recompute per-entry counters deterministically from the immutable event log,
+ * optionally folding in legacy `knowledge-application.jsonl` records.
+ *
+ * Determinism & double-counting: the ONLY outcome our code writes to both logs
+ * is "shown" — the injector emits both a legacy `recordKnowledgeShown` record
+ * AND a `retrieved` event for the same injection. Every other legacy verb
+ * (`applied`/`ignored`/`violated`/`acknowledged`) originates from `knowledge_ack`
+ * and has no event-log counterpart; the event-sourced equivalents come from the
+ * separate `knowledge_receipt` tool. So the race-free rule is:
+ *
+ *   - legacy `shown`: folded ONLY when the event log contains no `retrieved`
+ *     event (i.e. a pure pre-migration install). Once any `retrieved` event
+ *     exists, `shown_count` is derived from events alone, eliminating the
+ *     timestamp-race double-count.
+ *   - legacy non-`shown` verbs: always folded (no event counterpart, so no
+ *     double count), preserving pre-migration history.
+ *
+ * The result depends only on the input arrays, not on wall-clock time or order.
+ *
+ * @param events Events from {@link readKnowledgeEvents}.
+ * @param legacyRecords Optional legacy application records (any order).
+ */
+export declare function recomputeCounters(events: KnowledgeEvent[], legacyRecords?: KnowledgeApplicationRecord[]): Map<string, CounterRollup>;
+export declare const _internals: {
+    resolveKnowledgeEventsPath: typeof resolveKnowledgeEventsPath;
+    appendKnowledgeEvent: typeof appendKnowledgeEvent;
+    recordKnowledgeEvent: typeof recordKnowledgeEvent;
+    readKnowledgeEvents: typeof readKnowledgeEvents;
+    recomputeCounters: typeof recomputeCounters;
+    newTraceId: typeof newTraceId;
+    newEventId: typeof newEventId;
+};

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

@@ -18,7 +18,9 @@ export interface RankedEntry extends KnowledgeEntryBase {
     };
     finalScore: number;
 }
-export declare function readMergedKnowledge(directory: string, config: KnowledgeConfig, context?: ProjectContext): Promise<RankedEntry[]>;
+export declare function readMergedKnowledge(directory: string, config: KnowledgeConfig, context?: ProjectContext, opts?: {
+    skipScopeFilter?: boolean;
+}): Promise<RankedEntry[]>;
 export declare function updateRetrievalOutcome(directory: string, phaseInfo: string, phaseSucceeded: boolean): Promise<void>;
 /** Returns 0..1 score representing trigger/action match strength against the context. */
 export declare function scoreDirectiveAgainstContext(entry: KnowledgeEntryBase, ctx: KnowledgeRetrievalContext): {
@@ -27,17 +29,8 @@ export declare function scoreDirectiveAgainstContext(entry: KnowledgeEntryBase,
     agentHit: boolean;
     score: number;
 };
-/**
- * v2: Action-aware retrieval. Returns RankedEntry[] but uses the richer
- * KnowledgeRetrievalContext to bias ranking toward entries whose triggers,
- * applies_to_tools, applies_to_agents, or directive_priority match the
- * current decision point. Falls back to readMergedKnowledge ordering for
- * non-matching entries.
- */
-export declare function readContextualKnowledge(directory: string, config: KnowledgeConfig, ctx: KnowledgeRetrievalContext): Promise<RankedEntry[]>;
 export declare const _internals: {
     readMergedKnowledge: typeof readMergedKnowledge;
-    readContextualKnowledge: typeof readContextualKnowledge;
     updateRetrievalOutcome: typeof updateRetrievalOutcome;
     scoreDirectiveAgainstContext: typeof scoreDirectiveAgainstContext;
 };

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

@@ -1,5 +1,5 @@
 /** Core storage layer for the opencode-swarm v6.17 two-tier knowledge system. */
-import type { KnowledgeEntryBase, RejectedLesson } from './knowledge-types.js';
+import type { KnowledgeEntryBase, RejectedLesson, RetrievalOutcome } from './knowledge-types.js';
 export declare function getPlatformConfigDir(): string;
 export declare function resolveSwarmKnowledgePath(directory: string): string;
 export declare function resolveSwarmRejectedPath(directory: string): string;
@@ -40,6 +40,8 @@ export declare function findNearDuplicate<T extends {
     lesson: string;
 }>(candidate: string, entries: T[], threshold?: number): T | undefined;
 export declare function computeConfidence(confirmedByCount: number, autoGenerated: boolean): number;
+export declare const OUTCOME_SIGNAL_SMOOTHING = 4;
+export declare function computeOutcomeSignal(outcomes?: RetrievalOutcome): number;
 export declare function inferTags(lesson: string): string[];
 /**
  * Batch-update confidence scores on knowledge entries identified by their UUIDs.
@@ -80,6 +82,7 @@ export declare const _internals: {
     jaccardBigram: typeof jaccardBigram;
     findNearDuplicate: typeof findNearDuplicate;
     computeConfidence: typeof computeConfidence;
+    computeOutcomeSignal: typeof computeOutcomeSignal;
     inferTags: typeof inferTags;
     bumpKnowledgeConfidenceBatch: typeof bumpKnowledgeConfidenceBatch;
 };

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

@@ -37,6 +37,8 @@ export interface RetrievalOutcome {
     ignored_count?: number;
     /** v2: explicit/inferred violation count (KNOWLEDGE_VIOLATED: id reason=...). */
     violated_count?: number;
+    /** v3: explicit contradiction count (entry contradicted by current evidence). */
+    contradicted_count?: number;
     /** v2: phase-success count after a "shown" (replaces succeeded_after_count). */
     succeeded_after_shown_count?: number;
     /** v2: phase-failure count after a "shown" (replaces failed_after_count). */

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

@@ -0,0 +1,74 @@
+/**
+ * Unified knowledge retrieval service.
+ *
+ * This is the single core through which BOTH manual recall (`knowledge_recall`)
+ * and automatic injection (the phase-start injector) retrieve knowledge. It
+ * replaces the former split between Jaccard-only manual recall and the
+ * metadata-only action-aware injection ranker with one hybrid algorithm:
+ *
+ *   finalScore = TEXT_WEIGHT  * textScore        (Jaccard query↔lesson)
+ *              + META_WEIGHT  * metadataScore     (phase/confidence/keywords)
+ *              + directiveScore                   (trigger/action/agent/priority)
+ *              + boosts (status, generated-skill)
+ *
+ * Each signal degrades to 0 when its input is absent, so a query-only call
+ * (manual recall) is text-dominated while a context-only call (injection) is
+ * metadata/directive-dominated — without branching into two algorithms.
+ *
+ * Responsibilities (per the P0 plan):
+ *   load → normalize → filter archived/quarantined → dedup (hive wins) →
+ *   apply scope & agent-role constraints → hybrid score → rerank
+ *   (critical force-include) → emit a `retrieved` event → return trace_id.
+ */
+import { type RetrievalEventMode } from './knowledge-events.js';
+import { type RankedEntry } from './knowledge-reader.js';
+import type { KnowledgeConfig, KnowledgeRetrievalContext } from './knowledge-types.js';
+export interface SearchKnowledgeParams {
+    directory: string;
+    config: KnowledgeConfig;
+    /** Free-text query (manual recall). */
+    query?: string;
+    /** Action-aware decision-point context (injection / context packs). */
+    context?: KnowledgeRetrievalContext;
+    /** Retrieval mode — recorded on the emitted event. */
+    mode: RetrievalEventMode;
+    /** Agent role doing the retrieval (used for role scoping + the event). */
+    agent?: string;
+    /** Session id for the emitted event. */
+    sessionId?: string;
+    /** Tier filter. Default 'all'. */
+    tier?: 'all' | 'swarm' | 'hive';
+    /** Max results to return. Falls back to config.max_inject_count. */
+    maxResults?: number;
+    /** Emit a `retrieved` event (default true). */
+    emitEvent?: boolean;
+    /**
+     * Apply config.scope_filter (default true). Manual recall passes false so an
+     * explicit query can surface non-global-scoped lessons.
+     */
+    applyScopeFilter?: boolean;
+    /**
+     * Read the hive tier regardless of config.hive_enabled (default false).
+     * Manual recall passes true so `hive_enabled:false` (an injection knob) does
+     * not also hide hive entries from explicit queries.
+     */
+    forceReadHive?: boolean;
+    /**
+     * Apply agent-role scoping via applies_to_agents (default true). Manual recall
+     * passes false so an explicit query is not silently role-gated.
+     */
+    applyRoleScope?: boolean;
+}
+export interface SearchKnowledgeResult {
+    trace_id: string;
+    results: RankedEntry[];
+}
+/**
+ * Run unified knowledge retrieval. Returns a trace_id (always minted, even when
+ * no entries match) and the ranked results. Reading/scoring failures degrade to
+ * an empty result set; the event emission is fail-open.
+ */
+export declare function searchKnowledge(params: SearchKnowledgeParams): Promise<SearchKnowledgeResult>;
+export declare const _internals: {
+    searchKnowledge: typeof searchKnowledge;
+};