@gigaflow/gmux 0.15.0

package/dist/services/ask.js

@@ -0,0 +1,161 @@
+/**
+ * Ask: questions about the sessions you already have, answered from the
+ * summaries you already paid for.
+ *
+ * The design decision worth knowing before you change anything here:
+ *
+ * **The tool loop is the harness's, not ours.** The prompt tells the model it
+ * may run `gmux grep '<query>' --json`, and the provider is invoked with exactly
+ * that permission (see providers.ts `askArgv`). We parse no tool calls and speak
+ * no vendor protocol — the abstraction stays "a CLI that reads a prompt and
+ * writes text", which is the only reason gmux depends on no vendor SDK.
+ *
+ * The cost is that we don't meter how many greps the model runs. Accepted: grep
+ * is read-only and cheap, and the provider's own turn limit bounds it.
+ *
+ * The context block is bounded the way `distill()` is bounded — a few KB
+ * regardless of how many sessions you have — because a REPL re-sends it every
+ * turn.
+ */
+import { AskProviderError } from "../core/errors.js";
+import { relativeAge, truncate } from "../core/text.js";
+import { readConfig, resolveAskCommand } from "./config.js";
+import { runProviderCommand } from "./provider-process.js";
+import { onPath } from "./providers.js";
+/**
+ * Ask gets longer than a summary does: the model may run several greps before
+ * it answers, and each is a subprocess of its own.
+ */
+export const ASK_TIMEOUT_MS = 300_000;
+/** How many sessions go into the block. Matches the picker's default window. */
+export const ASK_SESSION_LIMIT = 20;
+/** Per-session caps. A refactor touching 200 files must not eat the prompt. */
+const MAX_FILES_PER_SESSION = 8;
+const MAX_FIELD_CHARS = 240;
+export function buildAskContext(views, focusId = null, limit = ASK_SESSION_LIMIT) {
+    const sessions = [...views]
+        .sort((a, b) => b.record.updatedAt.localeCompare(a.record.updatedAt))
+        .slice(0, limit);
+    // Only claim focus on a session that actually made the window — otherwise the
+    // prompt would point at a session whose details aren't in it.
+    const focused = focusId
+        ? (sessions.find((v) => v.record.sessionId.startsWith(focusId))?.record.sessionId ?? null)
+        : null;
+    return { sessions, focusId: focused };
+}
+/** Short id: what a human types and what the model should quote back. */
+export function shortId(sessionId) {
+    return sessionId.slice(0, 8);
+}
+function renderSession(view, index, focusId, now) {
+    const { record, summary } = view;
+    const lines = [];
+    const flags = [
+        record.endedMidTask ? "ENDED MID-TASK" : "",
+        record.sessionId === focusId ? "← the session the user is looking at" : "",
+    ].filter((f) => f !== "");
+    const where = record.gitBranch ? `${record.project ?? "?"}/${record.gitBranch}` : (record.project ?? "?");
+    lines.push(`### ${index + 1}. ${where} · ${relativeAge(record.updatedAt, now)} ago · id ${shortId(record.sessionId)}${flags.length > 0 ? `  [${flags.join(" · ")}]` : ""}`);
+    lines.push(`harness: ${record.harness}`);
+    if (summary) {
+        lines.push(`headline: ${truncate(summary.headline, MAX_FIELD_CHARS)}`);
+        if (summary.overview)
+            lines.push(`what it's about: ${truncate(summary.overview, MAX_FIELD_CHARS)}`);
+        if (summary.landed)
+            lines.push(`landed: ${truncate(summary.landed, MAX_FIELD_CHARS)}`);
+        if (summary.open)
+            lines.push(`open: ${truncate(summary.open, MAX_FIELD_CHARS)}`);
+        if (summary.nextStep)
+            lines.push(`next step: ${truncate(summary.nextStep, MAX_FIELD_CHARS)}`);
+    }
+    else {
+        // No summary yet. Say so rather than omitting the session: a gap the model
+        // knows about is a caveat it can give you, and one it doesn't is a lie.
+        lines.push("summary: NOT YET WRITTEN — the facts below are all we know");
+        if (record.title)
+            lines.push(`title (recorded at session START, often stale): ${record.title}`);
+        if (record.lastUserPrompt) {
+            lines.push(`the developer's last instruction: ${truncate(record.lastUserPrompt, MAX_FIELD_CHARS)}`);
+        }
+    }
+    if (record.filesTouched.length > 0) {
+        const shown = record.filesTouched.slice(0, MAX_FILES_PER_SESSION);
+        const more = record.filesTouched.length - shown.length;
+        lines.push(`files: ${shown.join(", ")}${more > 0 ? ` (+${more} more)` : ""}`);
+    }
+    if (record.lastToolFailure) {
+        lines.push(`last failing command: ${truncate(record.lastToolFailure, MAX_FIELD_CHARS)}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * The prompt for one turn.
+ *
+ * `turns` is the conversation so far. We re-send it because `claude -p` is
+ * one-shot and `--resume` is Claude-specific — carrying state in memory and
+ * replaying it is what keeps this working for any provider. Bounded, because
+ * the context block is.
+ */
+export function buildAskPrompt(context, turns, question, now = new Date()) {
+    const lines = [
+        "You are helping a developer decide what to work on next, using summaries of their recent AI coding-agent sessions.",
+        "",
+        "Each session below was summarized from the ARC of its transcript — what the developer originally asked for, how the work moved, and where it ended — so the fields describe both what the work IS and where it LANDED. A session's `title` is different: it was recorded in the session's first seconds and never revised, so it names the opening prompt and is usually stale. Trust the summary over the title.",
+        "",
+        `## The developer's ${context.sessions.length} most recent session${context.sessions.length === 1 ? "" : "s"}`,
+        "",
+    ];
+    if (context.sessions.length === 0) {
+        lines.push("(none — the developer has no indexed sessions)");
+    }
+    else {
+        lines.push(context.sessions.map((v, i) => renderSession(v, i, context.focusId, now)).join("\n\n"));
+    }
+    lines.push("", "## Digging deeper", "", "The summaries above are all you have by default. If answering well needs detail they don't carry — what was actually said, the text of an error, whether something was tried — you can search the full transcripts:", "", "    gmux grep '<query>' --json", "", "Useful flags: `-p <project>` narrows to one repo, `-n <count>` caps results, `-e` treats the query as a regex.", "Run it when it would change your answer. Don't run it to confirm something the summaries already say, and don't guess at detail you could have looked up.");
+    if (turns.length > 0) {
+        lines.push("", "## The conversation so far", "");
+        for (const turn of turns) {
+            lines.push(`Developer: ${turn.question}`, `You: ${turn.answer}`, "");
+        }
+    }
+    lines.push("", "## The question", "", question, "", "## How to answer", "", "Answer in plain prose for a terminal — no markdown headers, no tables.", "Be specific: name the session (by its short id), the files, the errors. Point at where to look.", "Ground every claim in the evidence above or in what you grep. If the summaries don't support an answer, say what's missing rather than filling the gap.", "Be brief. This is read in a terminal between other work.");
+    return lines.join("\n");
+}
+export class CliAskProvider {
+    name;
+    argv;
+    constructor(argv) {
+        this.argv = argv;
+        this.name = argv.join(" ");
+    }
+    async isAvailable() {
+        const binary = this.argv[0];
+        if (!binary)
+            return false;
+        return onPath(binary);
+    }
+    async ask(prompt) {
+        try {
+            const output = await runProviderCommand(this.argv, prompt, { timeoutMs: ASK_TIMEOUT_MS });
+            const answer = output.trim();
+            if (answer === "")
+                throw new Error("reply was empty");
+            return answer;
+        }
+        catch (error) {
+            throw new AskProviderError(this.name, error.message);
+        }
+    }
+}
+/**
+ * The ask provider for the current config, or null when the user has said no to
+ * model calls.
+ *
+ * Null is an answer, not a failure — `provider: null` in config means exactly
+ * this, and the caller renders it as "run `gmux setup`" rather than as an error.
+ */
+export async function defaultAskProvider() {
+    const command = resolveAskCommand(await readConfig());
+    return command ? new CliAskProvider(command) : null;
+}
+//# sourceMappingURL=ask.js.map

package/dist/services/ask.js.map

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

package/dist/services/auto-summarize.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Auto-summarize: keep the top of `gmux ls` written, without ever making you wait.
+ *
+ * A summary costs a model call (~8s). Ten of them, inline, would turn a 60ms
+ * `gmux ls` into a minute of staring at a cursor — so the foreground command never
+ * runs one. Instead it decides *what* would need summarizing, hands that job to
+ * a DETACHED child process, prints a one-line notice to stderr and exits. The
+ * summaries land in the cache and appear on the next run.
+ *
+ * Three things this module exists to prevent:
+ *
+ * 1. **Blocking.** The child is spawned `detached` with `stdio: "ignore"` and
+ *    unref'd, so it outlives its parent and the parent's event loop drains
+ *    immediately. Nothing is awaited.
+ *
+ * 2. **A stampede.** Five `gmux ls` in a row must not start five summarizers doing
+ *    identical work. A lock file in the cache dir is created with O_EXCL before
+ *    spawning; a lock whose owner is dead — or older than LOCK_STALE_MS — is
+ *    taken over. A short cooldown stops us re-deciding on every invocation.
+ *
+ * 3. **A feedback loop.** The provider is `claude -p`, which itself writes a new
+ *    Claude Code session to disk. If those were eligible targets, gmux
+ *    would summarize its own summarizer forever. `automated` and `sidechain`
+ *    sessions are therefore excluded from the target set — see
+ *    `autoSummarizeCandidates`, which is where that guarantee lives.
+ */
+import type { SessionRecord, SummaryProvider } from "../core/types.js";
+import { type SummarizeBatchResult } from "./summarize.js";
+/**
+ * How many recent sessions the background pass keeps summarized.
+ *
+ * This MUST be at least as large as `gmux ls`'s default limit, or the bottom of
+ * the default view is permanently `○` and the feature looks broken — which is
+ * exactly what happened when this was 10 and `gmux ls` showed 20.
+ *
+ * Override with `GMUX_AUTO_SUMMARIZE=<n>`.
+ */
+export declare const AUTO_SUMMARIZE_LIMIT = 20;
+/**
+ * Hard ceiling on one background pass.
+ *
+ * `gmux ls -n 500` should not fire 500 model calls. Anything beyond this is left
+ * for the next run, and we say so rather than truncating silently.
+ */
+export declare const MAX_PER_PASS = 50;
+/** A lock older than this belongs to a process that died without cleaning up. */
+export declare const LOCK_STALE_MS: number;
+/** Don't re-decide on every invocation; `gmux ls` in a loop should cost nothing. */
+export declare const COOLDOWN_MS = 60000;
+/** The hidden CLI command the detached worker runs. It never auto-summarizes itself. */
+export declare const AUTO_SUMMARIZE_COMMAND = "__auto-summarize";
+export declare function lockPath(): string;
+export declare function statePath(): string;
+/** The sessions the running worker is writing right now. Drives the `◐` marker. */
+export declare function queuePath(): string;
+/** Where a failing background pass leaves its evidence. */
+export declare function logPath(): string;
+/**
+ * Off via `GMUX_AUTO_SUMMARIZE=0`.
+ *
+ * Background model calls spend tokens. A user who has not opted into that must
+ * be able to say no once, in their shell profile, and be done with it.
+ */
+export declare function autoSummarizeEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Every reason the background pass might be off, in one place.
+ *
+ * Three independent "no"s, and any of them is final:
+ *
+ * - the env var — a shell-profile opt-out
+ * - the config — what the user answered in `gmux setup`
+ * - GMUX_CHILD — we are a `gmux` spawned by our own provider
+ *
+ * The last is the one that isn't obvious. `gmux ask`'s provider may run `gmux grep`,
+ * whose postAction hook would start a summarize pass — a model call spawned by a
+ * model call. The lock would absorb most of the damage; this makes it a
+ * non-question.
+ */
+export declare function autoSummarizeAllowedNow(env?: NodeJS.ProcessEnv): Promise<boolean>;
+export interface AutoSummarizeLock {
+    /** Pid of the worker. 0 when the lock is taken but the child is not spawned yet. */
+    pid: number;
+    startedAt: string;
+}
+/** A lock is stale when its owner is gone, or when it is simply too old. */
+export declare function isLockStale(lock: AutoSummarizeLock, now?: Date, staleMs?: number): boolean;
+export declare function readLock(): Promise<AutoSummarizeLock | null>;
+/**
+ * Take the lock, or report that someone else holds it.
+ *
+ * The create is O_EXCL, so two `gmux` processes racing cannot both win. A stale
+ * lock is removed and re-created rather than overwritten, so the takeover is
+ * itself a race whose loser backs off instead of double-spawning.
+ */
+export declare function acquireLock(now?: Date): Promise<boolean>;
+export declare function releaseLock(): Promise<void>;
+/** Record that we just decided; suppresses the next COOLDOWN_MS worth of checks. */
+export declare function noteCheck(now?: Date): Promise<void>;
+export declare function inCooldown(now?: Date, cooldownMs?: number): Promise<boolean>;
+export interface AutoSummarizeQueue {
+    ids: string[];
+    startedAt: string;
+}
+/** Publish what the worker is about to write, so the list can mark those rows `◐`. */
+export declare function writeQueue(ids: readonly string[], now?: Date): Promise<void>;
+export declare function readQueue(): Promise<AutoSummarizeQueue | null>;
+export declare function clearQueue(): Promise<void>;
+/**
+ * Sessions being summarized *right now*, for the `◐` marker.
+ *
+ * Guarded by the lock: a queue left behind by a crashed worker would otherwise
+ * mark rows as in-progress forever. No live lock, no in-progress rows.
+ */
+export declare function inProgressIds(now?: Date): Promise<Set<string>>;
+/**
+ * The sessions the background pass is allowed to touch.
+ *
+ * THE FEEDBACK-LOOP GUARD. `claude -p` — our own summary provider — writes a
+ * Claude Code session for every summary it produces, flagged `isAutomated`.
+ * Summarizing those would generate more of them, forever, at real token cost.
+ * Sidechains are excluded for the same reason plus a better one: nobody resumes
+ * a subagent transcript.
+ *
+ * Pure. This is the function the anti-loop test pins.
+ */
+export declare function autoSummarizeCandidates(records: readonly SessionRecord[], limit?: number): SessionRecord[];
+/**
+ * Of the recent, eligible sessions, the ones whose summary is missing or stale.
+ *
+ * Reads the summary cache but calls no model, so tests exercise it for real.
+ */
+export declare function selectAutoSummarizeTargets(records: readonly SessionRecord[], limit?: number): Promise<SessionRecord[]>;
+export type AutoSummarizeStatus = "spawned" | "disabled" | "no-provider" | "locked" | "cooling-down" | "nothing-to-do" | "spawn-failed";
+export interface AutoSummarizeOutcome {
+    status: AutoSummarizeStatus;
+    /** How many sessions the worker was asked to write. */
+    targets: number;
+    /** Their ids — the caller renders these as `◐` on this very run. */
+    targetIds: string[];
+}
+export interface MaybeAutoSummarizeOptions {
+    /**
+     * The sessions the command just displayed.
+     *
+     * Passing these is what makes `gmux ls -n 50` summarize all fifty: the window
+     * follows what you actually looked at, rather than a fixed top-N that leaves
+     * the bottom of your screen permanently un-summarized.
+     */
+    records?: readonly SessionRecord[];
+    /** False when `--no-auto-summarize` was passed. */
+    enabled?: boolean;
+    /**
+     * Skip the cooldown — and only the cooldown.
+     *
+     * Set when the user explicitly asked for a refresh (ctrl-r in the picker).
+     * The cooldown guards against *incidental* re-decisions, like `gmux ls` in a
+     * loop; a keypress is not incidental, and a key that silently does nothing
+     * for its first minute reads as broken.
+     *
+     * The lock still applies, so hammering the key cannot start two workers, and
+     * `GMUX_AUTO_SUMMARIZE=0` still wins: force overrides our own
+     * optimisation, never the user's opt-out.
+     */
+    force?: boolean;
+    now?: Date;
+    /** Injected in tests. Never a real model. */
+    provider?: SummaryProvider;
+    /** Injected in tests, so no test ever spawns anything. Returns the child pid. */
+    spawnWorker?: () => number | undefined;
+    /** Where the notice goes. STDERR — stdout must stay clean for `--json` and pipes. */
+    notify?: (message: string) => void;
+}
+/**
+ * Decide whether to kick off a background summarize pass, and if so, do it.
+ *
+ * Never throws and never blocks on a model: every failure path is a silent skip.
+ * A read command must not die because `claude` is missing or a cache file is odd.
+ */
+export declare function maybeAutoSummarize(options?: MaybeAutoSummarizeOptions): Promise<AutoSummarizeOutcome>;
+/**
+ * The worker body. Runs in the detached child, holding the lock its parent took.
+ *
+ * Re-selects its own targets rather than trusting a list handed down an argv: by
+ * the time it starts, the parent's view of the store is already stale.
+ */
+export declare function runAutoSummarize(provider: SummaryProvider): Promise<SummarizeBatchResult>;
+/** The most recent background failure, if any — surfaced by `gmux doctor`. */
+export declare function lastAutoSummarizeError(): Promise<string | null>;