@skrr-ai/cli 0.1.91 → 0.1.93

package/dist/lib/dedicated-power.js

@@ -4,9 +4,15 @@ exports.setDedicatedPowerPolicy = setDedicatedPowerPolicy;
 exports.describePolicyWords = describePolicyWords;
 exports.describePowerPolicy = describePowerPolicy;
 exports.getDedicatedPowerSummary = getDedicatedPowerSummary;
+exports.getDedicatedWaitingWork = getDedicatedWaitingWork;
+exports.describeWaitingWork = describeWaitingWork;
+exports.describeLastWakeTiming = describeLastWakeTiming;
+exports.describeOnDemandAvailability = describeOnDemandAvailability;
+exports.describePrewarm = describePrewarm;
 exports.describePowerDecisionLines = describePowerDecisionLines;
 exports.describeLastAutoStopLines = describeLastAutoStopLines;
 exports.describeLastWakeDecisionLines = describeLastWakeDecisionLines;
+exports.describePendingStopLines = describePendingStopLines;
 exports.describePowerSummary = describePowerSummary;
 exports.describePowerExplanation = describePowerExplanation;
 exports.describeBudget = describeBudget;
@@ -45,7 +51,7 @@ async function setDedicatedPowerPolicy(leaseId, request, scope = {}) {
             return {
                 ok: false,
                 refusal: {
-                    error: String(body.error ?? 'on_demand is not available for this machine yet.'),
+                    error: String(body.error ?? 'On demand is not available for this machine yet.'),
                     code: 'ON_DEMAND_INELIGIBLE',
                     reason: reason,
                     detail: String(body.detail ?? copy?.detail ?? ''),
@@ -83,11 +89,126 @@ function describePowerPolicy(power, autoStopMode) {
 function getDedicatedPowerSummary(leaseId, scope = {}) {
     return (0, api_fetch_1.apiFetch)((0, dedicated_machines_1.withDedicatedScope)(`/api/machines/dedicated/${encodeURIComponent(leaseId)}/power`, scope));
 }
+/** `GET /api/machines/dedicated/:leaseId/power/waiting` — work waiting for this machine. */
+function getDedicatedWaitingWork(leaseId, scope = {}) {
+    return (0, api_fetch_1.apiFetch)((0, dedicated_machines_1.withDedicatedScope)(`/api/machines/dedicated/${encodeURIComponent(leaseId)}/power/waiting`, scope));
+}
+const WAITING_SOURCE_LABELS = {
+    dispatch_intent: 'just dispatched',
+    parked_fire: 'parked trigger fire',
+    parked_run: 'parked run',
+    queued_run: 'queued run',
+    agent_queued_run: 'queued run (agent)',
+    expected_firing: 'expected firing',
+};
+/** The lines of `power waiting`. An unreadable source is said, never folded into "nothing waiting". */
+function describeWaitingWork(waiting, when = {}) {
+    const lines = [`Dedicated Runtime ${waiting.leaseId} (${waiting.state})`];
+    if (waiting.items.length === 0 && waiting.unreadable.length === 0) {
+        lines.push('Waiting work: none');
+    }
+    else {
+        lines.push(waiting.items.length === 0
+            ? 'Waiting work: none seen'
+            : `Waiting work: ${waiting.items.length} item${waiting.items.length === 1 ? '' : 's'}`);
+        for (const item of waiting.items) {
+            const label = WAITING_SOURCE_LABELS[item.source] ?? item.source;
+            lines.push(`  - ${label} ${item.ref}${item.since ? ` · since ${(0, format_1.formatWhen)(item.since, when)}` : ''}`);
+            if (item.detail)
+                lines.push(`    ${item.detail}`);
+        }
+    }
+    if (waiting.truncated.length > 0) {
+        lines.push(`More exists than is listed (${waiting.truncated.join(', ')}).`);
+    }
+    for (const u of waiting.unreadable) {
+        lines.push(`Cannot see ${u.source} (${u.reason}) — treat the list as incomplete.`);
+    }
+    const up = waiting.upcoming;
+    if (up) {
+        if (up.items.length > 0) {
+            lines.push(`Scheduled to fire: ${up.items.length}${up.truncated ? '+' : ''}`);
+            for (const f of up.items) {
+                lines.push(`  - ${f.source} ${f.title ?? f.ref}${f.at ? ` · ${(0, format_1.formatWhen)(f.at, when)}` : ''}`);
+            }
+        }
+        else if (up.unreadable.length === 0) {
+            lines.push('Scheduled to fire: none');
+        }
+        else {
+            lines.push('Scheduled to fire: none seen');
+        }
+        if (up.overdue > 0) {
+            lines.push(`${up.overdue} overdue firing${up.overdue === 1 ? '' : 's'} not yet fired.`);
+        }
+        for (const u of up.unreadable) {
+            lines.push(`Cannot see ${u.source} (${u.reason}) — scheduled firings may be missing.`);
+        }
+    }
+    if (waiting.state === 'stopped' && waiting.items.length > 0) {
+        lines.push('The machine is stopped. `skrr machines dedicated start <lease> --wait` starts it; work on an on_demand machine wakes it by itself.');
+    }
+    return lines;
+}
+const PHASE_ORDER = [
+    'start_requested',
+    'provider_start_accepted',
+    'instance_running',
+    'daemon_connected',
+    'first_heartbeat',
+    'assignable',
+];
+function formatMs(ms) {
+    return ms >= 1000 ? `${Math.round(ms / 100) / 10}s` : `${Math.round(ms)}ms`;
+}
+/** Last wake timing. A wake that never became assignable shows the phases it reached and no latency. */
+function describeLastWakeTiming(wake) {
+    if (!wake)
+        return [];
+    const known = Object.keys(wake.phases ?? {});
+    const names = [
+        ...PHASE_ORDER.filter((p) => known.includes(p)),
+        ...known.filter((p) => !PHASE_ORDER.includes(p)),
+    ].filter((p) => p !== 'start_requested');
+    const phases = names.map((p) => `${p} +${formatMs(wake.phases[p])}`).join(', ');
+    const total = wake.latencyMs === null || wake.latencyMs === undefined
+        ? 'not ready yet (no latency recorded)'
+        : `ready after ${formatMs(wake.latencyMs)}`;
+    return [`Wake timing: ${total}${phases ? ` — ${phases}` : ''}`];
+}
+/** on_demand availability, so a plan does not need a failed `power set` to find out. */
+function describeOnDemandAvailability(onDemand) {
+    if (!onDemand)
+        return [];
+    if (onDemand.eligible)
+        return ['on_demand: available'];
+    return [
+        `on_demand: not available (${onDemand.reason})`,
+        `          ${onDemand.detail}`,
+        `          Fix: ${onDemand.fix}`,
+    ];
+}
+/** Pre-warm lines: only a PAUSED pre-warm is in the summary, so silence here is not "pre-warm is on". */
+function describePrewarm(prewarm, when = {}) {
+    if (!prewarm?.paused)
+        return [];
+    const lines = [
+        `Pre-warm: paused${prewarm.since ? ` since ${(0, format_1.formatWhen)(prewarm.since, when)}` : ''} (${prewarm.idleStreak} early start${prewarm.idleStreak === 1 ? '' : 's'} in a row went unused)`,
+    ];
+    if (prewarm.decision?.detail)
+        lines.push(`          ${prewarm.decision.detail}`);
+    if (prewarm.decision?.fix)
+        lines.push(`          ${prewarm.decision.fix}`);
+    return lines;
+}
 /** The stay/stop/wake decision in words: the shared reason copy backs the server's detail. */
 function describePowerDecisionLines(decision) {
     const copy = (0, data_provider_1.describePowerReason)(decision.reason);
     const VERBS = { stay: 'Staying on', stop: 'Stopped', wake: 'Wake' };
-    const verb = VERBS[decision.question] ?? decision.question;
+    // `stop_scheduled` answers the stop question for a machine that is still running.
+    const verb = decision.reason === 'stop_scheduled'
+        ? 'Scheduled to stop'
+        : (VERBS[decision.question] ?? decision.question);
     return {
         // The headline is the human label only; the reason token lives in `--json` and `power explain`.
         // With no shared copy and no server detail there is no sentence, so the token is the last resort.
@@ -158,6 +279,28 @@ function describeLastWakeDecisionLines(wake, when = {}) {
         lines.push(`          ${wake.fix}`);
     return lines;
 }
+/** What the Keep awake offered by the stop notice means in the CLI: two hours. */
+const PENDING_STOP_KEEP_AWAKE_HOURS = 2;
+/**
+ * The announced-but-not-yet-done stop, in the shared words (`describePendingStop`). Empty when the
+ * summary carries none, which is also what an older server sends: absent is not "no stop coming".
+ */
+function describePendingStopLines(summary, when = {}) {
+    const pending = summary.pendingStop;
+    if (!pending)
+        return [];
+    const words = (0, data_provider_1.describePendingStop)(pending, {
+        nowMs: (when.now ?? new Date()).getTime(),
+        when: (0, format_1.formatWhen)(pending.stopsAt, when),
+        capWhen: pending.unreachableStopsAt ? (0, format_1.formatWhen)(pending.unreachableStopsAt, when) : null,
+        keepAwakeHours: PENDING_STOP_KEEP_AWAKE_HOURS,
+    });
+    const lines = [`Stop:     ${words.headline}`];
+    if (words.detail)
+        lines.push(`          ${words.detail}`);
+    lines.push(`          ${words.fix} skrr machines dedicated power keep-awake ${summary.leaseId} --for ${PENDING_STOP_KEEP_AWAKE_HOURS}h`);
+    return lines;
+}
 /** The lines of `power show`. */
 function describePowerSummary(summary, when = {}) {
     const { power } = summary;
@@ -186,6 +329,7 @@ function describePowerSummary(summary, when = {}) {
             lines.push('Decision: nothing to explain for this state');
         }
     }
+    lines.push(...describePendingStopLines(summary, when));
     lines.push(...describeLastAutoStopLines(summary.lastAutoStop, summary.decision?.detail, when).lines);
     lines.push(...describeLastWakeDecisionLines(summary.lastWakeDecision, when));
     if (summary.holders === null) {
@@ -205,6 +349,10 @@ function describePowerSummary(summary, when = {}) {
     lines.push(`Last wake: ${summary.lastWake
         ? `${summary.lastWake.at ? (0, format_1.formatWhen)(summary.lastWake.at, when) : 'unknown time'}${summary.lastWake.source ? ` (${summary.lastWake.source})` : ''}`
         : 'none'}`);
+    lines.push(...describeLastWakeTiming(summary.lastWake));
+    lines.push(...describePrewarm(summary.prewarm, when));
+    if (power.policy !== 'on_demand')
+        lines.push(...describeOnDemandAvailability(summary.onDemand));
     return lines;
 }
 /** The lines of `power explain`; the fix is always last. */
@@ -226,9 +374,12 @@ function describePowerExplanation(summary, when = {}) {
         lines.push(`At:       ${(0, format_1.formatWhen)(d.at, when)}`);
     if (text.detail)
         lines.push(`Detail:   ${text.detail}`);
+    lines.push(...describePendingStopLines(summary, when));
     const stop = describeLastAutoStopLines(summary.lastAutoStop, d.detail, when);
     lines.push(...stop.lines);
     lines.push(...wakeLines);
+    lines.push(...describeLastWakeTiming(summary.lastWake));
+    lines.push(...describePrewarm(summary.prewarm, when));
     // A false stop's fix replaces nothing: the decision's own fix is still last-but-one.
     if (text.fix && text.fix !== stop.fix)
         lines.push(`Fix: ${text.fix}`);

package/dist/lib/dry-run-plans.d.ts

@@ -0,0 +1,50 @@
+type Row = Record<string, unknown>;
+export type ProjectAction = 'archive' | 'unarchive' | 'delete';
+export declare function planProjectChange(action: ProjectAction, project: Row, projectRef: string): {
+    object: string;
+    source: string;
+    ok: boolean;
+    action: ProjectAction;
+    project: {
+        id: unknown;
+        ref: {};
+        title: unknown;
+        archived: boolean;
+    };
+    changes: {
+        deletesProject: boolean;
+        detachedTasksEstimate: number | null;
+        reversible: boolean;
+        archived?: undefined;
+    } | {
+        archived: boolean;
+        reversible: boolean;
+        deletesProject?: undefined;
+        detachedTasksEstimate?: undefined;
+    };
+    errors: string[];
+    notes: string[];
+};
+export type BulkUpdateInput = {
+    id: string;
+    patch: Row;
+};
+export declare function planBulkUpdate(updates: BulkUpdateInput[], currentById: Record<string, Row | null | undefined>, failedReads?: Record<string, string>): {
+    object: string;
+    source: string;
+    ok: boolean;
+    requested: number;
+    wouldChange: number;
+    invalid: number;
+    results: {
+        id: string;
+        ok: boolean;
+        changes: Record<string, {
+            from: unknown;
+            to: unknown;
+        }>;
+        noop: boolean;
+        errors: string[];
+    }[];
+};
+export {};

package/dist/lib/dry-run-plans.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planProjectChange = planProjectChange;
+exports.planBulkUpdate = planBulkUpdate;
+/**
+ * Client-side validated previews for `--dry-run` (audit P5).
+ *
+ * Each plan is built from READS only (a GET of the current row) and answers three
+ * things a caller needs before a destructive call: would it be accepted, what
+ * would change, and what is the blast radius. It is a preview, not a promise:
+ * the real call re-validates server-side, and a concurrent writer can still
+ * change the outcome. Where the server has no validate-only path the plan says
+ * `source: 'client_preview'` so nobody mistakes it for one.
+ */
+const data_provider_1 = require("@skrr-ai/data-provider");
+function planProjectChange(action, project, projectRef) {
+    const archived = Boolean(project.archivedAt);
+    const taskCounts = (project.taskCounts ?? {});
+    const errors = [];
+    const notes = [];
+    if (action === 'archive' && archived)
+        notes.push('Already archived; archiving again is a no-op.');
+    if (action === 'unarchive' && !archived)
+        notes.push('Not archived; unarchiving is a no-op.');
+    return {
+        object: 'project_change_dry_run',
+        source: 'client_preview',
+        ok: errors.length === 0,
+        action,
+        project: {
+            id: project.id,
+            ref: project.identifier ?? projectRef,
+            title: project.title,
+            archived,
+        },
+        changes: action === 'delete'
+            ? {
+                deletesProject: true,
+                // Member tasks are detached, never deleted (invariant P3).
+                detachedTasksEstimate: taskCounts.total ?? null,
+                reversible: false,
+            }
+            : { archived: action === 'archive', reversible: true },
+        errors,
+        notes,
+    };
+}
+function planBulkUpdate(updates, currentById, failedReads = {}) {
+    const rows = updates.map(({ id, patch }) => {
+        const errors = [];
+        const current = currentById[id];
+        if (failedReads[id])
+            errors.push(`could not read task: ${failedReads[id]}`);
+        else if (!current)
+            errors.push('task not found');
+        const status = patch.status;
+        if (status !== undefined && !data_provider_1.TASK_STATUSES.includes(status)) {
+            errors.push(`status must be one of: ${data_provider_1.TASK_STATUSES.join(', ')}`);
+        }
+        const changes = {};
+        for (const [field, to] of Object.entries(patch)) {
+            if (to === undefined)
+                continue;
+            const from = current?.[field];
+            if (JSON.stringify(from) !== JSON.stringify(to))
+                changes[field] = { from, to };
+        }
+        return {
+            id,
+            ok: errors.length === 0,
+            changes,
+            noop: errors.length === 0 && Object.keys(changes).length === 0,
+            errors,
+        };
+    });
+    return {
+        object: 'task_bulk_update_dry_run',
+        source: 'client_preview',
+        ok: rows.every((r) => r.ok),
+        requested: rows.length,
+        wouldChange: rows.filter((r) => r.ok && !r.noop).length,
+        invalid: rows.filter((r) => !r.ok).length,
+        results: rows,
+    };
+}

package/dist/lib/json-output.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Storage-field stripping for `--json` output (audit P9).
+ *
+ * The API returns Mongo documents, so every row carries `_id` and `__v` beside
+ * the real `id`: 47 keys per task row, two of which are storage detail an agent
+ * pays tokens for and can mistake for the identifier (OSK-12205 was exactly
+ * that: a 24-hex `_id` passed where a task id was wanted).
+ *
+ * This runs at the CLI SERIALIZER only (`BaseCommand.log`), never in the API or
+ * the data layer, so no other consumer's payload changes. `--raw` (or
+ * `OVERSKY_CLI_RAW=1`) turns it off for the caller that does want them.
+ *
+ * Two rules, both conservative:
+ *   - `__v` is the Mongoose version key and is always dropped.
+ *   - `_id` is dropped only when the same object has a usable `id`. A row that
+ *     has ONLY `_id` (some legacy collections) keeps it: removing the sole
+ *     identifier would turn a cosmetic cleanup into data loss.
+ */
+type Json = unknown;
+/**
+ * Returns the SAME reference when nothing needed stripping, so a caller can tell
+ * "unchanged" apart from "rebuilt" and leave the original text alone.
+ */
+export declare function stripStorageFields(value: Json): Json;
+/**
+ * Apply {@link stripStorageFields} to one line of CLI output. Anything that is
+ * not a JSON object/array (prose, a bare string, malformed text) is returned
+ * untouched, as is JSON with nothing to strip, so existing formatting survives.
+ */
+export declare function stripStorageFieldsFromText(text: string): string;
+export {};

package/dist/lib/json-output.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * Storage-field stripping for `--json` output (audit P9).
+ *
+ * The API returns Mongo documents, so every row carries `_id` and `__v` beside
+ * the real `id`: 47 keys per task row, two of which are storage detail an agent
+ * pays tokens for and can mistake for the identifier (OSK-12205 was exactly
+ * that: a 24-hex `_id` passed where a task id was wanted).
+ *
+ * This runs at the CLI SERIALIZER only (`BaseCommand.log`), never in the API or
+ * the data layer, so no other consumer's payload changes. `--raw` (or
+ * `OVERSKY_CLI_RAW=1`) turns it off for the caller that does want them.
+ *
+ * Two rules, both conservative:
+ *   - `__v` is the Mongoose version key and is always dropped.
+ *   - `_id` is dropped only when the same object has a usable `id`. A row that
+ *     has ONLY `_id` (some legacy collections) keeps it: removing the sole
+ *     identifier would turn a cosmetic cleanup into data loss.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripStorageFields = stripStorageFields;
+exports.stripStorageFieldsFromText = stripStorageFieldsFromText;
+function usableId(value) {
+    return (typeof value === 'string' && value.length > 0) || typeof value === 'number';
+}
+/**
+ * Returns the SAME reference when nothing needed stripping, so a caller can tell
+ * "unchanged" apart from "rebuilt" and leave the original text alone.
+ */
+function stripStorageFields(value) {
+    if (Array.isArray(value)) {
+        let changed = false;
+        const next = value.map((item) => {
+            const stripped = stripStorageFields(item);
+            if (stripped !== item)
+                changed = true;
+            return stripped;
+        });
+        return changed ? next : value;
+    }
+    if (value === null || typeof value !== 'object')
+        return value;
+    const source = value;
+    const dropId = '_id' in source && usableId(source.id);
+    const dropVersion = '__v' in source;
+    let changed = dropId || dropVersion;
+    const next = {};
+    for (const [key, child] of Object.entries(source)) {
+        if ((key === '_id' && dropId) || (key === '__v' && dropVersion))
+            continue;
+        const stripped = stripStorageFields(child);
+        if (stripped !== child)
+            changed = true;
+        next[key] = stripped;
+    }
+    return changed ? next : value;
+}
+/**
+ * Apply {@link stripStorageFields} to one line of CLI output. Anything that is
+ * not a JSON object/array (prose, a bare string, malformed text) is returned
+ * untouched, as is JSON with nothing to strip, so existing formatting survives.
+ */
+function stripStorageFieldsFromText(text) {
+    const head = text.trimStart()[0];
+    if (head !== '{' && head !== '[')
+        return text;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+    const stripped = stripStorageFields(parsed);
+    if (stripped === parsed)
+        return text;
+    return JSON.stringify(stripped, null, text.includes('\n') ? 2 : undefined);
+}

package/dist/lib/list-output.d.ts

@@ -0,0 +1,75 @@
+export type ListWarning = {
+    code: string;
+    value?: unknown;
+    hint: string;
+};
+export type ListEnvelope = {
+    object: 'list';
+    data: Array<Record<string, unknown>>;
+    has_more: boolean;
+    next_cursor: string | null;
+    limit_applied?: number;
+    warnings?: ListWarning[];
+} & Record<string, unknown>;
+/**
+ * The navigation projection per resource: enough to identify a row, decide
+ * whether it matters and fetch it with `show`. Allowlists, not drop-lists, so a
+ * field the server adds tomorrow does not silently re-inflate every compact row.
+ * Documented in docs/cli/SKRR_TASKS.md (List output for agents).
+ */
+export declare const COMPACT_FIELDS: {
+    readonly task: readonly ["id", "identifier", "ref", "title", "status", "statusType", "priority", "estimate", "assigneeAgentIds", "assigneeUserIds", "parentId", "spaceId", "projectId", "goalId", "dueDate", "scheduledFor", "labelIds", "tags", "externalKey", "version", "executionMode", "nextAction", "createdAt", "updatedAt", "url"];
+    readonly space: readonly ["id", "identifier", "title", "status", "parentSpaceId", "leadAgentId", "labelIds", "archivedAt", "createdAt", "updatedAt", "url"];
+    readonly project: readonly ["id", "identifier", "title", "spaceId", "externalKey", "taskCounts", "archivedAt", "createdAt", "updatedAt", "url"];
+};
+export type ListResource = keyof typeof COMPACT_FIELDS;
+/** The three flags every projecting list command declares. */
+export declare const listOutputFlags: {
+    fields: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    compact: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    ndjson: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+};
+export type ListOutputFlags = {
+    fields?: string;
+    compact?: boolean;
+    ndjson?: boolean;
+};
+/** `--fields a, b ,c` -> ['a','b','c']; empty/blank -> undefined. */
+export declare function parseFields(raw: string | undefined): string[] | undefined;
+export declare function projectRow(row: Record<string, unknown>, fields: readonly string[]): Record<string, unknown>;
+/**
+ * Normalize any list response to the shared envelope. `data` is where rows live
+ * for every list command; `projects` (an older serialization) is folded into it.
+ * A response that is not list-shaped is returned untouched (never invent rows).
+ */
+export declare function toListEnvelope(response: unknown): ListEnvelope | undefined;
+export type ShapeListOptions = ListOutputFlags & {
+    resource: ListResource;
+    /** What the caller asked for with --limit (undefined when the command has none). */
+    requestedLimit?: number;
+    warnings?: ListWarning[];
+    /** A filter the CLI applied that the caller did not ask for (E12). Echoed as `filter_applied`. */
+    filterApplied?: Record<string, unknown>;
+};
+/** Pure: envelope + projection + notes. Returns the response untouched if not a list. */
+export declare function shapeListResponse(response: unknown, options: ShapeListOptions): unknown;
+/**
+ * E11: the server silently clamps `--limit` (cap) and coerces `0` to its default.
+ * Echo what was applied. `applied` is only reported when we can prove it: a full
+ * page that still has more rows means the cap is exactly the row count.
+ */
+export declare function limitNote(requested: number | undefined, rowCount: number, hasMore: boolean): {
+    applied?: number;
+    warning?: ListWarning;
+};
+/** The text-mode twin of a warning: one `Note:` line a person can act on. */
+export declare function warningLines(warnings: readonly ListWarning[] | undefined): string[];
+export type ListOutput = {
+    stdout: string[];
+    stderr: string[];
+};
+/**
+ * Render a shaped list for `--json` (pretty envelope) or `--ndjson` (rows one per
+ * line, `_meta` on stderr). Pure; the caller writes the lines.
+ */
+export declare function renderListOutput(shaped: unknown, ndjson: boolean): ListOutput;