conatus 0.1.0

package/dist/observation/workspace-context.js

@@ -0,0 +1,229 @@
+import * as fsp from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+const ALLOWED_EXTERNAL_PREFIXES = [os.homedir(), "/tmp"];
+const DENIED_PREFIXES = [
+    path.join(os.homedir(), '.ssh'),
+    path.join(os.homedir(), '.aws'),
+    path.join(os.homedir(), '.gnupg'),
+    path.join(os.homedir(), '.config'),
+    path.join(os.homedir(), '.env'),
+];
+/**
+ * Extract absolute file paths from a text string.
+ * Matches paths starting with / that look like file paths.
+ */
+function extractAbsolutePaths(text) {
+    // Match absolute paths: /something/... (not just /)
+    const matches = text.match(/\/[^\s'"`,;)>]+/g) ?? [];
+    // Filter to plausible file paths (must have at least one path segment)
+    return [...new Set(matches.filter((p) => p.split("/").length >= 2))];
+}
+/**
+ * Extract relative file paths from a text string.
+ * Matches paths like src/xxx.ts, docs/yyy.md, etc.
+ */
+function extractRelativePaths(text) {
+    // Match relative paths: word/word... with common file extensions or multiple segments
+    const matches = text.match(/(?<![/\w])\w[\w.-]*(?:\/[\w.-]+)+/g) ?? [];
+    // Filter to plausible relative file paths (must contain a dot for extension or multiple segments)
+    return [...new Set(matches.filter((p) => {
+            const parts = p.split("/");
+            // Must have at least 2 parts and last part should look like a file (has extension or is recognizable)
+            return parts.length >= 2 && parts[parts.length - 1].includes(".");
+        }))];
+}
+/**
+ * Returns true if the resolved path is under an allowed prefix
+ * and not under any denied prefix (sensitive directories).
+ * Allowed: home directory or /tmp, except sensitive subdirectories.
+ */
+function isAllowedExternalPath(filePath) {
+    const resolved = path.resolve(filePath);
+    const isDenied = DENIED_PREFIXES.some((prefix) => resolved.startsWith(prefix + path.sep) || resolved === prefix);
+    if (isDenied)
+        return false;
+    return ALLOWED_EXTERNAL_PREFIXES.some((prefix) => resolved.startsWith(prefix + path.sep) || resolved === prefix);
+}
+/**
+ * Read an external file if it exists, is allowed, and is within size limit.
+ * Returns the content string or null if not readable.
+ */
+async function readExternalFile(filePath, maxBytes) {
+    if (!isAllowedExternalPath(filePath))
+        return null;
+    try {
+        const stat = await fsp.stat(filePath);
+        if (!stat.isFile())
+            return null;
+        if (stat.size > maxBytes)
+            return null;
+        return await fsp.readFile(filePath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+const STOPWORDS = new Set([
+    "the", "a", "an", "is", "are", "to", "for", "of", "in", "on", "at",
+    "and", "or", "not", "be", "was", "were", "has", "have", "had",
+    "do", "does", "did", "will", "would", "could", "should", "may",
+    "might", "can", "its", "it", "this", "that", "with", "as", "by",
+    "from", "up", "about", "into", "through", "during", "before",
+    "after", "above", "below", "between", "each", "but", "also",
+]);
+const EXCLUDE_DIRS = new Set(["node_modules", ".git", "dist", "coverage", ".DS_Store"]);
+function extractKeywords(text) {
+    return text
+        .toLowerCase()
+        .split(/[\s\-_\/\.]+/)
+        .filter((w) => w.length >= 3 && !STOPWORDS.has(w));
+}
+async function collectFiles(dir, rootDir, depth, result) {
+    if (depth > 3)
+        return;
+    let entries;
+    try {
+        entries = await fsp.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    const resolvedRoot = path.resolve(rootDir);
+    for (const entry of entries) {
+        if (EXCLUDE_DIRS.has(entry.name))
+            continue;
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            await collectFiles(full, rootDir, depth + 1, result);
+        }
+        else if (entry.isFile()) {
+            const resolved = path.resolve(full);
+            if (resolved.startsWith(resolvedRoot + path.sep) || resolved === resolvedRoot) {
+                result.push(full);
+            }
+        }
+    }
+}
+function fileMatchesKeywords(filePath, keywords) {
+    const name = path.basename(filePath).toLowerCase();
+    return keywords.some((kw) => name.includes(kw));
+}
+async function fileContentMatchesKeywords(filePath, keywords) {
+    try {
+        const raw = await fsp.readFile(filePath, "utf-8");
+        const content = raw.slice(0, 20480).toLowerCase();
+        return keywords.some((kw) => content.includes(kw));
+    }
+    catch {
+        return false;
+    }
+}
+async function readFileSection(filePath, maxChars) {
+    try {
+        const content = await fsp.readFile(filePath, "utf-8");
+        return content.slice(0, maxChars);
+    }
+    catch {
+        return "";
+    }
+}
+export function createWorkspaceContextProvider(options, getGoalDescription) {
+    const { workDir, maxFiles = 5, maxCharsPerFile = 4000, externalFileMaxBytes = 10240 } = options;
+    return async (goalId, dimensionName) => {
+        const goalDescription = (await getGoalDescription(goalId)) ?? "";
+        const keywords = extractKeywords(goalDescription + " " + dimensionName);
+        const parts = [`# Workspace: ${workDir}`];
+        // Read external absolute-path files mentioned in goal description
+        const externalPaths = extractAbsolutePaths(goalDescription);
+        for (const extPath of externalPaths) {
+            const content = await readExternalFile(extPath, externalFileMaxBytes);
+            if (content !== null) {
+                parts.push(`## External file: ${extPath}\n\`\`\`\n${content}\n\`\`\``);
+            }
+        }
+        // Directory listing
+        try {
+            const entries = await fsp.readdir(workDir);
+            parts.push(`## Directory listing\n${entries.join(", ")}`);
+        }
+        catch {
+            /* skip */
+        }
+        // Always-include candidates
+        const alwaysInclude = ["README.md", "package.json"];
+        const alwaysIncludePaths = [];
+        for (const rel of alwaysInclude) {
+            const fp = path.join(workDir, rel);
+            try {
+                await fsp.access(fp);
+                alwaysIncludePaths.push(fp);
+            }
+            catch {
+                // not accessible
+            }
+        }
+        // Relative path exact-match: files explicitly mentioned in goal description
+        const relativePathsInGoal = extractRelativePaths(goalDescription);
+        const pathMatchedPaths = [];
+        for (const rel of relativePathsInGoal) {
+            const fp = path.join(workDir, rel);
+            try {
+                await fsp.access(fp);
+                pathMatchedPaths.push(fp);
+            }
+            catch {
+                // not accessible
+            }
+        }
+        // Collect all files (depth 3)
+        const allFiles = [];
+        await collectFiles(workDir, workDir, 0, allFiles);
+        // Separate already-included from candidates
+        const alwaysSet = new Set(alwaysIncludePaths);
+        const pathMatchSet = new Set(pathMatchedPaths);
+        const candidates = allFiles.filter((fp) => !alwaysSet.has(fp) && !pathMatchSet.has(fp));
+        // Phase 1: filename match
+        const nameMatched = candidates.filter((fp) => fileMatchesKeywords(fp, keywords));
+        // Phase 2: content match (only if we still need more)
+        // alwaysInclude and pathMatch are treated as priority (outside maxFiles cap),
+        // so keyword-match fills remaining slots up to maxFiles
+        const neededFromCandidates = Math.max(0, maxFiles - alwaysIncludePaths.length - pathMatchedPaths.length);
+        let selected = nameMatched.slice(0, neededFromCandidates);
+        if (selected.length < neededFromCandidates) {
+            const remaining = candidates.filter((fp) => !selected.includes(fp));
+            const contentMatchResults = await Promise.all(remaining.map(async (fp) => ({ fp, match: await fileContentMatchesKeywords(fp, keywords) })));
+            const contentMatched = contentMatchResults.filter((r) => r.match).map((r) => r.fp);
+            selected = [
+                ...selected,
+                ...contentMatched.slice(0, neededFromCandidates - selected.length),
+            ];
+        }
+        // Read always-include files first
+        for (const fp of alwaysIncludePaths) {
+            const rel = path.relative(workDir, fp);
+            const content = await readFileSection(fp, maxCharsPerFile);
+            if (content) {
+                parts.push(`## ${rel}\n\`\`\`\n${content}\n\`\`\``);
+            }
+        }
+        // Read explicit path-matched files (priority, same as alwaysInclude)
+        for (const fp of pathMatchedPaths) {
+            const rel = path.relative(workDir, fp);
+            const content = await readFileSection(fp, maxCharsPerFile);
+            if (content) {
+                parts.push(`## ${rel}\n\`\`\`\n${content}\n\`\`\``);
+            }
+        }
+        // Read selected keyword-matched files
+        for (const fp of selected) {
+            const rel = path.relative(workDir, fp);
+            const content = await readFileSection(fp, maxCharsPerFile);
+            if (content) {
+                parts.push(`## ${rel}\n\`\`\`\n${content}\n\`\`\``);
+            }
+        }
+        return parts.join("\n\n");
+    };
+}
+//# sourceMappingURL=workspace-context.js.map

package/dist/observation/workspace-context.js.map

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

package/dist/observation-engine.d.ts

@@ -0,0 +1,218 @@
+import type { ObservationLogEntry, ObservationLog } from "./types/state.js";
+import type { ObservationLayer, ObservationMethod, ObservationTrigger, ConfidenceTier } from "./types/core.js";
+import type { StateManager } from "./state-manager.js";
+import type { KnowledgeGapSignal } from "./types/knowledge.js";
+import type { IDataSourceAdapter } from "./data-source-adapter.js";
+import type { ILLMClient } from "./llm/llm-client.js";
+export interface ObservationEngineOptions {
+    crossValidationEnabled?: boolean;
+    divergenceThreshold?: number;
+    /** Injectable override for git diff context (used in tests). */
+    gitContextFetcher?: (maxChars: number) => string;
+}
+export interface CrossValidationResult {
+    dimensionName: string;
+    mechanicalValue: number;
+    llmValue: number;
+    diverged: boolean;
+    divergenceRatio: number;
+    resolution: "mechanical_wins";
+}
+/**
+ * ObservationEngine handles the 3-layer observation architecture.
+ *
+ * Layers (in descending trust order):
+ *   mechanical         — confidence [0.85, 1.0],  progress ceiling 1.00
+ *   independent_review — confidence [0.50, 0.84], progress ceiling 0.90
+ *   self_report        — confidence [0.10, 0.49], progress ceiling 0.70
+ *
+ * Observation logs are persisted via StateManager.appendObservation.
+ * Goal state updates are persisted via StateManager.saveGoal.
+ */
+export declare class ObservationEngine {
+    private readonly stateManager;
+    private dataSources;
+    private readonly llmClient?;
+    private readonly contextProvider?;
+    private readonly options;
+    constructor(stateManager: StateManager, dataSources?: IDataSourceAdapter[], llmClient?: ILLMClient, contextProvider?: (goalId: string, dimensionName: string) => Promise<string>, options?: ObservationEngineOptions);
+    /**
+     * Compare a mechanical observation value against an LLM-produced value.
+     * Logs a warning when the two diverge beyond the configured threshold.
+     * The mechanical value always wins — LLM is used for diagnostics only.
+     */
+    private crossValidate;
+    /**
+     * Apply progress ceiling based on observation layer.
+     * Returns min(progress, ceiling).
+     */
+    applyProgressCeiling(progress: number, layer: ObservationLayer): number;
+    /**
+     * Return the ConfidenceTier and valid confidence range for a given layer.
+     */
+    getConfidenceTier(layer: ObservationLayer): {
+        tier: ConfidenceTier;
+        range: [number, number];
+    };
+    /**
+     * Construct a new ObservationLogEntry.
+     * Confidence is clamped to the layer's valid range.
+     */
+    createObservationEntry(params: {
+        goalId: string;
+        dimensionName: string;
+        layer: ObservationLayer;
+        method: ObservationMethod;
+        trigger: ObservationTrigger;
+        rawResult: unknown;
+        extractedValue: number | string | boolean | null;
+        confidence: number;
+        notes?: string;
+    }): ObservationLogEntry;
+    /**
+     * Returns true when effective progress meets the threshold but confidence
+     * is below 0.85, meaning a mechanical verification task should be generated.
+     */
+    needsVerificationTask(effectiveProgress: number, confidence: number, threshold: number): boolean;
+    /**
+     * Resolve contradictions among multiple observation entries.
+     *
+     * Resolution rules:
+     *   1. Higher-priority layer wins (mechanical > independent_review > self_report).
+     *   2. Within the same layer, take the pessimistic (lower) numeric value.
+     *   3. For non-numeric values, take the first entry in the winning layer.
+     *
+     * Returns the single "winning" entry.
+     * Throws if entries array is empty.
+     */
+    resolveContradiction(entries: ObservationLogEntry[]): ObservationLogEntry;
+    /**
+     * Apply an observation entry to the corresponding goal dimension.
+     *
+     * Steps:
+     *   1. Load goal via StateManager.
+     *   2. Find dimension by name.
+     *   3. Update current_value and confidence.
+     *   4. Append to dimension history.
+     *   5. Persist observation log entry via StateManager.appendObservation.
+     *   6. Persist updated goal via StateManager.saveGoal.
+     */
+    /**
+     * Strip trailing _2, _3, ... _N suffixes that LLMs sometimes append to
+     * deduplicate JSON keys.  Only applied to names from external (LLM) input.
+     *
+     * Examples:
+     *   "todo_count_2"  → "todo_count"
+     *   "quality_3"     → "quality"
+     *   "step_count"    → "step_count"  (trailing token is not a digit-only suffix)
+     *   "coverage"      → "coverage"
+     */
+    private normalizeDimensionName;
+    applyObservation(goalId: string, entry: ObservationLogEntry): void;
+    /**
+     * Load the observation log for a goal.
+     * Returns an empty log if none exists.
+     */
+    getObservationLog(goalId: string): ObservationLog;
+    /**
+     * Persist the observation log for a goal.
+     */
+    saveObservationLog(goalId: string, log: ObservationLog): void;
+    /**
+     * Perform an observation pass for all dimensions of a goal.
+     *
+     * For each dimension, the following priority order is used:
+     *   1. DataSource — if a registered data source covers this dimension,
+     *      call observeFromDataSource() (mechanical, confidence 0.90).
+     *   2. LLM — if an LLM client is available, call observeWithLLM()
+     *      (independent_review, confidence 0.70).
+     *   3. self_report — fall back to re-recording the existing stored value.
+     *
+     * @param goalId   The goal to observe.
+     * @param methods  Array of ObservationMethod descriptors (one per dimension,
+     *                 in the same order as goal.dimensions).  Extra entries are
+     *                 ignored; missing entries fall back to the dimension's own
+     *                 observation_method.
+     */
+    observe(goalId: string, methods: ObservationMethod[]): Promise<void>;
+    /**
+     * Observe a goal dimension by querying a registered data source.
+     *
+     * Steps:
+     *   1. Find the data source by sourceId.
+     *   2. Build a DataSourceQuery, using dimension_mapping if configured.
+     *   3. Call source.query().
+     *   4. Convert result value to numeric if possible.
+     *   5. Create and persist an ObservationLogEntry.
+     *   6. Return the entry.
+     */
+    observeFromDataSource(goalId: string, dimensionName: string, sourceId: string): Promise<ObservationLogEntry>;
+    /**
+     * Find the first DataSource adapter that can serve the given dimension name.
+     * Checks both getSupportedDimensions() and dimension_mapping config keys.
+     * Returns null if no adapter matches.
+     */
+    private findDataSourceForDimension;
+    /**
+     * Fetch a concise workspace context via git diff when no contextProvider is available.
+     * Returns an empty string if git commands fail (e.g., not a git repo).
+     *
+     * Uses execFileSync (not exec/execSync) to avoid shell-injection risks.
+     *
+     * @param maxChars  Maximum characters to return (default: 3000).
+     */
+    private fetchGitDiffContext;
+    /**
+     * Observe a goal dimension using the LLM client.
+     *
+     * The LLM is asked to score the dimension from 0.0 to 1.0.
+     * The score is used as extractedValue, and confidence is fixed at 0.70
+     * (middle of the independent_review range [0.50, 0.84]).
+     *
+     * If workspaceContext is not provided, a git diff fallback is attempted
+     * so the LLM has actual evidence to evaluate. If that also fails,
+     * the prompt includes an explicit warning and the LLM must score 0.0.
+     *
+     * @param goalId             The goal being observed.
+     * @param dimensionName      The dimension name (snake_case).
+     * @param goalDescription    Human-readable goal description.
+     * @param dimensionLabel     Human-readable dimension label.
+     * @param thresholdDescription  JSON-stringified threshold for context.
+     * @param workspaceContext   Optional pre-fetched workspace context.
+     * @param previousScore      Previous observed score for trend context.
+     * @param dryRun             If true, do not write to state.
+     */
+    observeWithLLM(goalId: string, dimensionName: string, goalDescription: string, dimensionLabel: string, thresholdDescription: string, workspaceContext?: string, previousScore?: number | null, dryRun?: boolean): Promise<ObservationLogEntry>;
+    /**
+     * Return the registered data source adapters.
+     */
+    getDataSources(): IDataSourceAdapter[];
+    /**
+     * Dynamically add a data source adapter at runtime.
+     * The adapter becomes immediately available for subsequent observe() calls.
+     */
+    addDataSource(adapter: IDataSourceAdapter): void;
+    /**
+     * Dynamically remove a data source adapter at runtime.
+     * Returns true if the adapter was found and removed, false otherwise.
+     */
+    removeDataSource(sourceId: string): boolean;
+    /**
+     * Return dimension info for all registered data sources that expose
+     * getSupportedDimensions().
+     */
+    getAvailableDimensionInfo(): Array<{
+        name: string;
+        dimensions: string[];
+    }>;
+    /**
+     * Detect whether a set of observation entries indicates a knowledge gap.
+     *
+     * Rule: if ALL entries have confidence < 0.3, interpretation is too
+     * uncertain — emit an `interpretation_difficulty` signal.
+     *
+     * Returns null when confidence is sufficient (no gap detected).
+     */
+    detectKnowledgeGap(entries: ObservationLogEntry[], dimensionName?: string): KnowledgeGapSignal | null;
+}
+//# sourceMappingURL=observation-engine.d.ts.map

package/dist/observation-engine.d.ts.map

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