@oratis/lisa 0.9.0 → 0.11.1

package/dist/agents/pty.js

@@ -0,0 +1,299 @@
+/**
+ * PTY-backed agents — EXPERIMENTAL spike (Stage C), OFF BY DEFAULT.
+ *
+ * Phase-3 managed agents run LISA's OWN agent loop (its tools, its provider).
+ * A PTY agent instead spawns the REAL `claude` / `codex` CLI inside a
+ * pseudo-terminal, so you get that tool's full configuration — its skills, MCP
+ * servers, hooks, model — while LISA owns stdin/stdout: it types your task and
+ * follow-ups, can answer prompts, and reads the stream for a coarse live status.
+ *
+ * HONEST LIMITS (why this is a flagged spike, not a shipped feature):
+ *  - Native dep: needs `node-pty` (an *optional* dependency). If it isn't built,
+ *    PTY agents are simply unavailable — nothing else in LISA changes.
+ *  - Off by default: set `LISA_PTY_AGENTS=1` to enable.
+ *  - Controls only CLIs LISA SPAWNS — NOT sessions you already opened in your
+ *    own terminal (those have no control channel; they stay observe-only).
+ *  - Output parsing is best-effort: the CLI's TUI is ANSI / box-drawn and
+ *    version-sensitive, so "state" is inferred from output quiescence, not from
+ *    parsed intent. The captured tail is shown to you (your own terminal), never
+ *    folded into the structural cross-agent roster.
+ */
+import { EventEmitter } from "node:events";
+import { readdirSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Is the PTY-agent spike enabled? Off unless LISA_PTY_AGENTS=1. */
+export function ptyEnabled() {
+    return process.env.LISA_PTY_AGENTS === "1";
+}
+/** Map a roster agent-kind to its CLI binary (env-overridable). */
+export function resolveCli(agent) {
+    const a = agent.toLowerCase();
+    if (a === "codex")
+        return process.env.LISA_PTY_CODEX_CMD || "codex";
+    // default to claude (covers "claude" / "claude-code")
+    return process.env.LISA_PTY_CLAUDE_CMD || "claude";
+}
+/** Normalize a loose agent label to a roster AgentKind. */
+export function normalizeAgentKind(agent) {
+    const a = agent.toLowerCase();
+    if (a === "codex")
+        return "codex";
+    if (a === "claude" || a === "claude-code")
+        return "claude-code";
+    return agent;
+}
+/**
+ * Best binary to drive a claude session: env override → the newest app-bundled
+ * claude (matches the version that wrote the sessions, best for --resume) → the
+ * PATH `claude`. The app-bundle probe is macOS-specific and silently no-ops
+ * elsewhere. Falls back to resolveCli for non-claude agents.
+ */
+export function detectClaudeBinary() {
+    if (process.env.LISA_PTY_CLAUDE_CMD)
+        return process.env.LISA_PTY_CLAUDE_CMD;
+    try {
+        const root = join(homedir(), "Library", "Application Support", "Claude", "claude-code");
+        const versions = readdirSync(root)
+            .filter((v) => /^\d+\.\d+\.\d+/.test(v))
+            .sort((a, b) => cmpVersion(b, a)); // newest first
+        for (const v of versions) {
+            const bin = join(root, v, "claude.app", "Contents", "MacOS", "claude");
+            if (existsSync(bin))
+                return bin;
+        }
+    }
+    catch {
+        /* not macOS / not installed → fall through */
+    }
+    return "claude";
+}
+function cmpVersion(a, b) {
+    const pa = a.split(".").map((n) => parseInt(n, 10) || 0);
+    const pb = b.split(".").map((n) => parseInt(n, 10) || 0);
+    for (let i = 0; i < 3; i++) {
+        if ((pa[i] || 0) !== (pb[i] || 0))
+            return (pa[i] || 0) - (pb[i] || 0);
+    }
+    return 0;
+}
+// Strip ANSI / VT100 escape sequences so the captured tail is plain-ish text.
+// Control anchors come via String.fromCharCode so the SOURCE carries no raw
+// control bytes (which trip greps, diffs, and some editors).
+const ESC = String.fromCharCode(27); // U+001B
+const CSI = String.fromCharCode(155); // U+009B
+const BEL = String.fromCharCode(7); // U+0007
+const ANSI = new RegExp("[" + ESC + CSI + "][[\\]()#;?]*" +
+    "(?:(?:(?:(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]+)*|[a-zA-Z\\d]+(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]*)*)?" +
+    BEL +
+    ")|(?:(?:\\d{1,4}(?:;\\d{0,4})*)?[\\dA-PR-TZcf-ntqry=><~]))", "g");
+/** Strip ANSI escape sequences + common bare control bytes (CR/backspace). Pure. */
+export function stripAnsi(s) {
+    // eslint-disable-next-line no-control-regex
+    return s.replace(ANSI, "").replace(/[\r\b]/g, "");
+}
+/**
+ * Coarse live state from output quiescence: actively streaming ⇒ "working";
+ * quiet longer than idleMs ⇒ "waiting" (likely awaiting input or a prompt).
+ * `done`/`error` are decided by lifecycle flags, not here. Pure.
+ */
+export function derivePtyState(lastChunkAtMs, nowMs, idleMs) {
+    return nowMs - lastChunkAtMs < idleMs ? "working" : "waiting";
+}
+const RING_MAX = 4000; // chars of ANSI-stripped tail kept
+const IDLE_MS = 4000; // quiet longer than this ⇒ "waiting"
+let counter = 0;
+async function loadPty() {
+    try {
+        // Non-literal specifier so `tsc` treats this as `any` and never hard-requires
+        // node-pty (it's an optionalDependency that may be absent). Resolved at runtime.
+        const spec = "node-pty";
+        const mod = await import(spec);
+        const resolved = mod && typeof mod.spawn === "function" ? mod : ((mod && mod.default) ?? mod);
+        return resolved;
+    }
+    catch {
+        return null;
+    }
+}
+/** One real CLI running under a pseudo-terminal that LISA drives. */
+export class PtyAgent {
+    id;
+    agent;
+    cli;
+    cwd;
+    project;
+    /** Real claude session id, when this agent is a resume-adopt (claude only). */
+    adoptedSessionId;
+    onChange = () => { };
+    /** Called with each ANSI-stripped output chunk — drives the live attach stream
+     *  (GET /api/agents/pty/<id>/stream). Distinct from onChange (state snapshots). */
+    onOutput = () => { };
+    proc;
+    now;
+    ring = "";
+    bytesOut = 0;
+    aborted = false;
+    exited = false;
+    exitReason = "";
+    lastChunkAt;
+    lastMtime;
+    constructor(id, opts, cli, proc, now) {
+        this.id = id;
+        this.agent = normalizeAgentKind(opts.agent);
+        this.cli = cli;
+        this.cwd = opts.cwd;
+        this.project = opts.cwd.split("/").filter(Boolean).pop() || opts.cwd;
+        this.adoptedSessionId =
+            opts.resumeSessionId && this.agent === "claude-code" ? opts.resumeSessionId : undefined;
+        this.proc = proc;
+        this.now = now;
+        this.lastChunkAt = now();
+        this.lastMtime = now();
+        proc.onData((d) => this.onData(d));
+        proc.onExit((e) => this.onExit(e));
+    }
+    /** Spawn a real CLI under a PTY and type the initial task. */
+    static async start(opts) {
+        if (!ptyEnabled()) {
+            throw new Error("PTY agents are disabled — set LISA_PTY_AGENTS=1 to enable this spike");
+        }
+        const pty = opts.ptyModule ?? (await loadPty());
+        if (!pty) {
+            throw new Error("node-pty is not installed — run `npm i node-pty` to enable PTY agents");
+        }
+        const kind = normalizeAgentKind(opts.agent);
+        const cli = opts.cli ?? (kind === "claude-code" ? detectClaudeBinary() : resolveCli(opts.agent));
+        // Adopt an existing session by id (claude only): `claude --resume <id>`.
+        const resumeArgs = opts.resumeSessionId && kind === "claude-code" ? ["--resume", opts.resumeSessionId] : [];
+        const args = [...resumeArgs, ...(opts.args ?? [])];
+        const now = opts.now ?? Date.now;
+        const proc = pty.spawn(cli, args, {
+            name: "xterm-256color",
+            cols: opts.cols ?? 120,
+            rows: opts.rows ?? 32,
+            cwd: opts.cwd,
+            env: process.env,
+        });
+        const id = "p" + (++counter).toString(36) + "-" + Date.now().toString(36).slice(-4);
+        const agent = new PtyAgent(id, opts, cli, proc, now);
+        if (opts.task)
+            agent.send(opts.task);
+        return agent;
+    }
+    /** Type a line into the CLI (initial task or a follow-up). */
+    send(text) {
+        if (this.aborted || this.exited)
+            return;
+        this.proc.write(text + "\r");
+        this.touch();
+    }
+    /** Kill the CLI. Idempotent. */
+    cancel() {
+        if (this.exited)
+            return;
+        this.aborted = true;
+        try {
+            this.proc.kill();
+        }
+        catch {
+            /* already gone */
+        }
+        this.exitReason = "cancelled";
+        this.touch();
+    }
+    /**
+     * ANSI-stripped tail of the terminal — the user's window into THEIR agent.
+     * Exposed only via an explicit endpoint, never folded into the structural
+     * cross-agent roster (which stays metadata-only).
+     */
+    output() {
+        return this.ring;
+    }
+    view() {
+        let state;
+        let reason;
+        if (this.aborted) {
+            state = "done";
+            reason = "cancelled";
+        }
+        else if (this.exited) {
+            state = "done";
+            reason = this.exitReason || "exited";
+        }
+        else {
+            state = derivePtyState(this.lastChunkAt, this.now(), IDLE_MS);
+            reason = state === "working" ? "streaming" : "idle";
+        }
+        return {
+            id: this.id,
+            agent: this.agent,
+            cli: this.cli,
+            project: this.project,
+            cwd: this.cwd,
+            state,
+            stateReason: reason,
+            lastMtime: this.lastMtime,
+            bytesOut: this.bytesOut,
+            ...(this.adoptedSessionId ? { adoptedSessionId: this.adoptedSessionId } : {}),
+        };
+    }
+    // ── internals ──
+    onData(d) {
+        this.bytesOut += d.length;
+        const clean = stripAnsi(d);
+        this.ring = (this.ring + clean).slice(-RING_MAX);
+        this.lastChunkAt = this.now();
+        if (clean)
+            this.onOutput(clean);
+        this.touch();
+    }
+    onExit(e) {
+        this.exited = true;
+        if (!this.exitReason)
+            this.exitReason = "exit " + e.exitCode;
+        this.touch();
+    }
+    touch() {
+        this.lastMtime = this.now();
+        this.onChange();
+    }
+}
+/** Process-wide registry of PTY agents; emits "update" with a PtyView. */
+export class PtyRegistry extends EventEmitter {
+    agents = new Map();
+    async start(opts) {
+        const a = await PtyAgent.start(opts);
+        a.onChange = () => this.emit("update", a.view());
+        a.onOutput = (chunk) => this.emit("output", { id: a.id, chunk });
+        this.agents.set(a.id, a);
+        this.emit("update", a.view());
+        return a.view();
+    }
+    send(id, text) {
+        const a = this.agents.get(id);
+        if (!a)
+            return false;
+        a.send(text);
+        return true;
+    }
+    cancel(id) {
+        const a = this.agents.get(id);
+        if (!a)
+            return false;
+        a.cancel();
+        return true;
+    }
+    /** ANSI-stripped tail of a PTY agent's terminal, or null if unknown. */
+    output(id) {
+        return this.agents.get(id)?.output() ?? null;
+    }
+    get(id) {
+        return this.agents.get(id);
+    }
+    list() {
+        return [...this.agents.values()].map((a) => a.view());
+    }
+}
+export const ptyRegistry = new PtyRegistry();
+//# sourceMappingURL=pty.js.map

package/dist/agents/pty.js.map

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

package/dist/approval.d.ts

@@ -3,7 +3,20 @@ export type ApprovalMode = "auto" | "ask" | "ask-mutating";
 export interface ApprovalConfig {
     mode: ApprovalMode;
     mutatingTools: Set<string>;
+    /** Per-tool action-level mutating gate, for action-dispatched tools whose
+     *  reads are safe but writes aren't (e.g. github). tool → mutating actions. */
+    mutatingActions?: Record<string, string[]>;
+    /** Injectable prompt reader (tests); defaults to reading one stdin line. */
+    readLine?: () => Promise<string>;
 }
 export declare const DEFAULT_MUTATING_TOOLS: Set<string>;
+/**
+ * Action-dispatched tools where only SOME actions mutate. Reads (issue_view,
+ * pr_view, …) stay un-gated under ask-mutating; only these write actions prompt.
+ * Mirrors github.ts's own "reads are safe; create/comment/merge are writes".
+ */
+export declare const DEFAULT_MUTATING_ACTIONS: Record<string, string[]>;
+/** Does this tool call change state (so ask-mutating should prompt)? */
+export declare function isMutatingCall(cfg: ApprovalConfig, toolName: string, input: unknown): boolean;
 export declare function buildApprovalCallback(cfg: ApprovalConfig): ApprovalCallback | undefined;
 //# sourceMappingURL=approval.d.ts.map

package/dist/approval.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"approval.d.ts","sourceRoot":"","sources":["../src/approval.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAoB,MAAM,YAAY,CAAC;AAErE,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,KAAK,GAAG,cAAc,CAAC;AAE3D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,YAAY,CAAC;IACnB,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC5B;AAED,eAAO,MAAM,sBAAsB,aAKjC,CAAC;AAEH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,cAAc,GAClB,gBAAgB,GAAG,SAAS,CAgB9B"}
+{"version":3,"file":"approval.d.ts","sourceRoot":"","sources":["../src/approval.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAoB,MAAM,YAAY,CAAC;AAErE,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,KAAK,GAAG,cAAc,CAAC;AAE3D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,YAAY,CAAC;IACnB,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B;mFAC+E;IAC/E,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC3C,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CAClC;AAED,eAAO,MAAM,sBAAsB,aAQjC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAE7D,CAAC;AAEF,wEAAwE;AACxE,wBAAgB,cAAc,CAC5B,GAAG,EAAE,cAAc,EACnB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,OAAO,GACb,OAAO,CAQT;AAED,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,cAAc,GAClB,gBAAgB,GAAG,SAAS,CAgB9B"}

package/dist/approval.js

@@ -4,17 +4,40 @@ export const DEFAULT_MUTATING_TOOLS = new Set([
     "edit",
     "apply_patch",
     "bash",
+    // Local execution / process control — always state-changing.
+    "dispatch_agent",
+    "signal_agent",
 ]);
+/**
+ * Action-dispatched tools where only SOME actions mutate. Reads (issue_view,
+ * pr_view, …) stay un-gated under ask-mutating; only these write actions prompt.
+ * Mirrors github.ts's own "reads are safe; create/comment/merge are writes".
+ */
+export const DEFAULT_MUTATING_ACTIONS = {
+    github: ["issue_create", "issue_comment", "pr_create", "pr_comment", "pr_merge"],
+};
+/** Does this tool call change state (so ask-mutating should prompt)? */
+export function isMutatingCall(cfg, toolName, input) {
+    if (cfg.mutatingTools.has(toolName))
+        return true;
+    const actions = cfg.mutatingActions?.[toolName];
+    if (actions && input && typeof input === "object") {
+        const action = input.action;
+        if (typeof action === "string" && actions.includes(action))
+            return true;
+    }
+    return false;
+}
 export function buildApprovalCallback(cfg) {
     if (cfg.mode === "auto")
         return undefined;
     return async (toolName, toolInput) => {
-        if (cfg.mode === "ask-mutating" && !cfg.mutatingTools.has(toolName)) {
+        if (cfg.mode === "ask-mutating" && !isMutatingCall(cfg, toolName, toolInput)) {
             return { allow: true };
         }
         const preview = previewInput(toolInput);
         process.stderr.write(`\n[approval] ${toolName}(${preview})\n  [y]es / [n]o (default n) > `);
-        const answer = await readSingleLine();
+        const answer = await (cfg.readLine ?? readSingleLine)();
         if (/^y(es)?$/i.test(answer.trim())) {
             return { allow: true };
         }

package/dist/approval.js.map

@@ -1 +1 @@
-{"version":3,"file":"approval.js","sourceRoot":"","sources":["../src/approval.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,eAAe,CAAC;AAUrC,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,GAAG,CAAC;IAC5C,OAAO;IACP,MAAM;IACN,aAAa;IACb,MAAM;CACP,CAAC,CAAC;AAEH,MAAM,UAAU,qBAAqB,CACnC,GAAmB;IAEnB,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM;QAAE,OAAO,SAAS,CAAC;IAC1C,OAAO,KAAK,EAAE,QAAgB,EAAE,SAAkB,EAA6B,EAAE;QAC/E,IAAI,GAAG,CAAC,IAAI,KAAK,cAAc,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YACpE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QACzB,CAAC;QACD,MAAM,OAAO,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC;QACxC,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,gBAAgB,QAAQ,IAAI,OAAO,kCAAkC,CACtE,CAAC;QACF,MAAM,MAAM,GAAG,MAAM,cAAc,EAAE,CAAC;QACtC,IAAI,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;YACpC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QACzB,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,aAAa,EAAE,CAAC;IAClE,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACnC,IAAI,IAAI,CAAC,MAAM,IAAI,GAAG;YAAE,OAAO,IAAI,CAAC;QACpC,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,KAAK,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;AACH,CAAC;AAED,SAAS,cAAc;IACrB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,EAAE,GAAG,QAAQ,CAAC,eAAe,CAAC;YAClC,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,CAAC;QACH,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;YACvB,EAAE,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,CAAC,IAAI,CAAC,CAAC;QAChB,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"approval.js","sourceRoot":"","sources":["../src/approval.ts"],"names":[],"mappings":"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"}

package/dist/autonomy/runs.d.ts

@@ -0,0 +1,33 @@
+export declare const AUTONOMY_DIR: string;
+/** Which self-driven mechanism produced the run. */
+export type AutonomyKind = "idle" | "heartbeat" | "examen" | "desire" | "reflect";
+/**
+ * What actually happened — replaces the old silent/non-silent binary.
+ * - "done"       — produced a user-facing result / made real progress
+ * - "no-update"  — ran fine, nothing worth surfacing (internal-only)
+ * - "blocked"    — stopped early by a guard (e.g. token budget breaker)
+ * - "error"      — threw / produced unusable output
+ */
+export type AutonomyOutcome = "done" | "no-update" | "blocked" | "error";
+export interface AutonomyRun {
+    kind: AutonomyKind;
+    /** Task name for heartbeat/desire/examen runs (e.g. "desire:learn-rust"). */
+    task?: string;
+    /** ISO 8601 start time. */
+    startedAt: string;
+    durationMs: number;
+    inputTokens: number;
+    outputTokens: number;
+    /** Tool calls observed during the run, when known. */
+    toolCalls?: number;
+    outcome: AutonomyOutcome;
+    /** Short human note — failure reason, stop reason, etc. */
+    note?: string;
+}
+/** Append one run record; trim the ledger opportunistically. Never throws. */
+export declare function recordAutonomyRun(run: AutonomyRun): Promise<void>;
+/** Read run records, optionally only those within the last `sinceMs`. */
+export declare function readAutonomyRuns(sinceMs?: number): Promise<AutonomyRun[]>;
+/** Human-readable digest for `lisa autonomy`. */
+export declare function summarizeAutonomyRuns(runs: AutonomyRun[]): string;
+//# sourceMappingURL=runs.d.ts.map

package/dist/autonomy/runs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runs.d.ts","sourceRoot":"","sources":["../../src/autonomy/runs.ts"],"names":[],"mappings":"AAoBA,eAAO,MAAM,YAAY,QAAmC,CAAC;AAK7D,oDAAoD;AACpD,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAElF;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AAEzE,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,YAAY,CAAC;IACnB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,eAAe,CAAC;IACzB,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,8EAA8E;AAC9E,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBvE;AAED,yEAAyE;AACzE,wBAAsB,gBAAgB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAgB/E;AAED,iDAAiD;AACjD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,MAAM,CAoCjE"}

package/dist/autonomy/runs.js

@@ -0,0 +1,106 @@
+/**
+ * Autonomy run ledger (PLAN_REVE_v1.0 R2).
+ *
+ * Every self-driven run — idle reflection (Reve), heartbeat tasks, desire pursuits, the
+ * weekly examen, end-of-session reflection — appends one structured record
+ * here. Before this, autonomy was a black box: idle/heartbeat logged their
+ * final text and a `silent` boolean, so you couldn't tell "did real work" from
+ * "said (no update) but actually failed to run". This ledger makes outcome,
+ * cost, and cadence observable (see `lisa autonomy`).
+ *
+ * Storage: append-only JSONL at ~/.lisa/autonomy/runs.jsonl, bounded to the
+ * last MAX_RUNS lines so it can't grow without limit. Append of a single small
+ * line is atomic on POSIX (O_APPEND); the trim runs opportunistically under a
+ * cross-process lock.
+ */
+import path from "node:path";
+import { LISA_HOME } from "../paths.js";
+import { appendLine, atomicWrite, readTextOrEmpty } from "../fs-utils.js";
+import { withFileLock } from "../soul/lock.js";
+export const AUTONOMY_DIR = path.join(LISA_HOME, "autonomy");
+const RUNS_FILE = path.join(AUTONOMY_DIR, "runs.jsonl");
+const RUNS_LOCK = path.join(AUTONOMY_DIR, "runs.lock");
+const MAX_RUNS = 2000;
+/** Append one run record; trim the ledger opportunistically. Never throws. */
+export async function recordAutonomyRun(run) {
+    try {
+        await appendLine(RUNS_FILE, JSON.stringify(run));
+    }
+    catch {
+        return; // recording is best-effort; never break the autonomy run on it
+    }
+    try {
+        const lineCount = (await readTextOrEmpty(RUNS_FILE)).split("\n").filter((l) => l.trim()).length;
+        if (lineCount > MAX_RUNS) {
+            await withFileLock(RUNS_LOCK, async () => {
+                const lines = (await readTextOrEmpty(RUNS_FILE)).split("\n").filter((l) => l.trim());
+                if (lines.length > MAX_RUNS) {
+                    await atomicWrite(RUNS_FILE, lines.slice(lines.length - MAX_RUNS).join("\n") + "\n");
+                }
+            }, { timeoutMs: 2_000, staleMs: 60_000 });
+        }
+    }
+    catch {
+        // trimming is best-effort
+    }
+}
+/** Read run records, optionally only those within the last `sinceMs`. */
+export async function readAutonomyRuns(sinceMs) {
+    const raw = await readTextOrEmpty(RUNS_FILE);
+    const cutoff = sinceMs != null ? Date.now() - sinceMs : null;
+    const out = [];
+    for (const line of raw.split("\n")) {
+        const t = line.trim();
+        if (!t)
+            continue;
+        try {
+            const run = JSON.parse(t);
+            if (cutoff != null && new Date(run.startedAt).getTime() < cutoff)
+                continue;
+            out.push(run);
+        }
+        catch {
+            // skip a malformed line rather than failing the whole read
+        }
+    }
+    return out;
+}
+/** Human-readable digest for `lisa autonomy`. */
+export function summarizeAutonomyRuns(runs) {
+    if (runs.length === 0)
+        return "No autonomy runs recorded yet.";
+    const byKind = new Map();
+    const byOutcome = new Map();
+    let inTok = 0;
+    let outTok = 0;
+    for (const r of runs) {
+        byKind.set(r.kind, (byKind.get(r.kind) ?? 0) + 1);
+        byOutcome.set(r.outcome, (byOutcome.get(r.outcome) ?? 0) + 1);
+        inTok += r.inputTokens || 0;
+        outTok += r.outputTokens || 0;
+    }
+    const fmtMap = (m) => Array.from(m.entries())
+        .sort((a, b) => b[1] - a[1])
+        .map(([k, n]) => `${k} ${n}`)
+        .join(" · ");
+    const k = (n) => (n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n));
+    const recent = runs
+        .slice(-10)
+        .reverse()
+        .map((r) => {
+        const when = r.startedAt.replace("T", " ").slice(0, 16);
+        const label = (r.task ?? r.kind).padEnd(22).slice(0, 22);
+        const tok = k((r.inputTokens || 0) + (r.outputTokens || 0));
+        return `  ${when}  ${label} ${r.outcome.padEnd(10)} ${tok} tok`;
+    })
+        .join("\n");
+    return [
+        `Autonomy runs: ${runs.length} total`,
+        `  by kind:    ${fmtMap(byKind)}`,
+        `  by outcome: ${fmtMap(byOutcome)}`,
+        `  tokens:     in ${k(inTok)} · out ${k(outTok)}`,
+        `  recent:`,
+        recent,
+    ].join("\n");
+}
+//# sourceMappingURL=runs.js.map

package/dist/autonomy/runs.js.map

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

package/dist/channels/feishu.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"feishu.d.ts","sourceRoot":"","sources":["../../src/channels/feishu.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EACf,eAAe,EAChB,MAAM,YAAY,CAAC;AAEpB,UAAU,aAAa;IACrB,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,8DAA8D;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAOD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,aAAc,YAAW,cAAc;IAClD,QAAQ,CAAC,IAAI,YAAY;IACzB,OAAO,CAAC,IAAI,CAAgB;IAC5B,OAAO,CAAC,MAAM,CAAC,CAAc;IAC7B,OAAO,CAAC,OAAO,CAAC,CAA0C;IAC1D,OAAO,CAAC,UAAU,CAAC,CAAyB;IAC5C,OAAO,CAAC,cAAc,CAAqB;gBAE/B,IAAI,EAAE,aAAa;IASzB,KAAK,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAWtE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAQrB,IAAI,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;YA+BjC,SAAS;YAwCT,WAAW;YA+DX,oBAAoB;IAoClC,OAAO,CAAC,OAAO;CAoBhB"}
+{"version":3,"file":"feishu.d.ts","sourceRoot":"","sources":["../../src/channels/feishu.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EACf,eAAe,EAChB,MAAM,YAAY,CAAC;AAEpB,UAAU,aAAa;IACrB,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,8DAA8D;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAOD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,aAAc,YAAW,cAAc;IAClD,QAAQ,CAAC,IAAI,YAAY;IACzB,OAAO,CAAC,IAAI,CAAgB;IAC5B,OAAO,CAAC,MAAM,CAAC,CAAc;IAC7B,OAAO,CAAC,OAAO,CAAC,CAA0C;IAC1D,OAAO,CAAC,UAAU,CAAC,CAAyB;IAC5C,OAAO,CAAC,cAAc,CAAqB;gBAE/B,IAAI,EAAE,aAAa;IAkBzB,KAAK,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAWtE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAQrB,IAAI,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;YA+BjC,SAAS;YA2FT,WAAW;YA+DX,oBAAoB;IAoClC,OAAO,CAAC,OAAO;CAoBhB"}

package/dist/channels/feishu.js

@@ -32,6 +32,13 @@ export class FeishuChannel {
         if (!opts.appId || !opts.appSecret) {
             throw new Error("feishu: appId and appSecret are required");
         }
+        // Without either credential we cannot authenticate inbound events at all —
+        // anyone who can reach the webhook port could impersonate Feishu and feed
+        // arbitrary messages to the agent. Both values live on the same console
+        // page as the app secret (事件订阅 → Verification Token / Encrypt Key).
+        if (!opts.verificationToken && !opts.encryptKey) {
+            throw new Error("feishu: verificationToken (or encryptKey) is required — without one, inbound events are unauthenticated");
+        }
         this.opts = opts;
     }
     // ─── Lifecycle ────────────────────────────────────────────────────────────
@@ -78,6 +85,35 @@ export class FeishuChannel {
             return;
         }
         const rawBody = await readBody(req);
+        // ── Signature check (when encryptKey is configured) ─────────────────────
+        // Feishu signs every delivery with X-Lark-Signature =
+        // sha256(timestamp + nonce + encryptKey + rawBody) hex, alongside
+        // X-Lark-Request-Timestamp / X-Lark-Request-Nonce. Verify it (and a 5min
+        // freshness window against replays) whenever the headers are present.
+        if (this.opts.encryptKey) {
+            const sig = headerString(req, "x-lark-signature");
+            const ts = headerString(req, "x-lark-request-timestamp");
+            const nonce = headerString(req, "x-lark-request-nonce");
+            if (sig && ts && nonce) {
+                const expected = crypto
+                    .createHash("sha256")
+                    .update(ts + nonce + this.opts.encryptKey + rawBody)
+                    .digest("hex");
+                if (!timingSafeEqualStr(sig, expected)) {
+                    console.error("[feishu] rejected event: bad X-Lark-Signature");
+                    res.writeHead(403);
+                    res.end("bad signature");
+                    return;
+                }
+                const ageMs = Math.abs(Date.now() - Number(ts) * 1000);
+                if (!Number.isFinite(ageMs) || ageMs > 5 * 60_000) {
+                    console.error("[feishu] rejected event: stale timestamp (replay?)");
+                    res.writeHead(403);
+                    res.end("stale timestamp");
+                    return;
+                }
+            }
+        }
         let payload;
         try {
             payload = this.opts.encryptKey
@@ -90,6 +126,25 @@ export class FeishuChannel {
             res.end("bad payload");
             return;
         }
+        // ── Verification-token check ─────────────────────────────────────────────
+        // The token rides in the payload itself: top-level `token` on the URL
+        // challenge (v1), `header.token` on v2 events. It was stored in config but
+        // never actually checked — making the webhook spoofable by anyone who
+        // could reach the port.
+        if (this.opts.verificationToken) {
+            const header = payload.header;
+            const presented = typeof payload.token === "string"
+                ? payload.token
+                : typeof header?.token === "string"
+                    ? header.token
+                    : "";
+            if (!presented || !timingSafeEqualStr(presented, this.opts.verificationToken)) {
+                console.error("[feishu] rejected event: verification token mismatch");
+                res.writeHead(403);
+                res.end("bad token");
+                return;
+            }
+        }
         // ── URL verification challenge ──────────────────────────────────────────
         if (typeof payload.challenge === "string") {
             res.writeHead(200, { "content-type": "application/json" });
@@ -202,6 +257,16 @@ export class FeishuChannel {
     }
 }
 // ─── Helpers ──────────────────────────────────────────────────────────────────
+function headerString(req, name) {
+    const v = req.headers[name];
+    return typeof v === "string" ? v : Array.isArray(v) ? (v[0] ?? "") : "";
+}
+function timingSafeEqualStr(a, b) {
+    // Hash both sides so the comparison is constant-time regardless of length.
+    const ha = crypto.createHash("sha256").update(a).digest();
+    const hb = crypto.createHash("sha256").update(b).digest();
+    return crypto.timingSafeEqual(ha, hb);
+}
 function readBody(req) {
     return new Promise((resolve, reject) => {
         let body = "";