@ashlr/hub 3.10.1 → 3.11.2

package/dist/core/cloud/budget.js

@@ -0,0 +1,99 @@
+/**
+ * Budget view + gates (unit C1). Spend = creditsSpentAdjustmentUsd + sum of
+ * estimatedCostUsd over tasks that reached `running` or later (failed
+ * launches cost nothing). "Today" = the operator's local calendar day.
+ *
+ * Pure: no clock, no disk — the caller passes the tasks, the budget and now.
+ */
+import { CLOUD_BALANCE_URL } from './types.js';
+const OK = Object.freeze({ ok: true, reason: null });
+const refuse = (reason) => ({ ok: false, reason });
+/**
+ * Whether a task consumed a session. A session id is the proof; the states
+ * cover a task recorded without one. A `closed` task with no session is a
+ * dismissed failure, not spend.
+ */
+export function taskConsumedSession(task) {
+    return task.sessionId !== null || task.state === 'running' || task.state === 'pr-open' || task.state === 'merged' || task.state === 'expired';
+}
+/** In flight: accepted and not yet resolved into a session or a failure. Counts toward the daily caps so a burst cannot overshoot them. */
+const inFlight = (task) => task.state === 'queued' || task.state === 'launching';
+/** `YYYY-MM-DD` of the operator's local calendar day. */
+export function localDayKey(date) {
+    return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
+}
+/** `$3`, `$2.50`, `$1,234` — whole dollars without cents. */
+export function formatUsd(value) {
+    const rounded = Math.round(value * 100) / 100;
+    const whole = Number.isInteger(rounded);
+    return `$${rounded.toLocaleString('en-US', { minimumFractionDigits: whole ? 0 : 2, maximumFractionDigits: whole ? 0 : 2 })}`;
+}
+const plural = (n, one, many) => (n === 1 ? one : many);
+export function cloudBudgetView(tasks, budget, now) {
+    const today = localDayKey(now);
+    let spent = budget.creditsSpentAdjustmentUsd;
+    let sessionsToday = 0;
+    let selfImproveToday = 0;
+    let running = 0;
+    let queued = 0;
+    for (const task of tasks) {
+        const consumed = taskConsumedSession(task);
+        if (consumed)
+            spent += task.estimatedCostUsd;
+        if (task.state === 'launching' || task.state === 'running')
+            running += 1;
+        if (task.state === 'queued')
+            queued += 1;
+        if (!consumed && !inFlight(task))
+            continue;
+        const at = Date.parse(task.launchedAt ?? task.createdAt);
+        if (!Number.isFinite(at) || localDayKey(new Date(at)) !== today)
+            continue;
+        sessionsToday += 1;
+        if (task.origin === 'self-improve')
+            selfImproveToday += 1;
+    }
+    const estimatedSpentUsd = Math.round(spent * 100) / 100;
+    const estimatedRemainingUsd = Math.max(0, Math.round((budget.creditsTotalUsd - estimatedSpentUsd) * 100) / 100);
+    const cost = budget.estimatedCostPerSessionUsd;
+    let canLaunch = OK;
+    if (estimatedRemainingUsd < cost || (cost === 0 && estimatedRemainingUsd <= 0)) {
+        canLaunch = refuse(`About ${formatUsd(estimatedRemainingUsd)} of estimated credits is left — not enough for another session at ${formatUsd(cost)} each.`);
+    }
+    else if (sessionsToday >= budget.maxSessionsPerDay) {
+        canLaunch = refuse(`${sessionsToday} of ${budget.maxSessionsPerDay} cloud ${plural(budget.maxSessionsPerDay, 'session', 'sessions')} used today.`);
+    }
+    else if (running + queued >= budget.maxConcurrent) {
+        // Queued tasks are about to launch, so they hold a slot: otherwise two
+        // launches accepted back to back (different repos) could both pass a cap of one.
+        canLaunch = refuse(`${running + queued} of ${budget.maxConcurrent} cloud ${plural(budget.maxConcurrent, 'session is', 'sessions are')} already running.`);
+    }
+    let canSelfImprove = canLaunch;
+    if (canLaunch.ok) {
+        if (!budget.selfImprove.enabled) {
+            canSelfImprove = refuse('Self-improvement is turned off.');
+        }
+        else if (selfImproveToday >= budget.selfImprove.maxPerDay) {
+            canSelfImprove = refuse(`${selfImproveToday} of ${budget.selfImprove.maxPerDay} self-improvement ${plural(budget.selfImprove.maxPerDay, 'launch', 'launches')} used today.`);
+        }
+        else if (estimatedRemainingUsd - cost < budget.selfImprove.reserveUsd) {
+            // The reserve is kept for the operator's own tasks: self-improvement
+            // stops BEFORE a launch would take the estimate below it.
+            canSelfImprove = refuse(`Another self-improvement session would take estimated credits below the ${formatUsd(budget.selfImprove.reserveUsd)} reserve.`);
+        }
+    }
+    return {
+        creditsTotalUsd: budget.creditsTotalUsd,
+        estimatedSpentUsd,
+        estimatedRemainingUsd,
+        sessionsToday,
+        selfImproveToday,
+        running,
+        canLaunch,
+        canSelfImprove,
+        estimateNote: `Estimated at ${formatUsd(cost)} per session — Claude doesn't expose the credit balance. Check it on claude.ai and adjust here.`,
+        balanceUrl: CLOUD_BALANCE_URL,
+        budget,
+    };
+}
+//# sourceMappingURL=budget.js.map

package/dist/core/cloud/budget.js.map

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

package/dist/core/cloud/checkout.d.ts

@@ -0,0 +1,41 @@
+export type CloudCheckoutResult = {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    failure: 'no-remote' | 'checkout-failed';
+    message: string;
+};
+export interface CloudCheckoutDeps {
+    git?: (args: string[], opts: {
+        cwd: string;
+        timeoutMs: number;
+    }) => Promise<{
+        ok: boolean;
+        stdout: string;
+        stderr: string;
+    }>;
+    originUrlFor?: (repo: string) => string;
+}
+export declare const CLOUD_CHECKOUTS_DIR = "checkouts";
+/**
+ * In-process FIFO mutex keyed by string. Two `--cloud` runs (or a fetch and
+ * a launch) in one folder would race on the checked-out branch, so every
+ * user of a folder queues here. The map entry is dropped when the last
+ * waiter finishes, so it never grows with the number of repos ever used.
+ */
+export declare class KeyedMutex {
+    private readonly tails;
+    run<T>(key: string, fn: () => Promise<T>): Promise<T>;
+    /** True while any caller holds or waits for `key` (tests, diagnostics). */
+    busy(key: string): boolean;
+}
+/**
+ * A branch name git accepts that also cannot be read as an option or escape
+ * the ref namespace. Stricter than check-ref-format on purpose: base
+ * branches are human names like `main` or `v3110-cloud`.
+ */
+export declare function isSafeBranchName(branch: string): boolean;
+/** Lower-cased: GitHub names are case-insensitive, and so is the default macOS filesystem — one repo, one folder, one lock. */
+export declare function cloudCheckoutPath(repo: string): string;
+export declare function ensureCloudCheckout(repo: string, branch: string, deps?: CloudCheckoutDeps): Promise<CloudCheckoutResult>;

package/dist/core/cloud/checkout.js

@@ -0,0 +1,168 @@
+/**
+ * Isolated launch checkouts (unit C1): `<cloudHome>/checkouts/<owner>__<name>`,
+ * a shallow single-branch clone of https://github.com/<owner>/<name>.git
+ * using the operator's normal git credentials. Before each launch:
+ * `git fetch --depth 1 origin <branch>` then `git checkout -B <branch>
+ * FETCH_HEAD` with upstream set, so the CLI sees a pushed branch. Never
+ * touches the operator's own clones or fleet mirrors. Serialise per path.
+ *
+ * WHY a checkout of our own: `claude --cloud` clones the cwd's origin at the
+ * cwd's CURRENT branch. Launching from the operator's working copy would pin
+ * the session to whatever branch they happen to have checked out (possibly
+ * unpushed); a private checkout pinned to the requested base makes the
+ * session start exactly where the task says.
+ */
+import { lstatSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { defaultGitRunner } from '../verse/git-ops.js';
+import { CLOUD_REPO_PATTERN, cloudHome, ensureCloudDirectory } from './store.js';
+export const CLOUD_CHECKOUTS_DIR = 'checkouts';
+const CLONE_TIMEOUT_MS = 180_000;
+const GIT_TIMEOUT_MS = 60_000;
+// ---------------------------------------------------------------------------
+// Per-key mutex
+// ---------------------------------------------------------------------------
+/**
+ * In-process FIFO mutex keyed by string. Two `--cloud` runs (or a fetch and
+ * a launch) in one folder would race on the checked-out branch, so every
+ * user of a folder queues here. The map entry is dropped when the last
+ * waiter finishes, so it never grows with the number of repos ever used.
+ */
+export class KeyedMutex {
+    tails = new Map();
+    async run(key, fn) {
+        const previous = this.tails.get(key) ?? Promise.resolve();
+        let release;
+        const current = new Promise((resolve) => { release = resolve; });
+        const tail = previous.then(() => current);
+        this.tails.set(key, tail);
+        await previous;
+        try {
+            return await fn();
+        }
+        finally {
+            release();
+            if (this.tails.get(key) === tail)
+                this.tails.delete(key);
+        }
+    }
+    /** True while any caller holds or waits for `key` (tests, diagnostics). */
+    busy(key) {
+        return this.tails.has(key);
+    }
+}
+const checkoutMutex = new KeyedMutex();
+// ---------------------------------------------------------------------------
+// Checkout
+// ---------------------------------------------------------------------------
+/**
+ * A branch name git accepts that also cannot be read as an option or escape
+ * the ref namespace. Stricter than check-ref-format on purpose: base
+ * branches are human names like `main` or `v3110-cloud`.
+ */
+export function isSafeBranchName(branch) {
+    return typeof branch === 'string'
+        && branch.length > 0 && branch.length <= 200
+        && /^[A-Za-z0-9._/-]+$/.test(branch)
+        && !branch.startsWith('-') && !branch.startsWith('/') && !branch.endsWith('/')
+        && !branch.endsWith('.') && !branch.endsWith('.lock')
+        && !branch.includes('..') && !branch.includes('//') && !branch.includes('/.');
+}
+/** Lower-cased: GitHub names are case-insensitive, and so is the default macOS filesystem — one repo, one folder, one lock. */
+export function cloudCheckoutPath(repo) {
+    const [owner, name] = repo.toLowerCase().split('/');
+    return join(cloudHome(), CLOUD_CHECKOUTS_DIR, `${owner}__${name}`);
+}
+const defaultOriginUrl = (repo) => `https://github.com/${repo}.git`;
+async function defaultGit(args, opts) {
+    const result = await defaultGitRunner('git', args, { cwd: opts.cwd, timeoutMs: opts.timeoutMs });
+    return { ok: result.code === 0 && !result.timedOut, stdout: result.stdout, stderr: result.missing ? 'git is not installed' : result.stderr };
+}
+/** git's words for "that repo or branch is not on GitHub (or not reachable with these credentials)". */
+function isMissingRemote(stderr) {
+    return /couldn't find remote ref|remote branch .* not found|repository not found|could not read from remote repository|could not read username|authentication failed|does not appear to be a git repository/i.test(stderr);
+}
+function failed(repo, branch, stderr) {
+    if (isMissingRemote(stderr)) {
+        return { ok: false, failure: 'no-remote', message: `Couldn't find branch ${branch} of ${repo} on GitHub. Check the repo name, that the branch is pushed, and that git can reach it.` };
+    }
+    return { ok: false, failure: 'checkout-failed', message: `Couldn't prepare a checkout of ${repo} at ${branch} for the cloud launch.` };
+}
+function isGitCheckout(path) {
+    try {
+        const dir = lstatSync(path);
+        if (!dir.isDirectory() || dir.isSymbolicLink())
+            return false;
+        return lstatSync(join(path, '.git')).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function prepare(repo, branch, deps) {
+    const git = deps.git ?? defaultGit;
+    const url = (deps.originUrlFor ?? defaultOriginUrl)(repo);
+    let parent;
+    try {
+        parent = ensureCloudDirectory(CLOUD_CHECKOUTS_DIR);
+    }
+    catch {
+        return { ok: false, failure: 'checkout-failed', message: "Couldn't create the private folder for cloud checkouts." };
+    }
+    const path = cloudCheckoutPath(repo);
+    if (!isGitCheckout(path)) {
+        // Anything else at our own path is a clone that died half-way (or was
+        // tampered with); it is ours to replace, and git refuses a non-empty target.
+        try {
+            rmSync(path, { recursive: true, force: true });
+        }
+        catch { /* clone below reports it */ }
+        const clone = await git(['clone', '--depth', '1', '--single-branch', '--no-tags', '--branch', branch, '--', url, path], { cwd: parent, timeoutMs: CLONE_TIMEOUT_MS });
+        if (!clone.ok) {
+            try {
+                rmSync(path, { recursive: true, force: true });
+            }
+            catch { /* best effort */ }
+            return failed(repo, branch, clone.stderr);
+        }
+    }
+    const steps = [
+        // The origin URL is re-asserted every time so a checkout can never launch
+        // against a remote other than the one the task names.
+        ['remote', 'set-url', 'origin', url],
+        // A single-branch clone only maps its first branch to a remote-tracking
+        // ref; git refuses an upstream (and cannot resolve @{u}) for any other
+        // base until the remote's fetch refspec covers it.
+        ['remote', 'set-branches', 'origin', '*'],
+        // An explicit refspec keeps a remote-tracking ref even in a single-branch
+        // clone, which is what the upstream below points at.
+        ['fetch', '--depth', '1', '--no-tags', 'origin', `+refs/heads/${branch}:refs/remotes/origin/${branch}`],
+        ['checkout', '--force', '-B', branch, 'FETCH_HEAD'],
+        ['branch', `--set-upstream-to=origin/${branch}`, branch],
+        // Nothing a previous launch left behind may ride along into the next session.
+        ['clean', '-ffdx'],
+    ];
+    for (const args of steps) {
+        const step = await git(args, { cwd: path, timeoutMs: args[0] === 'fetch' ? CLONE_TIMEOUT_MS : GIT_TIMEOUT_MS });
+        if (!step.ok)
+            return failed(repo, branch, step.stderr);
+    }
+    return { ok: true, path };
+}
+export async function ensureCloudCheckout(repo, branch, deps = {}) {
+    if (typeof repo !== 'string' || !CLOUD_REPO_PATTERN.test(repo)) {
+        return { ok: false, failure: 'checkout-failed', message: 'The repo must look like owner/name.' };
+    }
+    if (!isSafeBranchName(branch)) {
+        return { ok: false, failure: 'checkout-failed', message: `"${String(branch).slice(0, 80)}" isn't a branch name the cloud lane accepts.` };
+    }
+    return checkoutMutex.run(cloudCheckoutPath(repo), async () => {
+        try {
+            return await prepare(repo, branch, deps);
+        }
+        catch {
+            return { ok: false, failure: 'checkout-failed', message: `Couldn't prepare a checkout of ${repo} at ${branch} for the cloud launch.` };
+        }
+    });
+}
+//# sourceMappingURL=checkout.js.map

package/dist/core/cloud/checkout.js.map

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

package/dist/core/cloud/cloud-api.d.ts

@@ -0,0 +1,86 @@
+import type { ApiModule } from '../verse/api-modules.js';
+import { type NeedsYouItem } from '../verse/workbench-types.js';
+import { type CloudBudgetUpdate, type CloudLaunchRequest, type CloudTaskV1 } from './types.js';
+/** Same shape the service validates (spec C1); checked here too so bad input is a 400, not a failed task. */
+export declare const CLOUD_REPO_PATTERN: RegExp;
+export declare class CloudInputError extends Error {
+}
+export declare function isValidCloudRepo(value: unknown): value is string;
+export declare function isValidBranchName(value: unknown): value is string;
+/** Strict parse of a launch body; throws CloudInputError with a plain sentence. `origin` defaults to operator. */
+export declare function parseCloudLaunchBody(body: Record<string, unknown>): CloudLaunchRequest;
+/**
+ * Strict parse of a budget update: types and signs only. Clamping to sane
+ * maxima is the store's job (updateCloudBudget), so the two never disagree
+ * about what "sane" means.
+ */
+export declare function parseCloudBudgetBody(body: Record<string, unknown>): CloudBudgetUpdate;
+export declare function parseCloudImproveBody(body: Record<string, unknown>): {
+    count: number;
+};
+export declare const CLOUD_DISMISS_REASON = "Dismissed in Verse.";
+export type CloudDismissResult = {
+    ok: true;
+    task: CloudTaskV1;
+} | {
+    ok: false;
+    status: 404 | 409;
+    error: string;
+};
+/**
+ * Mark a task `closed` with "Dismissed in Verse." — idempotent for a task
+ * already closed. Refused for a MERGED task (closing it would rewrite what
+ * happened) and while a launch is still in flight (the service would then
+ * overwrite the dismissal with `running`).
+ */
+export declare function dismissCloudTask(id: string, now?: Date): CloudDismissResult;
+/** Failed launches stay in Needs-you this long (spec C2). */
+export declare const CLOUD_FAILED_WINDOW_MS: number;
+/**
+ * PURE: the Needs-you items for `tasks` at `now`.
+ *
+ * WHY THESE SOURCES AND KINDS: the Needs-you contract (workbench-types.ts
+ * §2) has a closed set of sources and kinds, and the web drawer and the
+ * desktop shell switch on both exhaustively, so a new one is not additive.
+ * A cloud PR is exactly an `owner-lane-pr` — a PR that is never merged
+ * automatically and waits for Mason — filed under `fleet`, the source the
+ * drawer already reads for that kind. A failed launch is a failed piece of
+ * work the operator started (often from a chat's "Run in cloud"), so it is a
+ * `chats` / `chat-failed` item with no session to open.
+ */
+export declare function cloudNeedsYouItems(tasks: readonly CloudTaskV1[], now: Date): NeedsYouItem[];
+/**
+ * Needs-you producer (activity-api.ts calls it on every poll). Returns the
+ * cached items in O(1) and, when the cache is stale, rebuilds it on a later
+ * tick — the task store is file I/O and never runs on the poll's stack. The
+ * first call answers [] (cloud items are additive to sources that vouch for
+ * themselves) and has the real answer ready for the next poll.
+ */
+export declare function needsYouItems(): NeedsYouItem[];
+/** Test seam: replace the task reader (null restores) and drop the cache. */
+export declare function setCloudNeedsYouReaderForTest(read: (() => readonly CloudTaskV1[]) | null): void;
+export declare function refreshCloudTasksGuarded(): Promise<{
+    checked: number;
+    updated: number;
+}>;
+export declare const CLOUD_REFRESH_EVERY_MS: number;
+export declare const CLOUD_IMPROVE_EVERY_MS: number;
+export declare const CLOUD_IMPROVE_FIRST_DELAY_MS: number;
+/** Why this process must not run the scheduler; null when it may. */
+export declare function cloudSchedulerRefusal(env?: NodeJS.ProcessEnv): string | null;
+export interface CloudSchedulerDeps {
+    refresh?: () => Promise<unknown>;
+    improve?: () => Promise<unknown>;
+    log?: (message: string) => void;
+}
+/**
+ * Start the process-wide scheduler once (idempotent, never throws). True when
+ * it runs. Jobs are guarded against overlapping runs — a tick that finds its
+ * previous run still going is skipped, not queued — and a failure is logged
+ * once per DISTINCT error, then stays quiet until it changes or clears.
+ */
+export declare function startCloudScheduler(env?: NodeJS.ProcessEnv, deps?: CloudSchedulerDeps): boolean;
+/** Stop the scheduler (tests, shutdown). Safe to call when it never started. */
+export declare function stopCloudScheduler(): void;
+export declare function cloudSchedulerRunning(): boolean;
+export declare const handleCloudApi: ApiModule;