opencode-swarm 7.20.2 → 7.21.1

package/dist/cli/index.js

@@ -34,7 +34,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "opencode-swarm",
-    version: "7.20.2",
+    version: "7.21.1",
     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",

package/dist/hooks/skill-propagation-gate.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Skill propagation gate — warns when the architect delegates to a
+ * skill-capable agent without providing a SKILLS field.
+ *
+ * Two integration points:
+ *
+ *   1. `tool.execute.before` — when the architect delegates via the Task
+ *      tool to a skill-capable agent (coder, reviewer, test_engineer, sme,
+ *      docs, designer) and the SKILLS field is missing or "none" while
+ *      skills exist in the project, appends a warning event to
+ *      `.swarm/events.jsonl`. This is a SOFT WARNING — it NEVER blocks
+ *      tool execution. Also records skill delegation entries to
+ *      `.swarm/skill-usage.jsonl` for auditability.
+ *
+ *   2. `experimental.chat.messages.transform` — scans reviewer output
+ *      for SKILL_COMPLIANCE verdicts and records compliance outcomes
+ *      to `.swarm/skill-usage.jsonl`.
+ */
+import * as fs from 'node:fs';
+import type { MessageWithParts } from './knowledge-types.js';
+import { computeSkillRelevanceScore } from './skill-scoring.js';
+import { appendSkillUsageEntry, readSkillUsageEntries, readSkillUsageEntriesTail } from './skill-usage-log.js';
+/** Agents that should receive skill context in delegations. */
+export declare const SKILL_CAPABLE_AGENTS: Set<string>;
+/**
+ * Maximum number of session-scoped skill-usage entries to process for
+ * skill scoring. When a session accumulates more entries than this
+ * limit, scoring is skipped to prevent unbounded file reads from
+ * stalling every delegated Task call.
+ */
+export declare const MAX_SCORING_SESSION_ENTRIES = 500;
+export interface SkillGateInput {
+    tool: unknown;
+    agent?: unknown;
+    sessionID?: unknown;
+    args?: unknown;
+}
+export interface SkillPropagationConfig {
+    enabled: boolean;
+}
+export declare const _internals: {
+    readdirSync: typeof fs.readdirSync;
+    existsSync: typeof fs.existsSync;
+    statSync: typeof fs.statSync;
+    mkdirSync: typeof fs.mkdirSync;
+    appendFileSync: typeof fs.appendFileSync;
+    skillPropagationGateBefore: typeof skillPropagationGateBefore;
+    skillPropagationTransformScan: typeof skillPropagationTransformScan;
+    SKILL_CAPABLE_AGENTS: Set<string>;
+    MAX_SCORING_SESSION_ENTRIES: number;
+    writeWarnEvent: typeof writeWarnEvent;
+    discoverAvailableSkills: typeof discoverAvailableSkills;
+    parseDelegationArgs: typeof parseDelegationArgs;
+    appendSkillUsageEntry: typeof appendSkillUsageEntry;
+    readSkillUsageEntries: typeof readSkillUsageEntries;
+    readSkillUsageEntriesTail: typeof readSkillUsageEntriesTail;
+    parseSkillPaths: typeof parseSkillPaths;
+    extractTaskIdFromPrompt: typeof extractTaskIdFromPrompt;
+    computeSkillRelevanceScore: typeof computeSkillRelevanceScore;
+};
+/**
+ * Scans project for available skill SKILL.md files.
+ * Returns array of relative skill paths (e.g., '.claude/skills/writing-tests/SKILL.md').
+ * Best-effort: returns empty array on any error.
+ */
+export declare function discoverAvailableSkills(directory: string): string[];
+/**
+ * Parse delegation args to extract target agent name and SKILLS field.
+ * Returns { targetAgent, skillsField } or null if not parseable.
+ *
+ * The args for Task tool are a JSON object with a "subagent_type" field
+ * (e.g., "mega_coder") which is the authoritative target agent name, and
+ * a "prompt" field containing the delegation text. The SKILLS: line from
+ * the prompt (if present) provides the skills field value.
+ */
+export declare function parseDelegationArgs(args: unknown): {
+    targetAgent: string;
+    skillsField: string;
+} | null;
+/** Write a warning event to .swarm/events.jsonl (sync, best-effort). */
+export declare function writeWarnEvent(directory: string, record: Record<string, unknown>): void;
+/**
+ * Parse a SKILLS or SKILLS_USED_BY_CODER field value into individual skill paths.
+ * Handles comma-separated paths and strips surrounding whitespace.
+ * Returns empty array for empty, "none", or unparseable values.
+ */
+export declare function parseSkillPaths(fieldValue: string): string[];
+/**
+ * Extract a task ID from a delegation prompt string.
+ * Looks for patterns like "taskId: <id>" or "TASK: <id>" (case-insensitive).
+ * Returns "unknown" when no pattern is found.
+ */
+export declare function extractTaskIdFromPrompt(prompt: string): string;
+/**
+ * Pre-tool gate. When the architect delegates via Task tool to a skill-capable
+ * agent and the SKILLS field is missing or 'none' while skills exist in the
+ * project, logs a warning event to events.jsonl. NEVER blocks execution.
+ *
+ * Also records skill delegation entries to `.swarm/skill-usage.jsonl` when
+ * the architect delegates to a skill-capable agent with a non-empty, non-"none"
+ * SKILLS field.
+ */
+export declare function skillPropagationGateBefore(directory: string, input: SkillGateInput, config: SkillPropagationConfig): Promise<void>;
+/**
+ * Chat messages transform hook. Scans reviewer output for SKILL_COMPLIANCE
+ * verdicts and records compliance outcomes to `.swarm/skill-usage.jsonl`.
+ * Also scans architect messages for skill delegation patterns.
+ *
+ * Best-effort: never throws; never mutates the messages array.
+ */
+export declare function skillPropagationTransformScan(directory: string, output: {
+    messages?: MessageWithParts[];
+}, sessionID?: string): Promise<void>;

package/dist/hooks/skill-scoring.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Skill scoring — computes skill relevance scores based on historical
+ * usage data from `.swarm/skill-usage.jsonl`.
+ *
+ * All public functions are pure over their inputs. File I/O goes through
+ * `readSkillUsageEntries` (imported from `skill-usage-log.ts`).
+ * An `_internals` DI seam mirrors the pattern in `skill-usage-log.ts`
+ * and `skill-propagation-gate.ts` for testability.
+ */
+import { type SkillUsageEntry } from './skill-usage-log.js';
+/** Per-skill ranking entry returned by `rankSkillsForContext`. */
+export interface SkillRankEntry {
+    /** Repo-relative path to the skill file. */
+    skillPath: string;
+    /** Composite relevance score in [0, 1]. */
+    score: number;
+    /** Total number of recorded usages for this skill. */
+    usageCount: number;
+    /** Ratio of compliant verdicts to total verdicts in [0, 1]. */
+    complianceRate: number;
+}
+/** Aggregate statistics for a single skill. */
+export interface SkillStats {
+    /** Total number of recorded usages. */
+    totalUsage: number;
+    /** Ratio of compliant verdicts to total verdicts in [0, 1]. */
+    complianceRate: number;
+    /** ISO 8601 timestamp of the most recent usage, or empty string. */
+    lastUsed: string;
+    /** Top agents by usage count, sorted descending. */
+    topAgents: Array<{
+        agent: string;
+        count: number;
+    }>;
+}
+export declare const _internals: {
+    computeSkillRelevanceScore: typeof computeSkillRelevanceScore;
+    rankSkillsForContext: typeof rankSkillsForContext;
+    getSkillStats: typeof getSkillStats;
+    formatSkillIndexWithContext: typeof formatSkillIndexWithContext;
+    extractSkillName: typeof extractSkillName;
+    computeRecencyScore: typeof computeRecencyScore;
+    computeContextMatchScore: typeof computeContextMatchScore;
+};
+/**
+ * Extracts a human-readable skill name from its file path.
+ * E.g. `.claude/skills/writing-tests/SKILL.md` → `writing-tests`
+ */
+declare function extractSkillName(skillPath: string): string;
+/**
+ * Computes a recency score in [0, 1] based on how recently the skill was used.
+ * Full score (1.0) for usage within 24 hours, linearly decaying to 0 over 30 days.
+ */
+declare function computeRecencyScore(lastUsedTimestamp: string): number;
+/**
+ * Computes a keyword-overlap context match score between a task description and a skill.
+ *
+ * Extracts keywords from both the task description and the skill's path + name,
+ * then returns the ratio of matching keywords to the total task keywords.
+ * Returns 0 when the task description has no extractable keywords.
+ *
+ * @param taskDescription - Free-text description of the current task.
+ * @param skillPath       - Repo-relative path to the skill file.
+ * @returns Context match score in [0, 1].
+ */
+declare function computeContextMatchScore(taskDescription: string, skillPath: string): number;
+/**
+ * Compute a composite relevance score for a skill based on its usage history
+ * and keyword overlap with the task description.
+ *
+ * Spec compliance: FR-002 requires scoring "based on historical usage data using the skill
+ * usage log and task descriptions." This function uses the usage log (frequency, compliance,
+ * recency, taskID diversity) and the current task description (keyword overlap with skill
+ * name/path) to produce context-aware rankings.
+ *
+ * Formula (all components clamped to [0, 1]):
+ *   frequencyScore    = min(1.0, usageCount / FREQUENCY_CAP) * FREQUENCY_WEIGHT
+ *   complianceScore   = (compliantCount / max(1, totalWithVerdict)) * COMPLIANCE_WEIGHT
+ *   recencyScore      = linearDecay(lastUsed) * RECENCY_WEIGHT
+ *   taskDiversityScore = (distinctTaskIDs / max(1, usageHistory.length)) * TASK_DIVERSITY_WEIGHT
+ *   contextScore      = keywordOverlap(taskDescription, skillPath) * CONTEXT_WEIGHT
+ *   total             = frequencyScore + complianceScore + recencyScore + taskDiversityScore + contextScore
+ *
+ * The context component ensures different task descriptions produce different
+ * rankings: keywords from the task description are matched against the skill's
+ * file path and name via simple set intersection.
+ *
+ * @param skillPath        - Repo-relative path to the skill file.
+ * @param taskDescription  - Free-text description of the current task.
+ * @param usageHistory     - Pre-loaded usage entries for this skill.
+ * @returns Composite score in [0, 1]. Returns contextScore only when history is empty.
+ */
+export declare function computeSkillRelevanceScore(skillPath: string, taskDescription: string, usageHistory: SkillUsageEntry[]): number;
+/**
+ * Rank an array of skill paths by relevance to a task context.
+ *
+ * Reads `.swarm/skill-usage.jsonl` for historical data, computes composite
+ * scores for each skill, and returns entries sorted by score descending.
+ *
+ * @param skills      - Array of repo-relative skill paths.
+ * @param taskContext  - Free-text description of the task.
+ * @param directory    - Project root directory (used to locate `.swarm/`).
+ * @returns Sorted array of `SkillRankEntry`, highest score first.
+ */
+export declare function rankSkillsForContext(skills: string[], taskContext: string, directory: string): SkillRankEntry[];
+/**
+ * Read usage log and compute aggregate statistics for a single skill.
+ *
+ * @param skillPath - Repo-relative path to the skill file.
+ * @param directory - Project root directory.
+ * @returns `SkillStats` with aggregate metrics. Returns zeros/empty when log is missing.
+ */
+export declare function getSkillStats(skillPath: string, directory: string): SkillStats;
+/**
+ * Produce a formatted skill index string with contextual usage stats.
+ *
+ * Each line looks like:
+ *   `engineering-conventions: Engineering invariants (used: 12, compliance: 95%) → coder, reviewer`
+ *
+ * Falls back to a simple index without stats if the usage log does not exist.
+ *
+ * @param skills    - Array of repo-relative skill paths.
+ * @param directory - Project root directory.
+ * @returns Multi-line formatted string, one line per skill.
+ */
+export declare function formatSkillIndexWithContext(skills: string[], directory: string): string;
+export {};

package/dist/hooks/skill-usage-log.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Skill usage log — tracks skill delegations and compliance outcomes.
+ *
+ * Writes one JSONL line per skill-usage event to `.swarm/skill-usage.jsonl`.
+ * Follows the same append-only JSONL pattern as knowledge-application.jsonl.
+ */
+import * as fs from 'node:fs';
+/** Single entry in the skill-usage audit log. */
+export interface SkillUsageEntry {
+    /** Auto-generated unique identifier (UUID v4). */
+    id: string;
+    /** Repo-relative path to the skill file. */
+    skillPath: string;
+    /** Name of the agent receiving the skill. */
+    agentName: string;
+    /** Plan task ID the skill was loaded for. */
+    taskID: string;
+    /** ISO 8601 timestamp of the event. */
+    timestamp: string;
+    /** Compliance outcome — 'compliant' | 'violation' | 'partial' | 'not_checked' | custom. */
+    complianceVerdict: string;
+    /** Optional free-text notes from the reviewer. */
+    reviewerNotes?: string;
+    /** Session identifier. */
+    sessionID: string;
+}
+/** Filter options for reading skill-usage entries. */
+export interface SkillUsageFilterOptions {
+    /** Filter entries by session ID (exact match). */
+    sessionID?: string;
+    /** Filter entries by skill path (exact match). */
+    skillPath?: string;
+    /** Filter entries by agent name (exact match). */
+    agentName?: string;
+    /** Filter entries by plan task ID (exact match). */
+    taskID?: string;
+    /** Filter entries to timestamps within this ISO 8601 range (inclusive). */
+    dateRange?: {
+        start: string;
+        end: string;
+    };
+}
+/** Return value from prune operations. */
+export interface PruneResult {
+    /** Number of entries removed. */
+    pruned: number;
+    /** Number of entries remaining in the log. */
+    remaining: number;
+    /** Error message when the write/rename step fails; absent on success. */
+    error?: string;
+}
+/**
+ * Test-only dependency-injection seam. Tests override these without
+ * `mock.module` (which leaks across files in Bun's shared test-runner).
+ * Restore in `afterEach`.
+ */
+export declare const _internals: {
+    generateId: () => string;
+    appendFileSync: typeof fs.appendFileSync;
+    readFileSync: typeof fs.readFileSync;
+    writeFileSync: typeof fs.writeFileSync;
+    renameSync: typeof fs.renameSync;
+    mkdirSync: typeof fs.mkdirSync;
+    existsSync: typeof fs.existsSync;
+    statSync: any;
+    openSync: typeof fs.openSync;
+    readSync: typeof fs.readSync;
+    closeSync: typeof fs.closeSync;
+};
+/**
+ * Validate and append a single skill-usage entry to the JSONL log.
+ *
+ * The `id` field is auto-generated; callers provide all other fields.
+ * Uses synchronous I/O for consistency with the JSONL append pattern.
+ */
+export declare function appendSkillUsageEntry(directory: string, entry: Omit<SkillUsageEntry, 'id'>): void;
+/**
+ * Read and parse skill-usage entries from the JSONL log, optionally filtered.
+ *
+ * Malformed lines are silently skipped (no throw). Returns an empty array
+ * if the log file does not exist.
+ */
+export declare function readSkillUsageEntries(directory: string, options?: SkillUsageFilterOptions): SkillUsageEntry[];
+/** Default maximum bytes to read from the end of the log file. */
+export declare const TAIL_BYTES_DEFAULT: number;
+/**
+ * Read the last `maxBytes` of the skill-usage JSONL log and parse matching
+ * entries. Much faster than `readSkillUsageEntries` for large logs because
+ * it reads only a bounded number of bytes from the end of the file instead
+ * of loading the entire file into memory.
+ *
+ * Uses low-level `openSync` / `readSync` / `closeSync` to seek to the last
+ * `maxBytes` of the file. Skips the first (potentially partial) line that
+ * results from starting mid-file. Best-effort: returns an empty array on any
+ * I/O or parse error.
+ */
+export declare function readSkillUsageEntriesTail(directory: string, filters: {
+    sessionID?: string;
+}, maxBytes?: number): SkillUsageEntry[];
+/**
+ * Prune the skill-usage log, keeping at most `maxEntriesPerSkill` entries
+ * per unique skillPath. Oldest entries beyond the limit are removed.
+ *
+ * Writes atomically (temp file + rename). No-op if the log file doesn't
+ * exist or all skills are within their limits.
+ *
+ * @returns Stats about how many entries were pruned and how many remain.
+ */
+export declare function pruneSkillUsageLog(directory: string, maxEntriesPerSkill?: number): PruneResult;