conatus 0.1.0

package/dist/adapters/shell-datasource.d.ts

@@ -0,0 +1,36 @@
+import type { IDataSourceAdapter } from "../observation/data-source-adapter.js";
+import type { DataSourceType, DataSourceConfig, DataSourceQuery, DataSourceResult } from "../types/data-source.js";
+import type { Logger } from "../runtime/logger.js";
+export interface ShellCommandSpec {
+    argv: string[];
+    output_type: "number" | "boolean" | "raw";
+    cwd?: string;
+    timeout_ms?: number;
+}
+export declare class ShellDataSourceAdapter implements IDataSourceAdapter {
+    readonly sourceId: string;
+    readonly sourceType: DataSourceType;
+    readonly config: DataSourceConfig;
+    private readonly commands;
+    private readonly defaultCwd;
+    private readonly logger?;
+    constructor(sourceId: string, commands: Record<string, ShellCommandSpec>, cwd?: string, logger?: Logger);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    healthCheck(): Promise<boolean>;
+    getSupportedDimensions(): string[];
+    /**
+     * Observe a set of dimensions by running their configured shell commands.
+     * Returns a map of dimensionName → numeric value.
+     * Dimensions without a configured command are silently skipped.
+     */
+    observe(dimensionNames: string[]): Promise<Record<string, number>>;
+    /**
+     * IDataSourceAdapter.query() — wraps observe() for single-dimension queries.
+     * Called by ObservationEngine when this adapter is used as a generic DataSource.
+     */
+    query(params: DataSourceQuery): Promise<DataSourceResult>;
+    private parseOutput;
+    private isExecError;
+}
+//# sourceMappingURL=shell-datasource.d.ts.map

package/dist/adapters/shell-datasource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-datasource.d.ts","sourceRoot":"","sources":["../../src/adapters/shell-datasource.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAChF,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EACjB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAMnD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,WAAW,EAAE,QAAQ,GAAG,SAAS,GAAG,KAAK,CAAC;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,sBAAuB,YAAW,kBAAkB;IAC/D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAU;IAC7C,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAElC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;IAC5D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;gBAErB,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;IAyBjG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAIrC,sBAAsB,IAAI,MAAM,EAAE;IAIlC;;;;OAIG;IACG,OAAO,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAoCxE;;;OAGG;IACG,KAAK,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAc/D,OAAO,CAAC,WAAW;IAqBnB,OAAO,CAAC,WAAW;CAGpB"}

package/dist/adapters/shell-datasource.js

@@ -0,0 +1,138 @@
+// ─── ShellDataSourceAdapter ───
+//
+// IDataSourceAdapter implementation that runs shell commands to observe
+// count-based dimensions like todo_count, fixme_count, test_pass_count.
+//
+// Uses execFile (NOT exec/execSync) to prevent shell injection.
+//
+// Each dimension maps to a ShellCommandSpec with a pre-split argv array.
+// The command's stdout is parsed according to output_type:
+//   "number"  — sums all trailing integers found on each line (handles grep -c multi-file output)
+//   "boolean" — "1" or "true" → 1, otherwise → 0
+//   "raw"     — parseFloat of the trimmed stdout
+//
+// grep exit code 1 (zero matches) is treated as 0, not an error.
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import * as path from "node:path";
+const execFileAsync = promisify(execFile);
+const SHELL_BLOCKLIST = ['bash', 'sh', 'zsh', 'dash', 'fish', 'csh', 'ksh', 'cmd', 'cmd.exe', 'powershell', 'powershell.exe', 'pwsh'];
+export class ShellDataSourceAdapter {
+    sourceId;
+    sourceType = "file";
+    config;
+    commands;
+    defaultCwd;
+    logger;
+    constructor(sourceId, commands, cwd, logger) {
+        // Validate that no command uses a shell binary as argv[0]
+        for (const [dimName, spec] of Object.entries(commands)) {
+            const basename = path.basename(spec.argv[0]);
+            if (SHELL_BLOCKLIST.includes(basename)) {
+                throw new Error(`Shell binary "${spec.argv[0]}" is not allowed as argv[0] (dimension: "${dimName}")`);
+            }
+        }
+        this.sourceId = sourceId;
+        this.commands = commands;
+        this.defaultCwd = cwd ?? process.cwd();
+        this.logger = logger;
+        // Synthesize a minimal DataSourceConfig to satisfy the interface
+        this.config = {
+            id: sourceId,
+            name: `ShellDataSource(${sourceId})`,
+            type: "file",
+            connection: {},
+            enabled: true,
+            created_at: new Date().toISOString(),
+        };
+    }
+    async connect() {
+        // no persistent connection required
+    }
+    async disconnect() {
+        // no-op
+    }
+    async healthCheck() {
+        return true;
+    }
+    getSupportedDimensions() {
+        return Object.keys(this.commands);
+    }
+    /**
+     * Observe a set of dimensions by running their configured shell commands.
+     * Returns a map of dimensionName → numeric value.
+     * Dimensions without a configured command are silently skipped.
+     */
+    async observe(dimensionNames) {
+        const results = {};
+        for (const dimName of dimensionNames) {
+            const spec = this.commands[dimName];
+            if (!spec)
+                continue; // skip dimensions we don't handle
+            try {
+                const { stdout } = await execFileAsync(spec.argv[0], spec.argv.slice(1), {
+                    cwd: spec.cwd ?? this.defaultCwd,
+                    timeout: spec.timeout_ms ?? 15000,
+                });
+                results[dimName] = this.parseOutput(stdout, spec.output_type);
+            }
+            catch (err) {
+                // grep returns exit code 1 for zero matches — treat as 0, not an error
+                if (this.isExecError(err) && err.code === 1 && spec.argv[0] === "grep") {
+                    results[dimName] = 0;
+                }
+                else if (this.isExecError(err) && err.code === 1 && spec.output_type === "boolean") {
+                    results[dimName] = 0; // false
+                }
+                else if (this.isExecError(err) && err.code === 1 && err.stdout) {
+                    // Test runners (vitest, jest) exit 1 when tests fail but still output valid results
+                    results[dimName] = this.parseOutput(err.stdout, spec.output_type);
+                }
+                else {
+                    this.logger?.warn(`[ShellDataSource] command failed for "${dimName}": ${String(err)}`);
+                    // Don't include in results — let ObservationEngine fallback handle it
+                }
+            }
+        }
+        return results;
+    }
+    /**
+     * IDataSourceAdapter.query() — wraps observe() for single-dimension queries.
+     * Called by ObservationEngine when this adapter is used as a generic DataSource.
+     */
+    async query(params) {
+        const observed = await this.observe([params.dimension_name]);
+        const value = params.dimension_name in observed ? observed[params.dimension_name] : null;
+        return {
+            value,
+            raw: { argv: this.commands[params.dimension_name]?.argv, result: value },
+            timestamp: new Date().toISOString(),
+            source_id: this.sourceId,
+        };
+    }
+    // ─── Private helpers ───
+    parseOutput(stdout, outputType) {
+        const trimmed = stdout.trim();
+        switch (outputType) {
+            case "number": {
+                // Handle multi-line grep -c output (e.g. "src/a.ts:2\nsrc/b.ts:1") — sum all lines
+                const lines = trimmed.split("\n");
+                let total = 0;
+                for (const line of lines) {
+                    const match = line.match(/(\d+)\s*$/);
+                    if (match)
+                        total += parseInt(match[1], 10);
+                }
+                return total;
+            }
+            case "boolean":
+                return trimmed === "1" || trimmed.toLowerCase() === "true" ? 1 : 0;
+            case "raw":
+                return parseFloat(trimmed) || 0;
+        }
+    }
+    isExecError(err) {
+        return typeof err === "object" && err !== null && "code" in err;
+    }
+}
+//# sourceMappingURL=shell-datasource.js.map

package/dist/adapters/shell-datasource.js.map

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

package/dist/capability-detector.d.ts

@@ -0,0 +1,124 @@
+import { StateManager } from "./state-manager.js";
+import { ReportingEngine } from "./reporting-engine.js";
+import type { ILLMClient } from "./llm/llm-client.js";
+import type { Task } from "./types/task.js";
+import type { Capability, CapabilityRegistry, CapabilityGap, CapabilityStatus, AcquisitionContext, CapabilityAcquisitionTask, CapabilityVerificationResult, CapabilityDependency } from "./types/capability.js";
+import type { AgentResult } from "./adapter-layer.js";
+export declare class CapabilityDetector {
+    private readonly stateManager;
+    private readonly llmClient;
+    private readonly reportingEngine;
+    constructor(stateManager: StateManager, llmClient: ILLMClient, reportingEngine: ReportingEngine);
+    /**
+     * 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[]): Promise<{
+        gap: CapabilityGap;
+        acquirable: boolean;
+    } | null>;
+    /**
+     * Reads capability registry from ~/.motiva/capability_registry.json.
+     * Returns an empty registry if the file does not exist.
+     */
+    loadRegistry(): Promise<CapabilityRegistry>;
+    /**
+     * Persists the capability registry to disk.
+     */
+    saveRegistry(registry: CapabilityRegistry): Promise<void>;
+    /**
+     * Adds a capability to the registry (or updates an existing one by id) and saves.
+     * If context is provided, sets acquisition_context and acquired_at on the capability.
+     */
+    registerCapability(cap: Capability, context?: AcquisitionContext): 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>;
+    /**
+     * Removes a capability from the registry by id and saves.
+     */
+    removeCapability(capabilityId: string): Promise<void>;
+    /**
+     * Finds the first capability in the registry matching the given name (case-insensitive).
+     * Returns null if no match is found.
+     */
+    findCapabilityByName(name: string): Promise<Capability | null>;
+    /**
+     * Returns all AcquisitionContext entries for capabilities acquired in service of a given goal.
+     */
+    getAcquisitionHistory(goalId: string): Promise<AcquisitionContext[]>;
+    /**
+     * Updates the status of a capability in the registry by name, or creates a
+     * placeholder entry if no capability with that name exists yet.
+     */
+    setCapabilityStatus(capabilityName: string, capabilityType: CapabilityGap["missing_capability"]["type"], status: CapabilityStatus): Promise<void>;
+    /**
+     * Fires a capability_insufficient notification via ReportingEngine with a
+     * structured message describing what is missing, why, alternatives, and impact.
+     */
+    escalateToUser(gap: CapabilityGap, goalId: string): Promise<void>;
+    /**
+     * Reads the capability dependency map from disk.
+     * Returns an empty array if the file does not exist.
+     */
+    private loadDependencies;
+    /**
+     * Persists the dependency map to disk.
+     */
+    private saveDependencies;
+    /**
+     * Records that capabilityId depends on the capabilities listed in dependsOn.
+     * If an entry already exists for capabilityId, it is replaced.
+     */
+    addDependency(capabilityId: string, dependsOn: string[]): void;
+    /**
+     * Returns the list of capability IDs that the given capabilityId depends on.
+     * Returns an empty array if no dependency entry exists.
+     */
+    getDependencies(capabilityId: string): string[];
+    /**
+     * 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.
+     */
+    resolveDependencies(dependencies: CapabilityDependency[]): string[];
+    /**
+     * 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.
+     */
+    detectCircularDependency(dependencies: CapabilityDependency[]): string[] | null;
+    /**
+     * 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.
+     */
+    getAcquisitionOrder(gaps: CapabilityGap[]): CapabilityGap[];
+}
+//# sourceMappingURL=capability-detector.d.ts.map

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

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