fixo-cli 1.0.0

package/dist/agent/subagent.js

@@ -0,0 +1,193 @@
+/**
+ * subagent.ts — Isolated WorkerAgent driver.
+ *
+ * Phase 3.2: lets the parent agent delegate a sub-task to a
+ * fresh WorkerAgent whose conversation history is *not* shared
+ * with the parent. The subagent runs in BUILD mode (mutating
+ * allowed) regardless of the parent's mode, and returns a
+ * structured {@link SubagentResult} whose `transcript` field
+ * carries only the final summary — never the raw tool log —
+ * so the parent's context never bloats.
+ *
+ * Safety:
+ *   - `selectedFiles` is replaced with the caller-supplied
+ *     `contextFiles` (default: empty). The parent cannot leak
+ *     its own pin-set into the subagent.
+ *   - The subagent always runs in BUILD mode and inherits the
+ *     parent's `cwd` and `policy`.
+ *   - The subagent's own policy/permission engine still gates
+ *     every tool call — there is no escape hatch.
+ *   - If `runInBackground` is true, the spawn is fire-and-forget
+ *     and a `jobId` is returned. The caller can poll via the
+ *     shared BackgroundJobRegistry (Phase 3.1).
+ */
+import { randomUUID } from 'node:crypto';
+import { WorkerAgent } from './worker-agent.js';
+import { recordTelemetry, telemetry } from './telemetry.js';
+const DEFAULT_INTERNAL_OPTIONS = {
+    summaryOnly: true,
+    cleanHistory: true,
+};
+const MAX_LOCAL_TOOL_CALLS_DEFAULT = 15;
+/**
+ * Spawn a subagent. Returns immediately when `runInBackground`
+ * is true; otherwise awaits the subagent's completion and
+ * returns its final summary.
+ */
+export async function spawnSubagent(req, parentCtx, internalOpts = {}) {
+    const opts = { ...DEFAULT_INTERNAL_OPTIONS, ...internalOpts };
+    const start = Date.now();
+    const id = `subagent_${randomUUID().slice(0, 8)}`;
+    // The subagent inherits the parent's cwd and policy but
+    // gets a *fresh* AgentContext. selectedFiles is replaced
+    // with the caller's contextFiles (default empty) so the
+    // parent cannot leak its pin-set.
+    const subagentCtx = {
+        task: req.task,
+        model: parentCtx.model,
+        cwd: parentCtx.cwd,
+        verbose: parentCtx.verbose,
+        selectedFiles: req.contextFiles ? [...req.contextFiles] : [],
+        systemPromptOverride: undefined, // never inherit the parent's override
+        checkCommand: undefined,
+        policy: parentCtx.policy,
+        yes: parentCtx.yes,
+        // Phase 3.2 hard rule: subagents are always mutating.
+        mode: 'BUILD',
+    };
+    if (req.runInBackground) {
+        // Fire-and-forget. The caller polls by jobId.
+        void runSubagentInBackground(id, req, subagentCtx, opts, start);
+        return {
+            success: true,
+            summary: '(subagent running in background)',
+            tokensUsed: { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 },
+            toolCallCount: 0,
+            durationMs: 0,
+            type: req.type,
+            transcript: '',
+            jobId: id,
+        };
+    }
+    return await runSubagentInline(id, req, subagentCtx, opts, start);
+}
+async function runSubagentInline(id, req, subagentCtx, _opts, start) {
+    const subtask = {
+        id,
+        title: req.task.slice(0, 80),
+        description: req.task,
+        persona: 'code',
+        dependencies: [],
+        files: req.contextFiles ?? [],
+        status: 'running',
+    };
+    const worker = new WorkerAgent(subagentCtx.verbose);
+    const noopBudget = () => undefined;
+    try {
+        const inner = await worker.run(subagentCtx, subtask, noopBudget);
+        const durationMs = Date.now() - start;
+        const tokensUsed = inner.tokensUsed;
+        const summary = extractSummary(inner.output);
+        recordTelemetry(telemetry.subagentSummary({
+            taskType: req.type,
+            inputTokens: tokensUsed.prompt_tokens,
+            outputTokens: tokensUsed.completion_tokens,
+            durationMs,
+        }));
+        return {
+            success: inner.success,
+            summary,
+            tokensUsed,
+            toolCallCount: inner.toolCallCount,
+            durationMs,
+            type: req.type,
+            transcript: opts_transcript(inner.output, summary),
+        };
+    }
+    catch (err) {
+        const msg = err.message ?? String(err);
+        recordTelemetry(telemetry.subagentSummary({
+            taskType: req.type,
+            inputTokens: 0,
+            outputTokens: 0,
+            durationMs: Date.now() - start,
+        }));
+        return {
+            success: false,
+            summary: `Subagent failed: ${msg}`,
+            tokensUsed: { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 },
+            toolCallCount: 0,
+            durationMs: Date.now() - start,
+            type: req.type,
+            transcript: '',
+        };
+    }
+}
+async function runSubagentInBackground(id, req, subagentCtx, opts, start) {
+    try {
+        const result = await runSubagentInline(id, req, subagentCtx, opts, start);
+        // Stash the result in a small global in-memory cache so
+        // `/jobs` or a future `poll_subagent` can read it back.
+        backgroundSubagentResults.set(id, result);
+    }
+    catch (err) {
+        backgroundSubagentResults.set(id, {
+            success: false,
+            summary: `Subagent crashed: ${err.message}`,
+            tokensUsed: { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 },
+            toolCallCount: 0,
+            durationMs: Date.now() - start,
+            type: req.type,
+            transcript: '',
+        });
+    }
+}
+const backgroundSubagentResults = new Map();
+/** Read the latest result for a background subagent. */
+export function getBackgroundSubagentResult(jobId) {
+    return backgroundSubagentResults.get(jobId) ?? null;
+}
+/** Clear the background subagent cache (test-only). */
+export function _resetBackgroundSubagents() {
+    backgroundSubagentResults.clear();
+}
+/**
+ * Build the subagent's `AgentContext` from the parent context
+ * and a request. Exposed for testability — the actual subagent
+ * is constructed inside `spawnSubagent`.
+ *
+ * Invariants locked by Phase 3.2:
+ *   - `mode` is forced to 'BUILD'
+ *   - `selectedFiles` is replaced by `req.contextFiles` (or [])
+ *   - `systemPromptOverride` is dropped
+ *   - `cwd`, `policy`, `yes`, `model`, `verbose` are inherited
+ */
+export function buildSubagentContext(req, parentCtx) {
+    return {
+        task: req.task,
+        model: parentCtx.model,
+        cwd: parentCtx.cwd,
+        verbose: parentCtx.verbose,
+        selectedFiles: req.contextFiles ? [...req.contextFiles] : [],
+        systemPromptOverride: undefined,
+        checkCommand: undefined,
+        policy: parentCtx.policy,
+        yes: parentCtx.yes,
+        mode: 'BUILD',
+    };
+}
+/* ──────────────────────── helpers ──────────────────────── */
+function extractSummary(rawOutput) {
+    // The WorkerAgent returns the assistant's final `content`
+    // field. When `summaryOnly` is on, this is the only piece
+    // of output the parent gets to see. We do *not* parse the
+    // raw output further — that would risk leaking tool log.
+    return rawOutput.trim();
+}
+function opts_transcript(rawOutput, summary) {
+    // When `summaryOnly` is true, transcript === summary. We
+    // still pass the raw output as a fallback so the parent
+    // can recover more context if it asks for it explicitly.
+    return summary.length > 0 ? summary : rawOutput;
+}
+//# sourceMappingURL=subagent.js.map

package/dist/agent/subagent.js.map

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

package/dist/agent/telemetry.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Telemetry — local NDJSON sink + on-demand failure diagnosis.
+ *
+ * The original `logTelemetry` shipped a remote-only HTTP poster to
+ * the FreeLLMAPI server. Pillar 5 (Telemetry) replaces it with a
+ * first-class, *local-first* event store:
+ *
+ *   - All events are appended to `~/.fixocli/telemetry.jsonl` in
+ *     newline-delimited JSON. One event per line, easy to tail,
+ *     grep, and post-process.
+ *   - The legacy remote poster is preserved as an opt-in
+ *     secondary sink (controlled by `preferences.telemetryRemote`).
+ *   - The on-disk log is rotated at 1 MiB with a single `.1`
+ *     backup, so disk usage is bounded.
+ *   - `diagnoseFailures(windowMs)` reads the last N events and
+ *     produces human-readable remediation hints — useful for
+ *     `/diagnose` slash commands and for the post-mortem shown
+ *     when a tool call exhausts its budget.
+ *
+ * The module is *side-effect free at import time*; the file is
+ * opened lazily on first write so the CLI cold-start is unaffected.
+ *
+ * The previous public surface — `logTelemetry(payload)` and the
+ * `TelemetryPayload` interface — is preserved so the 7 existing
+ * callsites in `worker-agent.ts` and `agent-pool.ts` keep working
+ * without modification. New code should prefer `TelemetrySink`
+ * directly.
+ */
+/** Discriminated union of every event the system can emit. */
+export type TelemetryEventType = 'tool_call' | 'session_start' | 'session_end' | 'retry' | 'cooldown' | 'stream_resume' | 'stream_resume_exhausted' | 'context_budget' | 'provider_error' | 'tool_surgical_edit' | 'tool_glob' | 'tool_async_spawn' | 'subagent_summary' | 'fixo_md_loaded' | 'todo_mutation' | 'session_snapshot' | 'hook_fired' | 'permission_decision';
+export interface TelemetryEvent {
+    /** ISO timestamp the event was recorded. */
+    readonly ts: string;
+    /** Discriminator — see {@link TelemetryEventType}. */
+    readonly type: TelemetryEventType;
+    /** Stable, anonymised machine id (not the user's hostname). */
+    readonly sid: string;
+    /** Free-form fields. The shape depends on `type`; see the
+     *  per-type helpers below for ergonomic constructors. */
+    readonly fields: Readonly<Record<string, unknown>>;
+}
+/** Legacy payload shape preserved for `logTelemetry` compatibility. */
+export interface TelemetryPayload {
+    id: string;
+    tool: string;
+    arguments: unknown;
+    status: 'started' | 'completed' | 'failed';
+    error?: string;
+    originalContent?: string;
+    newContent?: string;
+}
+export declare const telemetry: {
+    toolCall(fields: {
+        tool: string;
+        status: "started" | "completed" | "failed";
+        error?: string;
+        durationMs?: number;
+    }): TelemetryEvent;
+    retry(fields: {
+        fn: string;
+        attempt: number;
+        delayMs: number;
+        error: string;
+    }): TelemetryEvent;
+    cooldown(fields: {
+        providerId: string;
+        status: number | string;
+        cooldownMs: number;
+        reason: string;
+    }): TelemetryEvent;
+    streamResume(fields: {
+        resumeAttempt: number;
+        partialTokens: number;
+        ok: boolean;
+        reason?: string;
+    }): TelemetryEvent;
+    contextBudget(fields: {
+        tokensBefore: number;
+        tokensAfter: number;
+        actions: string[];
+        markedForCompaction: boolean;
+    }): TelemetryEvent;
+    providerError(fields: {
+        providerId: string;
+        status: number;
+        message: string;
+    }): TelemetryEvent;
+    sessionStart(fields: {
+        model: string;
+        cwd: string;
+    }): TelemetryEvent;
+    sessionEnd(fields: {
+        durationMs: number;
+        toolCalls: number;
+        totalTokens: number;
+    }): TelemetryEvent;
+    surgicalEdit(fields: {
+        path: string;
+        occurrences: number;
+        mode: string;
+        bytes: number;
+    }): TelemetryEvent;
+    glob(fields: {
+        pattern: string;
+        returned: number;
+        truncated: boolean;
+    }): TelemetryEvent;
+    fixoMdLoaded(fields: {
+        source: string;
+        bytes: number;
+    }): TelemetryEvent;
+    todoMutation(fields: {
+        op: string;
+        items: number;
+        id?: string;
+    }): TelemetryEvent;
+    sessionSnapshot(fields: {
+        id: string;
+        op: "save" | "load";
+        tokens: number;
+        items: number;
+    }): TelemetryEvent;
+    asyncSpawn(fields: {
+        jobId: string;
+        cmd: string;
+        pid?: number;
+    }): TelemetryEvent;
+    subagentSummary(fields: {
+        taskType: string;
+        inputTokens: number;
+        outputTokens: number;
+        durationMs: number;
+    }): TelemetryEvent;
+    hookFired(fields: {
+        hook: string;
+        phase: "pre" | "post";
+        matched: boolean;
+        durationMs: number;
+    }): TelemetryEvent;
+    permissionDecision(fields: {
+        tool: string;
+        pattern: string;
+        decision: string;
+    }): TelemetryEvent;
+};
+/** Path to the local NDJSON sink. Exposed for tests and the
+ *  `/diagnose` slash command. */
+export declare function getTelemetryPath(): string;
+/**
+ * Append an event to the local NDJSON sink. The file is opened in
+ * append mode for every write — the cost of an open/close cycle
+ * is negligible compared to the JSON.stringify call.
+ *
+ * Returns true on success, false on any error. Errors are swallowed
+ * because telemetry must never break the calling code.
+ */
+export declare function recordTelemetry(event: TelemetryEvent): boolean;
+/** Read the last N events (most recent last). Safe to call when the
+ *  file is missing or empty — returns []. */
+export declare function readRecentEvents(limit?: number): TelemetryEvent[];
+/** Clear the local sink. Test-only; not exposed in the UI. */
+export declare function clearTelemetry(): void;
+export interface DiagnosisHint {
+    /** Short, human-readable summary. */
+    readonly summary: string;
+    /** Severity: info | warn | error. */
+    readonly severity: 'info' | 'warn' | 'error';
+    /** Number of matching events in the window. */
+    readonly count: number;
+    /** Suggested action for the user. */
+    readonly suggestion: string;
+}
+/**
+ * Scan the recent event window and return a prioritised list of
+ * remediation hints. Pure function — does not modify state.
+ *
+ * Rules implemented:
+ *   - 3+ retries in the window       → "Flaky network or rate-limit" (warn)
+ *   - 1+ cooldown event              → "Provider X is rate-limited" (warn)
+ *   - 1+ stream_resume_exhausted     → "Stream cuts not recovering" (error)
+ *   - 1+ context_budget with compact → "Context is filling up" (info)
+ *   - 3+ tool_call failures of same tool → "Tool X keeps failing" (warn)
+ *   - 5+ provider_error in window    → "Provider outage" (error)
+ */
+export declare function diagnoseFailures(windowMs?: number): DiagnosisHint[];
+/**
+ * @deprecated Prefer the typed helpers on the `telemetry` object and
+ * `recordTelemetry()` directly. This wrapper maps a `TelemetryPayload`
+ * to a `tool_call` event.
+ */
+export declare function logTelemetry(payload: TelemetryPayload): Promise<void>;
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/agent/telemetry.d.ts.map

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