@gracker/smartperfetto 1.0.13

package/dist/agentv3/selfImprove/promoteSkillNote.js

@@ -0,0 +1,146 @@
+"use strict";
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2024-2026 Gracker (Chris)
+// This file is part of SmartPerfetto. See LICENSE for details.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.promoteSkillNote = promoteSkillNote;
+/**
+ * CLI to promote a runtime skill note (under logs/skill_notes/) to the
+ * curated baseline (backend/skills/curated_skill_notes/) which is checked
+ * into git. The promoted note is removed from the runtime file so it
+ * doesn't double-count at injection time.
+ *
+ * Usage:
+ *   npx tsx src/agentv3/selfImprove/promoteSkillNote.ts <skillId> <noteId> [--dry-run]
+ *
+ * The runtime file lives in `logs/` (gitignored) so skill notes don't
+ * pollute repo history with auto-generated content. Promotion is a manual
+ * gate — a human reviews the note and explicitly elevates it.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const skillNotesWriter_1 = require("./skillNotesWriter");
+const runtimePaths_1 = require("../../runtimePaths");
+const RUNTIME_DIR = (0, runtimePaths_1.backendLogPath)('skill_notes');
+const CURATED_DIR = path.resolve(__dirname, '..', '..', '..', 'skills', 'curated_skill_notes');
+/**
+ * Move a single note from runtime → curated. Idempotent: a second call with
+ * the same arguments is a no-op once the runtime entry is gone.
+ */
+function promoteSkillNote(skillId, noteId, opts = {}) {
+    const runtimeDir = opts.runtimeDir ?? RUNTIME_DIR;
+    const curatedDir = opts.curatedDir ?? CURATED_DIR;
+    const runtimeFile = path.join(runtimeDir, `${skillId}.notes.json`);
+    const curatedFile = path.join(curatedDir, `${skillId}.notes.json`);
+    if (!fs.existsSync(runtimeFile)) {
+        return { ok: false, reason: 'skill_not_found', details: `${runtimeFile} does not exist` };
+    }
+    const runtime = (0, skillNotesWriter_1.readSkillNotesFile)(runtimeFile);
+    const noteIdx = runtime.notes.findIndex(n => n.id === noteId);
+    if (noteIdx < 0) {
+        return { ok: false, reason: 'note_not_found', details: `noteId ${noteId} not found in ${runtimeFile}` };
+    }
+    const note = runtime.notes[noteIdx];
+    const curated = fs.existsSync(curatedFile)
+        ? (0, skillNotesWriter_1.readSkillNotesFile)(curatedFile)
+        : { schemaVersion: 1, skillId, notes: [], lastUpdated: 0, totalBytes: 0 };
+    if (curated.notes.some(n => n.id === note.id)) {
+        return { ok: false, reason: 'already_curated', details: `note ${note.id} already in curated baseline` };
+    }
+    if (opts.dryRun) {
+        return {
+            ok: true,
+            curatedPath: curatedFile,
+            details: 'dry-run — no files modified',
+        };
+    }
+    try {
+        if (!fs.existsSync(curatedDir))
+            fs.mkdirSync(curatedDir, { recursive: true });
+        const updatedCurated = {
+            ...curated,
+            notes: [...curated.notes, note],
+            lastUpdated: Date.now(),
+        };
+        updatedCurated.totalBytes = Buffer.byteLength(JSON.stringify(updatedCurated, null, 2), 'utf-8');
+        atomicWrite(curatedFile, updatedCurated);
+        const updatedRuntime = {
+            ...runtime,
+            notes: runtime.notes.filter(n => n.id !== note.id),
+            lastUpdated: Date.now(),
+        };
+        updatedRuntime.totalBytes = Buffer.byteLength(JSON.stringify(updatedRuntime, null, 2), 'utf-8');
+        atomicWrite(runtimeFile, updatedRuntime);
+        return { ok: true, curatedPath: curatedFile };
+    }
+    catch (err) {
+        return { ok: false, reason: 'io_error', details: err.message };
+    }
+}
+function atomicWrite(file, data) {
+    const tmp = `${file}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2));
+    fs.renameSync(tmp, file);
+}
+function printUsage() {
+    console.error('Usage: npx tsx src/agentv3/selfImprove/promoteSkillNote.ts <skillId> <noteId> [--dry-run]');
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length < 2) {
+        printUsage();
+        process.exit(2);
+    }
+    const [skillId, noteId, ...rest] = args;
+    const dryRun = rest.includes('--dry-run');
+    const result = promoteSkillNote(skillId, noteId, { dryRun });
+    if (result.ok) {
+        console.log(`[promote] ${dryRun ? 'would promote' : 'promoted'} ${skillId}/${noteId}`);
+        if (result.curatedPath)
+            console.log(`[promote] target: ${result.curatedPath}`);
+    }
+    else {
+        console.error(`[promote] failed (${result.reason}): ${result.details}`);
+        process.exit(1);
+    }
+}
+if (require.main === module) {
+    main().catch(err => {
+        console.error('[promote] unhandled:', err);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=promoteSkillNote.js.map

package/dist/agentv3/selfImprove/promoteSkillNote.js.map

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

package/dist/agentv3/selfImprove/proposeStrategyPatch.d.ts

@@ -0,0 +1,40 @@
+import { type PhaseHintProposal } from './phaseHintsRenderer';
+import { type WorktreeHandle } from './worktreeRunner';
+export interface ProposeStrategyPatchInput {
+    /** Validated proposal from the review agent. */
+    proposal: PhaseHintProposal;
+    /** Scene whose strategy file to patch (e.g. `scrolling`, `startup`). */
+    scene: string;
+    /** Unique job id (matches worktreeRunner's whitelist regex). */
+    jobId: string;
+    /** Optional: override the validation step (used by tests). */
+    validate?: (handle: WorktreeHandle) => Promise<{
+        ok: boolean;
+        details?: string;
+    }>;
+    /** Optional: override the tool registry passed to the renderer. */
+    toolRegistry?: ReadonlySet<string>;
+    /** Override repo root — for tests. */
+    workingDir?: string;
+}
+export type ProposeRejectReason = 'render_failed' | 'worktree_failed' | 'patch_failed' | 'validation_failed';
+export type ProposeResult = {
+    ok: true;
+    handle: WorktreeHandle;
+    patchFingerprint: string;
+    phaseHintId: string;
+    renderedYaml: string;
+    strategyFilePath: string;
+} | {
+    ok: false;
+    reason: ProposeRejectReason;
+    details: string;
+};
+/**
+ * Drive the full pipeline. On success, the worktree is left intact so the
+ * caller can run downstream checks; the worktree handle is returned for
+ * cleanup. On failure, the worktree is cleaned up (if it was opened) and a
+ * structured reason is returned — never throws.
+ */
+export declare function proposeStrategyPatch(input: ProposeStrategyPatchInput): Promise<ProposeResult>;
+//# sourceMappingURL=proposeStrategyPatch.d.ts.map

package/dist/agentv3/selfImprove/proposeStrategyPatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proposeStrategyPatch.d.ts","sourceRoot":"","sources":["../../../src/agentv3/selfImprove/proposeStrategyPatch.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAmB,KAAK,iBAAiB,EAAqB,MAAM,sBAAsB,CAAC;AAElG,OAAO,EAAkC,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvF,MAAM,WAAW,yBAAyB;IACxC,gDAAgD;IAChD,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClF,mEAAmE;IACnE,YAAY,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACnC,sCAAsC;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,MAAM,mBAAmB,GAC3B,eAAe,GACf,iBAAiB,GACjB,cAAc,GACd,mBAAmB,CAAC;AAExB,MAAM,MAAM,aAAa,GACrB;IACE,EAAE,EAAE,IAAI,CAAC;IACT,MAAM,EAAE,cAAc,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;CAC1B,GACD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhE;;;;;GAKG;AACH,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,yBAAyB,GAAG,OAAO,CAAC,aAAa,CAAC,CAiDnG"}

package/dist/agentv3/selfImprove/proposeStrategyPatch.js

@@ -0,0 +1,115 @@
+"use strict";
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2024-2026 Gracker (Chris)
+// This file is part of SmartPerfetto. See LICENSE for details.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.proposeStrategyPatch = proposeStrategyPatch;
+/**
+ * High-level orchestrator that turns a review-agent JSON proposal into a
+ * patch landed inside an isolated git worktree. The actual git push +
+ * GitHub PR creation lives outside this module — once the worktree is
+ * verified, the caller (or an operator) takes over.
+ *
+ * The five-step pipeline:
+ *   1. Render the proposal via phaseHintsRenderer (deterministic YAML).
+ *   2. Open a tmp worktree via worktreeRunner (PR3).
+ *   3. Apply the rendered entry to the target strategy file.
+ *   4. Run a validation hook (typically `validate:strategies`).
+ *   5. Return success + the worktree handle, or failure with a structured
+ *      reason. Worktree cleanup is the caller's responsibility on success
+ *      so they can run heavier downstream checks (regression, e2e) before
+ *      pushing the branch.
+ *
+ * See docs/architecture/self-improving-design.md §13.2 (Worktree isolation), §13 (PR9c).
+ */
+const path = __importStar(require("path"));
+const phaseHintsRenderer_1 = require("./phaseHintsRenderer");
+const strategyPatchApplier_1 = require("./strategyPatchApplier");
+const worktreeRunner_1 = require("./worktreeRunner");
+/**
+ * Drive the full pipeline. On success, the worktree is left intact so the
+ * caller can run downstream checks; the worktree handle is returned for
+ * cleanup. On failure, the worktree is cleaned up (if it was opened) and a
+ * structured reason is returned — never throws.
+ */
+async function proposeStrategyPatch(input) {
+    const renderResult = (0, phaseHintsRenderer_1.renderPhaseHint)(input.proposal, { toolRegistry: input.toolRegistry });
+    if (!renderResult.ok) {
+        return { ok: false, reason: 'render_failed', details: `${renderResult.reason}: ${renderResult.details}` };
+    }
+    const rendered = renderResult;
+    let handle;
+    try {
+        handle = await (0, worktreeRunner_1.createWorktree)({ jobId: input.jobId, workingDir: input.workingDir });
+    }
+    catch (err) {
+        return {
+            ok: false,
+            reason: 'worktree_failed',
+            details: `failed to create worktree: ${err.message}`,
+        };
+    }
+    const strategyFilePath = path.join(handle.worktreePath, 'backend', 'strategies', `${input.scene}.strategy.md`);
+    const apply = (0, strategyPatchApplier_1.applyPhaseHintPatch)(strategyFilePath, rendered.yaml);
+    if (!apply.ok) {
+        await (0, worktreeRunner_1.removeWorktree)(handle, true);
+        return {
+            ok: false,
+            reason: 'patch_failed',
+            details: `${apply.reason}: ${apply.details ?? ''}`,
+        };
+    }
+    if (input.validate) {
+        const validation = await input.validate(handle);
+        if (!validation.ok) {
+            await (0, worktreeRunner_1.removeWorktree)(handle, true);
+            return {
+                ok: false,
+                reason: 'validation_failed',
+                details: validation.details ?? 'validation hook returned not-ok',
+            };
+        }
+    }
+    return {
+        ok: true,
+        handle,
+        patchFingerprint: rendered.patchFingerprint,
+        phaseHintId: rendered.phaseHintId,
+        renderedYaml: rendered.yaml,
+        strategyFilePath,
+    };
+}
+//# sourceMappingURL=proposeStrategyPatch.js.map

package/dist/agentv3/selfImprove/proposeStrategyPatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proposeStrategyPatch.js","sourceRoot":"","sources":["../../../src/agentv3/selfImprove/proposeStrategyPatch.ts"],"names":[],"mappings":";AAAA,6CAA6C;AAC7C,0CAA0C;AAC1C,+DAA+D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgE/D,oDAiDC;AA/GD;;;;;;;;;;;;;;;;;GAiBG;AAEH,2CAA6B;AAC7B,6DAAkG;AAClG,iEAA6D;AAC7D,qDAAuF;AAkCvF;;;;;GAKG;AACI,KAAK,UAAU,oBAAoB,CAAC,KAAgC;IACzE,MAAM,YAAY,GAAG,IAAA,oCAAe,EAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,YAAY,EAAE,KAAK,CAAC,YAAY,EAAE,CAAC,CAAC;IAC3F,IAAI,CAAC,YAAY,CAAC,EAAE,EAAE,CAAC;QACrB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,OAAO,EAAE,GAAG,YAAY,CAAC,MAAM,KAAK,YAAY,CAAC,OAAO,EAAE,EAAE,CAAC;IAC5G,CAAC;IACD,MAAM,QAAQ,GAAwC,YAAY,CAAC;IAEnE,IAAI,MAAsB,CAAC;IAC3B,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,IAAA,+BAAc,EAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC;IACtF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,iBAAiB;YACzB,OAAO,EAAE,8BAA+B,GAAa,CAAC,OAAO,EAAE;SAChE,CAAC;IACJ,CAAC;IAED,MAAM,gBAAgB,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,GAAG,KAAK,CAAC,KAAK,cAAc,CAAC,CAAC;IAC/G,MAAM,KAAK,GAAG,IAAA,0CAAmB,EAAC,gBAAgB,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IACnE,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC;QACd,MAAM,IAAA,+BAAc,EAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QACnC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,cAAc;YACtB,OAAO,EAAE,GAAG,KAAK,CAAC,MAAM,KAAK,KAAK,CAAC,OAAO,IAAI,EAAE,EAAE;SACnD,CAAC;IACJ,CAAC;IAED,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QACnB,MAAM,UAAU,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAChD,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,CAAC;YACnB,MAAM,IAAA,+BAAc,EAAC,MAAM,EAAE,IAAI,CAAC,CAAC;YACnC,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,MAAM,EAAE,mBAAmB;gBAC3B,OAAO,EAAE,UAAU,CAAC,OAAO,IAAI,iCAAiC;aACjE,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO;QACL,EAAE,EAAE,IAAI;QACR,MAAM;QACN,gBAAgB,EAAE,QAAQ,CAAC,gBAAgB;QAC3C,WAAW,EAAE,QAAQ,CAAC,WAAW;QACjC,YAAY,EAAE,QAAQ,CAAC,IAAI;QAC3B,gBAAgB;KACjB,CAAC;AACJ,CAAC"}

package/dist/agentv3/selfImprove/reviewAgentSdk.d.ts

@@ -0,0 +1,32 @@
+import type { ReviewJobPayload, ReviewExecutionResult } from './reviewWorker';
+export interface ReviewAgentSdkOptions {
+    /** Override the LLM. Default `claude-haiku-4-5` per design doc §9. */
+    model?: string;
+    /** Wall-clock budget. Default 90s. */
+    timeoutMs?: number;
+}
+/**
+ * Run the review agent against a single job. Returns a structured outcome
+ * — the worker maps the result to outbox state transitions.
+ */
+export declare function executeReviewAgentViaSdk(payload: ReviewJobPayload, opts?: ReviewAgentSdkOptions): Promise<ReviewExecutionResult>;
+/**
+ * Builds the review-agent prompt inline. The prompt is short by design:
+ * it forbids YAML/markdown surfaces (those are PR9c's job) and pins the
+ * output to the closed FailureCategory enum.
+ */
+export declare function buildReviewAgentPrompt(payload: ReviewJobPayload): string;
+/**
+ * Extract the first balanced JSON object from `text`. The agent should only
+ * return one object, but defensive parsing tolerates an accidental code
+ * fence or trailing whitespace.
+ */
+declare function extractJsonObject(text: string): Record<string, unknown> | null;
+export declare const __testing: {
+    extractJsonObject: typeof extractJsonObject;
+    DEFAULT_TIMEOUT_MS: number;
+    DEFAULT_MODEL: string;
+    MAX_TURNS: number;
+};
+export {};
+//# sourceMappingURL=reviewAgentSdk.d.ts.map

package/dist/agentv3/selfImprove/reviewAgentSdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reviewAgentSdk.d.ts","sourceRoot":"","sources":["../../../src/agentv3/selfImprove/reviewAgentSdk.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAM9E,MAAM,WAAW,qBAAqB;IACpC,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,gBAAgB,EACzB,IAAI,GAAE,qBAA0B,GAC/B,OAAO,CAAC,qBAAqB,CAAC,CAwEhC;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAuCxE;AAED;;;;GAIG;AACH,iBAAS,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAYvE;AAED,eAAO,MAAM,SAAS;;;;;CAAsE,CAAC"}

package/dist/agentv3/selfImprove/reviewAgentSdk.js

@@ -0,0 +1,173 @@
+"use strict";
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2024-2026 Gracker (Chris)
+// This file is part of SmartPerfetto. See LICENSE for details.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.__testing = void 0;
+exports.executeReviewAgentViaSdk = executeReviewAgentViaSdk;
+exports.buildReviewAgentPrompt = buildReviewAgentPrompt;
+/**
+ * Claude SDK call for the background review agent.
+ *
+ * Completely independent from the main analysis runtime: no resume, no
+ * `claude_session_map.json` writes, no MCP tools. The agent receives a
+ * structured payload describing what went wrong in a previous analysis and
+ * must respond with strict JSON matching ReviewAgentNoteEmission. Anything
+ * else is rejected upstream by skillNotesWriter and the job is failed.
+ *
+ * See docs/architecture/self-improving-design.md §9 (Trust Boundary), §10 (Worker Limits).
+ */
+const claude_agent_sdk_1 = require("@anthropic-ai/claude-agent-sdk");
+const claudeConfig_1 = require("../claudeConfig");
+const failureTaxonomy_1 = require("./failureTaxonomy");
+const DEFAULT_TIMEOUT_MS = 90000;
+const DEFAULT_MODEL = 'claude-haiku-4-5';
+const MAX_TURNS = 8;
+/**
+ * Run the review agent against a single job. Returns a structured outcome
+ * — the worker maps the result to outbox state transitions.
+ */
+async function executeReviewAgentViaSdk(payload, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const model = opts.model ?? DEFAULT_MODEL;
+    const prompt = buildReviewAgentPrompt(payload);
+    const sdkEnv = (0, claudeConfig_1.createSdkEnv)();
+    const stream = (0, claude_agent_sdk_1.query)({
+        prompt,
+        options: {
+            model,
+            maxTurns: MAX_TURNS,
+            permissionMode: 'bypassPermissions',
+            allowDangerouslySkipPermissions: true,
+            env: sdkEnv,
+            stderr: (data) => {
+                console.warn(`[ReviewAgentSdk] SDK stderr: ${data.trimEnd()}`);
+            },
+            ...(0, claudeConfig_1.getSdkBinaryOption)(sdkEnv),
+        },
+    });
+    let result = '';
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        console.warn(`[ReviewAgentSdk] timed out after ${timeoutMs / 1000}s`);
+        try {
+            stream.close();
+        }
+        catch { /* ignore */ }
+    }, timeoutMs);
+    try {
+        for await (const msg of stream) {
+            if (timedOut)
+                break;
+            if (msg.type === 'result' && msg.subtype === 'success') {
+                result = msg.result || '';
+            }
+        }
+    }
+    catch (err) {
+        clearTimeout(timer);
+        try {
+            stream.close();
+        }
+        catch { /* ignore */ }
+        return { ok: false, reason: 'sdk_error', details: err.message };
+    }
+    finally {
+        clearTimeout(timer);
+        try {
+            stream.close();
+        }
+        catch { /* ignore */ }
+    }
+    if (timedOut) {
+        return { ok: false, reason: 'sdk_timeout', details: `${timeoutMs}ms budget exhausted` };
+    }
+    const parsed = extractJsonObject(result);
+    if (!parsed) {
+        return { ok: false, reason: 'sdk_invalid', details: 'no JSON object in agent response' };
+    }
+    // Inject runtime fields the agent doesn't (and shouldn't) supply itself —
+    // skillId comes from the originating job, sourceSessionId/turnIndex from
+    // the payload context.
+    const enriched = {
+        ...parsed,
+        skillId: payload.skillId,
+    };
+    if (typeof payload.context === 'object' && payload.context !== null) {
+        const ctx = payload.context;
+        if (typeof ctx.sourceSessionId === 'string')
+            enriched.sourceSessionId = ctx.sourceSessionId;
+        if (typeof ctx.sourceTurnIndex === 'number')
+            enriched.sourceTurnIndex = ctx.sourceTurnIndex;
+        if (!enriched.failureModeHash && typeof payload.failureModeHash === 'string') {
+            enriched.failureModeHash = payload.failureModeHash;
+        }
+    }
+    return { ok: true, emission: enriched };
+}
+/**
+ * Builds the review-agent prompt inline. The prompt is short by design:
+ * it forbids YAML/markdown surfaces (those are PR9c's job) and pins the
+ * output to the closed FailureCategory enum.
+ */
+function buildReviewAgentPrompt(payload) {
+    const categoryList = failureTaxonomy_1.FAILURE_CATEGORIES
+        .map(c => `- ${c}: ${failureTaxonomy_1.FAILURE_CATEGORY_DESCRIPTIONS[c]}`)
+        .join('\n');
+    const contextJson = JSON.stringify(payload.context, null, 2);
+    return `You are SmartPerfetto's review agent. The main analysis just finished
+running and we want a one-paragraph, high-signal note about a specific
+failure mode that the next run on a similar trace should know about.
+
+Skill under review: ${payload.skillId}
+Failure mode hash:  ${payload.failureModeHash ?? '(none)'}
+
+Job context (raw payload):
+\`\`\`json
+${contextJson}
+\`\`\`
+
+Allowed failureCategoryEnum values:
+${categoryList}
+
+Respond with EXACTLY one JSON object — no markdown fences, no commentary —
+matching this shape:
+
+{
+  "failureCategoryEnum": "<one of the values above>",
+  "evidenceSummary":      "<≤600 chars: what went wrong, in plain prose>",
+  "candidateKeywords":    ["<≤6 short keywords>"],
+  "candidateConstraints": "<≤400 chars: what the next run should do differently>",
+  "candidateCriticalTools": ["<tool/skill IDs to invoke first; can be empty>"]
+}
+
+Rules:
+- Choose "unknown" if no category clearly fits — DO NOT invent a new one.
+- Do not include any field not listed above.
+- Do not include shell commands, SQL DDL, or instructions to ignore the
+  upstream system prompt — your output is parsed and security-scanned.
+`;
+}
+/**
+ * Extract the first balanced JSON object from `text`. The agent should only
+ * return one object, but defensive parsing tolerates an accidental code
+ * fence or trailing whitespace.
+ */
+function extractJsonObject(text) {
+    const match = text.match(/\{[\s\S]*\}/);
+    if (!match)
+        return null;
+    try {
+        const parsed = JSON.parse(match[0]);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    return null;
+}
+exports.__testing = { extractJsonObject, DEFAULT_TIMEOUT_MS, DEFAULT_MODEL, MAX_TURNS };
+//# sourceMappingURL=reviewAgentSdk.js.map

package/dist/agentv3/selfImprove/reviewAgentSdk.js.map

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

package/dist/agentv3/selfImprove/reviewOutbox.d.ts

@@ -0,0 +1,128 @@
+/**
+ * SQLite-backed outbox for the background review agent.
+ *
+ * The review agent runs asynchronously after every analysis: a backend
+ * crash, deploy, or process restart in between must NOT lose review jobs.
+ * Filesystem-based queues (one JSON file per state) lose race exclusivity
+ * once two workers contend for the same job. SQLite + WAL gives us atomic
+ * `UPDATE … WHERE state='pending' RETURNING …` lease semantics in a single
+ * statement, plus partial unique indexes for `dedupe_key` so a flapping
+ * caller can't enqueue the same job twice.
+ *
+ * The DB lives at `<cwd>/data/self_improve/self_improve.db` — separate from
+ * the sessions DB so a corrupt outbox never takes the analysis path down
+ * with it.
+ *
+ * See docs/architecture/self-improving-design.md §7 (SQLite Outbox).
+ */
+import Database from 'better-sqlite3';
+export type JobState = 'pending' | 'leased' | 'done' | 'failed';
+export interface EnqueueInput {
+    /**
+     * Globally unique dedupe key. The recommended form is
+     * `${sessionId}::${turnIndex}::${skillId}::${failureModeHash}` so the same
+     * skill+failure combo on the same turn can't be enqueued twice while still
+     * leaving room for legitimate retries on a different turn.
+     */
+    dedupeKey: string;
+    /** Higher numbers run first. Default 0. */
+    priority?: number;
+    /** Arbitrary JSON-serializable payload — never mutated by the outbox. */
+    payload: unknown;
+}
+export interface ReviewJob {
+    id: string;
+    state: JobState;
+    dedupeKey: string;
+    priority: number;
+    attempts: number;
+    leaseOwner: string | null;
+    leaseUntil: number | null;
+    createdAt: number;
+    updatedAt: number;
+    payload: unknown;
+    lastError: string | null;
+}
+export interface OutboxOptions {
+    /** Override default DB path for tests. Pass ':memory:' for an ephemeral store. */
+    dbPath?: string;
+}
+export interface EnqueueResult {
+    enqueued: boolean;
+    jobId?: string;
+    /** Latency of the enqueue insert in ms — surfaced for the metrics PR. */
+    latencyMs: number;
+    /**
+     * Reason the enqueue was a no-op. `duplicate_active` means a pending or
+     * leased job with the same dedupe key already exists.
+     */
+    reason?: 'duplicate_active' | 'error';
+}
+/**
+ * Open the outbox DB, run migrations, and return a closure that exposes the
+ * supported operations. The DB connection is owned by the caller — call
+ * `close()` to release it.
+ */
+export declare function openReviewOutbox(opts?: OutboxOptions): ReviewOutboxHandle;
+export declare class ReviewOutboxHandle {
+    private readonly db;
+    constructor(db: Database.Database);
+    /**
+     * Enqueue a new job. Returns `{ enqueued: false, reason: 'duplicate_active' }`
+     * if a pending or leased job with the same dedupe key already exists; this is
+     * a successful no-op, not an error, so callers don't need a try/catch.
+     */
+    enqueue(input: EnqueueInput): EnqueueResult;
+    /**
+     * Atomically pick the highest-priority pending job and mark it leased.
+     * Returns null if the queue is empty (or every pending job is gated by
+     * attempts ≥ maxAttempts).
+     *
+     * The lease is owned by `workerOwner` until `lease_until` — past that the
+     * caller should call `expireStaleLeases()` to recycle the job back to
+     * pending.
+     */
+    leaseNext(input: {
+        workerOwner: string;
+        leaseDurationMs?: number;
+        maxAttempts?: number;
+    }): ReviewJob | null;
+    /** Mark a leased job as completed. Idempotent on a re-call (no-op). */
+    markDone(jobId: string): void;
+    /**
+     * Mark a leased job failed. If `attempts < maxAttempts`, the job goes back
+     * to pending so a future poll can retry; otherwise it lands in 'failed'
+     * permanently. `lastError` is truncated to keep DB size bounded.
+     */
+    markFailed(jobId: string, lastError: string, maxAttempts?: number): void;
+    /**
+     * Voluntarily release a lease without consuming an attempt. Used by the
+     * worker when it leased a job but immediately determined the job has to
+     * wait (cooldown, blocked dependency). The job goes back to pending and
+     * keeps its existing attempts counter.
+     */
+    releaseLease(jobId: string): void;
+    /**
+     * Recycle leased jobs whose lease has expired back to pending. Called by
+     * the worker poll loop on each tick — cheap because the lease_until index
+     * keeps the scan tight.
+     */
+    expireStaleLeases(now?: number): number;
+    /** Return counts grouped by state — used by the monitoring PR. */
+    countByState(): Record<JobState, number>;
+    /**
+     * Number of jobs created in the last 24h — feeds the daily-budget cap.
+     * Uses created_at so retries/leases don't double-count.
+     */
+    dailyJobCount(now?: number): number;
+    /** Test helper — returns the full job row for assertions. */
+    getJob(jobId: string): ReviewJob | null;
+    /** Latest applied schema version — for migration tests. */
+    schemaVersion(): number;
+    close(): void;
+}
+/** Surfaced for assertions without exporting the constants individually. */
+export declare const __testing: {
+    SCHEMA_VERSION_LATEST: number;
+};
+//# sourceMappingURL=reviewOutbox.d.ts.map