@oratis/lisa 0.5.0 → 0.8.0

package/dist/orchestrator/journal.js

@@ -0,0 +1,82 @@
+/**
+ * Orchestrator journal (L6) — a small temporal record of agent activity.
+ *
+ * The hub (L1) only holds a *live snapshot*; once a session goes idle/done it
+ * falls out of `hub.list()`. The advisor (L5) surfaces relevance-gated alerts.
+ * Neither answers "what actually happened across all my agents while I was
+ * away?" — which needs a record over *time*, including sessions that have since
+ * ended. This journal is that record: every meaningful state transition the hub
+ * emits is appended to a capped ring buffer, from which recap.ts synthesizes a
+ * cross-agent "while you were away" digest.
+ *
+ * In-memory + capped (no growth): a recap covers the current server's uptime,
+ * which is exactly the window the user was away *for*. PRIVACY: stores only the
+ * same structural metadata the hub emits (agent, project, state, tool/file
+ * names, error strings) — never prompts, replies, or file contents.
+ */
+const MAX_EVENTS = 400;
+const events = [];
+/** Compact, structural one-liner from a session's Tier-2 activity. */
+export function summarizeActivity(s) {
+    const a = s.activity;
+    if (!a)
+        return undefined;
+    const bits = [];
+    const tool = a.lastTools?.length ? a.lastTools[a.lastTools.length - 1] : "";
+    if (tool)
+        bits.push(tool);
+    if (a.lastCommandName)
+        bits.push("$" + a.lastCommandName);
+    const file = a.filesTouched?.length
+        ? a.filesTouched[a.filesTouched.length - 1].split("/").pop()
+        : "";
+    if (file)
+        bits.push(file);
+    return bits.length ? bits.join(" · ") : undefined;
+}
+/**
+ * Append a transition. Consecutive events for the same session with the same
+ * state + reason are collapsed (we only record *changes*), so a session that
+ * sits in "working" for an hour produces one entry, not hundreds.
+ */
+export function recordEvent(s, now = Date.now()) {
+    // Find the most recent event for this session.
+    let prev;
+    for (let i = events.length - 1; i >= 0; i--) {
+        if (events[i].sessionId === s.sessionId) {
+            prev = events[i];
+            break;
+        }
+    }
+    if (prev && prev.state === s.state && prev.stateReason === s.stateReason) {
+        return null; // no real transition
+    }
+    const ev = {
+        agent: s.agent,
+        sessionId: s.sessionId,
+        project: s.project,
+        cwd: s.cwd,
+        state: s.state,
+        stateReason: s.stateReason,
+        at: Number.isFinite(s.lastMtime) && s.lastMtime > 0 ? s.lastMtime : now,
+        activity: summarizeActivity(s),
+        error: s.activity?.lastError,
+    };
+    events.push(ev);
+    if (events.length > MAX_EVENTS)
+        events.splice(0, events.length - MAX_EVENTS);
+    return ev;
+}
+/** All recorded events (oldest → newest). */
+export function allEvents() {
+    return events.slice();
+}
+/** Events at or after `sinceMs` (epoch ms), oldest → newest. */
+export function eventsSince(sinceMs) {
+    return events.filter((e) => e.at >= sinceMs);
+}
+/** Test hook — wipe the buffer. */
+export function _resetJournalForTest() {
+    events.length = 0;
+}
+//# sourceMappingURL=journal.js.map

package/dist/orchestrator/journal.js.map

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

package/dist/orchestrator/recap.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Recap (L6) — synthesize the orchestrator journal into a cross-agent
+ * "while you were away" digest. Deterministic (no LLM): given the journal
+ * events in a time window, group by project, tally how each session ended,
+ * and surface the notable moments (errors, finishes, merged PRs, blocks).
+ *
+ * This is the narrative counterpart to the advisor's alerts and list_agents'
+ * roster: it answers "what happened, across everything, since I left?"
+ */
+import type { AgentEvent } from "./journal.js";
+export interface ProjectRecap {
+    project: string;
+    agents: string[];
+    /** Distinct sessions seen in the window. */
+    sessions: number;
+    finished: number;
+    errored: number;
+    active: number;
+    /** Up to a few file basenames touched. */
+    files: string[];
+    /** Human-readable notable lines for this project. */
+    notable: string[];
+}
+export interface Recap {
+    sinceMs: number;
+    now: number;
+    /** Distinct sessions that had any event in the window. */
+    totalSessions: number;
+    totalEvents: number;
+    projects: ProjectRecap[];
+    /** One-line headline. */
+    headline: string;
+}
+/** Build the structured recap from journal events in [sinceMs, now]. Pure. */
+export declare function buildRecap(events: AgentEvent[], sinceMs: number, now: number): Recap;
+/** Render the recap as a readable multi-line digest. Pure. */
+export declare function formatRecap(recap: Recap): string;
+//# sourceMappingURL=recap.d.ts.map

package/dist/orchestrator/recap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recap.d.ts","sourceRoot":"","sources":["../../src/orchestrator/recap.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG/C,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,qDAAqD;IACrD,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,KAAK;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,0DAA0D;IAC1D,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,yBAAyB;IACzB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAoBD,8EAA8E;AAC9E,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,KAAK,CA6GpF;AAED,8DAA8D;AAC9D,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAShD"}

package/dist/orchestrator/recap.js

@@ -0,0 +1,134 @@
+/**
+ * Recap (L6) — synthesize the orchestrator journal into a cross-agent
+ * "while you were away" digest. Deterministic (no LLM): given the journal
+ * events in a time window, group by project, tally how each session ended,
+ * and surface the notable moments (errors, finishes, merged PRs, blocks).
+ *
+ * This is the narrative counterpart to the advisor's alerts and list_agents'
+ * roster: it answers "what happened, across everything, since I left?"
+ */
+const FILES_PER_PROJECT = 6;
+function basename(p) {
+    return p.split("/").pop() || p;
+}
+/** Build the structured recap from journal events in [sinceMs, now]. Pure. */
+export function buildRecap(events, sinceMs, now) {
+    const inWindow = events.filter((e) => e.at >= sinceMs);
+    // Roll up per session (the latest meaningful state wins).
+    const sessions = new Map();
+    for (const e of inWindow) {
+        let r = sessions.get(e.sessionId);
+        if (!r) {
+            r = {
+                agent: e.agent,
+                project: e.project || "(unknown)",
+                lastState: e.state,
+                lastReason: e.stateReason,
+                lastAt: e.at,
+                files: new Set(),
+                errored: false,
+            };
+            sessions.set(e.sessionId, r);
+        }
+        if (e.at >= r.lastAt) {
+            r.lastState = e.state;
+            r.lastReason = e.stateReason;
+            r.lastAt = e.at;
+            if (e.activity)
+                r.lastActivity = e.activity;
+        }
+        if (e.state === "error") {
+            r.errored = true;
+            if (e.error || e.stateReason)
+                r.lastError = e.error || e.stateReason;
+        }
+        if (e.activity) {
+            // The activity summary's last token is often a file basename; cheap to keep.
+            const f = e.activity.split(" · ").find((t) => /\.[a-z0-9]+$/i.test(t));
+            if (f)
+                r.files.add(f);
+        }
+    }
+    // Group sessions by project.
+    const byProject = new Map();
+    for (const r of sessions.values()) {
+        const list = byProject.get(r.project) ?? [];
+        list.push(r);
+        byProject.set(r.project, list);
+    }
+    const projects = [];
+    let totalFinished = 0, totalErrored = 0, totalActive = 0;
+    for (const [project, rolls] of byProject) {
+        const agents = [...new Set(rolls.map((r) => r.agent))].sort();
+        let finished = 0, errored = 0, active = 0;
+        const files = new Set();
+        const notable = [];
+        for (const r of rolls) {
+            if (r.errored) {
+                errored++;
+                notable.push(`✗ ${r.agent} errored${r.lastError ? `: ${r.lastError}` : ""}`);
+            }
+            else if (r.lastState === "done") {
+                finished++;
+                notable.push(`✓ ${r.agent} finished${r.lastReason ? ` (${r.lastReason})` : ""}`);
+            }
+            else if (r.lastState === "working" || r.lastState === "waiting") {
+                active++;
+                if (r.lastState === "waiting" && r.lastReason)
+                    notable.push(`• ${r.agent} waiting — ${r.lastReason}`);
+            }
+            for (const f of r.files)
+                files.add(basename(f));
+        }
+        totalFinished += finished;
+        totalErrored += errored;
+        totalActive += active;
+        projects.push({
+            project,
+            agents,
+            sessions: rolls.length,
+            finished,
+            errored,
+            active,
+            files: [...files].slice(0, FILES_PER_PROJECT),
+            notable: notable.slice(0, 6),
+        });
+    }
+    // Errors first, then most sessions, then name.
+    projects.sort((a, b) => b.errored - a.errored || b.sessions - a.sessions || a.project.localeCompare(b.project));
+    const parts = [];
+    if (totalFinished)
+        parts.push(`${totalFinished} finished`);
+    if (totalErrored)
+        parts.push(`${totalErrored} errored`);
+    if (totalActive)
+        parts.push(`${totalActive} still going`);
+    const headline = sessions.size === 0
+        ? "No agent activity in this window."
+        : `${sessions.size} agent session${sessions.size === 1 ? "" : "s"} across ` +
+            `${projects.length} project${projects.length === 1 ? "" : "s"}` +
+            (parts.length ? ` — ${parts.join(", ")}.` : ".");
+    return {
+        sinceMs,
+        now,
+        totalSessions: sessions.size,
+        totalEvents: inWindow.length,
+        projects,
+        headline,
+    };
+}
+/** Render the recap as a readable multi-line digest. Pure. */
+export function formatRecap(recap) {
+    if (recap.totalSessions === 0)
+        return recap.headline;
+    const lines = [recap.headline, ""];
+    for (const p of recap.projects) {
+        lines.push(`${p.project} · ${p.agents.join(", ")}`);
+        for (const n of p.notable)
+            lines.push(`  ${n}`);
+        if (p.files.length)
+            lines.push(`  touched: ${p.files.join(", ")}`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=recap.js.map

package/dist/orchestrator/recap.js.map

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

package/dist/screen_advisor/engine.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Screen advisor — periodic, opt-in screen-aware coaching.
+ *
+ * When enabled, the server captures a full-screen screenshot every N minutes,
+ * asks the model for the single best next coding step grounded in what's on
+ * screen, and pushes it to the Lisa Island as a suggestion card. Clicking it
+ * prefills the suggestion into the chat composer so the user can confirm before
+ * any coding agent is dispatched.
+ *
+ * PRIVACY (this is a sensitive capability — treat it as such):
+ *   - DISABLED by default. Nothing is captured until the user turns it on in
+ *     Settings.
+ *   - The screenshot only leaves the machine for the single analysis call to
+ *     the model the user already uses; the image is never persisted by LISA
+ *     (capture writes a temp PNG that the capture layer deletes), and only the
+ *     short text suggestion is kept in memory.
+ *   - The suggestion never auto-runs anything: clicking it only prefills chat.
+ *
+ * This module is provider-agnostic and side-effect-light so the parsing and
+ * config logic can be unit-tested without a real LLM or a real screen.
+ */
+export interface ScreenAdvisorConfig {
+    /** Master switch. Off by default — capture only happens when true. */
+    enabled: boolean;
+    /** Minutes between captures. Clamped to [MIN, MAX]. */
+    intervalMinutes: number;
+}
+export declare const DEFAULT_SCREEN_ADVISOR_CONFIG: ScreenAdvisorConfig;
+export declare const MIN_INTERVAL_MINUTES = 2;
+export declare const MAX_INTERVAL_MINUTES = 240;
+export declare const SCREEN_ADVISOR_CONFIG_PATH: string;
+/** Coerce arbitrary input into a valid config (clamped interval, boolean enabled). */
+export declare function normalizeConfig(raw: Partial<ScreenAdvisorConfig> | null | undefined): ScreenAdvisorConfig;
+export declare function loadScreenAdvisorConfig(p?: string): Promise<ScreenAdvisorConfig>;
+export declare function saveScreenAdvisorConfig(cfg: ScreenAdvisorConfig, p?: string): Promise<ScreenAdvisorConfig>;
+/** A single screen-grounded next-step suggestion. */
+export interface ScreenSuggestion {
+    /** ≤8-word imperative headline. */
+    title: string;
+    /** 1–2 sentences citing what was on screen. */
+    rationale: string;
+    /** Self-contained prompt a coding agent could act on. */
+    task: string;
+    /** ISO timestamp, stamped by the caller. */
+    at: string;
+}
+export declare const SCREEN_ADVISOR_SYSTEM = "You are Lisa's screen advisor. You are shown ONE screenshot of the user's screen. Suggest the single highest-value next CODING step, grounded in what is actually visible \u2014 an error, a failing test, a TODO/FIXME, an open file, a diff, a PR, a design. Be specific and actionable: prefer something a coding agent could pick up and finish.\n\nRespond with ONLY a compact JSON object \u2014 no prose, no markdown, no code fences:\n{\"title\":\"<=8-word imperative headline\",\"rationale\":\"1-2 sentences citing what you saw\",\"task\":\"a self-contained prompt for a coding agent: exactly what to do, and in which file/dir if visible\"}\n\nIf the screen shows nothing actionable for coding (a video, a chat, the desktop, unrelated browsing), respond with exactly: {\"skip\":true}";
+/**
+ * Tolerantly parse the model's reply into a suggestion. Strips code fences,
+ * extracts the first JSON object, and returns null for {"skip":true} or any
+ * malformed / incomplete reply (so the loop simply surfaces nothing).
+ */
+export declare function parseSuggestion(text: string | null | undefined): Omit<ScreenSuggestion, "at"> | null;
+/** Minimal provider surface the analyzer needs (keeps the engine testable). */
+export interface SuggestionProvider {
+    runTurn(opts: {
+        systemPrompt: string;
+        messages: Array<{
+            role: "user" | "assistant";
+            content: unknown;
+        }>;
+        tools: unknown[];
+        model: string;
+        maxTokens?: number;
+    }): Promise<{
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+    }>;
+}
+/** Run one screenshot through the model and parse the suggestion (or null). */
+export declare function analyzeScreenshot(opts: {
+    provider: SuggestionProvider;
+    model: string;
+    imageBase64: string;
+    mediaType?: string;
+}): Promise<Omit<ScreenSuggestion, "at"> | null>;
+//# sourceMappingURL=engine.d.ts.map

package/dist/screen_advisor/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/screen_advisor/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAMH,MAAM,WAAW,mBAAmB;IAClC,sEAAsE;IACtE,OAAO,EAAE,OAAO,CAAC;IACjB,uDAAuD;IACvD,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,eAAO,MAAM,6BAA6B,EAAE,mBAG3C,CAAC;AAEF,eAAO,MAAM,oBAAoB,IAAI,CAAC;AACtC,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC,eAAO,MAAM,0BAA0B,QAA8C,CAAC;AAEtF,sFAAsF;AACtF,wBAAgB,eAAe,CAC7B,GAAG,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAAG,IAAI,GAAG,SAAS,GACnD,mBAAmB,CAQrB;AAED,wBAAsB,uBAAuB,CAC3C,CAAC,GAAE,MAAmC,GACrC,OAAO,CAAC,mBAAmB,CAAC,CAO9B;AAED,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,mBAAmB,EACxB,CAAC,GAAE,MAAmC,GACrC,OAAO,CAAC,mBAAmB,CAAC,CAK9B;AAED,qDAAqD;AACrD,MAAM,WAAW,gBAAgB;IAC/B,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,eAAO,MAAM,qBAAqB,ixBAKwG,CAAC;AAE3I;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAAC,gBAAgB,EAAE,IAAI,CAAC,GAAG,IAAI,CAwBpG;AAED,+EAA+E;AAC/E,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,IAAI,EAAE;QACZ,YAAY,EAAE,MAAM,CAAC;QACrB,QAAQ,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;YAAC,OAAO,EAAE,OAAO,CAAA;SAAE,CAAC,CAAC;QAClE,KAAK,EAAE,OAAO,EAAE,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC,CAAC;CAClE;AAED,+EAA+E;AAC/E,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,gBAAgB,EAAE,IAAI,CAAC,GAAG,IAAI,CAAC,CAyB/C"}

package/dist/screen_advisor/engine.js

@@ -0,0 +1,128 @@
+/**
+ * Screen advisor — periodic, opt-in screen-aware coaching.
+ *
+ * When enabled, the server captures a full-screen screenshot every N minutes,
+ * asks the model for the single best next coding step grounded in what's on
+ * screen, and pushes it to the Lisa Island as a suggestion card. Clicking it
+ * prefills the suggestion into the chat composer so the user can confirm before
+ * any coding agent is dispatched.
+ *
+ * PRIVACY (this is a sensitive capability — treat it as such):
+ *   - DISABLED by default. Nothing is captured until the user turns it on in
+ *     Settings.
+ *   - The screenshot only leaves the machine for the single analysis call to
+ *     the model the user already uses; the image is never persisted by LISA
+ *     (capture writes a temp PNG that the capture layer deletes), and only the
+ *     short text suggestion is kept in memory.
+ *   - The suggestion never auto-runs anything: clicking it only prefills chat.
+ *
+ * This module is provider-agnostic and side-effect-light so the parsing and
+ * config logic can be unit-tested without a real LLM or a real screen.
+ */
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { LISA_HOME } from "../paths.js";
+export const DEFAULT_SCREEN_ADVISOR_CONFIG = {
+    enabled: false,
+    intervalMinutes: 10,
+};
+export const MIN_INTERVAL_MINUTES = 2;
+export const MAX_INTERVAL_MINUTES = 240;
+export const SCREEN_ADVISOR_CONFIG_PATH = path.join(LISA_HOME, "screen-advisor.json");
+/** Coerce arbitrary input into a valid config (clamped interval, boolean enabled). */
+export function normalizeConfig(raw) {
+    const enabled = raw?.enabled === true;
+    let n = Number(raw?.intervalMinutes);
+    if (!Number.isFinite(n))
+        n = DEFAULT_SCREEN_ADVISOR_CONFIG.intervalMinutes;
+    n = Math.round(n);
+    if (n < MIN_INTERVAL_MINUTES)
+        n = MIN_INTERVAL_MINUTES;
+    if (n > MAX_INTERVAL_MINUTES)
+        n = MAX_INTERVAL_MINUTES;
+    return { enabled, intervalMinutes: n };
+}
+export async function loadScreenAdvisorConfig(p = SCREEN_ADVISOR_CONFIG_PATH) {
+    try {
+        const raw = JSON.parse(await fsp.readFile(p, "utf8"));
+        return normalizeConfig(raw);
+    }
+    catch {
+        return { ...DEFAULT_SCREEN_ADVISOR_CONFIG };
+    }
+}
+export async function saveScreenAdvisorConfig(cfg, p = SCREEN_ADVISOR_CONFIG_PATH) {
+    const norm = normalizeConfig(cfg);
+    await fsp.mkdir(path.dirname(p), { recursive: true });
+    await fsp.writeFile(p, JSON.stringify(norm, null, 2));
+    return norm;
+}
+export const SCREEN_ADVISOR_SYSTEM = `You are Lisa's screen advisor. You are shown ONE screenshot of the user's screen. Suggest the single highest-value next CODING step, grounded in what is actually visible — an error, a failing test, a TODO/FIXME, an open file, a diff, a PR, a design. Be specific and actionable: prefer something a coding agent could pick up and finish.
+
+Respond with ONLY a compact JSON object — no prose, no markdown, no code fences:
+{"title":"<=8-word imperative headline","rationale":"1-2 sentences citing what you saw","task":"a self-contained prompt for a coding agent: exactly what to do, and in which file/dir if visible"}
+
+If the screen shows nothing actionable for coding (a video, a chat, the desktop, unrelated browsing), respond with exactly: {"skip":true}`;
+/**
+ * Tolerantly parse the model's reply into a suggestion. Strips code fences,
+ * extracts the first JSON object, and returns null for {"skip":true} or any
+ * malformed / incomplete reply (so the loop simply surfaces nothing).
+ */
+export function parseSuggestion(text) {
+    if (!text)
+        return null;
+    let s = text.trim();
+    // Drop a leading ```json / ``` fence and a trailing fence if present.
+    s = s.replace(/^```[a-zA-Z]*\s*/, "").replace(/\s*```$/, "").trim();
+    const a = s.indexOf("{");
+    const b = s.lastIndexOf("}");
+    if (a < 0 || b <= a)
+        return null;
+    let obj;
+    try {
+        obj = JSON.parse(s.slice(a, b + 1));
+    }
+    catch {
+        return null;
+    }
+    if (obj.skip === true)
+        return null;
+    const title = typeof obj.title === "string" ? obj.title.trim() : "";
+    const task = typeof obj.task === "string" ? obj.task.trim() : "";
+    if (!title || !task)
+        return null;
+    const rationale = typeof obj.rationale === "string" ? obj.rationale.trim() : "";
+    return {
+        title: title.slice(0, 120),
+        rationale: rationale.slice(0, 400),
+        task: task.slice(0, 2000),
+    };
+}
+/** Run one screenshot through the model and parse the suggestion (or null). */
+export async function analyzeScreenshot(opts) {
+    const result = await opts.provider.runTurn({
+        systemPrompt: SCREEN_ADVISOR_SYSTEM,
+        messages: [
+            {
+                role: "user",
+                content: [
+                    { type: "text", text: "Here is my screen right now. What is the single best next coding step?" },
+                    {
+                        type: "image",
+                        source: {
+                            type: "base64",
+                            media_type: opts.mediaType ?? "image/png",
+                            data: opts.imageBase64,
+                        },
+                    },
+                ],
+            },
+        ],
+        tools: [],
+        model: opts.model,
+        maxTokens: 600,
+    });
+    const textBlock = result.content.find((b) => b.type === "text");
+    return parseSuggestion(textBlock?.text ?? "");
+}
+//# sourceMappingURL=engine.js.map

package/dist/screen_advisor/engine.js.map

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

package/dist/soul/birth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"birth.d.ts","sourceRoot":"","sources":["../../src/soul/birth.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,eAAe,EAWhB,MAAM,YAAY,CAAC;AAQpB,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClD;AA8BD,wBAAsB,KAAK,CAAC,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAOlE;AAmKD,OAAO,EAAE,eAAe,EAAE,CAAC"}
+{"version":3,"file":"birth.d.ts","sourceRoot":"","sources":["../../src/soul/birth.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,eAAe,EAWhB,MAAM,YAAY,CAAC;AAQpB,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClD;AA8BD,wBAAsB,KAAK,CAAC,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAOlE;AA2KD,OAAO,EAAE,eAAe,EAAE,CAAC"}

package/dist/soul/birth.js

@@ -161,6 +161,14 @@ function parseBirthOutput(raw) {
     if (!parsed.first_value?.slug || !parsed.first_desire?.slug) {
         throw new Error("birth output missing first_value or first_desire");
     }
+    // Smaller models sometimes return `constitution` as an array of strings
+    // when the prompt asks for a "markdown list". Coerce to a numbered
+    // markdown block so downstream string ops work uniformly.
+    if (Array.isArray(parsed.constitution)) {
+        parsed.constitution = parsed.constitution
+            .map((line, i) => `${i + 1}. ${String(line).replace(/^\s*\d+[.)]\s*/, "")}`)
+            .join("\n");
+    }
     return parsed;
 }
 function countLines(s) {

package/dist/soul/birth.js.map

@@ -1 +1 @@
-{"version":3,"file":"birth.js","sourceRoot":"","sources":["../../src/soul/birth.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EACL,cAAc,EACd,MAAM,EACN,eAAe,EACf,aAAa,EACb,QAAQ,EACR,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,SAAS,EACT,YAAY,EACZ,SAAS,EACT,UAAU,EACV,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AACxD,OAAO,EACL,gBAAgB,GAGjB,MAAM,YAAY,CAAC;AAapB,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;iIA0B4G,CAAC;AAElI,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,OAAqB,EAAE;IACjD,IAAI,MAAM,MAAM,EAAE,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CACb,kGAAkG,CACnG,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,cAAc,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;AAC/D,CAAC;AAED,KAAK,UAAU,UAAU,CAAC,IAAkB;IAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACzC,MAAM,cAAc,EAAE,CAAC;IAEvB,UAAU;IACV,MAAM,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC,CAAC;IAC5D,MAAM,IAAI,GAAG,YAAY,EAAE,CAAC;IAC5B,MAAM,SAAS,CAAC,IAAI,CAAC,CAAC;IACtB,0EAA0E;IAC1E,uEAAuE;IACvE,wEAAwE;IACxE,MAAM,YAAY,EAAE,CAAC;IACrB,MAAM,MAAM,CAAC;QACX,IAAI,EAAE,MAAM;QACZ,MAAM,EAAE,QAAQ,IAAI,CAAC,MAAM,YAAY,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,GAAG,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,iBAAiB,GAAG,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,GAAG,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,GAAG,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG;KAC5R,CAAC,CAAC;IAEH,oBAAoB;IACpB,MAAM,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,yCAAyC,EAAE,CAAC,CAAC;IAClF,MAAM,QAAQ,GAAG,gBAAgB,CAAC,IAAI,CAAC,KAAK,IAAI,aAAa,CAAC,CAAC;IAC/D,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC;QACpC,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,aAAa;QAClC,YAAY,EAAE,YAAY;QAC1B,KAAK,EAAE,EAAE;QACT,QAAQ,EAAE;YACR;gBACE,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAM;wBACZ,IAAI,EACF,UAAU,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,uCAAuC;qBACjF;iBACF;aACF;SACF;QACD,SAAS,EAAE,KAAK;KACjB,CAAC,CAAC;IACH,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO;SACvB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC;SAChC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAE,CAAsB,CAAC,IAAI,CAAC;SACxC,IAAI,CAAC,EAAE,CAAC;SACR,IAAI,EAAE,CAAC;IACV,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IAErC,kBAAkB;IAClB,MAAM,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC,IAAI,GAAG,EAAE,CAAC,CAAC;IAC7D,MAAM,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAE7B,MAAM,MAAM,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;IAC/E,MAAM,aAAa,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAErC,MAAM,MAAM,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;IAC7E,MAAM,YAAY,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAEnC,MAAM,MAAM,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC,MAAM,CAAC,YAAY,CAAC,aAAa,EAAE,CAAC,CAAC;IAChG,MAAM,iBAAiB,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAE7C,MAAM,MAAM,CAAC;QACX,IAAI,EAAE,aAAa;QACnB,MAAM,EAAE,KAAK,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE;KACxC,CAAC,CAAC;IACH,MAAM,UAAU,CAAC;QACf,IAAI,EAAE,MAAM,CAAC,WAAW,CAAC,IAAI;QAC7B,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC,KAAK;QAC/B,IAAI,EAAE,MAAM,CAAC,WAAW,CAAC,IAAI;QAC7B,SAAS,EAAE,IAAI,CAAC,MAAM;KACvB,CAAC,CAAC;IAEH,MAAM,MAAM,CAAC;QACX,IAAI,EAAE,cAAc;QACpB,MAAM,EAAE,KAAK,MAAM,CAAC,YAAY,CAAC,IAAI,GAAG,MAAM,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,EAAE;KAChG,CAAC,CAAC;IACH,MAAM,WAAW,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC,YAAY,CAAC,IAAI;QAC9B,IAAI,EAAE,MAAM,CAAC,YAAY,CAAC,IAAI;QAC9B,GAAG,EAAE,MAAM,CAAC,YAAY,CAAC,GAAG;QAC5B,UAAU,EAAE,MAAM,CAAC,YAAY,CAAC,UAAU;QAC1C,eAAe,EAAE,MAAM,CAAC,YAAY,CAAC,gBAAgB;QACrD,MAAM,EAAE,IAAI,CAAC,MAAM;KACpB,CAAC,CAAC;IAEH,6BAA6B;IAC7B,MAAM,aAAa,CAAC,EAAE,GAAG,gBAAgB,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IAClF,MAAM,QAAQ,CAAC,MAAM,aAAa,EAAE,CAAC,CAAC;IAEtC,MAAM,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,YAAY,EAAE,CAAC,CAAC;AACrE,CAAC;AAED,SAAS,YAAY;IACnB,MAAM,SAAS,GAAG,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACzD,MAAM,QAAQ,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC;IAC/B,MAAM,QAAQ,GAAG,MAAM;SACpB,UAAU,CAAC,QAAQ,CAAC;SACpB,MAAM,CAAC,QAAQ,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC;SACzC,MAAM,CAAC,KAAK,CAAC,CAAC;IACjB,sEAAsE;IACtE,MAAM,IAAI,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC;IACvC,OAAO;QACL,MAAM,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QAChC,MAAM,EAAE,QAAQ;QAChB,UAAU,EAAE,SAAS;QACrB,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CAAC,GAAW;IACjC,iEAAiE;IACjE,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACpC,MAAM,KAAK,GAAG,CAAC,CAAS,EAAE,EAAE,CAC1B,MAAM,CAAC,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,eAAe,CAAC,GAAG,eAAe,CAAC;QACxE,MAAM,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,mBAAmB,CAAC,CAAC;IACnE,4BAA4B;IAC5B,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,UAAU,CAAC;IAChE,OAAO;QACL,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC;QAChB,iBAAiB,EAAE,GAAG,CAAC,CAAC,CAAC;QACzB,YAAY,EAAE,GAAG,CAAC,CAAC,CAAC;QACpB,aAAa,EAAE,GAAG,CAAC,CAAC,CAAC;QACrB,WAAW,EAAE,GAAG,CAAC,CAAC,CAAC;KACpB,CAAC;IACF,0EAA0E;IAC1E,6DAA6D;IAC7D,KAAK,KAAK,CAAC;AACb,CAAC;AAiBD,SAAS,gBAAgB,CAAC,GAAW;IACnC,MAAM,QAAQ,GAAG,GAAG;SACjB,OAAO,CAAC,mBAAmB,EAAE,EAAE,CAAC;SAChC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;SACpB,IAAI,EAAE,CAAC;IACV,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAgB,CAAC;IACnD,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;QAChF,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IAC1D,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC;QAC5D,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,UAAU,CAAC,CAAS;IAC3B,OAAO,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;AACzD,CAAC;AAED,8EAA8E;AAC9E,OAAO,EAAE,eAAe,EAAE,CAAC"}
+{"version":3,"file":"birth.js","sourceRoot":"","sources":["../../src/soul/birth.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EACL,cAAc,EACd,MAAM,EACN,eAAe,EACf,aAAa,EACb,QAAQ,EACR,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,SAAS,EACT,YAAY,EACZ,SAAS,EACT,UAAU,EACV,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AACxD,OAAO,EACL,gBAAgB,GAGjB,MAAM,YAAY,CAAC;AAapB,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;iIA0B4G,CAAC;AAElI,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,OAAqB,EAAE;IACjD,IAAI,MAAM,MAAM,EAAE,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CACb,kGAAkG,CACnG,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,cAAc,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;AAC/D,CAAC;AAED,KAAK,UAAU,UAAU,CAAC,IAAkB;IAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACzC,MAAM,cAAc,EAAE,CAAC;IAEvB,UAAU;IACV,MAAM,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC,CAAC;IAC5D,MAAM,IAAI,GAAG,YAAY,EAAE,CAAC;IAC5B,MAAM,SAAS,CAAC,IAAI,CAAC,CAAC;IACtB,0EAA0E;IAC1E,uEAAuE;IACvE,wEAAwE;IACxE,MAAM,YAAY,EAAE,CAAC;IACrB,MAAM,MAAM,CAAC;QACX,IAAI,EAAE,MAAM;QACZ,MAAM,EAAE,QAAQ,IAAI,CAAC,MAAM,YAAY,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,GAAG,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,iBAAiB,GAAG,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,GAAG,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,GAAG,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG;KAC5R,CAAC,CAAC;IAEH,oBAAoB;IACpB,MAAM,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,yCAAyC,EAAE,CAAC,CAAC;IAClF,MAAM,QAAQ,GAAG,gBAAgB,CAAC,IAAI,CAAC,KAAK,IAAI,aAAa,CAAC,CAAC;IAC/D,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC;QACpC,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,aAAa;QAClC,YAAY,EAAE,YAAY;QAC1B,KAAK,EAAE,EAAE;QACT,QAAQ,EAAE;YACR;gBACE,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAM;wBACZ,IAAI,EACF,UAAU,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,uCAAuC;qBACjF;iBACF;aACF;SACF;QACD,SAAS,EAAE,KAAK;KACjB,CAAC,CAAC;IACH,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO;SACvB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC;SAChC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAE,CAAsB,CAAC,IAAI,CAAC;SACxC,IAAI,CAAC,EAAE,CAAC;SACR,IAAI,EAAE,CAAC;IACV,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IAErC,kBAAkB;IAClB,MAAM,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC,IAAI,GAAG,EAAE,CAAC,CAAC;IAC7D,MAAM,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAE7B,MAAM,MAAM,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;IAC/E,MAAM,aAAa,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAErC,MAAM,MAAM,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;IAC7E,MAAM,YAAY,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAEnC,MAAM,MAAM,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC,MAAM,CAAC,YAAY,CAAC,aAAa,EAAE,CAAC,CAAC;IAChG,MAAM,iBAAiB,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAE7C,MAAM,MAAM,CAAC;QACX,IAAI,EAAE,aAAa;QACnB,MAAM,EAAE,KAAK,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE;KACxC,CAAC,CAAC;IACH,MAAM,UAAU,CAAC;QACf,IAAI,EAAE,MAAM,CAAC,WAAW,CAAC,IAAI;QAC7B,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC,KAAK;QAC/B,IAAI,EAAE,MAAM,CAAC,WAAW,CAAC,IAAI;QAC7B,SAAS,EAAE,IAAI,CAAC,MAAM;KACvB,CAAC,CAAC;IAEH,MAAM,MAAM,CAAC;QACX,IAAI,EAAE,cAAc;QACpB,MAAM,EAAE,KAAK,MAAM,CAAC,YAAY,CAAC,IAAI,GAAG,MAAM,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,EAAE;KAChG,CAAC,CAAC;IACH,MAAM,WAAW,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC,YAAY,CAAC,IAAI;QAC9B,IAAI,EAAE,MAAM,CAAC,YAAY,CAAC,IAAI;QAC9B,GAAG,EAAE,MAAM,CAAC,YAAY,CAAC,GAAG;QAC5B,UAAU,EAAE,MAAM,CAAC,YAAY,CAAC,UAAU;QAC1C,eAAe,EAAE,MAAM,CAAC,YAAY,CAAC,gBAAgB;QACrD,MAAM,EAAE,IAAI,CAAC,MAAM;KACpB,CAAC,CAAC;IAEH,6BAA6B;IAC7B,MAAM,aAAa,CAAC,EAAE,GAAG,gBAAgB,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IAClF,MAAM,QAAQ,CAAC,MAAM,aAAa,EAAE,CAAC,CAAC;IAEtC,MAAM,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,YAAY,EAAE,CAAC,CAAC;AACrE,CAAC;AAED,SAAS,YAAY;IACnB,MAAM,SAAS,GAAG,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACzD,MAAM,QAAQ,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC;IAC/B,MAAM,QAAQ,GAAG,MAAM;SACpB,UAAU,CAAC,QAAQ,CAAC;SACpB,MAAM,CAAC,QAAQ,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC;SACzC,MAAM,CAAC,KAAK,CAAC,CAAC;IACjB,sEAAsE;IACtE,MAAM,IAAI,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC;IACvC,OAAO;QACL,MAAM,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QAChC,MAAM,EAAE,QAAQ;QAChB,UAAU,EAAE,SAAS;QACrB,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CAAC,GAAW;IACjC,iEAAiE;IACjE,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACpC,MAAM,KAAK,GAAG,CAAC,CAAS,EAAE,EAAE,CAC1B,MAAM,CAAC,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,eAAe,CAAC,GAAG,eAAe,CAAC;QACxE,MAAM,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,mBAAmB,CAAC,CAAC;IACnE,4BAA4B;IAC5B,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,UAAU,CAAC;IAChE,OAAO;QACL,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC;QAChB,iBAAiB,EAAE,GAAG,CAAC,CAAC,CAAC;QACzB,YAAY,EAAE,GAAG,CAAC,CAAC,CAAC;QACpB,aAAa,EAAE,GAAG,CAAC,CAAC,CAAC;QACrB,WAAW,EAAE,GAAG,CAAC,CAAC,CAAC;KACpB,CAAC;IACF,0EAA0E;IAC1E,6DAA6D;IAC7D,KAAK,KAAK,CAAC;AACb,CAAC;AAiBD,SAAS,gBAAgB,CAAC,GAAW;IACnC,MAAM,QAAQ,GAAG,GAAG;SACjB,OAAO,CAAC,mBAAmB,EAAE,EAAE,CAAC;SAChC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;SACpB,IAAI,EAAE,CAAC;IACV,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAgB,CAAC;IACnD,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;QAChF,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IAC1D,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC;QAC5D,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;IACtE,CAAC;IACD,wEAAwE;IACxE,mEAAmE;IACnE,0DAA0D;IAC1D,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC;QACvC,MAAM,CAAC,YAAY,GAAI,MAAM,CAAC,YAA0B;aACrD,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC,EAAE,CAAC;aAC3E,IAAI,CAAC,IAAI,CAAC,CAAC;IAChB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,UAAU,CAAC,CAAS;IAC3B,OAAO,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;AACzD,CAAC;AAED,8EAA8E;AAC9E,OAAO,EAAE,eAAe,EAAE,CAAC"}

package/dist/soul/lock.d.ts

@@ -9,10 +9,13 @@
  *   - lose a desire-progress append (read-modify-write race), or
  *   - collide on .git/index.lock (one commit fails).
  *
- * withFileLock implements a portable advisory mutex via exclusive file
- * creation (`open(..., "wx")` succeeds only if the file doesn't exist). It
- * self-heals from a crashed holder via a staleness timeout + a best-effort
- * liveness check on the recorded pid.
+ * withFileLock implements a portable advisory mutex by writing the lock body to
+ * a private temp file and then `link()`-ing it into place — link() fails if the
+ * target exists, so the lock is created exclusively AND already holds its full
+ * content (no window where a contender can read a half-written file and mistake
+ * it for stale). It self-heals from a crashed holder via a staleness timeout +
+ * a best-effort liveness check on the recorded pid, stealing atomically by
+ * renaming the stale file away so racing contenders can't clobber each other.
  */
 export interface FileLockOpts {
     /** Treat a held lock as abandoned after this many ms (crashed holder). */

package/dist/soul/lock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/soul/lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,MAAM,WAAW,YAAY;IAC3B,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAoCD;;;GAGG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,IAAI,GAAE,YAAiB,GACtB,OAAO,CAAC,CAAC,CAAC,CAmCZ;AAED,0CAA0C;AAC1C,eAAO,MAAM,cAAc,QAAqC,CAAC;AAEjE;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,CAAC,CAAC,CAErF"}
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/soul/lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAOH,MAAM,WAAW,YAAY;IAC3B,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAyCD;;;GAGG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,IAAI,GAAE,YAAiB,GACtB,OAAO,CAAC,CAAC,CAAC,CAkDZ;AAED,0CAA0C;AAC1C,eAAO,MAAM,cAAc,QAAqC,CAAC;AAEjE;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,CAAC,CAAC,CAErF"}