opencode-swarm 7.9.0 → 7.11.0

package/dist/plan/manager.d.ts

@@ -97,6 +97,19 @@ export declare function updateTaskStatus(directory: string, taskId: string, stat
  * Ensures stable ordering: phases by ID (ascending), tasks by ID (natural numeric).
  */
 export declare function derivePlanMarkdown(plan: Plan): string;
+/**
+ * Return the id of the current task within the plan's current phase, or
+ * undefined if no incomplete task can be identified. PURE function — no I/O.
+ *
+ * Resolution: among tasks of the current phase, pick the first
+ * in_progress task; otherwise the first non-completed task; otherwise
+ * undefined (between phases / phase exhausted).
+ *
+ * Used by the v2 knowledge-injector to populate `taskId` in the retrieval
+ * context so action-aware ranking and shown-set keying can scope to a
+ * specific task.
+ */
+export declare function getCurrentTaskId(plan: Plan | null | undefined): string | undefined;
 /**
  * Convert existing plan.md to plan.json. PURE function — no I/O.
  */

package/dist/services/skill-generator.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Knowledge-to-skill compiler.
+ *
+ * Selects mature, high-confidence knowledge entries (with optional actionable
+ * directive metadata), clusters them, and emits SKILL.md files either as draft
+ * proposals (.swarm/skills/proposals/<slug>.md) or active generated skills
+ * (.opencode/skills/generated/<slug>/SKILL.md).
+ *
+ * Safety:
+ *   - slug sanitizer rejects path traversal / control chars / absolute paths
+ *   - active mode never overwrites a manually edited skill unless force=true
+ *   - generated files always carry an explicit "<!-- generated -->" header
+ *   - file writes are atomic (write to .tmp, rename)
+ */
+import type { KnowledgeEntryBase } from '../hooks/knowledge-types.js';
+export declare function sanitizeSlug(input: string): string;
+export declare function isValidSlug(slug: string): boolean;
+export declare function proposalPath(directory: string, slug: string): string;
+export declare function activePath(directory: string, slug: string): string;
+/** Repo-relative path used inside SKILLS: file: references and entry metadata. */
+export declare function activeRepoRelativePath(slug: string): string;
+export interface CandidateSelectionOptions {
+    minConfidence: number;
+    minConfirmations: number;
+}
+export interface KnowledgeCluster {
+    slug: string;
+    title: string;
+    entries: KnowledgeEntryBase[];
+    triggers: string[];
+    required_actions: string[];
+    forbidden_actions: string[];
+    target_agents: string[];
+    verification_checks: string[];
+    avgConfidence: number;
+}
+export declare function selectCandidateEntries(directory: string, opts: CandidateSelectionOptions): Promise<KnowledgeEntryBase[]>;
+export declare function clusterEntries(entries: KnowledgeEntryBase[]): KnowledgeCluster[];
+export declare function renderSkillMarkdown(cluster: KnowledgeCluster, mode?: GenerateMode): string;
+export type GenerateMode = 'draft' | 'active';
+export interface GenerateRequest {
+    directory: string;
+    mode: GenerateMode;
+    slug?: string;
+    sourceKnowledgeIds?: string[];
+    force?: boolean;
+    minConfidence?: number;
+    minConfirmations?: number;
+}
+export interface GenerateResult {
+    written: Array<{
+        slug: string;
+        path: string;
+        mode: GenerateMode;
+        sourceKnowledgeIds: string[];
+        preserved: boolean;
+    }>;
+    skipped: Array<{
+        slug: string;
+        reason: string;
+    }>;
+}
+export declare function generateSkills(req: GenerateRequest): Promise<GenerateResult>;
+/**
+ * Stamp source knowledge entries with `generated_skill_slug` and
+ * `generated_skill_path` metadata. Refactored in Phase G′ to take
+ * `(directory, slug, ids)` so it can be called both from direct active-mode
+ * generation AND from `activateProposal` after parsing the draft frontmatter.
+ */
+declare function stampSourceEntries(directory: string, slug: string, ids: string[]): Promise<void>;
+/**
+ * Bounded YAML frontmatter parser for generated drafts. Recognises the exact
+ * shape we emit in renderSkillMarkdown — no full YAML lib required.
+ *
+ * Returns null when the document does not begin with a `---` frontmatter
+ * fence or the closing fence is missing.
+ */
+export declare function parseDraftFrontmatter(content: string): {
+    name?: string;
+    status?: string;
+    sourceKnowledgeIds: string[];
+} | null;
+export declare function activateProposal(directory: string, slug: string, force?: boolean): Promise<{
+    activated: boolean;
+    from: string;
+    to: string;
+    reason?: string;
+    stamped?: boolean;
+    stampedIds?: string[];
+}>;
+export declare function listSkills(directory: string): Promise<{
+    proposals: Array<{
+        slug: string;
+        path: string;
+    }>;
+    active: Array<{
+        slug: string;
+        path: string;
+    }>;
+}>;
+export declare function inspectSkill(directory: string, slug: string, prefer?: 'auto' | 'proposal' | 'active'): Promise<{
+    found: boolean;
+    path?: string;
+    content?: string;
+    mode?: GenerateMode;
+}>;
+export declare const _internals: {
+    sanitizeSlug: typeof sanitizeSlug;
+    isValidSlug: typeof isValidSlug;
+    selectCandidateEntries: typeof selectCandidateEntries;
+    clusterEntries: typeof clusterEntries;
+    renderSkillMarkdown: typeof renderSkillMarkdown;
+    generateSkills: typeof generateSkills;
+    activateProposal: typeof activateProposal;
+    listSkills: typeof listSkills;
+    inspectSkill: typeof inspectSkill;
+    stampSourceEntries: typeof stampSourceEntries;
+    parseDraftFrontmatter: typeof parseDraftFrontmatter;
+};
+export {};

package/dist/services/skill-improver-quota.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Skill-improver daily-quota tracker.
+ *
+ * State file: .swarm/skill-improver-quota.json
+ * Counts every LLM-credentialed call by the skill_improver agent.
+ * The window is configurable: 'utc' (default) resets at 00:00 UTC; 'local'
+ * resets at the host's local midnight.
+ */
+export type QuotaWindow = 'utc' | 'local';
+export interface QuotaState {
+    /** YYYY-MM-DD in the chosen window */
+    date: string;
+    calls_used: number;
+    max_calls: number;
+    last_run_at?: string;
+    window: QuotaWindow;
+}
+export declare function resolveQuotaPath(directory: string): string;
+export declare function todayKey(window: QuotaWindow, now?: Date): string;
+export interface QuotaCheckOptions {
+    maxCalls: number;
+    window: QuotaWindow;
+    now?: Date;
+}
+export interface QuotaCheckResult {
+    allowed: boolean;
+    state: QuotaState;
+    reason?: string;
+}
+/** Read the quota state, rolling over the day if needed. Does not increment. */
+export declare function getQuotaState(directory: string, opts: QuotaCheckOptions): Promise<QuotaState>;
+/**
+ * Atomically reserve `nCalls` quota slots, holding a directory-level lockfile
+ * for the read-modify-write so parallel skill_improve invocations cannot
+ * lost-update each other. Returns { allowed: false } and leaves state
+ * unchanged if the reservation would exceed max_calls.
+ */
+export declare function reserveQuota(directory: string, opts: QuotaCheckOptions & {
+    nCalls: number;
+}): Promise<QuotaCheckResult>;
+/**
+ * Release `nCalls` previously-reserved quota slots. Floors at zero. Used by
+ * the skill_improver service when an LLM call fails BEFORE any network I/O
+ * (e.g. delegate construction error, no client wired). Once network I/O has
+ * begun, the slot stays consumed — see runSkillImprover for the policy.
+ */
+export declare function releaseQuota(directory: string, opts: QuotaCheckOptions & {
+    nCalls: number;
+}): Promise<QuotaState>;
+export declare const _internals: {
+    resolveQuotaPath: typeof resolveQuotaPath;
+    todayKey: typeof todayKey;
+    getQuotaState: typeof getQuotaState;
+    reserveQuota: typeof reserveQuota;
+    releaseQuota: typeof releaseQuota;
+    LOCK_ACQUIRE_TIMEOUT_MS: number;
+};

package/dist/services/skill-improver.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Skill-improver service — produces a proposal markdown reviewing accumulated
+ * knowledge, generated skills, the spec, and the architect prompt. When an
+ * LLM delegate is available the body is generated by the configured
+ * skill_improver agent (issue #629). When no delegate is wired and the
+ * `allow_deterministic_fallback` flag is true, a deterministic offline body
+ * is written, clearly tagged.
+ *
+ * Quota policy:
+ *   - Reservation happens BEFORE any network I/O.
+ *   - If the delegate is undefined and fallback is disabled, no quota is
+ *     reserved — we refuse early with `no_llm_client`.
+ *   - If the delegate construction itself fails before any network call
+ *     (extremely unlikely in practice), we release the quota.
+ *   - Once `client.session.prompt` has begun, the slot stays consumed even
+ *     on failure: a flaky model must not burn unbounded retries within a
+ *     window.
+ */
+import type { SwarmKnowledgeEntry } from '../hooks/knowledge-types.js';
+import { type SkillImproverLLMDelegate } from '../hooks/skill-improver-llm-factory.js';
+import { type QuotaWindow } from './skill-improver-quota.js';
+export interface SkillImproverConfigInput {
+    enabled: boolean;
+    model: string | null;
+    fallback_models: string[];
+    max_calls_per_day: number;
+    trigger: 'manual' | 'scheduled';
+    targets: Array<'skills' | 'spec' | 'architect_prompt' | 'knowledge'>;
+    write_mode: 'proposal' | 'draft_skills';
+    require_user_approval: boolean;
+    quota_window: QuotaWindow;
+    allow_deterministic_fallback: boolean;
+}
+export type SkillImproverTarget = 'skills' | 'spec' | 'architect_prompt' | 'knowledge';
+export interface SkillImproveRequest {
+    directory: string;
+    config: SkillImproverConfigInput;
+    targets?: SkillImproverTarget[];
+    mode?: 'proposal' | 'draft_skills';
+    maxCalls?: number;
+    now?: Date;
+    sessionId?: string;
+    /** Test-only seam: inject a delegate. When undefined, the service uses
+     *  createSkillImproverLLMDelegate(directory, sessionId) which returns
+     *  undefined unless swarmState.opencodeClient is wired. */
+    delegate?: SkillImproverLLMDelegate;
+}
+export interface SkillImproveResult {
+    ran: boolean;
+    reason?: string;
+    proposalPath?: string;
+    source?: 'llm' | 'deterministic_fallback';
+    quota: {
+        date: string;
+        calls_used: number;
+        max_calls: number;
+    };
+    draftSkillsWritten?: Array<{
+        slug: string;
+        path: string;
+        sourceKnowledgeIds: string[];
+    }>;
+    model?: string;
+}
+interface InventorySnapshot {
+    knowledge: {
+        swarm: number;
+        hive: number;
+        archived: number;
+    };
+    skills: {
+        proposals: number;
+        active: number;
+    };
+    highConfidenceClusters: number;
+    matureCandidates: SwarmKnowledgeEntry[];
+}
+declare function gatherInventory(directory: string): Promise<InventorySnapshot>;
+declare function buildSystemPrompt(targets: SkillImproverTarget[], cfg: SkillImproverConfigInput): string;
+declare function buildUserPrompt(inv: InventorySnapshot): string;
+declare function buildDeterministicProposal(args: {
+    targets: SkillImproverTarget[];
+    inventory: InventorySnapshot;
+    model: string | null;
+    now: Date;
+}): string;
+declare function buildLLMProposalFrame(args: {
+    body: string;
+    targets: SkillImproverTarget[];
+    model: string | null;
+    now: Date;
+}): string;
+export declare function runSkillImprover(req: SkillImproveRequest): Promise<SkillImproveResult>;
+export declare const _internals: {
+    runSkillImprover: typeof runSkillImprover;
+    buildDeterministicProposal: typeof buildDeterministicProposal;
+    buildLLMProposalFrame: typeof buildLLMProposalFrame;
+    buildSystemPrompt: typeof buildSystemPrompt;
+    buildUserPrompt: typeof buildUserPrompt;
+    gatherInventory: typeof gatherInventory;
+};
+export {};

package/dist/state.d.ts

@@ -269,6 +269,28 @@ export declare const swarmState: {
      * name at call time by matching the active session's agent prefix. */
     curatorInitAgentNames: string[];
     curatorPhaseAgentNames: string[];
+    /** All registered skill_improver / spec_writer agent names across swarms,
+     * mirroring curatorInitAgentNames so the LLM delegate factory can resolve
+     * the correct prefixed agent under multi-swarm configs. */
+    skillImproverAgentNames: string[];
+    specWriterAgentNames: string[];
+    /** v2: in-memory cache of "currently-active critical directive ids" per
+     *  session+task, populated by the knowledge-injector when it injects a
+     *  critical+matching directive. Read by the toolBefore enforcement gate
+     *  so we don't re-scan the entire knowledge file on every high-risk tool
+     *  call. Cleared by phase change, curator commits, knowledge mutations,
+     *  and resetSwarmState. FIFO-capped — see setCriticalShownIds. */
+    currentCriticalShownIds: Map<string, {
+        ids: string[];
+        taskId?: string;
+        phase?: string;
+        generatedAt: number;
+    }>;
+    /** v2: dedup set for ack records. Key = `${sessionId}|${id}|${result}|${dayKey}`.
+     *  Prevents the chat.messages.transform path AND a knowledge_ack tool call
+     *  from double-counting the same ack within a session-day. FIFO-capped —
+     *  see addKnowledgeAckDedup. */
+    knowledgeAckDedup: Set<string>;
     /**
      * All generated agent names registered with OpenCode at plugin init.
      * Used by Full-Auto v2 delegation guard to apply strict registry-aware
@@ -514,6 +536,24 @@ export declare function hasActiveFullAuto(sessionID?: string): boolean;
 export declare function setSessionEnvironment(sessionId: string, profile: EnvironmentProfile): void;
 export declare function getSessionEnvironment(sessionId: string): EnvironmentProfile | undefined;
 export declare function ensureSessionEnvironment(sessionId: string): EnvironmentProfile;
+export declare const MAX_TRACKED_CRITICAL_SHOWN = 500;
+export declare const MAX_TRACKED_KNOWLEDGE_ACKS = 5000;
+/** Set the critical shown ids for a session, FIFO-evicting the oldest entry
+ * if the cap is exceeded. Re-setting an existing key keeps insertion order
+ * fresh for that key (delete-then-set). */
+export declare function setCriticalShownIds(sessionID: string, value: {
+    ids: string[];
+    taskId?: string;
+    phase?: string;
+    generatedAt: number;
+}): void;
+/** Clear the critical shown ids for a session. Centralised so call sites do
+ *  not bypass the FIFO-cap pathway with a direct `.delete()`. Returns
+ *  whether an entry was removed. */
+export declare function clearCriticalShownIds(sessionID: string): boolean;
+/** Add a knowledge ack dedup key, FIFO-evicting the oldest if the cap is
+ * exceeded. Sets preserve insertion order in JS. */
+export declare function addKnowledgeAckDedup(key: string): void;
 /**
  * Test-only dependency-injection seam. Production code calls
  * `_internals.*` for key exported functions and objects so tests can replace

package/dist/tools/index.d.ts

@@ -20,6 +20,7 @@ export { get_approved_plan } from './get-approved-plan';
 export { get_qa_gate_profile } from './get-qa-gate-profile';
 export { fetchGitingest, type GitingestArgs, gitingest } from './gitingest';
 export { imports } from './imports';
+export { knowledge_ack } from './knowledge-ack';
 export { knowledge_add } from './knowledge-add';
 export { knowledge_query } from './knowledge-query';
 export { knowledge_recall } from './knowledge-recall';
@@ -42,6 +43,12 @@ export { schema_drift } from './schema-drift';
 export { search } from './search';
 export { type SecretFinding, type SecretscanResult, secretscan, } from './secretscan';
 export { set_qa_gates } from './set-qa-gates';
+export { skill_apply } from './skill-apply';
+export { skill_generate } from './skill-generate';
+export { skill_improve } from './skill-improve';
+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';
 import { suggestPatch } from './suggest-patch';
 export { suggestPatch };

package/dist/tools/knowledge-ack.d.ts

@@ -0,0 +1,15 @@
+/**
+ * knowledge_ack — Architect-facing tool to record an explicit acknowledgment
+ * outcome for an injected knowledge directive.
+ *
+ * The same outcome can also be expressed inline in chat with markers like
+ *   KNOWLEDGE_APPLIED: <id>
+ *   KNOWLEDGE_IGNORED: <id> reason=<reason>
+ * but this tool gives a deterministic, auditable surface that doesn't depend
+ * on chat-text scanning.
+ */
+import { createSwarmTool } from './create-tool.js';
+export declare const knowledge_ack: ReturnType<typeof createSwarmTool>;
+export declare const _internals: {
+    knowledge_ack: typeof knowledge_ack;
+};

package/dist/tools/skill-apply.d.ts

@@ -0,0 +1,11 @@
+/**
+ * skill_apply — Activate a draft proposal into the active generated skills tree.
+ *
+ * Refuses to overwrite an active SKILL.md that lacks the generator stamp
+ * (i.e., one a human has authored or edited) unless force=true is passed.
+ */
+import { createSwarmTool } from './create-tool.js';
+export declare const skill_apply: ReturnType<typeof createSwarmTool>;
+export declare const _internals: {
+    skill_apply: typeof skill_apply;
+};

package/dist/tools/skill-generate.d.ts

@@ -0,0 +1,16 @@
+/**
+ * skill_generate — Compile mature knowledge into a SKILL.md.
+ *
+ * Modes:
+ *   - draft  → writes .swarm/skills/proposals/<slug>.md
+ *   - active → writes .opencode/skills/generated/<slug>/SKILL.md and stamps
+ *              source knowledge entries with generated_skill_path metadata.
+ *
+ * Refuses to overwrite a manually edited active SKILL.md unless force=true.
+ * Slugs are sanitized; path traversal is rejected at the validator layer.
+ */
+import { createSwarmTool } from './create-tool.js';
+export declare const skill_generate: ReturnType<typeof createSwarmTool>;
+export declare const _internals: {
+    skill_generate: typeof skill_generate;
+};

package/dist/tools/skill-improve.d.ts

@@ -0,0 +1,16 @@
+/**
+ * skill_improve — Run the skill_improver agent / service under daily quota.
+ *
+ * Default write_mode is 'proposal' — writes only to
+ * .swarm/skill-improver/proposals/<ts>.md and never mutates source code.
+ * 'draft_skills' mode additionally calls skill_generate (draft mode) for
+ * mature, un-compiled clusters.
+ *
+ * Closes issue #629: lets users wire an expensive OpenRouter model and cap
+ * its usage to e.g. 10 calls/day.
+ */
+import { createSwarmTool } from './create-tool.js';
+export declare const skill_improve: ReturnType<typeof createSwarmTool>;
+export declare const _internals: {
+    skill_improve: typeof skill_improve;
+};

package/dist/tools/skill-inspect.d.ts

@@ -0,0 +1,9 @@
+/**
+ * skill_inspect — Print a generated skill (active or draft) with its source
+ * knowledge IDs.
+ */
+import { createSwarmTool } from './create-tool.js';
+export declare const skill_inspect: ReturnType<typeof createSwarmTool>;
+export declare const _internals: {
+    skill_inspect: typeof skill_inspect;
+};

package/dist/tools/skill-list.d.ts

@@ -0,0 +1,8 @@
+/**
+ * skill_list — List generator-emitted skill drafts and active SKILL.md files.
+ */
+import { createSwarmTool } from './create-tool.js';
+export declare const skill_list: ReturnType<typeof createSwarmTool>;
+export declare const _internals: {
+    skill_list: typeof skill_list;
+};

package/dist/tools/spec-write.d.ts

@@ -0,0 +1,13 @@
+/**
+ * spec_write — Safe writer for `.swarm/spec.md`.
+ *
+ * Allows the spec_writer agent (or architect) to update the project spec
+ * without granting general filesystem write access. Validates target path is
+ * `.swarm/spec.md`, performs an atomic rename, and rejects content that would
+ * break the basic shape (must be markdown, must contain a top-level heading).
+ */
+import { createSwarmTool } from './create-tool.js';
+export declare const spec_write: ReturnType<typeof createSwarmTool>;
+export declare const _internals: {
+    spec_write: typeof spec_write;
+};

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';
+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';
 /** Readonly array of all tool names */
 export declare const TOOL_NAMES: readonly ToolName[];
 /** Set for O(1) tool name validation */

package/package.json

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