@oratis/lisa 0.3.1 → 0.5.0

package/dist/advisor/detectors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Advisor detectors — pure functions: an AdvisorInput snapshot in, candidate
+ * Suggestions out. No I/O, no state mutation, fully testable. The engine
+ * (engine.ts) is what scores + throttles + dedupes them.
+ *
+ * Every detector works from STRUCTURAL signals only (state, cwd, the Tier-2
+ * SessionActivity) — never conversation content.
+ */
+import type { AdvisorInput, Suggestion } from "./types.js";
+export declare const STUCK_MS: number;
+export declare const COST_SPIKE_TOKENS = 1500000;
+/** Pending permission → urgent, actionable. */
+export declare function detectPermission(input: AdvisorInput): Suggestion[];
+export declare function detectStuck(input: AdvisorInput): Suggestion[];
+/** Two+ active sessions sharing a cwd (or an overlapping touched file). */
+export declare function detectConflict(input: AdvisorInput): Suggestion[];
+/** Combined token usage across active sessions above the spike threshold. */
+export declare function detectCostSpike(input: AdvisorInput): Suggestion[];
+/** A session that finished a turn and is awaiting you (end_turn / done). */
+export declare function detectReady(input: AdvisorInput): Suggestion[];
+/** Nothing running but standing chores exist. */
+export declare function detectIdleCapacity(input: AdvisorInput): Suggestion[];
+/** Run every detector and concatenate their candidates. */
+export declare function runAllDetectors(input: AdvisorInput): Suggestion[];
+//# sourceMappingURL=detectors.d.ts.map

package/dist/advisor/detectors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detectors.d.ts","sourceRoot":"","sources":["../../src/advisor/detectors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAA+B,MAAM,YAAY,CAAC;AAGxF,eAAO,MAAM,QAAQ,QAAc,CAAC;AACpC,eAAO,MAAM,iBAAiB,UAAY,CAAC;AAoB3C,+CAA+C;AAC/C,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,UAAU,EAAE,CAkBlE;AAoBD,wBAAgB,WAAW,CAAC,KAAK,EAAE,YAAY,GAAG,UAAU,EAAE,CAyC7D;AAED,2EAA2E;AAC3E,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,UAAU,EAAE,CA2BhE;AAED,6EAA6E;AAC7E,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,UAAU,EAAE,CA6BjE;AAED,4EAA4E;AAC5E,wBAAgB,WAAW,CAAC,KAAK,EAAE,YAAY,GAAG,UAAU,EAAE,CAqB7D;AAED,iDAAiD;AACjD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,UAAU,EAAE,CAiBpE;AAED,2DAA2D;AAC3D,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,UAAU,EAAE,CASjE"}

package/dist/advisor/detectors.js

@@ -0,0 +1,161 @@
+/**
+ * Advisor detectors — pure functions: an AdvisorInput snapshot in, candidate
+ * Suggestions out. No I/O, no state mutation, fully testable. The engine
+ * (engine.ts) is what scores + throttles + dedupes them.
+ *
+ * Every detector works from STRUCTURAL signals only (state, cwd, the Tier-2
+ * SessionActivity) — never conversation content.
+ */
+// Thresholds (ms). Tuned to "a human would want this flagged".
+export const STUCK_MS = 10 * 60_000; // waiting/error with no change for 10 min
+export const COST_SPIKE_TOKENS = 1_500_000; // combined tokens across active sessions
+function mk(id, category, urgency, text, conditionHash, now, action) {
+    return { id, category, urgency, text, conditionHash, ts: now, action, score: 0 };
+}
+function basename(p) {
+    if (!p)
+        return "";
+    const parts = p.split("/");
+    return parts[parts.length - 1] || p;
+}
+/** Pending permission → urgent, actionable. */
+export function detectPermission(input) {
+    const out = [];
+    for (const s of input.sessions) {
+        const pend = s.activity?.pendingPermission;
+        if (!pend)
+            continue;
+        out.push(mk(`permission:${s.agent}:${s.sessionId}`, "stuck", "urgent", `${s.project} wants to run ${pend} — approve?`, `permission:${pend}`, input.now, { label: "Approve", kind: "approve", arg: s.sessionId }));
+    }
+    return out;
+}
+/**
+ * "Stuck" = a session that looks like it needs attention but isn't making
+ * progress. The trap (and the v1 noise bug) is that a `waiting` session is
+ * USUALLY fine — Claude finished its turn (end_turn) and is just idle waiting
+ * for the user. That's not stuck, it's normal, and flagging every >10min idle
+ * session buries the real signal.
+ *
+ * So a session counts as stuck only when:
+ *   - state is `error` (something actually broke), OR
+ *   - state is `waiting` with a reason that means "blocked / not cleanly
+ *     finished" — i.e. NOT end_turn/stop_sequence/max_tokens (clean stops,
+ *     surfaced quietly by detectReady instead).
+ * AND it's been quiet for ≥ STUCK_MS. If more than COLLAPSE_THRESHOLD qualify,
+ * emit ONE rolled-up line so the digest stays scannable.
+ */
+const CLEAN_STOP_REASONS = new Set(["end_turn", "stop_sequence", "max_tokens"]);
+const COLLAPSE_THRESHOLD = 3;
+export function detectStuck(input) {
+    const stuck = input.sessions.filter((s) => {
+        if (s.activity?.pendingPermission)
+            return false; // detectPermission owns these
+        if (input.now - s.lastMtime < STUCK_MS)
+            return false;
+        if (s.state === "error")
+            return true;
+        if (s.state === "waiting")
+            return !CLEAN_STOP_REASONS.has(s.stateReason);
+        return false;
+    });
+    if (stuck.length === 0)
+        return [];
+    if (stuck.length > COLLAPSE_THRESHOLD) {
+        const errs = stuck.filter((s) => s.state === "error").length;
+        const detail = errs > 0 ? ` (${errs} errored)` : "";
+        return [
+            mk(`stuck-many:${stuck.length}`, "stuck", "notice", `${stuck.length} agent sessions look stuck or stalled${detail} — want the list?`, `stuck-many:${stuck.length}:${errs}`, input.now, { label: "List", kind: "look", arg: "stuck" }),
+        ];
+    }
+    return stuck.map((s) => {
+        const mins = Math.round((input.now - s.lastMtime) / 60_000);
+        const cmd = s.activity?.lastCommandName;
+        const why = s.state === "error" ? "errored" : "has stalled";
+        const on = cmd ? ` on \`${cmd}\`` : "";
+        return mk(`stuck:${s.agent}:${s.sessionId}`, "stuck", "notice", `${s.project} ${why}${on} (idle ${mins}m) — want me to look, or cancel it?`, `stuck:${s.state}:${s.stateReason}:${cmd ?? ""}`, input.now, { label: "Look", kind: "look", arg: s.sessionId });
+    });
+}
+/** Two+ active sessions sharing a cwd (or an overlapping touched file). */
+export function detectConflict(input) {
+    const out = [];
+    const byCwd = new Map();
+    for (const s of input.sessions) {
+        if (!s.cwd)
+            continue;
+        if (s.state !== "working" && s.state !== "waiting")
+            continue;
+        const arr = byCwd.get(s.cwd) ?? [];
+        arr.push(s);
+        byCwd.set(s.cwd, arr);
+    }
+    for (const [cwd, group] of byCwd) {
+        if (group.length < 2)
+            continue;
+        const agents = [...new Set(group.map((g) => g.agent))];
+        const label = basename(cwd);
+        out.push(mk(`conflict:${cwd}`, "conflict", "notice", `${group.length} agents (${agents.join(", ")}) are both working in ${label} — high risk of clobbering. Serialize?`, `conflict:${group.map((g) => g.sessionId).sort().join(",")}`, input.now, { label: "Serialize", kind: "serialize", arg: cwd }));
+    }
+    return out;
+}
+/** Combined token usage across active sessions above the spike threshold. */
+export function detectCostSpike(input) {
+    let total = 0;
+    let topSession = null;
+    let topTokens = 0;
+    for (const s of input.sessions) {
+        const t = s.activity?.tokens;
+        if (!t)
+            continue;
+        const sum = (t.input ?? 0) + (t.output ?? 0);
+        total += sum;
+        if (sum > topTokens) {
+            topTokens = sum;
+            topSession = s;
+        }
+    }
+    if (total < COST_SPIKE_TOKENS)
+        return [];
+    const millions = (total / 1_000_000).toFixed(1);
+    const pct = total > 0 ? Math.round((topTokens / total) * 100) : 0;
+    const who = topSession ? ` — ${topSession.project} is ${pct}% of it` : "";
+    return [
+        mk(`cost:${Math.round(total / 100_000)}`, // bucketed so it re-fires per ~100k step
+        "cost_spike", "notice", `Active agents are at ${millions}M tokens${who}.`, `cost:${Math.round(total / 500_000)}`, input.now, topSession ? { label: "Look", kind: "look", arg: topSession.sessionId } : undefined),
+    ];
+}
+/** A session that finished a turn and is awaiting you (end_turn / done). */
+export function detectReady(input) {
+    const out = [];
+    for (const s of input.sessions) {
+        const ready = s.state === "done" ||
+            (s.state === "waiting" && s.stateReason === "end_turn");
+        if (!ready)
+            continue;
+        if (s.activity?.lastError)
+            continue; // erroring isn't "ready"
+        out.push(mk(`ready:${s.agent}:${s.sessionId}`, "ready", "info", `${s.project} finished and is waiting for you.`, `ready:${s.lastMtime}`, input.now, { label: "Open", kind: "open", arg: s.cwd ?? s.sessionId }));
+    }
+    return out;
+}
+/** Nothing running but standing chores exist. */
+export function detectIdleCapacity(input) {
+    const active = input.sessions.some((s) => s.state === "working" || s.state === "waiting");
+    const pending = input.pendingDesireCount ?? 0;
+    if (active || pending <= 0)
+        return [];
+    return [
+        mk("idle-capacity", "idle", "info", `Nothing's running and you have ${pending} standing ${pending === 1 ? "task" : "tasks"} — want me to dispatch them?`, `idle:${pending}`, input.now, { label: "Dispatch", kind: "dispatch", arg: String(pending) }),
+    ];
+}
+/** Run every detector and concatenate their candidates. */
+export function runAllDetectors(input) {
+    return [
+        ...detectPermission(input),
+        ...detectStuck(input),
+        ...detectConflict(input),
+        ...detectCostSpike(input),
+        ...detectReady(input),
+        ...detectIdleCapacity(input),
+    ];
+}
+//# sourceMappingURL=detectors.js.map

package/dist/advisor/detectors.js.map

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

package/dist/advisor/engine.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Advisor engine — the anti-annoyance brain.
+ *
+ * Pure decision core: given this run's candidate suggestions + the persisted
+ * advisor state + the clock, decide which clear the relevance bar AND the
+ * throttle AND dedup, and which get suppressed (journaled, not shown). The
+ * caller does the I/O (load/save state, surface the survivors).
+ *
+ * See docs/ORCHESTRATOR_PLAN.md §5b.3 for the anti-annoyance contract.
+ */
+import { type AdvisorDecision, type AdvisorInput, type AdvisorState, type Suggestion, type SuggestionCategory } from "./types.js";
+export declare const ADVISOR_STATE_PATH: string;
+/** Relevance score = urgency × actionability × dismissal-decay. */
+export declare function scoreSuggestion(s: Suggestion, state: AdvisorState): number;
+/**
+ * Pure decision. Returns the surface/suppress split AND the next state to
+ * persist. Does not touch disk.
+ */
+export declare function decide(candidates: Suggestion[], state: AdvisorState, now: number): {
+    decision: AdvisorDecision;
+    nextState: AdvisorState;
+};
+/** Record a user dismissal so the category fades over time. */
+export declare function applyDismissal(state: AdvisorState, id: string, category: SuggestionCategory): AdvisorState;
+export declare function loadAdvisorState(p?: string): Promise<AdvisorState>;
+export declare function saveAdvisorState(state: AdvisorState, p?: string): Promise<void>;
+/**
+ * Full advise cycle: detect → decide → persist. Returns the suggestions to
+ * surface. Uses the soul lock so a heartbeat advise can't race a manual one.
+ */
+export declare function advise(input: AdvisorInput, statePath?: string): Promise<AdvisorDecision>;
+/**
+ * On-demand ("pull") advice: run the detectors against the current snapshot
+ * and return everything above the bar, sorted — WITHOUT the throttle/dedup
+ * (the user explicitly asked, so don't suppress) and WITHOUT mutating state.
+ * Used by the advise_now tool.
+ */
+export declare function adviseNow(input: AdvisorInput, state?: AdvisorState): Suggestion[];
+/** Render surfaced suggestions into one digest card (markdown-ish text). */
+export declare function formatDigest(suggestions: Suggestion[]): string;
+//# sourceMappingURL=engine.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/advisor/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAQH,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,kBAAkB,EACxB,MAAM,YAAY,CAAC;AAQpB,eAAO,MAAM,kBAAkB,QAA6C,CAAC;AAE7E,mEAAmE;AACnE,wBAAgB,eAAe,CAAC,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE,YAAY,GAAG,MAAM,CAO1E;AAUD;;;GAGG;AACH,wBAAgB,MAAM,CACpB,UAAU,EAAE,UAAU,EAAE,EACxB,KAAK,EAAE,YAAY,EACnB,GAAG,EAAE,MAAM,GACV;IAAE,QAAQ,EAAE,eAAe,CAAC;IAAC,SAAS,EAAE,YAAY,CAAA;CAAE,CAgDxD;AAED,+DAA+D;AAC/D,wBAAgB,cAAc,CAC5B,KAAK,EAAE,YAAY,EACnB,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,kBAAkB,GAC3B,YAAY,CASd;AAID,wBAAsB,gBAAgB,CACpC,CAAC,GAAE,MAA2B,GAC7B,OAAO,CAAC,YAAY,CAAC,CAQvB;AAED,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,YAAY,EACnB,CAAC,GAAE,MAA2B,GAC7B,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;GAGG;AACH,wBAAsB,MAAM,CAC1B,KAAK,EAAE,YAAY,EACnB,SAAS,GAAE,MAA2B,GACrC,OAAO,CAAC,eAAe,CAAC,CAQ1B;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,GAAE,YAAkC,GAAG,UAAU,EAAE,CAMtG;AAED,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,WAAW,EAAE,UAAU,EAAE,GAAG,MAAM,CAQ9D"}

package/dist/advisor/engine.js

@@ -0,0 +1,156 @@
+/**
+ * Advisor engine — the anti-annoyance brain.
+ *
+ * Pure decision core: given this run's candidate suggestions + the persisted
+ * advisor state + the clock, decide which clear the relevance bar AND the
+ * throttle AND dedup, and which get suppressed (journaled, not shown). The
+ * caller does the I/O (load/save state, surface the survivors).
+ *
+ * See docs/ORCHESTRATOR_PLAN.md §5b.3 for the anti-annoyance contract.
+ */
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { LISA_HOME } from "../paths.js";
+import { atomicWrite } from "../fs-utils.js";
+import { withFileLock } from "../soul/lock.js";
+import { runAllDetectors } from "./detectors.js";
+import { emptyAdvisorState, } from "./types.js";
+// Tunables.
+const URGENCY_WEIGHT = { info: 1, notice: 2, urgent: 4 };
+const MIN_SCORE = 1.5; // relevance bar: below this → journal, not user
+const DIGEST_THROTTLE_MS = 3 * 60 * 60_000; // ≤1 non-urgent digest / 3h
+const RE_ARM_MS = 24 * 60 * 60_000; // a standing condition can re-surface daily
+export const ADVISOR_STATE_PATH = path.join(LISA_HOME, "advisor-state.json");
+/** Relevance score = urgency × actionability × dismissal-decay. */
+export function scoreSuggestion(s, state) {
+    const urgency = URGENCY_WEIGHT[s.urgency];
+    const actionability = s.action ? 1 : 0.5;
+    const catDismissals = state.categoryDismissals[s.category] ?? 0;
+    // Each dismissal of this category halves its pull (learns to shut up).
+    const decay = 1 / (1 + catDismissals * 1.0);
+    return urgency * actionability * decay;
+}
+/** Has this exact condition been surfaced recently (→ suppress as dup)? */
+function isDuplicate(s, state, now) {
+    const prev = state.surfaced[s.id];
+    if (!prev)
+        return false;
+    if (prev.conditionHash !== s.conditionHash)
+        return false; // condition changed → fresh
+    return now - prev.ts < RE_ARM_MS;
+}
+/**
+ * Pure decision. Returns the surface/suppress split AND the next state to
+ * persist. Does not touch disk.
+ */
+export function decide(candidates, state, now) {
+    const surface = [];
+    const suppressed = [];
+    // Score everything first.
+    for (const c of candidates)
+        c.score = scoreSuggestion(c, state);
+    const withinThrottle = now - state.lastDigestAt < DIGEST_THROTTLE_MS;
+    let surfacedAnyNonUrgent = false;
+    for (const c of candidates) {
+        // Dedup: same condition seen recently → suppress.
+        if (isDuplicate(c, state, now)) {
+            suppressed.push(c);
+            continue;
+        }
+        if (c.urgency === "urgent") {
+            // Urgent bypasses the bar + throttle — but still deduped above.
+            surface.push(c);
+            continue;
+        }
+        // Non-urgent must clear the relevance bar…
+        if (c.score < MIN_SCORE) {
+            suppressed.push(c);
+            continue;
+        }
+        // …and the digest throttle.
+        if (withinThrottle) {
+            suppressed.push(c);
+            continue;
+        }
+        surface.push(c);
+        surfacedAnyNonUrgent = true;
+    }
+    // Build next state: record what we surfaced + advance the digest clock.
+    const nextState = {
+        ...state,
+        surfaced: { ...state.surfaced },
+    };
+    for (const s of surface) {
+        nextState.surfaced[s.id] = { ts: now, conditionHash: s.conditionHash };
+    }
+    if (surfacedAnyNonUrgent)
+        nextState.lastDigestAt = now;
+    // Sort surfaced by score desc so the digest leads with what matters.
+    surface.sort((a, b) => b.score - a.score);
+    return { decision: { surface, suppressed }, nextState };
+}
+/** Record a user dismissal so the category fades over time. */
+export function applyDismissal(state, id, category) {
+    return {
+        ...state,
+        dismissals: { ...state.dismissals, [id]: (state.dismissals[id] ?? 0) + 1 },
+        categoryDismissals: {
+            ...state.categoryDismissals,
+            [category]: (state.categoryDismissals[category] ?? 0) + 1,
+        },
+    };
+}
+// ── I/O ─────────────────────────────────────────────────────────────────
+export async function loadAdvisorState(p = ADVISOR_STATE_PATH) {
+    try {
+        const raw = await fsp.readFile(p, "utf8");
+        const parsed = JSON.parse(raw);
+        return { ...emptyAdvisorState(), ...parsed };
+    }
+    catch {
+        return emptyAdvisorState();
+    }
+}
+export async function saveAdvisorState(state, p = ADVISOR_STATE_PATH) {
+    await atomicWrite(p, JSON.stringify(state, null, 2));
+}
+/**
+ * Full advise cycle: detect → decide → persist. Returns the suggestions to
+ * surface. Uses the soul lock so a heartbeat advise can't race a manual one.
+ */
+export async function advise(input, statePath = ADVISOR_STATE_PATH) {
+    return withFileLock(statePath + ".lock", async () => {
+        const state = await loadAdvisorState(statePath);
+        const candidates = runAllDetectors(input);
+        const { decision, nextState } = decide(candidates, state, input.now);
+        await saveAdvisorState(nextState, statePath);
+        return decision;
+    });
+}
+/**
+ * On-demand ("pull") advice: run the detectors against the current snapshot
+ * and return everything above the bar, sorted — WITHOUT the throttle/dedup
+ * (the user explicitly asked, so don't suppress) and WITHOUT mutating state.
+ * Used by the advise_now tool.
+ */
+export function adviseNow(input, state = emptyAdvisorState()) {
+    const cands = runAllDetectors(input);
+    for (const c of cands)
+        c.score = scoreSuggestion(c, state);
+    return cands
+        .filter((c) => c.urgency === "urgent" || c.score >= MIN_SCORE)
+        .sort((a, b) => b.score - a.score);
+}
+/** Render surfaced suggestions into one digest card (markdown-ish text). */
+export function formatDigest(suggestions) {
+    if (suggestions.length === 0)
+        return "";
+    if (suggestions.length === 1)
+        return suggestions[0].text;
+    const lines = suggestions.map((s) => {
+        const mark = s.urgency === "urgent" ? "⚠ " : "• ";
+        return mark + s.text;
+    });
+    return "A few things across your agents:\n" + lines.join("\n");
+}
+//# sourceMappingURL=engine.js.map

package/dist/advisor/engine.js.map

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

package/dist/advisor/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Advisor (L5 ADVISE) — types.
+ *
+ * The advisor turns cross-agent observation into periodic, proactive
+ * suggestions. Its one hard problem is not being annoying, so everything is
+ * organized around the relevance bar + throttle + dedup (see engine.ts).
+ *
+ * See docs/ORCHESTRATOR_PLAN.md §5b.
+ */
+import type { AgentSession } from "../integrations/types.js";
+export type SuggestionCategory = "stuck" | "conflict" | "repeated_failure" | "cost_spike" | "ready" | "idle";
+/** How loudly a suggestion wants to be surfaced. */
+export type Urgency = "info" | "notice" | "urgent";
+/** A concrete action LISA can offer to take. A suggestion without one is
+ *  considered non-actionable and won't clear the relevance bar. */
+export interface SuggestedAction {
+    label: string;
+    kind: "approve" | "cancel" | "open" | "serialize" | "look" | "dispatch";
+    /** Opaque arg the action handler needs (sessionId, cwd, …). */
+    arg?: string;
+}
+export interface Suggestion {
+    /** Stable dedup key — same underlying condition → same id. */
+    id: string;
+    category: SuggestionCategory;
+    urgency: Urgency;
+    /** One-line, user-facing. Structural — no conversation content. */
+    text: string;
+    action?: SuggestedAction;
+    /** Computed relevance score (urgency × novelty × actionability). */
+    score: number;
+    /** A hash of the underlying condition; re-surface only when it changes. */
+    conditionHash: string;
+    /** When this was generated (epoch ms). */
+    ts: number;
+}
+/** Persisted advisor memory (~/.lisa/advisor-state.json). */
+export interface AdvisorState {
+    /** id → last time we surfaced it + the condition hash then. */
+    surfaced: Record<string, {
+        ts: number;
+        conditionHash: string;
+    }>;
+    /** id → number of times the user dismissed it (down-weights category). */
+    dismissals: Record<string, number>;
+    /** category → dismissal count, for learning what to stop saying. */
+    categoryDismissals: Partial<Record<SuggestionCategory, number>>;
+    /** last time ANY non-urgent digest was surfaced (throttle). */
+    lastDigestAt: number;
+    /** rolling memory of (command → error count) for repeated-failure detection. */
+    errorCommandCounts: Record<string, number>;
+}
+export declare function emptyAdvisorState(): AdvisorState;
+/** Input snapshot for the detectors. */
+export interface AdvisorInput {
+    sessions: AgentSession[];
+    now: number;
+    /** Count of actionable desires with nothing running (drives "idle"). */
+    pendingDesireCount?: number;
+}
+/** What the engine decided to do with this run's candidates. */
+export interface AdvisorDecision {
+    /** Cleared the bar + throttle/dedup → surface to the user. */
+    surface: Suggestion[];
+    /** Generated but suppressed (logged to journal, not shown). */
+    suppressed: Suggestion[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/advisor/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/advisor/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAE7D,MAAM,MAAM,kBAAkB,GAC1B,OAAO,GACP,UAAU,GACV,kBAAkB,GAClB,YAAY,GACZ,OAAO,GACP,MAAM,CAAC;AAEX,oDAAoD;AACpD,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEnD;mEACmE;AACnE,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,GAAG,UAAU,CAAC;IACxE,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,UAAU;IACzB,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,aAAa,EAAE,MAAM,CAAC;IACtB,0CAA0C;IAC1C,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,6DAA6D;AAC7D,MAAM,WAAW,YAAY;IAC3B,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChE,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,oEAAoE;IACpE,kBAAkB,EAAE,OAAO,CAAC,MAAM,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC,CAAC;IAChE,+DAA+D;IAC/D,YAAY,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5C;AAED,wBAAgB,iBAAiB,IAAI,YAAY,CAQhD;AAED,wCAAwC;AACxC,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,gEAAgE;AAChE,MAAM,WAAW,eAAe;IAC9B,8DAA8D;IAC9D,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,+DAA+D;IAC/D,UAAU,EAAE,UAAU,EAAE,CAAC;CAC1B"}

package/dist/advisor/types.js

@@ -0,0 +1,19 @@
+/**
+ * Advisor (L5 ADVISE) — types.
+ *
+ * The advisor turns cross-agent observation into periodic, proactive
+ * suggestions. Its one hard problem is not being annoying, so everything is
+ * organized around the relevance bar + throttle + dedup (see engine.ts).
+ *
+ * See docs/ORCHESTRATOR_PLAN.md §5b.
+ */
+export function emptyAdvisorState() {
+    return {
+        surfaced: {},
+        dismissals: {},
+        categoryDismissals: {},
+        lastDigestAt: 0,
+        errorCommandCounts: {},
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/advisor/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/advisor/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAsDH,MAAM,UAAU,iBAAiB;IAC/B,OAAO;QACL,QAAQ,EAAE,EAAE;QACZ,UAAU,EAAE,EAAE;QACd,kBAAkB,EAAE,EAAE;QACtB,YAAY,EAAE,CAAC;QACf,kBAAkB,EAAE,EAAE;KACvB,CAAC;AACJ,CAAC"}

package/dist/integrations/claude-code/observer.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Claude Code AgentObserver — adapts the existing ClaudeCodeWatcher to the
+ * normalized cross-agent interface and registers it in the integration
+ * registry.
+ *
+ * The watcher itself is unchanged (it's well-tested); this is a thin
+ * normalization layer: ClaudeSessionInfo → AgentSession. Activity (Tier 2)
+ * is attached when the watcher provides it.
+ */
+import type { AgentIntegrationConfig, AgentObserver, AgentSession } from "../types.js";
+export declare class ClaudeCodeObserver implements AgentObserver {
+    readonly agent = "claude-code";
+    private watcher;
+    constructor(cfg: AgentIntegrationConfig);
+    start(emit: (s: AgentSession) => void): Promise<void>;
+    list(): AgentSession[];
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=observer.d.ts.map

package/dist/integrations/claude-code/observer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer.d.ts","sourceRoot":"","sources":["../../../src/integrations/claude-code/observer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EACV,sBAAsB,EACtB,aAAa,EACb,YAAY,EACb,MAAM,aAAa,CAAC;AAerB,qBAAa,kBAAmB,YAAW,aAAa;IACtD,QAAQ,CAAC,KAAK,iBAAiB;IAC/B,OAAO,CAAC,OAAO,CAAoB;gBAEvB,GAAG,EAAE,sBAAsB;IAWjC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAc3D,IAAI,IAAI,YAAY,EAAE;IAIhB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAG5B"}

package/dist/integrations/claude-code/observer.js

@@ -0,0 +1,59 @@
+/**
+ * Claude Code AgentObserver — adapts the existing ClaudeCodeWatcher to the
+ * normalized cross-agent interface and registers it in the integration
+ * registry.
+ *
+ * The watcher itself is unchanged (it's well-tested); this is a thin
+ * normalization layer: ClaudeSessionInfo → AgentSession. Activity (Tier 2)
+ * is attached when the watcher provides it.
+ */
+import { ClaudeCodeWatcher } from "./watcher.js";
+import { registerIntegration } from "../registry.js";
+function toAgentSession(info) {
+    return {
+        agent: "claude-code",
+        sessionId: info.sessionId,
+        project: info.projectLabel,
+        cwd: info.cwd,
+        state: info.state,
+        stateReason: info.stateReason,
+        lastMtime: info.lastMtime,
+        activity: info.activity,
+    };
+}
+export class ClaudeCodeObserver {
+    agent = "claude-code";
+    watcher;
+    constructor(cfg) {
+        // Tier 2: compute structural activity when visibility is "activity" or
+        // "intent". At "metadata"/"off" we stay metadata-only (cheaper, and the
+        // privacy-minimal default).
+        const computeActivity = cfg.visibility === "activity" || cfg.visibility === "intent";
+        this.watcher = new ClaudeCodeWatcher({
+            log: (m) => console.error(m),
+            computeActivity,
+        });
+    }
+    async start(emit) {
+        // The watcher's "update" payload is a lightweight ClaudeSessionUpdate
+        // (no lastMtime/activity), so we re-derive the full session from the
+        // current snapshot by sessionId. listActive() includes the just-updated
+        // session (its mtime is current), so the lookup succeeds.
+        this.watcher.on("update", (payload) => {
+            const info = this.watcher
+                .listActive()
+                .find((s) => s.sessionId === payload.sessionId);
+            if (info)
+                emit(toAgentSession(info));
+        });
+        await this.watcher.start();
+    }
+    list() {
+        return this.watcher.listActive().map(toAgentSession);
+    }
+    async stop() {
+        this.watcher.stop();
+    }
+}
+registerIntegration("claude-code", (cfg) => new ClaudeCodeObserver(cfg));
+//# sourceMappingURL=observer.js.map

package/dist/integrations/claude-code/observer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer.js","sourceRoot":"","sources":["../../../src/integrations/claude-code/observer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,iBAAiB,EAA0B,MAAM,cAAc,CAAC;AACzE,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAOrD,SAAS,cAAc,CAAC,IAAuB;IAC7C,OAAO;QACL,KAAK,EAAE,aAAa;QACpB,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,OAAO,EAAE,IAAI,CAAC,YAAY;QAC1B,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,QAAQ,EAAE,IAAI,CAAC,QAAQ;KACxB,CAAC;AACJ,CAAC;AAED,MAAM,OAAO,kBAAkB;IACpB,KAAK,GAAG,aAAa,CAAC;IACvB,OAAO,CAAoB;IAEnC,YAAY,GAA2B;QACrC,uEAAuE;QACvE,wEAAwE;QACxE,4BAA4B;QAC5B,MAAM,eAAe,GAAG,GAAG,CAAC,UAAU,KAAK,UAAU,IAAI,GAAG,CAAC,UAAU,KAAK,QAAQ,CAAC;QACrF,IAAI,CAAC,OAAO,GAAG,IAAI,iBAAiB,CAAC;YACnC,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;YAC5B,eAAe;SAChB,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,IAA+B;QACzC,sEAAsE;QACtE,qEAAqE;QACrE,wEAAwE;QACxE,0DAA0D;QAC1D,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,OAA8B,EAAE,EAAE;YAC3D,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO;iBACtB,UAAU,EAAE;iBACZ,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;YAClD,IAAI,IAAI;gBAAE,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC;QACvC,CAAC,CAAC,CAAC;QACH,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IAC7B,CAAC;IAED,IAAI;QACF,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACvD,CAAC;IAED,KAAK,CAAC,IAAI;QACR,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;IACtB,CAAC;CACF;AAED,mBAAmB,CAAC,aAAa,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC"}

package/dist/integrations/claude-code/parser.d.ts

@@ -39,6 +39,7 @@
  *   take the LAST complete line). File deletion mid-parse returns
  *   "unknown".
  */
+import type { SessionActivity } from "../types.js";
 export type ClaudeSessionState = "working" | "waiting" | "error" | "unknown";
 export interface SessionStateInfo {
     state: ClaudeSessionState;
@@ -53,4 +54,5 @@ export interface SessionStateInfo {
     cwd?: string;
 }
 export declare function parseSessionState(filePath: string): Promise<SessionStateInfo>;
+export declare function parseSessionActivity(filePath: string): Promise<SessionActivity | undefined>;
 //# sourceMappingURL=parser.d.ts.map

package/dist/integrations/claude-code/parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../../src/integrations/claude-code/parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAIH,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;AAE7E,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,kBAAkB,CAAC;IAC1B,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAgBD,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAoDnF"}
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../../src/integrations/claude-code/parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;AAE7E,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,kBAAkB,CAAC;IAC1B,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAgBD,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAoDnF;AAwID,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CA+GtC"}