fixo-cli 1.0.0

package/dist/config.d.ts

@@ -0,0 +1,162 @@
+import type { PolicyProfile } from './runtime/policy.js';
+export declare const DEFAULT_API_URL = "https://api.freellmapi.com/v1";
+/** Stream-resume policy. */
+export type StreamResumePolicy = 'auto' | 'never';
+/**
+ * Context-budget policy.
+ *  - `auto`     — proactive enforcement is enabled and, if the enforcer
+ *                 asks for compaction, the agent summarises the oldest
+ *                 turns via an LLM call. (default)
+ *  - `truncate` — proactive enforcement runs but the agent will NOT
+ *                 trigger LLM-based compaction. If even the enforcer
+ *                 cannot fit the budget, the request is sent anyway
+ *                 (and may 413).
+ *  - `never`    — kill-switch. No enforcement, no compaction. Useful
+ *                 when a user wants exact 1:1 historical behaviour.
+ */
+export type ContextBudgetPolicy = 'auto' | 'truncate' | 'never';
+/**
+ * Loop-trap configuration. Lives under `preferences.safety.loopTrap`
+ * (not `preferences.resilience`) so the safety and resilience
+ * concerns remain orthogonal.
+ *
+ * The defaults match the design decision: warn at 3 consecutive
+ * equivalent turns (acts as an intentional psychological disruptor
+ * to the LLM via system-prompt injection), hard-abort at 6.
+ */
+export interface LoopTrapPolicy {
+    /** Number of consecutive equivalent turns that triggers a directive. */
+    triggerCount: number;
+    /** Number of consecutive equivalent turns that triggers a hard abort. */
+    hardAbortCount: number;
+    /** Maximum number of tool-result bytes to include in the fingerprint. */
+    toolResultTailBytes: number;
+    /** Hard cap on in-memory history to bound memory growth. */
+    maxHistory: number;
+    /** Master kill-switch; when false, the detector is never invoked. */
+    enabled: boolean;
+}
+/** Semantic loop-trap configuration. Tracks file-target frequency
+ *  inside a sliding window so that an LLM which varies its search
+ *  arguments but keeps hammering the same file still trips. */
+export interface SemanticLoopTrapPolicy {
+    enabled: boolean;
+    windowSize: number;
+    triggerCount: number;
+    hardAbortCount: number;
+}
+/** Pre-save gate severity. */
+export type LspPreSaveMode = 'off' | 'warn' | 'block' | 'sandbox-mock';
+/** Safety preferences — Pillar 1, 2, 3 surface. Pillar 4 lives in the
+ *  credential vault module, not in the user-facing config. */
+export interface SafetyConfig {
+    /** Run file writes through the atomic shadow-staging pipeline. */
+    atomicStaging: boolean;
+    /** Staged writes older than this (ms) are eligible for auto-GC. */
+    stagingTtlMs: number;
+    /** How to react to LSP diagnostics on a staged write. */
+    lspPreSave: LspPreSaveMode;
+    /** Loop-trap thresholds. */
+    loopTrap: LoopTrapPolicy;
+    /** Semantic loop-trap thresholds (Pillar 2 of the refit). */
+    semanticLoopTrap: SemanticLoopTrapPolicy;
+    /** Maximum bytes a file may be before read_file is gated by the
+     *  structural pre-scan rule. Defaults to 15 KiB. */
+    largeFileGateBytes: number;
+    /** Maximum line count before read_file is gated. Defaults to 350. */
+    largeFileGateLines: number;
+    /**
+     * Predictive context-budget gate (Phase 4). When set to a value in
+     * (0, 1], `read_file` projects the token cost of the read against
+     * the model's input window and defers if projected total exceeds
+     * this fraction. Default 0.85. Set to 1.0 to disable.
+     */
+    predictiveBudgetPct?: number;
+}
+/** Resilience preferences for the new withRetry + chatStreamWithResume paths. */
+export interface ResilienceConfig {
+    /** When 'auto', mid-stream cuts are resumed transparently (default). */
+    streamResume: StreamResumePolicy;
+    /** Max additional resume attempts after a mid-stream cut. */
+    maxResumeAttempts: number;
+    /** When true, the new withRetry engine is used for non-streaming calls. */
+    useWithRetry: boolean;
+    /**
+     * Context-budget policy. When 'auto' or 'truncate', the
+     * {@link ContextBudgetEnforcer} runs before every LLM call and
+     * trims the conversation to fit the model's input window. When
+     * 'auto', the agent may also call `compact()` to summarise the
+     * oldest turns.
+     */
+    contextBudget: ContextBudgetPolicy;
+    /**
+     * Fraction of the model context window to use as the hard cap when
+     * enforcing the budget. 0.8 leaves 20% headroom for the response.
+     */
+    contextBudgetRatio: number;
+}
+/**
+ * Global configuration for the FixO CLI.
+ * Persisted at `~/.fixocli/config.json`.
+ */
+export interface FreeLLMConfig {
+    freellmapi_api_key?: string;
+    apiUrl?: string;
+    defaultModel: string;
+    preferences: {
+        autoCommit: boolean;
+        streaming: boolean;
+        theme: 'dark' | 'light';
+        maxRetries: number;
+        policy: PolicyProfile;
+        telemetry: boolean;
+        /**
+         * Local NDJSON sink. Defaults to true. When false, no events are
+         * written to `~/.fixocli/telemetry.jsonl` — useful for users who
+         * want to keep their disk private but still want to send events
+         * to the remote sink.
+         */
+        telemetryLocal: boolean;
+        /**
+         * Remote HTTP sink (legacy). Defaults to false. When true, the
+         * legacy `logTelemetry` HTTP poster is re-enabled alongside the
+         * local sink. The free FixO API server collects anonymous usage
+         * stats so we can prioritise provider fixes.
+         */
+        telemetryRemote: boolean;
+        resilience: ResilienceConfig;
+        /**
+         * Safety preferences — orthogonal to `resilience`.
+         *
+         * - `resilience` keeps the system alive through network noise.
+         * - `safety`     keeps the system from corrupting the user's
+         *                 workspace or leaking secrets.
+         *
+         * Pillar 1 (loop-trap), Pillar 2 (atomic staging), and Pillar 3
+         * (LSP pre-save) are wired up here. Pillar 4 (credential vault)
+         * is a programmatic-only surface and is not user-configurable.
+         */
+        safety: SafetyConfig;
+    };
+    _firstRunComplete: boolean;
+}
+/** Returns the FixO CLI config directory (`~/.fixocli/`). */
+export declare function getConfigDir(): string;
+/** Returns the full path to the config file (`~/.fixocli/config.json`). */
+export declare function getConfigPath(): string;
+/** Returns the full path to the prompt history log (`~/.fixocli/history.jsonl`). */
+export declare function getHistoryPath(): string;
+/** Returns a complete default configuration object. */
+export declare function getDefaultConfig(): FreeLLMConfig;
+/**
+ * Reads `~/.fixocli/config.json` and returns the parsed config.
+ * If the file doesn't exist or is unreadable, a default config is returned
+ * instead — the caller can then decide whether to run the setup wizard.
+ */
+export declare function loadConfig(): FreeLLMConfig;
+/**
+ * Persists the given config to `~/.fixocli/config.json`.
+ * Creates the config directory if it doesn't already exist.
+ */
+export declare function saveConfig(config: FreeLLMConfig): void;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

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

package/dist/config.js

@@ -0,0 +1,138 @@
+import os from 'node:os';
+import fs from 'node:fs';
+import path from 'node:path';
+export const DEFAULT_API_URL = 'https://api.freellmapi.com/v1';
+// ---------------------------------------------------------------------------
+// Path helpers
+// ---------------------------------------------------------------------------
+/** Returns the FixO CLI config directory (`~/.fixocli/`). */
+export function getConfigDir() {
+    return path.join(os.homedir(), '.fixocli');
+}
+/** Returns the full path to the config file (`~/.fixocli/config.json`). */
+export function getConfigPath() {
+    return path.join(getConfigDir(), 'config.json');
+}
+/** Returns the full path to the prompt history log (`~/.fixocli/history.jsonl`). */
+export function getHistoryPath() {
+    return path.join(getConfigDir(), 'history.jsonl');
+}
+// ---------------------------------------------------------------------------
+// Config I/O
+// ---------------------------------------------------------------------------
+/** Returns a complete default configuration object. */
+export function getDefaultConfig() {
+    return {
+        defaultModel: 'auto',
+        preferences: {
+            autoCommit: false,
+            streaming: true,
+            theme: 'dark',
+            maxRetries: 3,
+            policy: 'shell-confirm',
+            telemetry: true,
+            telemetryLocal: true,
+            telemetryRemote: false,
+            resilience: {
+                streamResume: 'auto',
+                maxResumeAttempts: 3,
+                useWithRetry: true,
+                contextBudget: 'auto',
+                contextBudgetRatio: 0.8,
+            },
+            safety: {
+                atomicStaging: true,
+                stagingTtlMs: 24 * 60 * 60 * 1000,
+                lspPreSave: 'warn',
+                loopTrap: {
+                    triggerCount: 3,
+                    hardAbortCount: 6,
+                    toolResultTailBytes: 1024,
+                    maxHistory: 64,
+                    enabled: true,
+                },
+                semanticLoopTrap: {
+                    enabled: true,
+                    windowSize: 5,
+                    triggerCount: 3,
+                    hardAbortCount: 6,
+                },
+                largeFileGateBytes: 15 * 1024,
+                largeFileGateLines: 350,
+            },
+        },
+        _firstRunComplete: false,
+    };
+}
+/**
+ * Reads `~/.fixocli/config.json` and returns the parsed config.
+ * If the file doesn't exist or is unreadable, a default config is returned
+ * instead — the caller can then decide whether to run the setup wizard.
+ */
+export function loadConfig() {
+    const configPath = getConfigPath();
+    try {
+        const raw = fs.readFileSync(configPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        const defaults = getDefaultConfig();
+        // Merge top-level keys while keeping nested `preferences` safe.
+        // `resilience` and `safety` are deep-merged so old configs that
+        // predate a new field still pick up the new default.
+        const parsedPreferences = parsed.preferences ?? {};
+        const parsedResilience = parsedPreferences.resilience ?? {};
+        const parsedSafety = parsedPreferences.safety ?? {};
+        const parsedLoopTrap = parsedSafety.loopTrap ?? {};
+        const parsedSemanticLoopTrap = parsedSafety
+            .semanticLoopTrap ?? {};
+        return {
+            ...defaults,
+            ...parsed,
+            preferences: {
+                ...defaults.preferences,
+                ...parsedPreferences,
+                resilience: {
+                    ...defaults.preferences.resilience,
+                    ...parsedResilience,
+                },
+                safety: {
+                    ...defaults.preferences.safety,
+                    ...parsedSafety,
+                    loopTrap: {
+                        ...defaults.preferences.safety.loopTrap,
+                        ...parsedLoopTrap,
+                    },
+                    semanticLoopTrap: {
+                        ...defaults.preferences.safety.semanticLoopTrap,
+                        ...parsedSemanticLoopTrap,
+                    },
+                },
+            },
+        };
+    }
+    catch {
+        // File missing, corrupt, or otherwise unreadable — use defaults.
+        return getDefaultConfig();
+    }
+}
+/**
+ * Persists the given config to `~/.fixocli/config.json`.
+ * Creates the config directory if it doesn't already exist.
+ */
+export function saveConfig(config) {
+    const dir = getConfigDir();
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    const configPath = getConfigPath();
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', {
+        encoding: 'utf-8',
+        mode: 0o600,
+    });
+    try {
+        fs.chmodSync(configPath, 0o600);
+    }
+    catch {
+        // Ignore OS limitations
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/context/fixo-md-watcher.d.ts

@@ -0,0 +1,42 @@
+import { type FixoMdLoadResult } from './fixo-md.js';
+export type FixoMdWatchResult = {
+    kind: 'unchanged';
+} | {
+    kind: 'created';
+    block: string;
+    result: FixoMdLoadResult;
+} | {
+    kind: 'updated';
+    block: string;
+    result: FixoMdLoadResult;
+} | {
+    kind: 'deleted';
+    previousPath: string;
+};
+export declare class FixoMdWatcher {
+    private readonly cwd;
+    /** The fingerprint we last surfaced (or captured at construction). */
+    private lastSeen;
+    constructor(cwd: string);
+    /**
+     * Compare the current on-disk state to the last surfaced
+     * fingerprint and return the delta. Internal state advances on
+     * non-`unchanged` results so a single change is announced once.
+     */
+    check(): FixoMdWatchResult;
+    /**
+     * Render a watch result into an injectable directive, or null
+     * when nothing should be surfaced. Matches the directive shape
+     * used by the safety alert and background-jobs awareness so the
+     * agent model already knows how to parse it.
+     */
+    formatDirective(watch: FixoMdWatchResult): string | null;
+}
+/**
+ * Convenience wrapper for tests + callers that don't need the
+ * persistent watcher state.
+ *
+ * @internal
+ */
+export declare function readFixoMd(cwd: string): FixoMdLoadResult;
+//# sourceMappingURL=fixo-md-watcher.d.ts.map

package/dist/context/fixo-md-watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixo-md-watcher.d.ts","sourceRoot":"","sources":["../../src/context/fixo-md-watcher.ts"],"names":[],"mappings":"AAoBA,OAAO,EAIL,KAAK,gBAAgB,EAEtB,MAAM,cAAc,CAAC;AActB,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAA;CAAE,GAC5D;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAA;CAAE,GAC5D;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC;AAgC9C,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,sEAAsE;IACtE,OAAO,CAAC,QAAQ,CAAyB;gBAE7B,GAAG,EAAE,MAAM;IASvB;;;;OAIG;IACH,KAAK,IAAI,iBAAiB;IAkC1B;;;;;OAKG;IACH,eAAe,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,GAAG,IAAI;CAqBzD;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAExD"}

package/dist/context/fixo-md-watcher.js

@@ -0,0 +1,126 @@
+/**
+ * fixo-md-watcher.ts — Phase 4: per-turn re-injection of FIXO.md
+ * changes.
+ *
+ * The system prompt bakes the FIXO.md content in at run start, so
+ * a long-running agent loop normally never sees later edits. This
+ * watcher closes that gap by stat-checking the active FIXO.md
+ * before each `chat()` call and emitting a delta when the file is
+ * created, updated, or removed mid-run.
+ *
+ * Why a delta model instead of always re-injecting? The full
+ * contents already live in the system prompt; re-sending them on
+ * every turn would double the token cost without any new signal.
+ * The watcher injects only when the on-disk file no longer matches
+ * what the prompt currently reflects.
+ *
+ * Pure read: stats, optional read, and an in-memory cursor. No
+ * `fs.watch`, no subprocesses, no globals.
+ */
+import fs from 'node:fs';
+import { buildProjectInstructionsBlock, findFixoMdPath, loadProjectInstructions, } from './fixo-md.js';
+/* ──────────────────────── helpers ──────────────────────── */
+function fingerprint(cwd) {
+    const found = findFixoMdPath(cwd);
+    if (found.path === null)
+        return null;
+    let stat;
+    try {
+        stat = fs.statSync(found.path);
+    }
+    catch {
+        return null;
+    }
+    return {
+        path: found.path,
+        source: found.source,
+        mtimeMs: stat.mtimeMs,
+        bytes: stat.size,
+    };
+}
+function fingerprintsEqual(a, b) {
+    return (a.path === b.path &&
+        a.source === b.source &&
+        a.mtimeMs === b.mtimeMs &&
+        a.bytes === b.bytes);
+}
+/* ──────────────────────── watcher ──────────────────────── */
+export class FixoMdWatcher {
+    cwd;
+    /** The fingerprint we last surfaced (or captured at construction). */
+    lastSeen;
+    constructor(cwd) {
+        this.cwd = cwd;
+        // Snapshot the baseline so the very first `check()` after the
+        // agent loop starts returns 'unchanged' for files that were
+        // already present. Those files are already baked into the
+        // system prompt by `buildSystemPrompt`.
+        this.lastSeen = fingerprint(cwd);
+    }
+    /**
+     * Compare the current on-disk state to the last surfaced
+     * fingerprint and return the delta. Internal state advances on
+     * non-`unchanged` results so a single change is announced once.
+     */
+    check() {
+        const current = fingerprint(this.cwd);
+        const previous = this.lastSeen;
+        // Both null → nothing on disk now or before. Quiet path.
+        if (current === null && previous === null) {
+            return { kind: 'unchanged' };
+        }
+        // File appeared (or moved into the chain) mid-run.
+        if (current !== null && previous === null) {
+            const { block, result } = buildProjectInstructionsBlock(this.cwd);
+            this.lastSeen = current;
+            return { kind: 'created', block, result };
+        }
+        // File disappeared mid-run.
+        if (current === null && previous !== null) {
+            const previousPath = previous.path;
+            this.lastSeen = null;
+            return { kind: 'deleted', previousPath };
+        }
+        // Both non-null. If fingerprint matches we're done.
+        if (current !== null && previous !== null && fingerprintsEqual(current, previous)) {
+            return { kind: 'unchanged' };
+        }
+        // Otherwise: content (or path / source) changed.
+        const { block, result } = buildProjectInstructionsBlock(this.cwd);
+        this.lastSeen = current;
+        return { kind: 'updated', block, result };
+    }
+    /**
+     * Render a watch result into an injectable directive, or null
+     * when nothing should be surfaced. Matches the directive shape
+     * used by the safety alert and background-jobs awareness so the
+     * agent model already knows how to parse it.
+     */
+    formatDirective(watch) {
+        if (watch.kind === 'unchanged')
+            return null;
+        if (watch.kind === 'deleted') {
+            return (`[Project Instructions]\n` +
+                `The FIXO.md previously loaded from \`${watch.previousPath}\` was ` +
+                `removed mid-run. Stop relying on its rules until a new one appears.`);
+        }
+        // Created or updated — surface the block verbatim under a
+        // labelled header so the LLM sees this is a refresh, not a
+        // duplicate of what's in the system prompt.
+        const verb = watch.kind === 'created' ? 'now available' : 'updated mid-run';
+        const sourceLine = watch.result.path ?? '(unknown path)';
+        return (`[Project Instructions]\n` +
+            `FIXO.md is ${verb}. Source: ${sourceLine}.\n` +
+            `Latest content:\n${watch.block.trim()}`);
+    }
+}
+/**
+ * Convenience wrapper for tests + callers that don't need the
+ * persistent watcher state.
+ *
+ * @internal
+ */
+export function readFixoMd(cwd) {
+    return loadProjectInstructions(cwd);
+}
+//# sourceMappingURL=fixo-md-watcher.js.map

package/dist/context/fixo-md-watcher.js.map

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

package/dist/context/fixo-md.d.ts

@@ -0,0 +1,50 @@
+export type FixoMdSource = 'project-fixo' | 'project-cwd' | 'global' | 'none';
+export interface FixoMdLoadResult {
+    /** The path that won, or null when no FIXO.md was found. */
+    readonly source: FixoMdSource;
+    /** Absolute path of the file that was loaded, when source !== 'none'. */
+    readonly path: string | null;
+    /** Raw file content. Empty string when source === 'none'. */
+    readonly content: string;
+    /** Byte size of the loaded file. 0 when source === 'none'. */
+    readonly bytes: number;
+}
+/**
+ * Search the lookup chain and return the first match. Does not
+ * read the file — the caller decides whether to read it
+ * synchronously or stream it.
+ */
+export declare function findFixoMdPath(cwd: string): {
+    source: FixoMdSource;
+    path: string | null;
+};
+/**
+ * Read the FIXO.md content from the first match in the lookup
+ * chain. Returns `{ source: 'none', ... }` when no file exists.
+ *
+ * Best-effort sandboxing: each candidate is read through the
+ * platform's `fs.readFileSync` and capped at 1 MiB so a runaway
+ * file cannot OOM the agent.
+ */
+export declare function loadProjectInstructions(cwd: string): FixoMdLoadResult;
+/**
+ * Build the `<project-instructions>` block that is appended to
+ * the agent's system prompt. The block is wrapped in clearly
+ * labelled fences so the LLM cannot confuse it with the
+ * platform-managed system prompt.
+ *
+ * The block is empty when no FIXO.md was found; callers can
+ * detect this by inspecting `source === 'none'`.
+ */
+export declare function buildProjectInstructionsBlock(cwd: string): {
+    block: string;
+    result: FixoMdLoadResult;
+};
+/**
+ * Best-effort telemetry emission. Imported lazily so a missing
+ * `telemetry.js` (e.g. during early bootstrap) never blocks
+ * the loader. Errors are swallowed — telemetry must never
+ * break a tool call.
+ */
+export declare function recordFixoMdLoad(result: FixoMdLoadResult): Promise<void>;
+//# sourceMappingURL=fixo-md.d.ts.map

package/dist/context/fixo-md.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixo-md.d.ts","sourceRoot":"","sources":["../../src/context/fixo-md.ts"],"names":[],"mappings":"AAsBA,MAAM,MAAM,YAAY,GAAG,cAAc,GAAG,aAAa,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE9E,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAID;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAiBzF;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAkBrE;AAID;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,MAAM,GAAG;IAC1D,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,gBAAgB,CAAC;CAC1B,CAeA;AAID;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAY9E"}

package/dist/context/fixo-md.js

@@ -0,0 +1,118 @@
+/**
+ * FIXO.md loader — Phase 2 deliverable.
+ *
+ * Convention: a single, optional `FIXO.md` (or `.fixo/FIXO.md`)
+ * provides project-local instructions for the agent. The
+ * loader reads it from a deterministic lookup chain and
+ * surfaces the loaded content to the system-prompt builder.
+ *
+ * Lookup order (first hit wins):
+ *   1. `<cwd>/.fixo/FIXO.md`
+ *   2. `<cwd>/FIXO.md`
+ *   3. `~/.fixocli/FIXO.md`
+ *
+ * The loader is *additive* — `AgentContext.systemPromptOverride`
+ * still wins if the caller already supplied one. The FIXO.md
+ * content is appended under a clearly-labelled
+ * `<project-instructions>` block.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { getConfigDir } from '../config.js';
+/* ──────────────────────── lookup chain ──────────────────────── */
+/**
+ * Search the lookup chain and return the first match. Does not
+ * read the file — the caller decides whether to read it
+ * synchronously or stream it.
+ */
+export function findFixoMdPath(cwd) {
+    const candidates = [
+        { source: 'project-fixo', p: path.join(cwd, '.fixo', 'FIXO.md') },
+        { source: 'project-cwd', p: path.join(cwd, 'FIXO.md') },
+        { source: 'global', p: path.join(getConfigDir(), 'FIXO.md') },
+    ];
+    for (const c of candidates) {
+        try {
+            const stat = fs.statSync(c.p);
+            if (stat.isFile() && stat.size > 0) {
+                return { source: c.source, path: c.p };
+            }
+        }
+        catch {
+            // ENOENT or permission denied — try the next candidate.
+        }
+    }
+    return { source: 'none', path: null };
+}
+/**
+ * Read the FIXO.md content from the first match in the lookup
+ * chain. Returns `{ source: 'none', ... }` when no file exists.
+ *
+ * Best-effort sandboxing: each candidate is read through the
+ * platform's `fs.readFileSync` and capped at 1 MiB so a runaway
+ * file cannot OOM the agent.
+ */
+export function loadProjectInstructions(cwd) {
+    const found = findFixoMdPath(cwd);
+    if (found.path === null) {
+        return { source: 'none', path: null, content: '', bytes: 0 };
+    }
+    let content;
+    try {
+        content = fs.readFileSync(found.path, 'utf-8');
+    }
+    catch {
+        return { source: 'none', path: found.path, content: '', bytes: 0 };
+    }
+    const bytes = Buffer.byteLength(content, 'utf-8');
+    return {
+        source: found.source,
+        path: found.path,
+        content,
+        bytes,
+    };
+}
+/* ──────────────────────── prompt block ──────────────────────── */
+/**
+ * Build the `<project-instructions>` block that is appended to
+ * the agent's system prompt. The block is wrapped in clearly
+ * labelled fences so the LLM cannot confuse it with the
+ * platform-managed system prompt.
+ *
+ * The block is empty when no FIXO.md was found; callers can
+ * detect this by inspecting `source === 'none'`.
+ */
+export function buildProjectInstructionsBlock(cwd) {
+    const result = loadProjectInstructions(cwd);
+    if (result.source === 'none' || result.content.length === 0) {
+        return { block: '', result };
+    }
+    const header = result.source === 'global'
+        ? 'Global instructions (from ~/.fixocli/FIXO.md)'
+        : `Project instructions (from ${result.path ?? 'FIXO.md'})`;
+    const block = `\n\n<project-instructions source="${result.source}">\n` +
+        `## ${header}\n\n` +
+        `${result.content.trim()}\n` +
+        `</project-instructions>\n`;
+    return { block, result };
+}
+/* ──────────────────────── telemetry ──────────────────────── */
+/**
+ * Best-effort telemetry emission. Imported lazily so a missing
+ * `telemetry.js` (e.g. during early bootstrap) never blocks
+ * the loader. Errors are swallowed — telemetry must never
+ * break a tool call.
+ */
+export async function recordFixoMdLoad(result) {
+    try {
+        const { recordTelemetry, telemetry } = await import('../agent/telemetry.js');
+        recordTelemetry(telemetry.fixoMdLoaded({
+            source: result.source,
+            bytes: result.bytes,
+        }));
+    }
+    catch {
+        // ignore
+    }
+}
+//# sourceMappingURL=fixo-md.js.map