@ashlr/hub 3.10.1 → 3.11.2

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

@@ -0,0 +1,30 @@
+export interface CloudTrackerDeps {
+    gh?: (args: string[]) => Promise<{
+        ok: boolean;
+        stdout: string;
+        stderr: string;
+    }>;
+    now?: () => Date;
+}
+/**
+ * `expired` only means Verse stopped waiting: the session keeps running on
+ * claude.ai and may still open its PR. Expired tasks stay watched this long
+ * after creation so a late delivery is not lost, then are left alone.
+ */
+export declare const EXPIRED_WATCH_MS: number;
+/**
+ * A task still `queued`/`launching` this long after creation was orphaned by
+ * a server restart mid-launch (a live launch finishes within the checkout +
+ * CLOUD_LAUNCH_TIMEOUT_MS). Left alone it would hold a concurrency slot forever.
+ */
+export declare const STALE_LAUNCH_MS: number;
+/** Production gh: argv only, bounded, never prompts (git-ops' runner and env). */
+export declare function defaultCloudGh(args: string[]): Promise<{
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+}>;
+export declare function refreshCloudTasks(deps?: CloudTrackerDeps): Promise<{
+    checked: number;
+    updated: number;
+}>;

package/dist/core/cloud/tracker.js

@@ -0,0 +1,152 @@
+/**
+ * Delivery tracker (unit C1): for every non-terminal task, ask GitHub for a
+ * PR whose head is `task.branch` (`gh pr list --repo <repo> --head <branch>
+ * --state all --json number,url,state,isDraft,title,body --limit 1`), update
+ * state/pr/report, and expire tasks with no PR after CLOUD_TASK_EXPIRY_MS.
+ * `gh` failures leave tasks unchanged (never throw into callers).
+ *
+ * Transitions:
+ *   running  → pr-open | merged | closed   (a PR appeared on the branch)
+ *   pr-open  → merged | closed             (and pr/report stay current while open)
+ *   running  → expired                     (no PR after CLOUD_TASK_EXPIRY_MS)
+ *   expired  → pr-open | merged | closed   (a late PR, within EXPIRED_WATCH_MS)
+ *   queued | launching → failed            (a launch interrupted by a restart)
+ */
+import { tmpdir } from 'node:os';
+import { defaultGitRunner } from '../verse/git-ops.js';
+import { parseCloudReport } from './delivery-contract.js';
+import { listCloudTasks, readCloudTask, writeCloudTask } from './store.js';
+import { CLOUD_LAUNCH_TIMEOUT_MS, CLOUD_TASK_EXPIRY_MS } from './types.js';
+const HOUR = 60 * 60 * 1000;
+/**
+ * `expired` only means Verse stopped waiting: the session keeps running on
+ * claude.ai and may still open its PR. Expired tasks stay watched this long
+ * after creation so a late delivery is not lost, then are left alone.
+ */
+export const EXPIRED_WATCH_MS = 48 * HOUR;
+/**
+ * A task still `queued`/`launching` this long after creation was orphaned by
+ * a server restart mid-launch (a live launch finishes within the checkout +
+ * CLOUD_LAUNCH_TIMEOUT_MS). Left alone it would hold a concurrency slot forever.
+ */
+export const STALE_LAUNCH_MS = 10 * CLOUD_LAUNCH_TIMEOUT_MS;
+/** Bound on gh calls per refresh; newest tasks are checked first. */
+const MAX_CHECKS_PER_REFRESH = 50;
+const GH_TIMEOUT_MS = 30_000;
+/** Production gh: argv only, bounded, never prompts (git-ops' runner and env). */
+export async function defaultCloudGh(args) {
+    const result = await defaultGitRunner('gh', args, { cwd: tmpdir(), timeoutMs: GH_TIMEOUT_MS, maxStdoutBytes: 2 * 1024 * 1024 });
+    return { ok: result.code === 0 && !result.timedOut && !result.truncated, stdout: result.stdout, stderr: result.stderr };
+}
+/** First PR of `gh pr list --json …` output; undefined when the output is not what gh prints (a failure, not "no PR"). */
+function parseGhPrList(stdout) {
+    let value;
+    try {
+        value = JSON.parse(stdout);
+    }
+    catch {
+        return undefined;
+    }
+    if (!Array.isArray(value))
+        return undefined;
+    if (value.length === 0)
+        return null;
+    const pr = value[0];
+    if (!pr || typeof pr !== 'object' || typeof pr['number'] !== 'number' || typeof pr['url'] !== 'string' || typeof pr['state'] !== 'string')
+        return undefined;
+    return {
+        number: pr['number'],
+        url: pr['url'],
+        state: pr['state'],
+        isDraft: pr['isDraft'] === true,
+        title: typeof pr['title'] === 'string' ? pr['title'] : '',
+        body: typeof pr['body'] === 'string' ? pr['body'] : null,
+    };
+}
+function prFrom(gh) {
+    const state = gh.state.toUpperCase();
+    const mapped = state === 'OPEN' ? 'open' : state === 'MERGED' ? 'merged' : state === 'CLOSED' ? 'closed' : null;
+    if (!mapped || !/^https:\/\/github\.com\//.test(gh.url))
+        return null;
+    return { number: gh.number, url: gh.url, state: mapped, draft: gh.isDraft, title: gh.title.slice(0, 300) };
+}
+function stateFor(pr) {
+    if (pr.state === 'merged')
+        return { state: 'merged', reason: `Pull request #${pr.number} was merged.` };
+    if (pr.state === 'closed')
+        return { state: 'closed', reason: `Pull request #${pr.number} was closed without merging.` };
+    return { state: 'pr-open', reason: `${pr.draft ? 'Draft pull request' : 'Pull request'} #${pr.number} is open for review.` };
+}
+const watched = (task, nowMs) => task.state === 'running' || task.state === 'pr-open'
+    || (task.state === 'expired' && task.pr === null && nowMs - Date.parse(task.createdAt) < EXPIRED_WATCH_MS);
+/** Writes `next` only when the task on disk is still the one this refresh read (a launch or dismiss in between wins). */
+function commit(before, next) {
+    const current = readCloudTask(before.id);
+    if (!current || current.updatedAt !== before.updatedAt || current.state !== before.state)
+        return false;
+    writeCloudTask(next);
+    return true;
+}
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+export async function refreshCloudTasks(deps = {}) {
+    const gh = deps.gh ?? defaultCloudGh;
+    const nowMs = (deps.now ?? (() => new Date()))().getTime();
+    let checked = 0;
+    let updated = 0;
+    let tasks;
+    try {
+        tasks = listCloudTasks();
+    }
+    catch {
+        return { checked, updated };
+    }
+    for (const task of tasks) {
+        if ((task.state === 'queued' || task.state === 'launching') && nowMs - Date.parse(task.createdAt) > STALE_LAUNCH_MS) {
+            try {
+                if (commit(task, { ...task, state: 'failed', failure: 'unknown', stateReason: 'The launch was interrupted before a cloud session started.' }))
+                    updated += 1;
+            }
+            catch { /* never throw into callers */ }
+        }
+    }
+    for (const task of tasks.filter((t) => watched(t, nowMs)).slice(0, MAX_CHECKS_PER_REFRESH)) {
+        checked += 1;
+        let result;
+        try {
+            result = await gh(['pr', 'list', '--repo', task.repo, '--head', task.branch, '--state', 'all',
+                '--json', 'number,url,state,isDraft,title,body', '--limit', '1']);
+        }
+        catch {
+            continue;
+        }
+        if (!result.ok)
+            continue;
+        const ghPr = parseGhPrList(result.stdout);
+        if (ghPr === undefined)
+            continue;
+        let next = null;
+        if (ghPr) {
+            const pr = prFrom(ghPr);
+            if (!pr)
+                continue;
+            const { state, reason } = stateFor(pr);
+            // A PR edited to drop its report keeps the last good one.
+            const report = parseCloudReport(ghPr.body) ?? task.report;
+            if (state !== task.state || !same(pr, task.pr) || !same(report, task.report) || reason !== task.stateReason) {
+                next = { ...task, state, pr, report, stateReason: reason, failure: null };
+            }
+        }
+        else if (task.state === 'running' && nowMs - Date.parse(task.launchedAt ?? task.createdAt) > CLOUD_TASK_EXPIRY_MS) {
+            next = { ...task, state: 'expired', stateReason: `No pull request arrived within ${Math.round(CLOUD_TASK_EXPIRY_MS / HOUR)} hours. The session link still works.` };
+        }
+        if (!next)
+            continue;
+        try {
+            if (commit(task, next))
+                updated += 1;
+        }
+        catch { /* a failed write leaves the task as it was */ }
+    }
+    return { checked, updated };
+}
+//# sourceMappingURL=tracker.js.map

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

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

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

@@ -0,0 +1,233 @@
+/**
+ * Cloud lane (3.11) — FROZEN CONTRACTS.
+ *
+ * Ashlr Verse launches Claude Code cloud sessions (claude.ai/code) that run on
+ * the operator's Claude account — including its cloud / usage credits once
+ * the subscription window is spent — and tracks what they deliver.
+ *
+ * How a launch works (verified 2026-09-24 against Claude Code 2.1.280):
+ *   - A NEW cloud session can only be created by the interactive CLI:
+ *     `claude --cloud "<task>"` (with `-p` it is refused). Run under a
+ *     pseudo-terminal it prints, then exits 0:
+ *         Created cloud session: <title>
+ *         View: https://claude.ai/code/session_<id>?from=cli&m=0
+ *         Resume with: claude --teleport session_<id>
+ *   - It must run as the `claude-a` seat's native-profile launcher, which is
+ *     signed in with a claude.ai account; API-key auth is refused ("cloud
+ *     sessions require authentication with a Claude.ai account").
+ *   - The session clones the cwd's `origin` GitHub repo at the cwd's CURRENT
+ *     branch, which must be pushed. The Claude GitHub app already has access
+ *     to ashlrai/*.
+ *   - Attaching to / reading an existing session from the CLI is NOT enabled
+ *     for this account, so Verse never reads a session back. Every task is
+ *     told to DELIVER to GitHub instead (see delivery-contract.ts): push
+ *     branch `ashlr-cloud/<taskId>` and open a DRAFT PR whose body carries a
+ *     fenced `ashlr-cloud-report` JSON block. Verse tracks tasks with `gh`.
+ *   - The credit balance is not readable (neither `/usage` nor the CLI show
+ *     it), so spend is an ESTIMATE the operator can calibrate; the UI always
+ *     says so and links to https://claude.ai/settings/usage.
+ *
+ * Nothing here merges. A cloud PR is judged and merged by the existing merge
+ * gates (custody) or by Mason — never by the cloud lane.
+ */
+export declare const CLOUD_TASK_SCHEMA_VERSION: 1;
+export declare const CLOUD_BUDGET_SCHEMA_VERSION: 1;
+/** Branch every cloud task delivers to: `ashlr-cloud/<taskId>`. */
+export declare const CLOUD_BRANCH_PREFIX: "ashlr-cloud/";
+/** Fenced block language tag carrying the task report in the PR body. */
+export declare const CLOUD_REPORT_FENCE: "ashlr-cloud-report";
+/** Draft PR title prefix, so tasks are recognisable in GitHub lists. */
+export declare const CLOUD_PR_TITLE_PREFIX: "[ashlr-cloud]";
+/** Where the real credit balance lives (not readable programmatically). */
+export declare const CLOUD_BALANCE_URL: "https://claude.ai/settings/usage";
+/** The seat whose claude.ai login launches cloud sessions. */
+export declare const CLOUD_SEAT_ID: "claude-a";
+/** A task with no PR after this long is marked `expired` (still linkable). */
+export declare const CLOUD_TASK_EXPIRY_MS: number;
+/** Max prompt length accepted from any entry point (chars). */
+export declare const CLOUD_PROMPT_MAX_CHARS = 20000;
+/** Launch timeout for the PTY-wrapped CLI (creation took < 10 s in testing). */
+export declare const CLOUD_LAUNCH_TIMEOUT_MS = 90000;
+/** Task ids look like `ct_20260924T2331_k3f9q2` (sortable, branch-safe). */
+export declare const CLOUD_TASK_ID_PATTERN: RegExp;
+export type CloudTaskOrigin = 'chat' | 'operator' | 'leader' | 'self-improve' | 'cli';
+/**
+ * queued     accepted, waiting for its repo's launch slot (launches are
+ *            serialised per checkout folder — two concurrent `--cloud` runs
+ *            in one folder conflict).
+ * launching  PTY launch in flight.
+ * running    session created; no PR yet.
+ * pr-open    draft/ready PR exists on `ashlr-cloud/<id>`.
+ * merged     PR merged (by gates or Mason).
+ * closed     PR closed without merge (or dismissed by the operator).
+ * failed     launch failed (see stateReason / failure code).
+ * expired    no PR after CLOUD_TASK_EXPIRY_MS — the session link still works.
+ */
+export type CloudTaskState = 'queued' | 'launching' | 'running' | 'pr-open' | 'merged' | 'closed' | 'failed' | 'expired';
+export declare const CLOUD_TERMINAL_STATES: readonly CloudTaskState[];
+export type CloudLaunchFailureCode = 'seat-unavailable' | 'auth' | 'not-enabled' | 'rate-limited' | 'no-remote' | 'checkout-failed' | 'budget' | 'timeout' | 'unparsed' | 'unknown';
+export interface CloudTaskReport {
+    status: 'done' | 'partial' | 'blocked' | 'no-change';
+    summary: string;
+    testsRun: string[];
+    risks: string[];
+    filesChanged?: number;
+}
+export interface CloudTaskPr {
+    number: number;
+    url: string;
+    state: 'open' | 'closed' | 'merged';
+    draft: boolean;
+    title: string;
+}
+export interface CloudTaskV1 {
+    v: typeof CLOUD_TASK_SCHEMA_VERSION;
+    id: string;
+    /** GitHub `owner/name`. */
+    repo: string;
+    /** Branch the session starts from (must exist on origin). */
+    baseBranch: string;
+    /** Always `${CLOUD_BRANCH_PREFIX}${id}`. */
+    branch: string;
+    /** Short human title (≤ 80 chars). */
+    title: string;
+    /** The operator's / Leader's task text — WITHOUT the delivery contract. */
+    prompt: string;
+    origin: CloudTaskOrigin;
+    requestedBy: 'mason' | 'leader' | 'self-improve';
+    seat: string;
+    sessionId: string | null;
+    sessionUrl: string | null;
+    state: CloudTaskState;
+    /** Plain-language reason for the current state (never raw ISO / paths). */
+    stateReason: string | null;
+    failure: CloudLaunchFailureCode | null;
+    createdAt: string;
+    launchedAt: string | null;
+    updatedAt: string;
+    pr: CloudTaskPr | null;
+    report: CloudTaskReport | null;
+    /** Budget accounting — an ESTIMATE fixed at launch. */
+    estimatedCostUsd: number;
+    /** Backlog item this task came from (self-improvement), if any. */
+    backlogItemId: string | null;
+    /** Needs-you item created for approval (Leader-suggested tasks), if any. */
+    needsYouId: string | null;
+}
+export interface CloudBudgetV1 {
+    v: typeof CLOUD_BUDGET_SCHEMA_VERSION;
+    /** Credits the operator says the account has (default 250). */
+    creditsTotalUsd: number;
+    /**
+     * Operator calibration: credits already spent BEFORE the tasks Verse
+     * tracks (or a correction after checking claude.ai). Added to the estimate.
+     */
+    creditsSpentAdjustmentUsd: number;
+    /** Flat per-session estimate used for accounting (default 3). */
+    estimatedCostPerSessionUsd: number;
+    /** Max sessions in `launching|running` at once (all origins). */
+    maxConcurrent: number;
+    /** Max sessions per local day from ANY origin. */
+    maxSessionsPerDay: number;
+    selfImprove: {
+        /** Verse may launch its own self-improvement tasks without a click. */
+        enabled: boolean;
+        /** Repo self-improvement targets (default ashlrai/ashlr-hub). */
+        repo: string;
+        /** Max self-improvement launches per local day. */
+        maxPerDay: number;
+        /** Stop self-improvement when estimated remaining credits fall below this. */
+        reserveUsd: number;
+    };
+    updatedAt: string;
+}
+export declare const DEFAULT_CLOUD_BUDGET: Omit<CloudBudgetV1, 'updatedAt'>;
+export interface CloudGate {
+    ok: boolean;
+    /** Plain sentence when !ok ("4 of 4 self-improvement launches used today."). */
+    reason: string | null;
+}
+export interface CloudBudgetView {
+    creditsTotalUsd: number;
+    estimatedSpentUsd: number;
+    estimatedRemainingUsd: number;
+    sessionsToday: number;
+    selfImproveToday: number;
+    running: number;
+    canLaunch: CloudGate;
+    canSelfImprove: CloudGate;
+    /** Always shown next to spend: why this is an estimate. */
+    estimateNote: string;
+    balanceUrl: typeof CLOUD_BALANCE_URL;
+    budget: CloudBudgetV1;
+}
+export interface CloudSeatStatus {
+    id: string;
+    ready: boolean;
+    /** Plain sentence when not ready. */
+    reason: string | null;
+}
+/** One self-improvement item: built in (improvement-backlog.ts) or added by the operator/Leader (<cloudHome>/backlog.json). */
+export interface CloudBacklogItem {
+    id: string;
+    title: string;
+    /** Full task prompt handed to the cloud session. */
+    prompt: string;
+    area: string;
+    priority: 1 | 2 | 3;
+    /** Repo the item targets (default: budget.selfImprove.repo). */
+    repo?: string;
+}
+export interface CloudBacklogView {
+    items: Array<CloudBacklogItem & {
+        claimedBy: string | null;
+        lastState: CloudTaskState | null;
+    }>;
+    nextUp: string | null;
+}
+export declare const VERSE_CLOUD_PATH: "/api/verse/cloud";
+export declare const VERSE_CLOUD_LAUNCH_PATH: "/api/verse/cloud/launch";
+export declare const VERSE_CLOUD_BUDGET_PATH: "/api/verse/cloud/budget";
+export declare const VERSE_CLOUD_REFRESH_PATH: "/api/verse/cloud/refresh";
+export declare const VERSE_CLOUD_IMPROVE_PATH: "/api/verse/cloud/improve";
+/** POST `${VERSE_CLOUD_TASKS_PATH}/<id>/dismiss` */
+export declare const VERSE_CLOUD_TASKS_PATH: "/api/verse/cloud/tasks";
+/** GET /api/verse/cloud */
+export interface CloudOverviewResponse {
+    generatedAt: string;
+    seat: CloudSeatStatus;
+    budget: CloudBudgetView;
+    /** Newest first, at most 100. */
+    tasks: CloudTaskV1[];
+    backlog: CloudBacklogView;
+}
+/** POST /api/verse/cloud/launch (write token + read session) */
+export interface CloudLaunchRequest {
+    repo: string;
+    baseBranch?: string;
+    title?: string;
+    prompt: string;
+    origin: Extract<CloudTaskOrigin, 'chat' | 'operator' | 'cli'>;
+}
+export interface CloudLaunchResponse {
+    ok: boolean;
+    task: CloudTaskV1 | null;
+    /** Plain sentence on refusal/failure. */
+    error: string | null;
+    failure: CloudLaunchFailureCode | null;
+}
+/** POST /api/verse/cloud/budget — any subset; validated and clamped. */
+export type CloudBudgetUpdate = Partial<Pick<CloudBudgetV1, 'creditsTotalUsd' | 'creditsSpentAdjustmentUsd' | 'estimatedCostPerSessionUsd' | 'maxConcurrent' | 'maxSessionsPerDay'>> & {
+    selfImprove?: Partial<CloudBudgetV1['selfImprove']>;
+};
+/** POST /api/verse/cloud/improve — launch up to `count` backlog items now. */
+export interface CloudImproveRequest {
+    count?: number;
+}
+export interface CloudImproveResponse {
+    launched: CloudTaskV1[];
+    skipped: Array<{
+        itemId: string;
+        reason: string;
+    }>;
+}

package/dist/core/cloud/types.js

@@ -0,0 +1,73 @@
+/**
+ * Cloud lane (3.11) — FROZEN CONTRACTS.
+ *
+ * Ashlr Verse launches Claude Code cloud sessions (claude.ai/code) that run on
+ * the operator's Claude account — including its cloud / usage credits once
+ * the subscription window is spent — and tracks what they deliver.
+ *
+ * How a launch works (verified 2026-09-24 against Claude Code 2.1.280):
+ *   - A NEW cloud session can only be created by the interactive CLI:
+ *     `claude --cloud "<task>"` (with `-p` it is refused). Run under a
+ *     pseudo-terminal it prints, then exits 0:
+ *         Created cloud session: <title>
+ *         View: https://claude.ai/code/session_<id>?from=cli&m=0
+ *         Resume with: claude --teleport session_<id>
+ *   - It must run as the `claude-a` seat's native-profile launcher, which is
+ *     signed in with a claude.ai account; API-key auth is refused ("cloud
+ *     sessions require authentication with a Claude.ai account").
+ *   - The session clones the cwd's `origin` GitHub repo at the cwd's CURRENT
+ *     branch, which must be pushed. The Claude GitHub app already has access
+ *     to ashlrai/*.
+ *   - Attaching to / reading an existing session from the CLI is NOT enabled
+ *     for this account, so Verse never reads a session back. Every task is
+ *     told to DELIVER to GitHub instead (see delivery-contract.ts): push
+ *     branch `ashlr-cloud/<taskId>` and open a DRAFT PR whose body carries a
+ *     fenced `ashlr-cloud-report` JSON block. Verse tracks tasks with `gh`.
+ *   - The credit balance is not readable (neither `/usage` nor the CLI show
+ *     it), so spend is an ESTIMATE the operator can calibrate; the UI always
+ *     says so and links to https://claude.ai/settings/usage.
+ *
+ * Nothing here merges. A cloud PR is judged and merged by the existing merge
+ * gates (custody) or by Mason — never by the cloud lane.
+ */
+export const CLOUD_TASK_SCHEMA_VERSION = 1;
+export const CLOUD_BUDGET_SCHEMA_VERSION = 1;
+/** Branch every cloud task delivers to: `ashlr-cloud/<taskId>`. */
+export const CLOUD_BRANCH_PREFIX = 'ashlr-cloud/';
+/** Fenced block language tag carrying the task report in the PR body. */
+export const CLOUD_REPORT_FENCE = 'ashlr-cloud-report';
+/** Draft PR title prefix, so tasks are recognisable in GitHub lists. */
+export const CLOUD_PR_TITLE_PREFIX = '[ashlr-cloud]';
+/** Where the real credit balance lives (not readable programmatically). */
+export const CLOUD_BALANCE_URL = 'https://claude.ai/settings/usage';
+/** The seat whose claude.ai login launches cloud sessions. */
+export const CLOUD_SEAT_ID = 'claude-a';
+/** A task with no PR after this long is marked `expired` (still linkable). */
+export const CLOUD_TASK_EXPIRY_MS = 6 * 60 * 60 * 1000;
+/** Max prompt length accepted from any entry point (chars). */
+export const CLOUD_PROMPT_MAX_CHARS = 20_000;
+/** Launch timeout for the PTY-wrapped CLI (creation took < 10 s in testing). */
+export const CLOUD_LAUNCH_TIMEOUT_MS = 90_000;
+/** Task ids look like `ct_20260924T2331_k3f9q2` (sortable, branch-safe). */
+export const CLOUD_TASK_ID_PATTERN = /^ct_\d{8}T\d{4}_[a-z0-9]{6}$/;
+export const CLOUD_TERMINAL_STATES = ['merged', 'closed', 'failed', 'expired'];
+export const DEFAULT_CLOUD_BUDGET = Object.freeze({
+    v: CLOUD_BUDGET_SCHEMA_VERSION,
+    creditsTotalUsd: 250,
+    creditsSpentAdjustmentUsd: 0,
+    estimatedCostPerSessionUsd: 3,
+    maxConcurrent: 4,
+    maxSessionsPerDay: 20,
+    selfImprove: Object.freeze({ enabled: true, repo: 'ashlrai/ashlr-hub', maxPerDay: 4, reserveUsd: 40 }),
+});
+// ---------------------------------------------------------------------------
+// HTTP contract — mounted as the 'cloud' module (verse-api.ts)
+// ---------------------------------------------------------------------------
+export const VERSE_CLOUD_PATH = '/api/verse/cloud';
+export const VERSE_CLOUD_LAUNCH_PATH = '/api/verse/cloud/launch';
+export const VERSE_CLOUD_BUDGET_PATH = '/api/verse/cloud/budget';
+export const VERSE_CLOUD_REFRESH_PATH = '/api/verse/cloud/refresh';
+export const VERSE_CLOUD_IMPROVE_PATH = '/api/verse/cloud/improve';
+/** POST `${VERSE_CLOUD_TASKS_PATH}/<id>/dismiss` */
+export const VERSE_CLOUD_TASKS_PATH = '/api/verse/cloud/tasks';
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/cloud/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAU,CAAC;AACpD,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAU,CAAC;AAEtD,mEAAmE;AACnE,MAAM,CAAC,MAAM,mBAAmB,GAAG,cAAuB,CAAC;AAC3D,yEAAyE;AACzE,MAAM,CAAC,MAAM,kBAAkB,GAAG,oBAA6B,CAAC;AAChE,wEAAwE;AACxE,MAAM,CAAC,MAAM,qBAAqB,GAAG,eAAwB,CAAC;AAC9D,2EAA2E;AAC3E,MAAM,CAAC,MAAM,iBAAiB,GAAG,kCAA2C,CAAC;AAC7E,8DAA8D;AAC9D,MAAM,CAAC,MAAM,aAAa,GAAG,UAAmB,CAAC;AACjD,8EAA8E;AAC9E,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AACvD,+DAA+D;AAC/D,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC;AAC7C,gFAAgF;AAChF,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC;AAE9C,4EAA4E;AAC5E,MAAM,CAAC,MAAM,qBAAqB,GAAG,8BAA8B,CAAC;AAkBpE,MAAM,CAAC,MAAM,qBAAqB,GAA8B,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;AA6F1G,MAAM,CAAC,MAAM,oBAAoB,GAAqC,MAAM,CAAC,MAAM,CAAC;IAClF,CAAC,EAAE,2BAA2B;IAC9B,eAAe,EAAE,GAAG;IACpB,yBAAyB,EAAE,CAAC;IAC5B,0BAA0B,EAAE,CAAC;IAC7B,aAAa,EAAE,CAAC;IAChB,iBAAiB,EAAE,EAAE;IACrB,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,mBAAmB,EAAE,SAAS,EAAE,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;CACvG,CAAqC,CAAC;AA+CvC,8EAA8E;AAC9E,+DAA+D;AAC/D,8EAA8E;AAE9E,MAAM,CAAC,MAAM,gBAAgB,GAAG,kBAA2B,CAAC;AAC5D,MAAM,CAAC,MAAM,uBAAuB,GAAG,yBAAkC,CAAC;AAC1E,MAAM,CAAC,MAAM,uBAAuB,GAAG,yBAAkC,CAAC;AAC1E,MAAM,CAAC,MAAM,wBAAwB,GAAG,0BAAmC,CAAC;AAC5E,MAAM,CAAC,MAAM,wBAAwB,GAAG,0BAAmC,CAAC;AAC5E,oDAAoD;AACpD,MAAM,CAAC,MAAM,sBAAsB,GAAG,wBAAiC,CAAC"}

package/dist/core/universe/builtins/preparation/manifest.json

@@ -1 +1 @@
-{"schemaVersion":1,"id":"preparation-measurement-v1","files":[{"name":"preparation-bridge.mjs","digest":"39d5d562ad8d097fcb69c83f0fa3c0bf22dd206af2470bec98d065cc8292f8ef"},{"name":"preparation-verification-activity.mjs","digest":"bf0eb9f5cc3f059b6ae2b4075ba5934103511c1eed3e3bed2e398d07ed4ac2cf"},{"name":"preparation-verification-child.mjs","digest":"f89798b6b43006c72e00f53a2fabea8b27c121d4f4a55e081783974851b0ef37"},{"name":"preparation-verification-controller.mjs","digest":"4c7e80cb73a7f3b6df7a40301544273e9d08cdb28ee4d904223ae4e029c873bf"},{"name":"preparation-verification-fixtures.mjs","digest":"60e71eb41bee6ed221744b4f19c5109b0a0ea8526174fe15121b59b976bf3d41"},{"name":"preparation-verification-native.mjs","digest":"f61520b2dc6d3fb6d7e99afc167865ecefd0bb548df307166c32e2cac4787a5c"},{"name":"preparation-verification-protocol.mjs","digest":"9b9664097862c2391d0d9c12060905517a285e1fb8862e079e880bcb2ebb56c6"},{"name":"preparation-verification-tool.mjs","digest":"5e42f135f463c13f777e2ceef6751fabd252a02c2c11266dac550f13713e33e3"},{"name":"preparation-verification.mjs","digest":"f228f7767bb21fc49deb44a69632a644a88ecd71e75d1d61a00d8ba278eebd97"}]}
+{"schemaVersion":1,"id":"preparation-measurement-v1","files":[{"name":"preparation-bridge.mjs","digest":"a152d75de89c59fc6af920a15661a7ce34a726fd655afc5c3ac0c38d7adbccd6"},{"name":"preparation-verification-activity.mjs","digest":"bf0eb9f5cc3f059b6ae2b4075ba5934103511c1eed3e3bed2e398d07ed4ac2cf"},{"name":"preparation-verification-child.mjs","digest":"f89798b6b43006c72e00f53a2fabea8b27c121d4f4a55e081783974851b0ef37"},{"name":"preparation-verification-controller.mjs","digest":"4c7e80cb73a7f3b6df7a40301544273e9d08cdb28ee4d904223ae4e029c873bf"},{"name":"preparation-verification-fixtures.mjs","digest":"929b69440637b4f6ce342a5b38cff2182da8e108dc8ab69daae4d4260a2475a6"},{"name":"preparation-verification-native.mjs","digest":"f61520b2dc6d3fb6d7e99afc167865ecefd0bb548df307166c32e2cac4787a5c"},{"name":"preparation-verification-protocol.mjs","digest":"9b9664097862c2391d0d9c12060905517a285e1fb8862e079e880bcb2ebb56c6"},{"name":"preparation-verification-tool.mjs","digest":"5e42f135f463c13f777e2ceef6751fabd252a02c2c11266dac550f13713e33e3"},{"name":"preparation-verification.mjs","digest":"f228f7767bb21fc49deb44a69632a644a88ecd71e75d1d61a00d8ba278eebd97"}]}