pulseed 0.0.1 → 0.1.1

package/dist/observation/capability-dependencies.js

@@ -0,0 +1,208 @@
+import { z } from "zod";
+// ─── Constants ───
+const DEPENDENCIES_PATH = "capability_dependencies.json";
+// ─── loadDependencies ───
+/**
+ * Reads the capability dependency map from disk.
+ * Returns an empty array if the file does not exist.
+ */
+export async function loadDependencies(deps) {
+    const raw = await deps.stateManager.readRaw(DEPENDENCIES_PATH);
+    if (raw === null) {
+        return [];
+    }
+    const parsed = z
+        .array(z.object({ capability_id: z.string(), depends_on: z.array(z.string()) }))
+        .safeParse(raw);
+    return parsed.success ? parsed.data : [];
+}
+// ─── saveDependencies ───
+/**
+ * Persists the dependency map to disk.
+ */
+export async function saveDependencies(deps, dependencies) {
+    await deps.stateManager.writeRaw(DEPENDENCIES_PATH, dependencies);
+}
+// ─── addDependency ───
+/**
+ * Records that capabilityId depends on the capabilities listed in dependsOn.
+ * If an entry already exists for capabilityId, it is replaced.
+ */
+export async function addDependency(deps, capabilityId, dependsOn) {
+    const allDeps = await loadDependencies(deps);
+    const existingIndex = allDeps.findIndex((d) => d.capability_id === capabilityId);
+    const entry = { capability_id: capabilityId, depends_on: dependsOn };
+    if (existingIndex >= 0) {
+        allDeps[existingIndex] = entry;
+    }
+    else {
+        allDeps.push(entry);
+    }
+    await saveDependencies(deps, allDeps);
+}
+// ─── getDependencies ───
+/**
+ * Returns the list of capability IDs that the given capabilityId depends on.
+ * Returns an empty array if no dependency entry exists.
+ */
+export async function getDependencies(deps, capabilityId) {
+    const allDeps = await loadDependencies(deps);
+    const entry = allDeps.find((d) => d.capability_id === capabilityId);
+    return entry ? entry.depends_on : [];
+}
+// ─── resolveDependencies ───
+/**
+ * Performs a topological sort of the given capability dependencies using Kahn's algorithm.
+ * Returns an ordered list of capability IDs with dependencies appearing before the
+ * capabilities that depend on them.
+ *
+ * Capabilities referenced only as dependents (not appearing as `capability_id`) are
+ * implicitly treated as roots and prepended to the sorted output.
+ */
+export function resolveDependencies(dependencies) {
+    if (dependencies.length === 0) {
+        return [];
+    }
+    // Collect all node IDs (both as keys and as dependency targets)
+    const allIds = new Set();
+    for (const dep of dependencies) {
+        allIds.add(dep.capability_id);
+        for (const d of dep.depends_on) {
+            allIds.add(d);
+        }
+    }
+    // Build adjacency: dep.capability_id depends on dep.depends_on[i]
+    // Topological order: dependency nodes come first
+    // inDegree[node] = number of nodes that have `node` as a dependency target
+    // Edge direction for Kahn's: dependency → dependent (dependency must come first)
+    const inDegree = new Map();
+    // adjacency: from prerequisite → [nodes that depend on it]
+    const adj = new Map();
+    for (const id of allIds) {
+        inDegree.set(id, 0);
+        adj.set(id, []);
+    }
+    for (const dep of dependencies) {
+        for (const prereq of dep.depends_on) {
+            // prereq must come before dep.capability_id
+            // adj entries are initialized for all IDs in allIds (loop above)
+            const adjList = adj.get(prereq);
+            if (adjList)
+                adjList.push(dep.capability_id);
+            inDegree.set(dep.capability_id, (inDegree.get(dep.capability_id) ?? 0) + 1);
+        }
+    }
+    // Kahn's algorithm
+    const queue = [];
+    for (const [id, degree] of inDegree) {
+        if (degree === 0) {
+            queue.push(id);
+        }
+    }
+    // Sort queue for deterministic output
+    queue.sort();
+    const result = [];
+    while (queue.length > 0) {
+        const node = queue.shift();
+        result.push(node);
+        const neighbors = adj.get(node) ?? [];
+        for (const neighbor of neighbors) {
+            const newDegree = (inDegree.get(neighbor) ?? 0) - 1;
+            inDegree.set(neighbor, newDegree);
+            if (newDegree === 0) {
+                queue.push(neighbor);
+                queue.sort();
+            }
+        }
+    }
+    return result;
+}
+// ─── detectCircularDependency ───
+/**
+ * Detects whether the given dependency list contains a circular dependency.
+ * Returns the cycle as an array of capability IDs if found, or null if no cycle exists.
+ */
+export function detectCircularDependency(dependencies) {
+    if (dependencies.length === 0) {
+        return null;
+    }
+    // Build adjacency list: node → nodes it depends on
+    const adj = new Map();
+    for (const dep of dependencies) {
+        adj.set(dep.capability_id, dep.depends_on);
+    }
+    // DFS-based cycle detection with path tracking
+    const visited = new Set();
+    const inStack = new Set();
+    const stackPath = [];
+    const dfs = (node) => {
+        if (inStack.has(node)) {
+            // Found a cycle — extract the cycle path from stackPath
+            const cycleStart = stackPath.indexOf(node);
+            return [...stackPath.slice(cycleStart), node];
+        }
+        if (visited.has(node)) {
+            return null;
+        }
+        visited.add(node);
+        inStack.add(node);
+        stackPath.push(node);
+        const neighbors = adj.get(node) ?? [];
+        for (const neighbor of neighbors) {
+            const cycle = dfs(neighbor);
+            if (cycle !== null) {
+                return cycle;
+            }
+        }
+        stackPath.pop();
+        inStack.delete(node);
+        return null;
+    };
+    for (const dep of dependencies) {
+        if (!visited.has(dep.capability_id)) {
+            const cycle = dfs(dep.capability_id);
+            if (cycle !== null) {
+                return cycle;
+            }
+        }
+    }
+    return null;
+}
+// ─── getAcquisitionOrder ───
+/**
+ * Reorders a list of CapabilityGaps so that capabilities with dependencies on
+ * other gaps in the list come after those dependencies.
+ * Independent capabilities (no deps in the list) maintain their original relative order.
+ */
+export async function getAcquisitionOrder(deps, gaps) {
+    if (gaps.length === 0) {
+        return [];
+    }
+    const allDeps = await loadDependencies(deps);
+    // Build a dependency list restricted to capabilities that appear in the gaps list
+    const gapIds = new Set(gaps.map((g) => g.missing_capability.name));
+    const relevantDeps = [];
+    for (const dep of allDeps) {
+        if (gapIds.has(dep.capability_id)) {
+            // Only include depends_on entries that are also in the gaps list
+            const filteredDependsOn = dep.depends_on.filter((d) => gapIds.has(d));
+            if (filteredDependsOn.length > 0) {
+                relevantDeps.push({ capability_id: dep.capability_id, depends_on: filteredDependsOn });
+            }
+        }
+    }
+    if (relevantDeps.length === 0) {
+        // No cross-gap dependencies — return original order
+        return [...gaps];
+    }
+    const sortedIds = resolveDependencies(relevantDeps);
+    // Gaps that appear in the sorted order are placed first (in sorted order),
+    // gaps not in the sorted list (truly independent) maintain their relative original order.
+    const inSortedSet = new Set(sortedIds);
+    const independent = gaps.filter((g) => !inSortedSet.has(g.missing_capability.name));
+    const dependent = sortedIds
+        .map((id) => gaps.find((g) => g.missing_capability.name === id))
+        .filter((g) => g !== undefined);
+    return [...independent, ...dependent];
+}
+//# sourceMappingURL=capability-dependencies.js.map

package/dist/observation/capability-dependencies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-dependencies.js","sourceRoot":"","sources":["../../src/observation/capability-dependencies.ts"],"names":[],"mappings":"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"}

package/dist/observation/capability-detector.d.ts

@@ -0,0 +1,72 @@
+import { StateManager } from "../state-manager.js";
+import { ReportingEngine } from "../reporting-engine.js";
+import type { ILLMClient } from "../llm/llm-client.js";
+import type { IPromptGateway } from "../prompt/gateway.js";
+import type { Task } from "../types/task.js";
+import type { PluginMatchResult } from "../types/plugin.js";
+import type { PluginLoader } from "../runtime/plugin-loader.js";
+import type { Capability, CapabilityRegistry, CapabilityGap, CapabilityStatus, AcquisitionContext, CapabilityAcquisitionTask, CapabilityVerificationResult, CapabilityDependency } from "../types/capability.js";
+import type { AgentResult } from "../execution/adapter-layer.js";
+export declare class CapabilityDetector {
+    private readonly stateManager;
+    private readonly llmClient;
+    private readonly reportingEngine;
+    private readonly pluginLoader?;
+    private readonly gateway?;
+    constructor(stateManager: StateManager, llmClient: ILLMClient, reportingEngine: ReportingEngine, pluginLoader?: PluginLoader, gateway?: IPromptGateway);
+    /**
+     * Analyzes a task description against the capability registry via LLM.
+     * Returns a CapabilityGap if the task requires unavailable capabilities,
+     * or null if all required capabilities are available.
+     */
+    detectDeficiency(task: Task): Promise<CapabilityGap | null>;
+    /**
+     * Goal-level analog of detectDeficiency(). Takes a goal description and a flat
+     * list of adapter capability strings (e.g. ["create_github_issue", "execute_code"]),
+     * combines them with registry capabilities, and uses LLM to determine if any
+     * capabilities required by the goal are missing.
+     *
+     * Returns a CapabilityGap (without related_task_id) if a gap is found, or null if
+     * all required capabilities are available.
+     */
+    detectGoalCapabilityGap(goalDescription: string, adapterCapabilities: string[], goalDimensions?: string[]): Promise<{
+        gap: CapabilityGap;
+        acquirable: boolean;
+        suggestedPlugins?: PluginMatchResult[];
+    } | null>;
+    /**
+     * Finds installed plugins that match the goal's dimensions.
+     * Returns plugins with matchScore >= 0.5, sorted by score then trust.
+     */
+    matchPluginsForGoal(goalDimensions: string[]): Promise<PluginMatchResult[]>;
+    loadRegistry(): Promise<CapabilityRegistry>;
+    saveRegistry(registry: CapabilityRegistry): Promise<void>;
+    registerCapability(cap: Capability, context?: AcquisitionContext): Promise<void>;
+    removeCapability(capabilityId: string): Promise<void>;
+    findCapabilityByName(name: string): Promise<Capability | null>;
+    getAcquisitionHistory(goalId: string): Promise<AcquisitionContext[]>;
+    setCapabilityStatus(capabilityName: string, capabilityType: CapabilityGap["missing_capability"]["type"], status: CapabilityStatus): Promise<void>;
+    escalateToUser(gap: CapabilityGap, goalId: string): Promise<void>;
+    /**
+     * Returns true if consecutiveFailures has reached the escalation threshold (>= 3).
+     * This confirms that repeated failures are due to a capability deficiency.
+     */
+    confirmDeficiency(_taskId: string, consecutiveFailures: number): boolean;
+    /**
+     * Deterministically creates a CapabilityAcquisitionTask from a CapabilityGap.
+     * Pure synchronous function — no LLM needed. Rules from design doc §5.3.
+     */
+    planAcquisition(gap: CapabilityGap): CapabilityAcquisitionTask;
+    /**
+     * Uses LLM to verify a newly acquired capability.
+     * Checks basic operation, error handling, and scope boundary.
+     * Returns "pass", "fail", or "escalate" (if max verification attempts reached).
+     */
+    verifyAcquiredCapability(capability: Capability, acquisitionTask: CapabilityAcquisitionTask, agentResult: AgentResult): Promise<CapabilityVerificationResult>;
+    addDependency(capabilityId: string, dependsOn: string[]): Promise<void>;
+    getDependencies(capabilityId: string): Promise<string[]>;
+    resolveDependencies(dependencies: CapabilityDependency[]): string[];
+    detectCircularDependency(dependencies: CapabilityDependency[]): string[] | null;
+    getAcquisitionOrder(gaps: CapabilityGap[]): Promise<CapabilityGap[]>;
+}
+//# sourceMappingURL=capability-detector.d.ts.map

package/dist/observation/capability-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-detector.d.ts","sourceRoot":"","sources":["../../src/observation/capability-detector.ts"],"names":[],"mappings":"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"}

package/dist/observation/capability-detector.js

@@ -0,0 +1,373 @@
+import { z } from "zod";
+import { CapabilityAcquisitionTaskSchema, CapabilityGapSchema, } from "../types/capability.js";
+import { loadRegistry, saveRegistry, registerCapability, removeCapability, findCapabilityByName, getAcquisitionHistory, setCapabilityStatus, escalateToUser, } from "./capability-registry.js";
+import { addDependency, getDependencies, resolveDependencies, detectCircularDependency, getAcquisitionOrder, } from "./capability-dependencies.js";
+// ─── Constants ───
+const CONSECUTIVE_FAILURE_THRESHOLD = 3;
+// ─── LLM response schema for deficiency detection ───
+const DeficiencyResponseSchema = z.union([
+    z.object({
+        has_deficiency: z.literal(false),
+    }),
+    z.object({
+        has_deficiency: z.literal(true),
+        missing_capability: z.object({
+            name: z.string(),
+            type: z.enum(["tool", "permission", "service"]),
+        }),
+        reason: z.string(),
+        alternatives: z.array(z.string()),
+        impact_description: z.string(),
+    }),
+]);
+// ─── LLM response schema for goal-level capability gap detection ───
+const GoalCapabilityGapResponseSchema = z.union([
+    z.object({
+        has_gap: z.literal(false),
+    }),
+    z.object({
+        has_gap: z.literal(true),
+        missing_capability: z.object({
+            name: z.string(),
+            type: z.enum(["tool", "permission", "service", "data_source"]),
+        }),
+        reason: z.string(),
+        alternatives: z.array(z.string()),
+        impact_description: z.string(),
+        acquirable: z.boolean(),
+    }),
+]);
+// ─── CapabilityDetector ───
+export class CapabilityDetector {
+    stateManager;
+    llmClient;
+    reportingEngine;
+    pluginLoader;
+    gateway;
+    constructor(stateManager, llmClient, reportingEngine, pluginLoader, gateway) {
+        this.stateManager = stateManager;
+        this.llmClient = llmClient;
+        this.reportingEngine = reportingEngine;
+        this.pluginLoader = pluginLoader;
+        this.gateway = gateway;
+    }
+    // ─── detectDeficiency ───
+    /**
+     * Analyzes a task description against the capability registry via LLM.
+     * Returns a CapabilityGap if the task requires unavailable capabilities,
+     * or null if all required capabilities are available.
+     */
+    async detectDeficiency(task) {
+        const registry = await this.loadRegistry();
+        const availableCapabilities = registry.capabilities
+            .filter((c) => c.status === "available")
+            .map((c) => `- ${c.name} (${c.type}): ${c.description}`)
+            .join("\n");
+        const systemPrompt = "You are a capability analyzer for an AI orchestration system. " +
+            "Your job is to determine whether a given task can be executed with the available capabilities. " +
+            "Respond with valid JSON only — no markdown, no explanation outside the JSON.";
+        const userMessage = `Analyze the following task and determine if any required capabilities are missing.\n\n` +
+            `Task description: ${task.work_description}\n` +
+            `Task rationale: ${task.rationale}\n` +
+            `Task approach: ${task.approach}\n\n` +
+            `Available capabilities:\n${availableCapabilities || "(none registered)"}\n\n` +
+            `Respond with JSON in one of these two formats:\n` +
+            `If all capabilities are available:\n` +
+            `{ "has_deficiency": false }\n\n` +
+            `If a capability is missing:\n` +
+            `{\n` +
+            `  "has_deficiency": true,\n` +
+            `  "missing_capability": { "name": "<name>", "type": "tool|permission|service" },\n` +
+            `  "reason": "<why this capability is needed>",\n` +
+            `  "alternatives": ["<alternative approach 1>", "<alternative approach 2>"],\n` +
+            `  "impact_description": "<impact if capability remains unavailable>"\n` +
+            `}`;
+        let parsed;
+        if (this.gateway) {
+            parsed = await this.gateway.execute({
+                purpose: "capability_detect",
+                additionalContext: { deficiency_prompt: userMessage },
+                responseSchema: DeficiencyResponseSchema,
+            });
+        }
+        else {
+            const response = await this.llmClient.sendMessage([{ role: "user", content: userMessage }], { system: systemPrompt });
+            parsed = this.llmClient.parseJSON(response.content, DeficiencyResponseSchema);
+        }
+        if (!parsed.has_deficiency) {
+            return null;
+        }
+        const gap = CapabilityGapSchema.parse({
+            missing_capability: parsed.missing_capability,
+            reason: parsed.reason,
+            alternatives: parsed.alternatives,
+            impact_description: parsed.impact_description,
+            related_task_id: task.id,
+        });
+        return gap;
+    }
+    // ─── detectGoalCapabilityGap ───
+    /**
+     * Goal-level analog of detectDeficiency(). Takes a goal description and a flat
+     * list of adapter capability strings (e.g. ["create_github_issue", "execute_code"]),
+     * combines them with registry capabilities, and uses LLM to determine if any
+     * capabilities required by the goal are missing.
+     *
+     * Returns a CapabilityGap (without related_task_id) if a gap is found, or null if
+     * all required capabilities are available.
+     */
+    async detectGoalCapabilityGap(goalDescription, adapterCapabilities, goalDimensions) {
+        try {
+            const registry = await this.loadRegistry();
+            const registryCapabilityLines = registry.capabilities
+                .filter((c) => c.status === "available")
+                .map((c) => `- ${c.name} (${c.type}): ${c.description}`);
+            const adapterCapabilityLines = adapterCapabilities.map((cap) => `- ${cap} (adapter-declared)`);
+            const allAvailableLines = [...registryCapabilityLines, ...adapterCapabilityLines];
+            const availableCapabilities = allAvailableLines.length > 0 ? allAvailableLines.join("\n") : "(none registered)";
+            const systemPrompt = "You are a capability analyzer for an AI orchestration system. " +
+                "Your job is to determine whether a given goal can be achieved with the available capabilities. " +
+                "Respond with valid JSON only — no markdown, no explanation outside the JSON.";
+            const userMessage = `Analyze the following goal and determine if any required capabilities are missing.\n\n` +
+                `Goal description: ${goalDescription}\n\n` +
+                `Available capabilities (from capability registry and declared adapter capabilities):\n${availableCapabilities}\n\n` +
+                `Respond with JSON in one of these two formats:\n` +
+                `If all capabilities are available:\n` +
+                `{ "has_gap": false }\n\n` +
+                `If a capability is missing:\n` +
+                `{\n` +
+                `  "has_gap": true,\n` +
+                `  "missing_capability": { "name": "<name>", "type": "tool|permission|service|data_source" },\n` +
+                `  "reason": "<why this capability is needed>",\n` +
+                `  "alternatives": ["<alternative approach 1>", "<alternative approach 2>"],\n` +
+                `  "impact_description": "<impact if capability remains unavailable>",\n` +
+                `  "acquirable": true|false\n` +
+                `}`;
+            let parsed;
+            if (this.gateway) {
+                parsed = await this.gateway.execute({
+                    purpose: "capability_goal_gap",
+                    additionalContext: { goal_gap_prompt: userMessage },
+                    responseSchema: GoalCapabilityGapResponseSchema,
+                });
+            }
+            else {
+                const response = await this.llmClient.sendMessage([{ role: "user", content: userMessage }], { system: systemPrompt });
+                try {
+                    parsed = this.llmClient.parseJSON(response.content, GoalCapabilityGapResponseSchema);
+                }
+                catch (err) {
+                    console.warn(`[CapabilityDetector] Failed to parse LLM response as GoalCapabilityGapResponse: ${String(err)}`);
+                    return null;
+                }
+            }
+            if (!parsed.has_gap) {
+                return null;
+            }
+            const gap = CapabilityGapSchema.parse({
+                missing_capability: parsed.missing_capability,
+                reason: parsed.reason,
+                alternatives: parsed.alternatives,
+                impact_description: parsed.impact_description,
+                // related_task_id intentionally omitted — this is goal-level, not task-level
+            });
+            const result = {
+                gap,
+                acquirable: parsed.acquirable ?? false,
+            };
+            if (this.pluginLoader && goalDimensions && goalDimensions.length > 0) {
+                result.suggestedPlugins = await this.matchPluginsForGoal(goalDimensions);
+            }
+            return result;
+        }
+        catch {
+            return null;
+        }
+    }
+    // ─── matchPluginsForGoal ───
+    /**
+     * Finds installed plugins that match the goal's dimensions.
+     * Returns plugins with matchScore >= 0.5, sorted by score then trust.
+     */
+    async matchPluginsForGoal(goalDimensions) {
+        if (!this.pluginLoader || goalDimensions.length === 0) {
+            return [];
+        }
+        const pluginStates = await this.pluginLoader.loadAll();
+        const results = [];
+        for (const state of pluginStates) {
+            if (state.status !== "loaded")
+                continue;
+            const pluginDimensions = state.manifest.dimensions ?? [];
+            if (pluginDimensions.length === 0)
+                continue;
+            const matchedDimensions = goalDimensions.filter((d) => pluginDimensions.includes(d));
+            const matchScore = matchedDimensions.length / goalDimensions.length;
+            if (matchScore < 0.5)
+                continue;
+            results.push({
+                pluginName: state.name,
+                matchScore,
+                matchedDimensions,
+                trustScore: state.trust_score,
+                autoSelectable: state.trust_score >= 20,
+            });
+        }
+        // Sort by matchScore descending, then trustScore descending
+        results.sort((a, b) => {
+            if (b.matchScore !== a.matchScore)
+                return b.matchScore - a.matchScore;
+            return b.trustScore - a.trustScore;
+        });
+        return results;
+    }
+    // ─── Registry wrappers ───
+    async loadRegistry() {
+        return loadRegistry({ stateManager: this.stateManager });
+    }
+    async saveRegistry(registry) {
+        return saveRegistry({ stateManager: this.stateManager }, registry);
+    }
+    async registerCapability(cap, context) {
+        return registerCapability({ stateManager: this.stateManager }, cap, context);
+    }
+    async removeCapability(capabilityId) {
+        return removeCapability({ stateManager: this.stateManager }, capabilityId);
+    }
+    async findCapabilityByName(name) {
+        return findCapabilityByName({ stateManager: this.stateManager }, name);
+    }
+    async getAcquisitionHistory(goalId) {
+        return getAcquisitionHistory({ stateManager: this.stateManager }, goalId);
+    }
+    async setCapabilityStatus(capabilityName, capabilityType, status) {
+        return setCapabilityStatus({ stateManager: this.stateManager }, capabilityName, capabilityType, status);
+    }
+    async escalateToUser(gap, goalId) {
+        return escalateToUser({ reportingEngine: this.reportingEngine }, gap, goalId);
+    }
+    // ─── confirmDeficiency ───
+    /**
+     * Returns true if consecutiveFailures has reached the escalation threshold (>= 3).
+     * This confirms that repeated failures are due to a capability deficiency.
+     */
+    confirmDeficiency(_taskId, consecutiveFailures) {
+        return consecutiveFailures >= CONSECUTIVE_FAILURE_THRESHOLD;
+    }
+    // ─── planAcquisition ───
+    /**
+     * Deterministically creates a CapabilityAcquisitionTask from a CapabilityGap.
+     * Pure synchronous function — no LLM needed. Rules from design doc §5.3.
+     */
+    planAcquisition(gap) {
+        const capabilityName = gap.missing_capability.name;
+        const capabilityType = gap.missing_capability.type;
+        let method;
+        let task_description;
+        if (capabilityType === "tool") {
+            method = "tool_creation";
+            task_description =
+                `Create a tool named "${capabilityName}" that fulfills the following need: ${gap.reason}. ` +
+                    `The tool should be implemented and made available for use. ` +
+                    `Impact if unavailable: ${gap.impact_description}`;
+        }
+        else if (capabilityType === "permission") {
+            method = "permission_request";
+            task_description =
+                `Request permission for "${capabilityName}" from the user or system administrator. ` +
+                    `Reason the permission is needed: ${gap.reason}. ` +
+                    `Impact if unavailable: ${gap.impact_description}`;
+        }
+        else if (capabilityType === "service") {
+            method = "service_setup";
+            task_description =
+                `Set up the service "${capabilityName}" required for the following reason: ${gap.reason}. ` +
+                    `Configure and verify the service is operational. ` +
+                    `Impact if unavailable: ${gap.impact_description}`;
+        }
+        else {
+            // data_source — treated as a form of service setup
+            method = "service_setup";
+            task_description =
+                `Set up access to the data source "${capabilityName}" required for the following reason: ${gap.reason}. ` +
+                    `Configure and verify the data source is accessible. ` +
+                    `Impact if unavailable: ${gap.impact_description}`;
+        }
+        return CapabilityAcquisitionTaskSchema.parse({
+            gap,
+            method,
+            task_description,
+            success_criteria: [
+                "capability registered in registry",
+                `${capabilityName} is operational and accessible`,
+            ],
+            verification_attempts: 0,
+            max_verification_attempts: 3,
+        });
+    }
+    // ─── verifyAcquiredCapability ───
+    /**
+     * Uses LLM to verify a newly acquired capability.
+     * Checks basic operation, error handling, and scope boundary.
+     * Returns "pass", "fail", or "escalate" (if max verification attempts reached).
+     */
+    async verifyAcquiredCapability(capability, acquisitionTask, agentResult) {
+        const systemPrompt = "You are a capability verifier for an AI orchestration system. " +
+            "Your job is to assess whether a newly acquired capability is ready for use. " +
+            "Respond with valid JSON only — no markdown, no explanation outside the JSON.";
+        const userMessage = `Verify the following acquired capability.\n\n` +
+            `Capability name: ${capability.name}\n` +
+            `Capability type: ${capability.type}\n` +
+            `Capability description: ${capability.description}\n\n` +
+            `Acquisition task: ${acquisitionTask.task_description}\n` +
+            `Success criteria: ${acquisitionTask.success_criteria.join("; ")}\n\n` +
+            `Agent result output:\n${agentResult.output}\n\n` +
+            `Evaluate the following three criteria:\n` +
+            `1. Basic operation — does the capability work as described?\n` +
+            `2. Error handling — does it handle edge cases gracefully?\n` +
+            `3. Scope boundary — does it only do what is intended and nothing more?\n\n` +
+            `Respond with JSON in this format:\n` +
+            `{ "verdict": "pass" | "fail", "reason": "<explanation>" }`;
+        const VerificationResponseSchema = z.object({
+            verdict: z.enum(["pass", "fail"]),
+            reason: z.string(),
+        });
+        let parsed;
+        if (this.gateway) {
+            parsed = await this.gateway.execute({
+                purpose: "capability_verify",
+                additionalContext: { verify_prompt: userMessage },
+                responseSchema: VerificationResponseSchema,
+            });
+        }
+        else {
+            const response = await this.llmClient.sendMessage([{ role: "user", content: userMessage }], { system: systemPrompt });
+            parsed = this.llmClient.parseJSON(response.content, VerificationResponseSchema);
+        }
+        if (parsed.verdict === "fail") {
+            acquisitionTask.verification_attempts += 1;
+            if (acquisitionTask.verification_attempts >= acquisitionTask.max_verification_attempts) {
+                return "escalate";
+            }
+            return "fail";
+        }
+        return "pass";
+    }
+    // ─── Dependency wrappers ───
+    async addDependency(capabilityId, dependsOn) {
+        return addDependency({ stateManager: this.stateManager }, capabilityId, dependsOn);
+    }
+    async getDependencies(capabilityId) {
+        return getDependencies({ stateManager: this.stateManager }, capabilityId);
+    }
+    resolveDependencies(dependencies) {
+        return resolveDependencies(dependencies);
+    }
+    detectCircularDependency(dependencies) {
+        return detectCircularDependency(dependencies);
+    }
+    async getAcquisitionOrder(gaps) {
+        return getAcquisitionOrder({ stateManager: this.stateManager }, gaps);
+    }
+}
+//# sourceMappingURL=capability-detector.js.map