@onepointfour-packs/flaredeck-agent 0.2.38 → 0.2.39

package/dist/usage.js

@@ -0,0 +1,348 @@
+/**
+ * Asking a Claude subscription how much of itself is left.
+ *
+ * Everything else here learns about limits by being told: `rate_limit_event` arrives mid-run,
+ * and the text paths only appear once a cap has already been hit. That is enough to ROTATE off
+ * a dead subscription, which is what the user did by hand — but not enough to route by headroom,
+ * because by the time you know, the run has already failed.
+ *
+ * `/usage` is the missing half. It is a real slash command in the CLI, it runs through the SDK
+ * the same way `/goal` already does in engine-claude.ts, and it answers on demand. So FlareDeck
+ * can ask each subscription where it stands before choosing one, instead of discovering it
+ * afterwards.
+ *
+ * WHAT IT COSTS: a turn, with no model work beyond rendering a local command — but not nothing.
+ * It is for a scheduled refresh, not for every run.
+ *
+ * STRUCTURED FIRST, PROSE ONLY AS A FALLBACK. `/usage` attaches a `usage_report` to the
+ * synthetic assistant message that carries its text, and that is what is read: server-sent rows
+ * with a `kind` ('session', 'weekly_all', 'weekly_scoped'), a percent, and an ISO `resets_at`
+ * complete with offset. The SDK's own instruction is to "classify a row on this, never on a
+ * label" — which is exactly what an earlier version of this file did, matching "Current
+ * session" and "Current week" and inferring local time and a year the text never stated.
+ *
+ * The prose parser is kept because the SDK documents the text as the canonical fallback for
+ * CLIs too old to attach the report. It is written to fail SILENTLY AND COMPLETELY rather than
+ * partially: a line it does not recognise yields nothing for that window, and nothing means
+ * "unknown", never 0. A wrong number here would route every run at the plan it misread.
+ *
+ * Not on the init message, whatever the declarations imply: measured on this CLI, init carries
+ * no rate_limits, no subscription_type and no account id. Identity comes from `accountInfo()`,
+ * which answers without spending a turn at all.
+ */
+/**
+ * Pull the windows out of what `/usage` printed.
+ *
+ * The shape it answers with, as measured:
+ *
+ *   Current session: 15% used · resets Oct 10 at 12:10pm (Africa/Johannesburg)
+ *   Current week (all models): 30% used · resets Oct 16 at 4pm (Africa/Johannesburg)
+ *   Current week (Fable): 7% used · resets Oct 16 at 4pm (Africa/Johannesburg)
+ *
+ * "Current session" is the five-hour window and "Current week" the seven-day one — the labels
+ * are the product's words for them, not new concepts. A per-model week ("Fable") is kept
+ * separately rather than folded in, because it can be the one that blocks while the overall
+ * week still has room, which is precisely the case worth routing around.
+ */
+export function parseUsage(text, now = Date.now()) {
+    const out = [];
+    for (const raw of String(text ?? '').split('\n')) {
+        const line = raw.trim();
+        const m = /^Current (session|week)(?:\s*\(([^)]+)\))?:\s*(\d{1,3})%\s*used(?:\s*[·•-]\s*resets\s+(.+?))?$/i.exec(line);
+        if (!m)
+            continue;
+        const [, period = '', scope, pct, when] = m;
+        const utilization = Number(pct);
+        // A percentage outside 0-100 is a line we have misread, not a reading. Drop it rather than
+        // store something that would be acted on.
+        if (!Number.isFinite(utilization) || utilization < 0 || utilization > 100)
+            continue;
+        const model = scope && !/^all models$/i.test(scope) ? scope.trim() : undefined;
+        const resetsAt = when ? resetTime(when, now) : undefined;
+        out.push({
+            window: period.toLowerCase() === 'session' ? 'five_hour' : 'seven_day',
+            utilization,
+            ...(typeof resetsAt === 'number' ? { resetsAt } : {}),
+            ...(model ? { model } : {}),
+        });
+    }
+    return out;
+}
+/**
+ * "Oct 10 at 12:10pm (Africa/Johannesburg)" → epoch ms, or undefined.
+ *
+ * Deliberately undefined rather than a guess when it cannot be read with confidence. A derived
+ * reset is worse than none: twenty agents each contributing their own idea of when a window
+ * closes pushes it out for most of a day, which is the bug that already bit this ledger once.
+ * The YEAR is absent from the text, so it is inferred as the nearest future date — a reset is
+ * always ahead, and in late December that is next year.
+ */
+function resetTime(text, now) {
+    const m = /^([A-Z][a-z]{2})\s+(\d{1,2})\s+at\s+(\d{1,2})(?::(\d{2}))?\s*(am|pm)/i.exec(text.trim());
+    if (!m)
+        return undefined;
+    const [, mon, day, hour12, min, ampm] = m;
+    const month = ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec']
+        .indexOf(String(mon).toLowerCase());
+    if (month < 0)
+        return undefined;
+    let hour = Number(hour12) % 12;
+    if (/pm/i.test(String(ampm)))
+        hour += 12;
+    /* Local time, because the string is in the machine's own zone — `/usage` prints the zone it
+       used and it is this machine's. Reading it as UTC would shift every reset by the offset,
+       which in Johannesburg is two hours of a five-hour window. */
+    const here = new Date(now);
+    for (const year of [here.getFullYear(), here.getFullYear() + 1]) {
+        const t = new Date(year, month, Number(day), hour, Number(min ?? 0), 0, 0).getTime();
+        if (t > now)
+            return t;
+    }
+    return undefined;
+}
+/**
+ * Run `/usage` against a subscription and read what it says.
+ *
+ * `token` picks which subscription answers — the same CLAUDE_CODE_OAUTH_TOKEN the run itself
+ * would use, so the reading is about the plan that would actually have paid. Without one it
+ * reports on whatever this machine is logged in as.
+ */
+export async function readUsage(opts) {
+    const ask = opts.ask ?? defaultAsk;
+    const started = Date.now();
+    try {
+        const { report, text, seen, getter } = await withTimeout(ask(opts.token), opts.timeoutMs ?? 90_000);
+        // The SDK's usage call is the real source — the plan's own percentages and reset times.
+        if (getter?.length)
+            return getter;
+        /* Structured when the CLI attached it, prose only when it did not. Never merged: two
+           readings of the same window from two sources would disagree on rounding and on which is
+           newer, and the wrong one winning is invisible. */
+        const structured = windowsFromReport(report);
+        if (structured.length)
+            return structured;
+        const parsed = parseUsage(text ?? '');
+        /* Empty with no error was a black box: "could not read it" and nothing else, so a changed
+           SDK response, a timing problem and a refused token all looked the same. Say what came. */
+        if (!parsed.length) {
+            opts.onEmpty?.(`${Date.now() - started}ms · messages: ${(seen ?? []).join(' ') || 'none'} · ` +
+                `usage_report: ${report === undefined ? 'absent' : JSON.stringify(report).slice(0, 200)} · ` +
+                `text: ${JSON.stringify((text ?? '').slice(0, 300))}`);
+        }
+        return parsed;
+    }
+    catch (e) {
+        // Never throws: a failed reading costs a little routing accuracy and the next one tries
+        // again. It must not be able to stop a run, which is the whole point of asking early.
+        opts.onEmpty?.(`${Date.now() - started}ms · ${e instanceof Error ? e.message : String(e)}`);
+        return [];
+    }
+}
+/**
+ * Ask the SDK's usage call for this plan's windows, on a session that sends no prompt at all.
+ *
+ * `/usage` sent as a prompt, headless, answers with THIS SESSION's cost ("Total cost: $0.0000 …
+ * Usage: 0 input, 0 output") — never the plan's limits. Every read came back empty for that
+ * reason, which looked like a timing or token problem. The query handle has a dedicated call that
+ * returns the plan's 5-hour and weekly utilisation (0-100) with ISO reset times; it is marked
+ * experimental, so a missing or changed method falls back to `/usage` rather than failing.
+ *
+ * Only the two governing windows are taken. Model-scoped weeks (opus, sonnet) would be ranked as
+ * if they stopped the whole plan, which they do not.
+ */
+/** What the usage call last answered when it gave no windows — for the log, not for routing. */
+let lastGetterNote = '';
+async function askGetter(token) {
+    lastGetterNote = '';
+    const { query } = await import('@anthropic-ai/claude-agent-sdk');
+    const { readUsage: readHandle } = await import('./limits.js');
+    const { ANTHROPIC_API_KEY: _k, ANTHROPIC_AUTH_TOKEN: _t, ...rest } = process.env;
+    let release = () => { };
+    const held = new Promise((r) => { release = r; });
+    // A prompt stream that sends nothing and ends when we are done, so the CLI starts and waits.
+    const q = query({
+        prompt: (async function* () { await held; })(),
+        options: {
+            maxTurns: 1,
+            // No user settings: the read must not run this machine's hooks or load its MCP servers.
+            settingSources: [],
+            env: { ...rest, ...(token ? { CLAUDE_CODE_OAUTH_TOKEN: token } : {}) },
+        },
+    });
+    try {
+        const reading = await readHandle(q);
+        if (!reading) {
+            lastGetterNote = 'usage call: no answer (method missing, threw, or unrecognised)';
+            return [];
+        }
+        // False when the token cannot see plan limits — an API key, or an OAuth token without the
+        // profile scope, which is what `claude setup-token` mints.
+        if (!reading.rateLimitsAvailable) {
+            lastGetterNote = `usage call: rate_limits_available=false (subscription ${reading.subscriptionType ?? 'unknown'})`;
+            return [];
+        }
+        const out = [];
+        for (const name of ['five_hour', 'seven_day']) {
+            const w = reading.windows[name];
+            if (!w || typeof w.utilization !== 'number')
+                continue;
+            out.push({ window: name, utilization: w.utilization, ...(w.resetsAt ? { resetsAt: w.resetsAt } : {}) });
+        }
+        if (!out.length)
+            lastGetterNote = `usage call: available but no 5h/weekly figures (${JSON.stringify(reading.windows).slice(0, 200)})`;
+        return out;
+    }
+    finally {
+        release();
+        // Drain so the CLI exits rather than lingering; anything it says now is irrelevant.
+        void (async () => { try {
+            for await (const _ of q) { /* drain */ }
+        }
+        catch { /* closed */ } })();
+    }
+}
+/**
+ * The setup-token route: one tiny Haiku reply, read for the rate-limit state it carries.
+ *
+ * Costs a few hundred tokens of the plan's own quota (~$0.004 equivalent on a real account) — a
+ * real request is the only thing that returns the headers. No tools, no settings, one turn.
+ */
+async function askProbe(token) {
+    const { query } = await import('@anthropic-ai/claude-agent-sdk');
+    const { windowsFromRateLimit } = await import('./limits.js');
+    const { ANTHROPIC_API_KEY: _k, ANTHROPIC_AUTH_TOKEN: _t, ...rest } = process.env;
+    const q = query({
+        prompt: 'Reply with the single word OK.',
+        options: {
+            maxTurns: 1, model: 'haiku', settingSources: [], allowedTools: [],
+            env: { ...rest, ...(token ? { CLAUDE_CODE_OAUTH_TOKEN: token } : {}) },
+        },
+    });
+    const found = new Map();
+    for await (const m of q) {
+        for (const w of windowsFromRateLimit(m))
+            found.set(w.window, w);
+        if (m['type'] === 'result')
+            break;
+    }
+    return [...found.values()];
+}
+async function defaultAsk(token) {
+    const getter = await askGetter(token).catch((e) => { lastGetterNote = `usage call threw: ${e instanceof Error ? e.message : String(e)}`; return []; });
+    if (getter.length)
+        return { getter };
+    // No usage scope (a setup-token): ask the plan itself, through one tiny request.
+    const probed = await askProbe(token).catch((e) => { lastGetterNote += ` · probe threw: ${e instanceof Error ? e.message : String(e)}`; return []; });
+    if (probed.length)
+        return { getter: probed };
+    const { query } = await import('@anthropic-ai/claude-agent-sdk');
+    const { ANTHROPIC_API_KEY: _drop, ...rest } = process.env;
+    const say = (text) => ({ type: 'user', message: { role: 'user', content: text }, parent_tool_use_id: null });
+    const q = query({
+        prompt: (async function* () { yield say('/usage'); })(),
+        options: {
+            maxTurns: 1,
+            env: { ...rest, ...(token ? { CLAUDE_CODE_OAUTH_TOKEN: token } : {}) },
+        },
+    });
+    /* The report rides the synthetic ASSISTANT message that carries the text, not the result —
+       a wrapper-level sibling, deliberately outside message.content so it is never replayed to
+       the model. Reading the result alone finds nothing, which is how this was wrong once. */
+    let report;
+    let text = '';
+    // Every message type that came back, for the log when nothing usable did.
+    const seen = [];
+    for await (const m of q) {
+        seen.push(`${m['type']}${m['subtype'] ? `/${m['subtype']}` : ''}${m['usage_report'] ? '+report' : ''}`);
+        if (m['usage_report'])
+            report = m['usage_report'];
+        if (m['type'] === 'assistant' && !text) {
+            const c = m['message']?.content;
+            const t = Array.isArray(c) ? c.map((b) => b?.text ?? '').join('') : String(c ?? '');
+            if (t)
+                text = t;
+        }
+        if (m['type'] === 'result') {
+            text = String(m['result'] ?? '') || text;
+            break;
+        }
+    }
+    return { ...(report ? { report } : {}), text, seen: [lastGetterNote || 'usage call: nothing', ...seen] };
+}
+function withTimeout(p, ms) {
+    return Promise.race([p, new Promise((_r, reject) => setTimeout(() => reject(new Error('timed out')), ms))]);
+}
+/**
+ * The rows `/usage` attaches, mapped onto the ledger's window names.
+ *
+ * Classified on `kind`, never on a label — the SDK says so outright, and a label is a display
+ * string that can be reworded without warning. A `weekly_scoped` row is kept separate rather
+ * than folded into the weekly total: it can block while the overall week still has room, which
+ * is the case worth routing around.
+ */
+export function windowsFromReport(report) {
+    const rows = report?.rate_limits?.limits;
+    if (!Array.isArray(rows))
+        return [];
+    const out = [];
+    for (const row of rows) {
+        const percent = row?.percent;
+        if (typeof percent !== 'number' || !Number.isFinite(percent) || percent < 0 || percent > 100)
+            continue;
+        const kind = String(row?.kind ?? '');
+        const model = row?.scope?.model?.display_name;
+        /**
+         * A scoped week gets its OWN window name, not `seven_day` with a model beside it.
+         *
+         * The first version mapped every `weekly*` kind to `seven_day` and relied on the `model`
+         * field to tell them apart. Anything keying by window name then collided: in a real
+         * reading that is `weekly_all` at 31% and `weekly_scoped` at 7%, and the second overwrote
+         * the first — so the ledger believed the week was 7% used when the binding constraint was
+         * 31%, and would have routed work to a plan nearly three times fuller than it looked.
+         * Distinctness must not depend on a consumer remembering to check a second field.
+         */
+        const window = kind === 'session' ? 'five_hour'
+            : kind === 'weekly_all' ? 'seven_day'
+                : kind === 'weekly_scoped' ? `seven_day_scoped:${String(model ?? 'unknown')}`
+                    : kind;
+        if (!window)
+            continue;
+        // ISO with an offset, so no local-time guessing and no year to infer — the two things the
+        // prose path has to do and can get wrong.
+        const t = typeof row?.resets_at === 'string' ? Date.parse(row.resets_at) : NaN;
+        out.push({
+            window,
+            utilization: percent,
+            ...(Number.isFinite(t) ? { resetsAt: t } : {}),
+            ...(typeof model === 'string' && model ? { model } : {}),
+            // The server's own word for the row, sent so the ledger never has to infer what this is
+            // from a name this file chose. It owns window identity; this just reports.
+            ...(kind ? { kind } : {}),
+        });
+    }
+    return out;
+}
+/**
+ * Ask which account a token belongs to.
+ *
+ * Costs no turn — it is answered from the session handshake — so it is cheap enough to call
+ * whenever a subscription is added, and it is the only way to tell that two entries in the
+ * vault are secretly the same account. It is also what makes a run on this machine's own login
+ * attributable, which it otherwise is not.
+ */
+export async function readAccount(token) {
+    try {
+        const { query } = await import('@anthropic-ai/claude-agent-sdk');
+        const { ANTHROPIC_API_KEY: _drop, ...rest } = process.env;
+        const q = query({
+            prompt: (async function* () { })(),
+            options: { maxTurns: 1, env: { ...rest, ...(token ? { CLAUDE_CODE_OAUTH_TOKEN: token } : {}) } },
+        });
+        const info = await q.accountInfo();
+        return info ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=usage.js.map

package/dist/usage.js.map

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

package/dist/wall.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Is this page a sign-in wall?
+ *
+ * Without this, an agent that opens a page it has no session for gets a snapshot of a login form
+ * and no idea that is what it is. It then does the worst available thing: reasons about the login
+ * page, tries to fill it, invents credentials, or reports the card's feature as missing — because
+ * from inside the snapshot, "the screen does not have the thing I was sent to look at" is exactly
+ * what a login page looks like.
+ *
+ * Knowing is what makes the simple flow possible: open the browser, and if it is a wall, ask a
+ * person to sign in once. No token parsing, no expiry arithmetic, no guessing from cookies —
+ * none of which can tell you whether a server still honours a session anyway. The only reliable
+ * check is to use it and look.
+ *
+ * Ported from Sceneflo (BrowserAgent src/wall.ts), where the signals were learned the hard way:
+ * "is there a password box" is wrong on any site built in the last few years, and a visible
+ * Logout is the counter-signal that stops an app's own dashboard reading as a wall.
+ */
+import type { Page } from 'playwright-core';
+export type Wall = {
+    wall: boolean;
+    why: string;
+    how: 'password' | 'sso' | 'link' | 'confirm' | 'none';
+};
+export declare function signInWall(page: Page): Promise<Wall>;
+/**
+ * What to tell the AGENT when it lands on one.
+ *
+ * Deliberately not Sceneflo's wording. There, a wall it cannot drive is the end of the road. Here
+ * it is an ordinary thing with an ordinary remedy — a person signs in once, the session is kept,
+ * and every card after this one opens straight into the app. So this says what to do, not what
+ * cannot be done, and it is explicit about the two ways to get it wrong: inventing credentials,
+ * and reporting the card's own feature as missing because a login page does not have it.
+ */
+export declare function wallBrief(w: Wall, url: string, published?: string): string;

package/dist/wall.js

@@ -0,0 +1,94 @@
+const SCRIPT = `(() => {
+  const seen = (el) => {
+    if (!el) return false;
+    const r = el.getBoundingClientRect();
+    if (r.width < 1 || r.height < 1) return false;
+    const cs = getComputedStyle(el);
+    return cs.visibility !== 'hidden' && cs.display !== 'none' && Number(cs.opacity) > 0.05;
+  };
+  const words = (el) => (el.getAttribute('aria-label') || el.textContent || '').replace(/\\s+/g, ' ').trim();
+
+  const controls = Array.from(document.querySelectorAll('a, button, input, select, textarea, [role=button], [role=link]'))
+    .filter(seen);
+  const pressable = controls.filter((e) => e.matches('button, [role=button], a, input[type=submit], input[type=button]'));
+  const labels = pressable.map(words).filter(Boolean);
+
+  const password = controls.some((e) => e.matches('input[type=password]'));
+  const sso = labels.find((t) => /(continue|sign ?in|log ?in|connect)\\s+with\\s+(google|microsoft|apple|github|gitlab|okta|azure|facebook|saml|sso)|single sign|use sso/i.test(t));
+  const emailField = controls.some((e) =>
+    e.matches('input[type=email]') ||
+    (e.matches('input[type=text], input:not([type])') && /e-?mail|username|user name/i.test(
+      (e.getAttribute('name') || '') + ' ' + (e.getAttribute('id') || '') + ' ' + (e.getAttribute('placeholder') || '') + ' ' + (e.getAttribute('aria-label') || ''))));
+  const magic = labels.find((t) => /magic link|sign-?in link|email me a link|send (me )?(a )?link|one-?time (code|link)|passwordless/i.test(t));
+  const finish = labels.find((t) => /finish signing|finish sign|complete (your )?sign|confirm (your )?(e-?mail|address|identity)|verify (your )?(e-?mail|address)|continue signing/i.test(t));
+  const logout = labels.find((t) => /^(log ?out|sign ?out)$|\\b(log ?out|sign ?out)\\b/i.test(t) && t.length < 30);
+
+  return {
+    password, sso: sso || '', magic: magic || '', finish: finish || '', emailField, logout: logout || '',
+    controls: controls.length,
+  };
+})()`;
+/** How much else can be on the page before it stops looking like a wall and starts looking like an app. */
+const QUIET = 25;
+export async function signInWall(page) {
+    const r = (await page.evaluate(SCRIPT).catch(() => null));
+    if (!r)
+        return { wall: false, why: '', how: 'none' };
+    /* A password box settles it on its own — nothing but a sign-in has one, however busy the page. */
+    if (r.password)
+        return { wall: true, how: 'password', why: 'it is asking for a password' };
+    /* A visible Logout settles it the other way: a page offering to sign you OUT is signed in. An
+       app whose tiles are bare divs can distil to very few formal controls, and a login component
+       left in the DOM after sign-in then reads as a wall over a screen showing Logout twice. */
+    if (r.logout)
+        return { wall: false, why: '', how: 'none' };
+    /* A signed-in app often has an SSO button somewhere and dozens of other controls; a wall is a
+       page with almost nothing else on it, because there is nothing else you are allowed to do. */
+    if (r.controls > QUIET)
+        return { wall: false, why: '', how: 'none' };
+    if (r.sso)
+        return { wall: true, how: 'sso', why: `the way in is “${r.sso}”` };
+    if (r.magic && r.emailField)
+        return { wall: true, how: 'link', why: `it signs you in by emailing a link (“${r.magic}”)` };
+    if (r.finish && r.emailField)
+        return { wall: true, how: 'confirm', why: `it wants the address confirming first (“${r.finish}”)` };
+    return { wall: false, why: '', how: 'none' };
+}
+/**
+ * What to tell the AGENT when it lands on one.
+ *
+ * Deliberately not Sceneflo's wording. There, a wall it cannot drive is the end of the road. Here
+ * it is an ordinary thing with an ordinary remedy — a person signs in once, the session is kept,
+ * and every card after this one opens straight into the app. So this says what to do, not what
+ * cannot be done, and it is explicit about the two ways to get it wrong: inventing credentials,
+ * and reporting the card's own feature as missing because a login page does not have it.
+ */
+export function wallBrief(w, url, published = '') {
+    const how = w.how === 'sso' ? 'It signs in through another company — Google, Microsoft or similar — which nothing here can drive.'
+        : w.how === 'link' ? 'It signs in by emailing a link, which nothing here can read.'
+            : w.how === 'confirm' ? 'It is part-way through a sign-in and wants the address confirmed.'
+                : 'It wants a username and password.';
+    const common = `This is a SIGN-IN WALL, not the page you were looking for: ${w.why}. ${how}\n\n` +
+        `Nothing on this screen tells you anything about the card — in particular, the thing you ` +
+        `came to look at being absent here means nothing at all.\n\n`;
+    /* A project that publishes a way in HAS already answered this, and asking a person for what
+       the environment handed you is an interruption for nothing. HR Goat prints dev sign-in URLs
+       in its own start script for exactly this moment. */
+    if (published) {
+        return common +
+            `This project published a way in, so use it rather than asking anyone:\n\n${published}\n\n` +
+            `Those are test identities for this environment, published by the project itself. If none ` +
+            `of them works, say so and ask — but try first.`;
+    }
+    /* Name the tool. This used to say "ask for a sign-in" and nothing more, which is advice, not a
+       door: the agent dutifully wrote a comment, flagged the card and stopped, because asking was
+       not something it could DO. A brief that describes an action without naming the call is how a
+       capability that exists goes unused. */
+    return common +
+        `Do not try to sign in, and do not invent credentials.\n\n` +
+        `Call request_sign_in instead, with what you were going to check. A person signs in once, ` +
+        `the session is kept against the project, and every card after this one opens straight into ` +
+        `the app. You do not wait for it: say on the card that it is waiting on a sign-in, and you ` +
+        `are brought back automatically once the session lands.`;
+}
+//# sourceMappingURL=wall.js.map

package/dist/wall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wall.js","sourceRoot":"","sources":["../src/wall.ts"],"names":[],"mappings":"AAsBA,MAAM,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA6BV,CAAC;AAEN,2GAA2G;AAC3G,MAAM,KAAK,GAAG,EAAE,CAAC;AAEjB,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAU;IACzC,MAAM,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAQ,CAAC;IACjE,IAAI,CAAC,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC;IAErD,kGAAkG;IAClG,IAAI,CAAC,CAAC,QAAQ;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,6BAA6B,EAAE,CAAC;IAE3F;;gGAE4F;IAC5F,IAAI,CAAC,CAAC,MAAM;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC;IAE3D;mGAC+F;IAC/F,IAAI,CAAC,CAAC,QAAQ,GAAG,KAAK;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC;IAErE,IAAI,CAAC,CAAC,GAAG;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,kBAAkB,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC;IAC9E,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,UAAU;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,wCAAwC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;IAC1H,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,UAAU;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,2CAA2C,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC;IAClI,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC;AAC/C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CAAC,CAAO,EAAE,GAAW,EAAE,SAAS,GAAG,EAAE;IAC5D,MAAM,GAAG,GACP,CAAC,CAAC,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,oGAAoG;QACtH,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,MAAM,CAAC,CAAC,CAAC,8DAA8D;YACnF,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,mEAAmE;gBAC3F,CAAC,CAAC,mCAAmC,CAAC;IACxC,MAAM,MAAM,GACV,8DAA8D,CAAC,CAAC,GAAG,KAAK,GAAG,MAAM;QACjF,0FAA0F;QAC1F,6DAA6D,CAAC;IAEhE;;0DAEsD;IACtD,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,MAAM;YACX,4EAA4E,SAAS,MAAM;YAC3F,2FAA2F;YAC3F,gDAAgD,CAAC;IACrD,CAAC;IAED;;;6CAGyC;IACzC,OAAO,MAAM;QACX,2DAA2D;QAC3D,2FAA2F;QAC3F,6FAA6F;QAC7F,4FAA4F;QAC5F,wDAAwD,CAAC;AAC7D,CAAC"}

package/dist/worktree.d.ts

@@ -86,3 +86,22 @@ export declare function uncommittedCount(path: string): Promise<number>;
  * it left anything behind — a question that must never itself cut a checkout.
  */
 export declare function existingWorktree(repo: string, card: string): Promise<Worktree | null>;
+/** Bytes free on the disk holding `path`, or null when the platform cannot say. */
+export declare function freeDiskBytes(path: string): number | null;
+/**
+ * Release every card worktree of this repository that has sat unused for `idleMs` and holds
+ * nothing that is not already on the remote.
+ *
+ * releaseWorktree used to run only when an agent finished a turn on a card whose lane was Done,
+ * and agents never move a card to Done — a person does, later, when no agent is looking at it. So
+ * it almost never ran, and 78 worktrees and 45 GB built up on one machine. This sweeps instead,
+ * with the same refusals: uncommitted changes, untracked files or unpublished commits keep a
+ * worktree, and so does recent use, because several agents can share one repository's worktrees
+ * and the one another agent is in the middle of is not this agent's to take.
+ *
+ * Releasing loses nothing: a card that comes back is checked out again from what it pushed.
+ */
+export declare function sweepWorktrees(repo: string, idleMs: number, onStep: (text: string) => void, keep?: ReadonlySet<string>): Promise<{
+    removed: number;
+    kept: string[];
+}>;