opencode-swarm 7.10.0 → 7.11.1

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

@@ -0,0 +1,103 @@
+/**
+ * Knowledge application tracking — distinguishes shown / acknowledged / applied
+ * / ignored / violated outcomes for injected knowledge directives.
+ *
+ * Writes one JSONL line per outcome to `.swarm/knowledge-application.jsonl`,
+ * and updates per-entry retrieval-outcome counters on the source knowledge file.
+ */
+import type { KnowledgeApplicationResult } from './knowledge-types.js';
+export declare function resolveApplicationLogPath(directory: string): string;
+/**
+ * Parse explicit knowledge-acknowledgment markers from architect text.
+ * Recognised forms (case-insensitive, line-anchored or inline):
+ *   KNOWLEDGE_APPLIED: <id>
+ *   KNOWLEDGE_IGNORED: <id> reason=<reason>
+ *   KNOWLEDGE_VIOLATED: <id> reason=<reason>
+ */
+export interface ParsedAcknowledgment {
+    id: string;
+    result: 'applied' | 'ignored' | 'violated';
+    reason?: string;
+}
+export declare function parseAcknowledgments(text: string): ParsedAcknowledgment[];
+export interface RecordContext {
+    phase?: string;
+    taskId?: string;
+    action?: string;
+    tool?: string;
+    targetAgent?: string;
+    sessionId?: string;
+}
+/** Record one or more knowledge IDs as "shown" (injected into context). */
+export declare function recordKnowledgeShown(directory: string, ids: string[], ctx: RecordContext): Promise<void>;
+/** Record an explicit acknowledgment outcome (applied / ignored / violated).
+ *  Per-(sessionId, knowledgeId, result, dayKey) dedup is enforced by the
+ *  caller via swarmState.knowledgeAckDedup; this fn always records when
+ *  invoked, so test code can trigger duplicates if needed. The runtime
+ *  integration in src/index.ts uses recordAcknowledgmentDeduped instead. */
+export declare function recordAcknowledgment(directory: string, ack: ParsedAcknowledgment, ctx: RecordContext): Promise<void>;
+/** Build the dedup key. Exported so test code and the runtime integration
+ *  share the exact format. */
+export declare function buildAckDedupKey(sessionId: string, id: string, result: KnowledgeApplicationResult, now?: Date): string;
+/** Acknowledgment recording with dedup. Returns whether a record was actually
+ *  written (false on dedup hit). dedupSet should be swarmState.knowledgeAckDedup
+ *  in production; tests can pass a fresh Set. */
+export declare function recordAcknowledgmentDeduped(directory: string, ack: ParsedAcknowledgment, ctx: RecordContext, dedupSet: Set<string>, now?: Date): Promise<boolean>;
+/**
+ * Process a chunk of architect text: extract any KNOWLEDGE_* markers and record
+ * each as an outcome. Returns the parsed list (empty if none).
+ */
+export declare function processArchitectText(directory: string, text: string, ctx: RecordContext): Promise<ParsedAcknowledgment[]>;
+export interface ShownNotAppliedQuery {
+    taskId?: string;
+    phase?: string;
+    knowledgeIds: string[];
+}
+/**
+ * Returns the subset of `knowledgeIds` that have at least one "shown" record
+ * in the audit log without a subsequent "applied"/"ignored"/"violated" record
+ * in the same task or phase scope.
+ */
+export declare function getShownButNotAcknowledged(directory: string, q: ShownNotAppliedQuery): Promise<string[]>;
+export interface KnowledgeApplicationConfig {
+    enabled: boolean;
+    mode: 'warn' | 'enforce';
+    min_confidence: number;
+    critical_requires_ack: boolean;
+    require_skill_refs: boolean;
+}
+export declare const DEFAULT_KNOWLEDGE_APPLICATION_CONFIG: KnowledgeApplicationConfig;
+export interface GateResult {
+    allowed: boolean;
+    mode: 'warn' | 'enforce';
+    violations: Array<{
+        id: string;
+        reason: string;
+    }>;
+    warnings: Array<{
+        id: string;
+        reason: string;
+    }>;
+}
+/**
+ * Enforce the knowledge-application contract before a high-risk action.
+ * In 'warn' mode: never blocks; returns { allowed: true } with warnings.
+ * In 'enforce' mode: returns { allowed: false } if any critical+matching
+ * directive is in `criticalShownIds` and not present in `recentArchitectText`.
+ */
+export declare function gateKnowledgeApplication(args: {
+    criticalShownIds: string[];
+    recentArchitectText: string;
+    config: KnowledgeApplicationConfig;
+}): GateResult;
+export declare const _internals: {
+    parseAcknowledgments: typeof parseAcknowledgments;
+    recordKnowledgeShown: typeof recordKnowledgeShown;
+    recordAcknowledgment: typeof recordAcknowledgment;
+    recordAcknowledgmentDeduped: typeof recordAcknowledgmentDeduped;
+    processArchitectText: typeof processArchitectText;
+    getShownButNotAcknowledged: typeof getShownButNotAcknowledged;
+    gateKnowledgeApplication: typeof gateKnowledgeApplication;
+    resolveApplicationLogPath: typeof resolveApplicationLogPath;
+    buildAckDedupKey: typeof buildAckDedupKey;
+};

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

@@ -2,7 +2,7 @@
  * Merges swarm + hive knowledge, deduplicates (hive wins), ranks by composite score,
  * and provides utility tracking.
  */
-import type { KnowledgeConfig, KnowledgeEntryBase } from './knowledge-types.js';
+import type { KnowledgeConfig, KnowledgeEntryBase, KnowledgeRetrievalContext } from './knowledge-types.js';
 export interface ProjectContext {
     projectName: string;
     currentPhase: string;
@@ -20,7 +20,24 @@ export interface RankedEntry extends KnowledgeEntryBase {
 }
 export declare function readMergedKnowledge(directory: string, config: KnowledgeConfig, context?: ProjectContext): 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): {
+    triggerHit: boolean;
+    actionHit: boolean;
+    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

@@ -6,6 +6,7 @@ export declare function resolveSwarmRejectedPath(directory: string): string;
 export declare function resolveHiveKnowledgePath(): string;
 export declare function resolveHiveRejectedPath(): string;
 export declare function readKnowledge<T>(filePath: string): Promise<T[]>;
+export declare function normalizeEntry<T>(raw: T): T;
 export declare function readRejectedLessons(directory: string): Promise<RejectedLesson[]>;
 export declare function appendKnowledge<T>(filePath: string, entry: T): Promise<void>;
 export declare function rewriteKnowledge<T>(filePath: string, entries: T[]): Promise<void>;

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

@@ -11,12 +11,69 @@ export interface ProjectConfirmationRecord {
     phase_number?: number;
 }
 export interface RetrievalOutcome {
+    /** @deprecated v1 LEGACY field — frozen in v2.
+     *  v1 callers incremented this for every "shown" event (i.e. it conflated
+     *  shown with applied). v2 stops auto-incrementing it. Existing v1 entries
+     *  still load their historical value; the v1→v2 normalizer copies it into
+     *  `shown_count` so downstream consumers can keep working. New code MUST
+     *  read `applied_explicit_count` for explicit application or
+     *  `succeeded_after_shown_count` / `failed_after_shown_count` for outcome
+     *  attribution. */
     applied_count: number;
+    /** @deprecated v1 LEGACY: succeeded_after_count was bumped after
+     *  applied_count. Frozen in v2; new equivalent is succeeded_after_shown_count. */
     succeeded_after_count: number;
+    /** @deprecated v1 LEGACY: failed_after_count was bumped after
+     *  applied_count. Frozen in v2; new equivalent is failed_after_shown_count. */
     failed_after_count: number;
     last_applied_at?: string;
+    /** v2: number of times this entry was injected/shown to architect. */
+    shown_count?: number;
+    /** v2: explicit acknowledgment ("I see directive X") count. */
+    acknowledged_count?: number;
+    /** v2: explicit application count (KNOWLEDGE_APPLIED: id). */
+    applied_explicit_count?: number;
+    /** v2: explicit ignore count (KNOWLEDGE_IGNORED: id reason=...). */
+    ignored_count?: number;
+    /** v2: explicit/inferred violation count (KNOWLEDGE_VIOLATED: id reason=...). */
+    violated_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). */
+    failed_after_shown_count?: number;
 }
-export interface KnowledgeEntryBase {
+/** v2: priority used by retrieval ranking and enforcement. */
+export type DirectivePriority = 'low' | 'medium' | 'high' | 'critical';
+/** v2: optional actionable-directive metadata attached to a knowledge entry. */
+export interface ActionableDirectiveFields {
+    /** Trigger phrases that surface this entry (e.g. "coder delegation modifying source"). */
+    triggers?: string[];
+    /** Required actions when the trigger matches. */
+    required_actions?: string[];
+    /** Forbidden actions when the trigger matches. */
+    forbidden_actions?: string[];
+    /** Agent role names this directive applies to. */
+    applies_to_agents?: string[];
+    /** Tool names this directive applies to. */
+    applies_to_tools?: string[];
+    /** Reviewer/test-engineer/runtime checks the directive expects. */
+    verification_checks?: string[];
+    /** Source pointers (file:line, plan section, etc.). Sanitized. */
+    source_refs?: string[];
+    /** UUIDs of source knowledge entries (for derived/clustered entries). */
+    source_knowledge_ids?: string[];
+    /** Slug of generated skill, if a SKILL.md was compiled from this entry. */
+    generated_skill_slug?: string;
+    /** Repo-local path to generated SKILL.md. */
+    generated_skill_path?: string;
+    /** Directive priority for ranking/enforcement. */
+    directive_priority?: DirectivePriority;
+    /** ISO 8601 timestamp of last explicit application. */
+    last_applied_at?: string;
+    /** ISO 8601 timestamp of last explicit acknowledgment. */
+    last_acknowledged_at?: string;
+}
+export interface KnowledgeEntryBase extends ActionableDirectiveFields {
     id: string;
     tier: 'swarm' | 'hive';
     lesson: string;
@@ -35,6 +92,8 @@ export interface KnowledgeEntryBase {
     phases_alive?: number;
     max_phases?: number;
 }
+/** v2 schema marker. v1 entries are still parseable and normalized in-memory by knowledge-store.normalizeEntry. */
+export declare const KNOWLEDGE_SCHEMA_VERSION = 2;
 export interface SwarmKnowledgeEntry extends KnowledgeEntryBase {
     tier: 'swarm';
     confirmed_by: PhaseConfirmationRecord[];
@@ -129,3 +188,39 @@ export interface MessageWithParts {
     info: MessageInfo;
     parts: MessagePart[];
 }
+export type RetrievalMode = 'phase_start' | 'delegation' | 'tool_before' | 'phase_complete' | 'manual_recall' | 'curator';
+/** Decision-point context passed to action-aware retrieval. */
+export interface KnowledgeRetrievalContext {
+    projectName?: string;
+    currentPhase?: string;
+    taskId?: string;
+    taskTitle?: string;
+    taskDescription?: string;
+    lastUserMessage?: string;
+    currentTool?: string;
+    currentAction?: string;
+    targetAgent?: string;
+    filePaths?: string[];
+    recentReviewerFailures?: string[];
+    recentTestFailures?: string[];
+    recentToolErrors?: string[];
+    declaredScope?: string;
+    techStack?: string[];
+    planConstraints?: string[];
+    mode?: RetrievalMode;
+}
+export type KnowledgeApplicationResult = 'shown' | 'acknowledged' | 'applied' | 'ignored' | 'violated';
+/** One line of .swarm/knowledge-application.jsonl. */
+export interface KnowledgeApplicationRecord {
+    timestamp: string;
+    phase?: string;
+    taskId?: string;
+    action?: string;
+    tool?: string;
+    targetAgent?: string;
+    knowledgeId: string;
+    result: KnowledgeApplicationResult;
+    reason?: string;
+    generatedSkillPath?: string;
+    sessionId?: string;
+}

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

@@ -1,5 +1,5 @@
 /** Three-layer validation gate for the opencode-swarm v6.17 knowledge system. */
-import type { KnowledgeCategory, KnowledgeEntryBase } from './knowledge-types.js';
+import type { ActionableDirectiveFields, DirectivePriority, KnowledgeCategory, KnowledgeEntryBase } from './knowledge-types.js';
 export interface ValidationResult {
     valid: boolean;
     layer: 1 | 2 | 3 | null;
@@ -15,6 +15,21 @@ export declare function validateLesson(candidate: string, existingLessons: strin
     scope: string;
     confidence: number;
 }): ValidationResult;
+/** Maximum chars allowed per trigger / required-action / forbidden-action string. */
+export declare const ACTIONABLE_STRING_MAX = 200;
+/** Maximum number of items in any actionable list (triggers, required_actions, etc.). */
+export declare const ACTIONABLE_LIST_MAX = 20;
+/** Generated skill paths must be repo-local under one of these prefixes. */
+export declare const ALLOWED_SKILL_PATH_PREFIXES: string[];
+export interface ActionableValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/** Validate a generated_skill_path: must be repo-local and under an allowed prefix. */
+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 QuarantinedEntry extends KnowledgeEntryBase {
     quarantine_reason: string;
     quarantined_at: string;

package/dist/hooks/skill-improver-llm-factory.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Skill-improver LLM delegate factory.
+ *
+ * Mirrors src/hooks/curator-llm-factory.ts so the skill_improver agent can be
+ * dispatched via the same ephemeral-session-per-call pattern. Returns
+ * `undefined` when `swarmState.opencodeClient` is null (e.g. in unit tests),
+ * letting the caller fall back to deterministic mode behind an opt-in flag.
+ *
+ * Resolution priority for the registered agent name follows the curator
+ * factory exactly: direct lookup via active session → heuristic scan → static
+ * fallback. The `mode` parameter is reserved for future role variants (e.g.
+ * "review_only" vs "draft_skills"); today both modes resolve to the same
+ * `skill_improver` agent.
+ */
+export type SkillImproverLLMDelegate = (systemPrompt: string, userInput: string, signal?: AbortSignal) => Promise<string>;
+declare function resolveSkillImproverAgentName(sessionId?: string): string;
+/**
+ * Create a SkillImproverLLMDelegate that dispatches the registered
+ * skill_improver agent on an ephemeral OpenCode session.
+ *
+ * Returns `undefined` when no OpenCode client is wired (unit tests, library
+ * mode). Callers MUST handle that case explicitly: if the deterministic
+ * fallback is disabled, refuse the run BEFORE reserving any quota.
+ */
+export declare function createSkillImproverLLMDelegate(directory: string, sessionId?: string): SkillImproverLLMDelegate | undefined;
+export declare const _internals: {
+    createSkillImproverLLMDelegate: typeof createSkillImproverLLMDelegate;
+    resolveSkillImproverAgentName: typeof resolveSkillImproverAgentName;
+};
+export {};