qlogicagent 0.5.0 → 0.5.3

package/dist/types/orchestration/index.d.ts

@@ -0,0 +1,113 @@
+export { buildAssistantToolCallMessage, buildToolResultMessage, type FunctionToolDefinition, } from "./tool-schema.js";
+export { classifyError, getRetryStrategy, type ErrorCategory, type RetryStrategy, } from "./error-classification.js";
+export { composeStrategies, composeAsyncStrategies, SlidingWindowStrategy, SummarizeOldStrategy, ToolResultTrimStrategy, HeadTailProtectedStrategy, IncrementalCompactStrategy, CacheAwareCompressionStrategy, CompressionMetricsCollector, ContextEngineRegistry, MicroCompactStrategy, postCompactFileRecovery, type PostCompactRecoveryConfig, buildStructuredSummaryPrompt, computeAdaptiveBudget, isAsyncCompressionStrategy, selectCompressionTier, DEFAULT_ADAPTIVE_BUDGET_CONFIG, type AdaptiveBudgetConfig, type AsyncCompressionStrategy, type CacheAwareCompressionConfig, type CompressibleMessage, type CompressionEvent, type CompressionMetrics, type CompressionMetricsSnapshot, type CompressionResult, type CompressionStrategy, type CompressionTier, type ContextEngine, type HeadTailProtectionConfig, type IncrementalCompactConfig, type SummarizeFn, } from "./context-compression.js";
+export { snipCompactIfNeeded, type SnipResult, } from "./context-compression.js";
+export { applyCollapsesIfNeeded as applyContextCollapsesIfNeeded, recoverFromOverflow as recoverContextCollapseFromOverflow, createCollapseStore, type CollapseStore, type CollapseStage, } from "./context-collapse.js";
+export { buildSkillInstruction, type SkillCreateInstruction, type SkillImproveInstruction, type SkillInstruction, type SkillTurnResult, } from "./skill-improvement.js";
+export { buildSkillCandidateEffectivenessSummary, buildSkillCandidateEvidencePayload, buildSkillCandidateImprovementEvidenceBundle, buildSkillCandidateLatestReview, createDefaultSkillImprovementPolicy, normalizeSkillImprovementPolicy, type SkillCandidateImprovementEvidenceBundleContract, type SkillImprovementPolicyContract, } from "./skill-candidate.js";
+export declare const SIDECHAIN_TYPE_VALUES: readonly ["research", "planner", "plan-repair", "code-repair", "media-prep"];
+export type SidechainType = typeof SIDECHAIN_TYPE_VALUES[number];
+export type SidechainBudgetTier = "low" | "medium" | "high";
+export type SidechainMergePolicy = "summary-only" | "append-messages" | "replace-context" | "manual";
+export type SidechainToolAccessMode = "full" | "read-only" | "none";
+export interface SidechainTypePolicy {
+    type: SidechainType;
+    label: string;
+    description: string;
+    mergePolicy: SidechainMergePolicy;
+    budgetTier: SidechainBudgetTier;
+    budgetWeight: number;
+    preferFullContext: boolean;
+    preserveConversationHistory: boolean;
+    toolAccessMode: SidechainToolAccessMode;
+}
+export type SidechainToolAccessDecision = "allowed" | "denied";
+export type SidechainToolAccessInheritance = "inherit" | "shrink";
+export type SidechainToolAccessReason = "default-allow" | "always-deny" | "leaf-deny";
+export interface SidechainToolAccessRule {
+    toolName: string;
+    decision: SidechainToolAccessDecision;
+    inheritance: SidechainToolAccessInheritance;
+    reason: SidechainToolAccessReason;
+}
+export interface SidechainToolAccessPolicy {
+    deniedTools: string[];
+    canSpawnChildren: boolean;
+    defaultDecision: "allowed";
+    defaultInheritance: "inherit";
+    tools: SidechainToolAccessRule[];
+}
+export declare const SIDECHAIN_TOOL_DENY_ALWAYS: readonly ["gateway", "agents_list", "whatsapp_login", "session_status", "cron", "memory_query", "sessions_send"];
+export declare const SIDECHAIN_TOOL_DENY_LEAF: readonly ["sessions_list", "sessions_history", "sessions_spawn"];
+/** Tools that perform write/mutation operations — denied in read-only sidechain types. */
+export declare const SIDECHAIN_TOOL_DENY_WRITE: readonly ["file_edit", "create_file", "replace_string_in_file", "multi_replace_string_in_file", "create_directory", "run_in_terminal", "run_command", "delete_file", "rename_file", "move_file", "git_commit", "git_push", "manage_todo_list"];
+export declare function resolveSidechainToolAccessPolicy(params?: {
+    depth?: number;
+    maxDepth?: number;
+    role?: "leaf" | "orchestrator";
+    toolNames?: Iterable<string>;
+}): SidechainToolAccessPolicy;
+/**
+ * Resolve tool access policy for a specific sidechain type.
+ * Combines depth-based deny lists with type-specific access mode:
+ * - "full": only depth-based denials apply
+ * - "read-only": depth-based + all write/mutation tools denied
+ * - "none": all tools denied
+ */
+export declare function resolveSidechainToolAccessByType(params: {
+    type: SidechainType;
+    depth?: number;
+    maxDepth?: number;
+    role?: "leaf" | "orchestrator";
+    toolNames?: Iterable<string>;
+}): SidechainToolAccessPolicy;
+export interface ToolCallAccessFilterResult<T> {
+    allowed: T[];
+    denied: Array<{
+        toolCall: T;
+        reason: string;
+    }>;
+}
+/**
+ * Filter tool_calls against a resolved access policy.
+ * Returns allowed calls and denied calls with reasons.
+ * T must have at least { id: string; function: { name: string } }.
+ */
+export declare function filterToolCallsByAccessPolicy<T extends {
+    id: string;
+    function: {
+        name: string;
+    };
+}>(toolCalls: T[], policy: SidechainToolAccessPolicy): ToolCallAccessFilterResult<T>;
+export declare function listSidechainTypePolicies(): SidechainTypePolicy[];
+export declare function resolveSidechainTypePolicy(type: SidechainType): SidechainTypePolicy;
+export declare function resolveRepairSidechainType(params?: {
+    toolNames?: Iterable<string>;
+    preferCodeRepair?: boolean;
+    trigger?: string;
+}): Extract<SidechainType, "plan-repair" | "code-repair">;
+export declare function resolveSidechainMergePolicyByType(type: SidechainType, overrides?: {
+    forceManualReview?: boolean;
+    preferFullContext?: boolean;
+    preserveConversationHistory?: boolean;
+}): SidechainMergePolicy;
+export declare function resolveSidechainMergePolicy(params?: {
+    preferFullContext?: boolean;
+    forceManualReview?: boolean;
+    preserveConversationHistory?: boolean;
+}): SidechainMergePolicy;
+export { applyToolChoicePolicy, type ApplyToolChoicePolicyInput, type ApplyToolChoicePolicyResult, } from "./tool-choice-policy.js";
+export { repairOpenAiChatConversation, type ConversationRepairOptions, type OpenAiChatMessageLike, type OpenAiToolCall, } from "./conversation-repair.js";
+export { advanceToolLoopState, recoverToolLoopStateFromChatConversation, recoverToolLoopStateFromResponsesItems, settleToolLoopState, type RepairToolLoopStateResult, type ToolLoopRepairAction, type ToolLoopState, } from "./tool-loop-state.js";
+export { MEMORY_OBSERVATION_HOOK_VALUES, MEMORY_OBSERVATION_SOURCE_VALUES, MEMORY_WRITE_ACCESS_VALUES, type MemoryObservationHook, type MemoryObservationSource, type MemoryWriteAccess, type MemoryProviderLifecycleInvocation, } from "./memory-provider.js";
+export { isForegroundSource, isTransientCapacityError, computeRetryBackoff, isPersistentRetryEnabled, FallbackTriggeredError, type PersistentRetryConfig, } from "./retry-loop.js";
+export { computeLifecycleTransitions, DEFAULT_CURATOR_SCHEDULE_POLICY, INITIAL_CURATOR_STATE, selectReviewCandidates, shouldRunCurator, type CuratorAutoTransitionResult, type CuratorGateInput, type CuratorGateResult, type CuratorLifecycleTransition, type CuratorSchedulePolicy, type CuratorSkillLifecycleState, type CuratorSkillRecord, type CuratorState, } from "./curator-scheduler.js";
+export { buildConsolidationPrompt, buildCuratorRunSummary, detectPrefixClusters, parseConsolidationOutput, reconcileConsolidationPlan, type ConsolidationAction, type ConsolidationPlan, type ConsolidationSkillSummary, type CuratorRunReport, type PruningAction, type ReconciledConsolidationPlan, type SkillPrefixCluster, } from "./skill-consolidation.js";
+export { bigramSimilarity, computeSimilarity, decideSimilarityAction, DEFAULT_SKILL_SIMILARITY_POLICY, findSimilarSkills, stepCountProximity, toolSetJaccard, type SimilarityDecision, type SimilarityScore, type SimilarSkillMatch, type SkillSimilarityPolicy, type SkillSimilarityProfile, } from "./skill-similarity.js";
+export { aggregateTeamResults, allocateTokenBudgets, buildAgentTaskPrompt, inferAggregationPolicy, inferExecutionMode, mapRoleToSidechainType, resolveAgentToolAccess, resolveExecutionOrder, resolveTeamPlan, shouldCancelTeam, TEAM_MAX_AGENTS, TEAM_MAX_DEPTH, validateTeamPlan, type AgentRole, type TeamAgentResult, type TeamAgentSpec, type TeamAggregationPolicy, type TeamExecutionMode, type TeamLifecycleState, type TeamPlan, type TeamResult, } from "./team-orchestration.js";
+export { canForkAtDepth, buildForkedMessages, buildForkPlaceholderResults, FORK_PLACEHOLDER_RESULT, FORK_SENTINEL_TAG, generateForkChildAgentId, isInForkChild, MAX_FORK_DEPTH, MAX_SIDECHAIN_DB_DEPTH, resolveForkChildTools, type ForkChildConfig, type ForkChildMessage, type ForkContext, type ForkResult, } from "./fork-subagent.js";
+export { getBuiltInAgent, getBuiltInAgents, isBuiltInAgent, resolveAgentToolSet, type AgentDefinition, } from "./agent-registry.js";
+export { createTaskState, filterToolsByRole, type IsolationMode, type PermissionRole, type TaskType, type TaskLifecycle, type TaskState, type TaskStateBase, type LocalBashTaskState, type LocalAgentTaskState, type RemoteAgentTaskState, type InProcessTeammateTaskState, type DreamTaskState, type DreamTurn, type DreamPhase, } from "./task-types.js";
+export { calculateTokenWarningState, createTurnLoopGuardState, resolveApiErrorRecovery, resolveOutputTokenEscalation, shouldAbortTurn, type ApiErrorRecovery, type TokenWarningState, type TurnLoopGuardConfig, type TurnLoopGuardState, } from "./turn-loop-guard.js";
+export { buildPostCompactRestorationMessage, createReactiveCompactState, shouldAttemptReactiveCompact, type ReactiveCompactConfig, type ReactiveCompactState, } from "./reactive-compact.js";
+export { aggregateTeamToolResults, mapTeamRequestToForkConfigs, resolveTeamExecutionPlan, type TeamAgentRequest, type TeamAggregatedResult, type TeamExecutionBatch, type TeamExecutionPlan, type TeamToolRequest, } from "./team-tool-loop-wiring.js";

package/dist/types/orchestration/memory-provider.d.ts

@@ -0,0 +1,14 @@
+import { MEMORY_OBSERVATION_HOOK_VALUES, type MemoryObservationHook, MEMORY_OBSERVATION_SOURCE_VALUES, type MemoryObservationSource, MEMORY_WRITE_ACCESS_VALUES, type MemoryWriteAccess } from "qlogicagent-runtime-contracts";
+export { MEMORY_OBSERVATION_HOOK_VALUES, type MemoryObservationHook, MEMORY_OBSERVATION_SOURCE_VALUES, type MemoryObservationSource, MEMORY_WRITE_ACCESS_VALUES, type MemoryWriteAccess, };
+export interface MemoryProviderLifecycleInvocation {
+    hook: MemoryObservationHook;
+    source: MemoryObservationSource;
+    sessionId: string;
+    turnId?: string;
+    executionId?: string;
+    rootExecutionId?: string;
+    parentExecutionId?: string;
+    sidechainId?: string;
+    attemptId?: string;
+    writeAccess: MemoryWriteAccess;
+}

package/dist/types/orchestration/reactive-compact.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Reactive Compact — Emergency context compression when API returns prompt-too-long.
+ *
+ * Aligned with Claude Code's reactive compact chain:
+ * 1. API 413 → withhold error → attempt reactive compact → retry
+ * 2. Only one reactive compact attempt per turn (prevent infinite loops)
+ * 3. Falls back to abort if compact fails
+ *
+ * Also handles post-compact restoration:
+ * - Todo list re-injection
+ * - Skill context re-injection
+ * - Tool delta re-injection (new/removed tools since last compact)
+ */
+export interface ReactiveCompactConfig {
+    /** Maximum consecutive auto-compact failures before giving up (CC: 3). */
+    maxConsecutiveFailures: number;
+    /** Minimum messages to keep after reactive compact. */
+    minMessagesAfterCompact: number;
+    /** Target token usage after compact (percentage of context window). */
+    targetUsagePercent: number;
+}
+export declare const DEFAULT_REACTIVE_COMPACT_CONFIG: ReactiveCompactConfig;
+export interface PostCompactRestorationPayload {
+    /** Current active todo list to re-inject after compact. */
+    todoList?: Array<{
+        id: number;
+        title: string;
+        status: string;
+    }>;
+    /** Active skill context (if LLM is executing a skill). */
+    activeSkillContext?: {
+        name: string;
+        step: number;
+        instructions: string;
+    };
+    /** Tool delta since last compact (tools added/removed from available set). */
+    toolDelta?: {
+        added: string[];
+        removed: string[];
+    };
+    /** Custom restoration blocks from memory hooks. */
+    customBlocks?: Array<{
+        label: string;
+        content: string;
+    }>;
+}
+/**
+ * Build the restoration message to inject after a compact operation.
+ * This ensures critical state survives context compression.
+ */
+export declare function buildPostCompactRestorationMessage(payload: PostCompactRestorationPayload): string | null;
+export interface ReactiveCompactState {
+    /** Number of consecutive compact failures. */
+    consecutiveFailures: number;
+    /** Whether reactive compact has been attempted in this turn. */
+    attemptedThisTurn: boolean;
+    /** Last compact timestamp. */
+    lastCompactAt: number | null;
+    /** Tool names at time of last compact (for delta calculation). */
+    toolsAtLastCompact: string[];
+}
+export declare function createReactiveCompactState(): ReactiveCompactState;
+/**
+ * Determine if reactive compact should be attempted.
+ */
+export declare function shouldAttemptReactiveCompact(state: ReactiveCompactState, config?: ReactiveCompactConfig): boolean;
+/**
+ * Calculate the tool delta since last compact.
+ */
+export declare function computeToolDelta(currentTools: string[], toolsAtLastCompact: string[]): {
+    added: string[];
+    removed: string[];
+};

package/dist/types/orchestration/retry-loop.d.ts

@@ -0,0 +1,69 @@
+export declare function executeBoundedRetryLoop<TResult>(params: {
+    maxIterations: number;
+    onRetryLimit: (params: {
+        iterations: number;
+        maxIterations: number;
+    }) => Promise<TResult> | TResult;
+    executeIteration: (params: {
+        iteration: number;
+    }) => Promise<{
+        kind: "continue";
+    } | {
+        kind: "return";
+        result: TResult;
+    }>;
+}): Promise<TResult>;
+export declare function resolveScaledRetryIterations(params: {
+    candidateCount: number;
+    baseIterations?: number;
+    perCandidateIterations?: number;
+    minIterations?: number;
+    maxIterations?: number;
+}): number;
+export declare function isForegroundSource(source: string | undefined): boolean;
+/** Is this a transient capacity error (429 or 529/overloaded)? */
+export declare function isTransientCapacityError(status: number | undefined): boolean;
+/**
+ * Compute exponential backoff delay with jitter.
+ * CC parity: withRetry.ts — BASE_DELAY_MS=500, 2^n backoff, capped.
+ */
+export declare function computeRetryBackoff(attempt: number, baseDelayMs?: number, maxDelayMs?: number): number;
+/**
+ * Persistent retry mode — for unattended sessions.
+ * Retries 429/529 indefinitely with higher backoff.
+ * Yields heartbeat events periodically so the host doesn't mark us idle.
+ *
+ * CC parity: withRetry.ts CLAUDE_CODE_UNATTENDED_RETRY
+ */
+export interface PersistentRetryConfig {
+    /** Max backoff interval (CC: 5 min). */
+    maxBackoffMs: number;
+    /** Total cap before giving up (CC: 6 hours). */
+    resetCapMs: number;
+    /** Heartbeat interval during waits (CC: 30 seconds). */
+    heartbeatIntervalMs: number;
+}
+export declare const DEFAULT_PERSISTENT_RETRY_CONFIG: PersistentRetryConfig;
+/**
+ * Check if persistent retry is enabled via environment variable.
+ * CC parity: CLAUDE_CODE_UNATTENDED_RETRY
+ */
+export declare function isPersistentRetryEnabled(): boolean;
+/**
+ * Error class for triggering model fallback after repeated 529s.
+ * CC parity: FallbackTriggeredError
+ */
+export declare class FallbackTriggeredError extends Error {
+    readonly originalModel: string;
+    readonly fallbackModel: string;
+    constructor(originalModel: string, fallbackModel: string);
+}
+/**
+ * Error class for when retries are exhausted and cannot continue.
+ * CC parity: CannotRetryError
+ */
+export declare class CannotRetryError extends Error {
+    readonly originalError: unknown;
+    readonly model: string;
+    constructor(originalError: unknown, model: string);
+}

package/dist/types/orchestration/skill-candidate.d.ts

@@ -0,0 +1,52 @@
+import { type SkillCandidateAction, type SkillCandidateArtifactContract, type SkillCandidateEffectivenessContract, type SkillCandidateReviewContract, type SkillCandidateSourceExecutionContract } from "../contracts/skill-candidate.js";
+export type SkillImprovementPolicyContract = {
+    reviewRequired: boolean;
+    canaryRequired: boolean;
+    autoPromote: boolean;
+    minCanarySampleCount: number;
+    minSuccessRate: number;
+    maxRegressionRate: number;
+    maxCostIncreaseRate: number;
+    staleAfterHours: number;
+};
+export type SkillCandidateImprovementEvidenceBundleContract = {
+    artifact?: SkillCandidateArtifactContract | null;
+    sourceExecution?: SkillCandidateSourceExecutionContract | null;
+    sourceSessionKey?: string | null;
+    diffSummary?: string | null;
+    baselineCandidateId?: string | null;
+    rolloutNotes?: string | null;
+    validationRefs?: string[];
+    evidence?: Record<string, unknown>;
+};
+export declare function createDefaultSkillImprovementPolicy(overrides?: Partial<SkillImprovementPolicyContract>): SkillImprovementPolicyContract;
+export declare function normalizeSkillImprovementPolicy(value: unknown, fallback?: SkillImprovementPolicyContract): SkillImprovementPolicyContract;
+export declare function buildSkillCandidateEvidencePayload(params: {
+    evidence?: Record<string, unknown> | null;
+    artifact?: SkillCandidateArtifactContract | null;
+    sourceExecution?: SkillCandidateSourceExecutionContract | null;
+    sourceSessionKey?: string | null;
+}): Record<string, unknown>;
+export declare function buildSkillCandidateImprovementEvidenceBundle(params: SkillCandidateImprovementEvidenceBundleContract): Record<string, unknown>;
+export declare function buildSkillCandidateLatestReview(params: {
+    action: SkillCandidateAction;
+    actor?: string | null;
+    notes?: string | null;
+    payload?: Record<string, unknown> | null;
+    createdAt?: string;
+}): SkillCandidateReviewContract;
+export declare function buildSkillCandidateEffectivenessSummary(params: {
+    phase: "canary" | "published";
+    sampleCount?: number;
+    successCount?: number;
+    failureCount?: number;
+    regressionCount?: number;
+    avgLatencyMs?: number;
+    avgCostUsd?: number;
+    score?: number;
+    staleReason?: string | null;
+    notes?: string | null;
+    summary?: Record<string, unknown> | null;
+    lastObservedAt?: string;
+    updatedAt?: string;
+}): SkillCandidateEffectivenessContract;

package/dist/types/orchestration/skill-consolidation.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Skill consolidation strategy — pure decision logic for
+ * the Autonomous Curator's LLM-driven skill merging phase.
+ *
+ * This module:
+ * 1. Detects prefix clusters among skill names.
+ * 2. Builds the consolidation prompt for the LLM review agent.
+ * 3. Parses structured LLM output into actionable merge/prune plans.
+ * 4. Reconciles LLM intent against ground truth (existing skills).
+ *
+ * No I/O — the caller invokes the LLM and applies the results.
+ */
+/** A skill summary fed to the LLM reviewer. */
+export interface ConsolidationSkillSummary {
+    name: string;
+    description: string;
+    /** Comma-separated tool names the skill uses. */
+    tools: string;
+    useCount: number;
+    lastActivityAt: string | null;
+    state: "active" | "stale";
+}
+/** A single consolidation action proposed by the LLM. */
+export interface ConsolidationAction {
+    /** Source skill to be absorbed. */
+    sourceSkill: string;
+    /** Target umbrella skill (existing or to-be-created). */
+    targetUmbrella: string;
+    /** Whether the target umbrella already exists. */
+    targetExists: boolean;
+    /** LLM's reason for the merge. */
+    reason: string;
+}
+/** A single pruning action proposed by the LLM. */
+export interface PruningAction {
+    /** Skill to be archived (not deleted). */
+    skillName: string;
+    /** Reason for pruning. */
+    reason: string;
+}
+/** Full consolidation plan produced by parsing LLM output. */
+export interface ConsolidationPlan {
+    consolidations: ConsolidationAction[];
+    prunings: PruningAction[];
+    /** Skills mentioned by LLM but not found in ground truth. */
+    hallucinations: string[];
+}
+/** Result of reconciling the LLM plan against ground truth. */
+export interface ReconciledConsolidationPlan {
+    /** Validated consolidation actions (targets exist or are marked for creation). */
+    validConsolidations: ConsolidationAction[];
+    /** Validated pruning actions (skills exist). */
+    validPrunings: PruningAction[];
+    /** Rejected actions due to ground-truth mismatch. */
+    rejected: Array<{
+        action: string;
+        reason: string;
+    }>;
+}
+/** A detected cluster of skills sharing a naming prefix. */
+export interface SkillPrefixCluster {
+    prefix: string;
+    skills: string[];
+}
+/**
+ * Detect prefix clusters among skill names.
+ *
+ * A cluster is ≥2 skills sharing a common hyphenated prefix of ≥2 chars.
+ * E.g. `["pr-review", "pr-merge", "pr-label"]` → cluster `"pr"`.
+ */
+export declare function detectPrefixClusters(skillNames: readonly string[], minClusterSize?: number): SkillPrefixCluster[];
+/**
+ * Build the consolidation review prompt for the LLM curator agent.
+ *
+ * The prompt instructs the model to:
+ * 1. Identify prefix clusters and overlapping skills.
+ * 2. Propose umbrella consolidations.
+ * 3. Mark redundant/trivial skills for pruning (archive, not delete).
+ * 4. Output a structured YAML block.
+ */
+export declare function buildConsolidationPrompt(candidates: readonly ConsolidationSkillSummary[], existingUmbrellas: readonly string[], clusters: readonly SkillPrefixCluster[]): string;
+/**
+ * Parse the LLM's structured YAML response into a ConsolidationPlan.
+ *
+ * Tolerant: handles minor formatting variations, ignores unknown fields.
+ */
+export declare function parseConsolidationOutput(llmOutput: string, knownSkills: ReadonlySet<string>): ConsolidationPlan;
+/**
+ * Reconcile the LLM's consolidation plan against ground truth.
+ *
+ * Validates that:
+ * - Source skills exist and aren't already consolidated in this plan.
+ * - Target umbrellas either exist or are new (will be created).
+ * - Pruning targets aren't also being consolidated.
+ */
+export declare function reconcileConsolidationPlan(plan: ConsolidationPlan, knownSkills: ReadonlySet<string>): ReconciledConsolidationPlan;
+/** Summary of a curator review run. */
+export interface CuratorRunReport {
+    /** ISO-8601 timestamp of the run. */
+    runAt: string;
+    /** Duration in seconds. */
+    durationSeconds: number;
+    /** Number of skills checked for lifecycle transitions. */
+    autoTransitionsChecked: number;
+    /** Number of skills marked stale. */
+    autoMarkedStale: number;
+    /** Number of skills archived. */
+    autoArchived: number;
+    /** Number of skills reactivated. */
+    autoReactivated: number;
+    /** Number of LLM-proposed consolidations accepted. */
+    consolidationsAccepted: number;
+    /** Number of LLM-proposed prunings accepted. */
+    pruningsAccepted: number;
+    /** Number of LLM-proposed actions rejected. */
+    actionsRejected: number;
+    /** Number of hallucinated skill names. */
+    hallucinations: number;
+}
+/**
+ * Build a human-readable summary from a curator run report.
+ */
+export declare function buildCuratorRunSummary(report: CuratorRunReport): string;

package/dist/types/orchestration/skill-improvement.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Skill self-learning: decides whether a completed turn should
+ * trigger skill creation or improvement instructions.
+ */
+export interface SkillTurnResult {
+    ok: boolean;
+    /** Number of tool invocations in this turn */
+    toolCallCount: number;
+    /** Number of distinct tool names used */
+    distinctToolCount: number;
+    /** Was a multi-step orchestration (≥2 rounds) used? */
+    multiStep: boolean;
+    /** Did the turn involve a sidechain? */
+    hasSidechain: boolean;
+    /** Optional user feedback signal (positive/negative/none) */
+    feedback?: "positive" | "negative" | null;
+    /** Skill name if an existing skill was used */
+    existingSkillName?: string | null;
+}
+export interface SkillCreateInstruction {
+    type: "skill.create";
+    /** Suggested skill name derived from tool usage pattern */
+    suggestedName: string;
+    /** Short description of what the skill does */
+    description: string;
+    /** Tool names involved */
+    tools: string[];
+    /** Number of orchestration steps */
+    stepCount: number;
+}
+export interface SkillImproveInstruction {
+    type: "skill.improve";
+    /** Existing skill to improve */
+    skillName: string;
+    /** Reason for improvement */
+    reason: string;
+}
+export type SkillInstruction = SkillCreateInstruction | SkillImproveInstruction;
+/**
+ * Determine whether a completed turn should produce a skill instruction.
+ *
+ * A new skill is suggested when:
+ * - The turn succeeded
+ * - It involved multi-step orchestration
+ * - It used ≥3 tool calls across ≥2 distinct tools
+ * - No existing skill was already applied
+ *
+ * An improvement is suggested when:
+ * - The turn used an existing skill but got negative feedback
+ */
+export declare function shouldCreateSkill(result: SkillTurnResult): boolean;
+export declare function shouldImproveSkill(result: SkillTurnResult): boolean;
+/**
+ * Build a skill instruction from a turn result, or null if none is warranted.
+ */
+export declare function buildSkillInstruction(result: SkillTurnResult, context: {
+    tools: string[];
+    suggestedName?: string;
+}): SkillInstruction | null;

package/dist/types/orchestration/skill-similarity.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Skill similarity — pure strategy for detecting near-duplicate skills
+ * before creation and during curator consolidation reviews.
+ *
+ * Computes multi-signal similarity between skills:
+ * 1. Tool-set Jaccard overlap (primary signal for auto-generated skills)
+ * 2. Title/description cosine bigram similarity (complementary signal)
+ * 3. Step-count proximity (minor signal for workflow complexity)
+ *
+ * No I/O — all functions are pure.
+ */
+/** Minimal skill profile for similarity comparison. */
+export interface SkillSimilarityProfile {
+    skillKey: string;
+    title: string;
+    tools: readonly string[];
+    stepCount?: number;
+}
+/** Result of a pairwise similarity comparison. */
+export interface SimilarityScore {
+    /** Overall similarity [0, 1]. */
+    overall: number;
+    /** Tool-set Jaccard index [0, 1]. */
+    toolJaccard: number;
+    /** Title bigram similarity [0, 1]. */
+    titleSimilarity: number;
+    /** Step-count proximity [0, 1]. */
+    stepProximity: number;
+}
+/** A candidate detected as similar during pre-creation check. */
+export interface SimilarSkillMatch {
+    existingSkillKey: string;
+    score: SimilarityScore;
+}
+/** Policy for similarity thresholds. */
+export interface SkillSimilarityPolicy {
+    /**
+     * Overall similarity threshold to block creation and emit "improve"
+     * instead. Default: 0.75.
+     */
+    blockCreationThreshold: number;
+    /**
+     * Overall similarity threshold to flag for curator review.
+     * Default: 0.55.
+     */
+    curatorReviewThreshold: number;
+    /** Weight of toolJaccard in overall score. Default: 0.60. */
+    toolWeight: number;
+    /** Weight of titleSimilarity in overall score. Default: 0.30. */
+    titleWeight: number;
+    /** Weight of stepProximity in overall score. Default: 0.10. */
+    stepWeight: number;
+}
+export declare const DEFAULT_SKILL_SIMILARITY_POLICY: SkillSimilarityPolicy;
+/**
+ * Compute Jaccard index between two tool sets.
+ * Returns 0 if both sets are empty.
+ */
+export declare function toolSetJaccard(toolsA: readonly string[], toolsB: readonly string[]): number;
+/**
+ * Compute character-bigram similarity between two strings.
+ * Uses Dice coefficient of bigram sets.
+ */
+export declare function bigramSimilarity(a: string, b: string): number;
+/**
+ * Compute step-count proximity [0, 1].
+ * Returns 1 when counts are identical, decreases with difference.
+ */
+export declare function stepCountProximity(stepsA: number | undefined, stepsB: number | undefined): number;
+/**
+ * Compute overall similarity between two skill profiles.
+ */
+export declare function computeSimilarity(a: SkillSimilarityProfile, b: SkillSimilarityProfile, policy?: Partial<SkillSimilarityPolicy>): SimilarityScore;
+/**
+ * Check a new skill candidate against existing skills for similarity.
+ *
+ * Returns all existing skills above curatorReviewThreshold, sorted
+ * by descending similarity. The caller should:
+ * - Block creation if any match ≥ blockCreationThreshold (emit improve instead)
+ * - Tag for curator review if match ≥ curatorReviewThreshold
+ */
+export declare function findSimilarSkills(newSkill: SkillSimilarityProfile, existingSkills: readonly SkillSimilarityProfile[], policy?: Partial<SkillSimilarityPolicy>): SimilarSkillMatch[];
+/**
+ * Determine creation decision based on similarity matches.
+ */
+export type SimilarityDecision = {
+    action: "create";
+    reason: string;
+} | {
+    action: "improve";
+    targetSkillKey: string;
+    reason: string;
+} | {
+    action: "flag-for-review";
+    targetSkillKey: string;
+    reason: string;
+};
+export declare function decideSimilarityAction(matches: readonly SimilarSkillMatch[], policy?: Partial<SkillSimilarityPolicy>): SimilarityDecision;