@skrr-ai/cli 0.1.127 → 0.1.128

package/dist/lib/compasses.js

@@ -2,9 +2,17 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.compassApi = exports.COMPASS_STATUSES = void 0;
 exports.renderCompassList = renderCompassList;
+exports.describeSettings = describeSettings;
+exports.describeQuietHours = describeQuietHours;
+exports.describeMode = describeMode;
 exports.renderCompass = renderCompass;
+exports.describeBoundCommitments = describeBoundCommitments;
+exports.renderTacticResult = renderTacticResult;
+exports.renderEffectivePolicy = renderEffectivePolicy;
 exports.renderRevisionList = renderRevisionList;
 exports.renderCompassTrace = renderCompassTrace;
+exports.revisionTypeLabel = revisionTypeLabel;
+exports.renderRevertResult = renderRevertResult;
 const data_provider_1 = require("@skrr-ai/data-provider");
 /**
  * compasses.ts — request-based client for `/api/compasses`.
@@ -79,6 +87,76 @@ function renderCompassList(rows, log) {
         { key: 'updated', header: 'UPDATED' },
     ], log);
 }
+function scalar(value) {
+    if (value === null || value === undefined)
+        return 'none';
+    return typeof value === 'object' ? JSON.stringify(value) : String(value);
+}
+/**
+ * One setting per line (`key: value`, nested objects as dotted keys, lists joined with `;`), so a
+ * settings object reads as labelled lines rather than one JSON blob (OSK-21150).
+ */
+function describeSettings(value, prefix = '') {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return [];
+    const lines = [];
+    for (const [key, entry] of Object.entries(value)) {
+        if (entry && typeof entry === 'object' && !Array.isArray(entry)) {
+            lines.push(...describeSettings(entry, `${prefix}${key}.`));
+        }
+        else if (Array.isArray(entry)) {
+            lines.push(`${prefix}${key}: ${entry.map(scalar).join('; ') || 'none'}`);
+        }
+        else {
+            lines.push(`${prefix}${key}: ${scalar(entry)}`);
+        }
+    }
+    return lines;
+}
+/** A quiet-hours window in words: the hours and the zone, `off`, or `not set`. */
+function describeQuietHours(window) {
+    if (!window || typeof window !== 'object' || Array.isArray(window))
+        return 'not set';
+    const w = window;
+    if (w.enabled !== true)
+        return 'off';
+    const zone = typeof w.timezone === 'string' && w.timezone.trim() ? w.timezone.trim() : 'UTC (no zone set)';
+    return `${scalar(w.start ?? '?')} to ${scalar(w.end ?? '?')} ${zone}`;
+}
+/**
+ * The mode, and the word the author wrote when it differs from it. The server stores `auto` as
+ * `auto_run_limited`; saying so beats showing a value nobody typed as if they had (OSK-21150).
+ */
+function describeMode(mode, authoredMode) {
+    const normalized = typeof mode === 'string' && mode ? mode : null;
+    const authored = typeof authoredMode === 'string' && authoredMode ? authoredMode : null;
+    if (!normalized) {
+        return authored
+            ? `not set (${JSON.stringify(authored)} is not a mode the platform knows)`
+            : 'not set (the platform default applies)';
+    }
+    return authored && authored !== normalized
+        ? `${normalized} (normalized; you wrote ${JSON.stringify(authored)})`
+        : normalized;
+}
+const SOURCE_WORDS = {
+    authored: 'the author',
+    derived: 'nobody (a default the platform derived)',
+};
+function labelled(label, lines, log, width = 12) {
+    lines.forEach((line, index) => log(`${index === 0 ? label.padEnd(width) : ' '.repeat(width)}${line}`));
+}
+/** The stored autonomy defaults, as the lines `show` prints (no JSON). */
+function autonomyLines(autonomy) {
+    const { mode, authoredMode, modeSource, quietHours, ...rest } = autonomy;
+    const source = typeof modeSource === 'string' ? (SOURCE_WORDS[modeSource] ?? modeSource) : undefined;
+    const out = [];
+    const modeLine = `${describeMode(mode, authoredMode)}${source ? `; set by ${source}` : ''}`;
+    out.push(['Autonomy', [modeLine, ...describeSettings(rest)]]);
+    if (quietHours !== undefined)
+        out.push(['Quiet hours', [describeQuietHours(quietHours)]]);
+    return out;
+}
 function renderCompass(compass, log) {
     log(`${compass.title ?? '(untitled compass)'}  (${compass.id})`);
     log(`Agent       ${compass.agentId}`);
@@ -86,12 +164,13 @@ function renderCompass(compass, log) {
     if (compass.domain)
         log(`Domain      ${compass.domain}`);
     if (compass.scope)
-        log(`Scope       ${JSON.stringify(compass.scope)}`);
+        labelled('Scope', describeSettings(compass.scope), log);
     if (compass.autonomyDefaults) {
-        log(`Autonomy    ${JSON.stringify(compass.autonomyDefaults)}`);
+        for (const [label, lines] of autonomyLines(compass.autonomyDefaults))
+            labelled(label, lines, log);
     }
     if (compass.communicationDefaults) {
-        log(`Comms       ${JSON.stringify(compass.communicationDefaults)}`);
+        labelled('Comms', describeSettings(compass.communicationDefaults), log);
     }
     const rules = compass.rules ?? [];
     if (rules.length) {
@@ -126,6 +205,13 @@ function renderCompass(compass, log) {
             if (target.successMetrics?.length) {
                 log(`    measured by: ${target.successMetrics.join('; ')}`);
             }
+            // Tactics live on a target, not on the compass; they used to be printed nowhere.
+            if (target.learnedTactics?.length) {
+                log(`    learned tactics (${target.learnedTactics.length}):`);
+                for (const tactic of target.learnedTactics) {
+                    log(`      • ${tactic.id ?? '—'}: ${tactic.description ?? '—'}`);
+                }
+            }
             // The agent's prompt carries a bounded number of each list. Say which
             // were cut, so the list above is not read as what the agent sees.
             for (const overflow of (0, data_provider_1.describeCompassOverflow)(target)) {
@@ -133,17 +219,103 @@ function renderCompass(compass, log) {
             }
         }
     }
-    const tactics = compass.learnedTactics ?? [];
-    if (tactics.length) {
-        log('');
-        log(`Learned tactics (${tactics.length}):`);
-        for (const tactic of tactics)
-            log(`  • ${tactic.description ?? '—'}`);
-    }
     const commitments = compass.commitments ?? [];
     if (commitments.length) {
         log('');
-        log(`Commitments governed by this compass: ${commitments.length}`);
+        log(describeBoundCommitments(commitments.length, compass.status));
+    }
+}
+/**
+ * How many Commitments are bound to a Compass, and whether it governs them. A Commitment stays
+ * bound to an archived Compass but runs on defaults: the platform reads only an ACTIVE Compass's
+ * direction. "Governed by this compass: 1" printed the same words for both, on the Compass side,
+ * while the Commitment's own preflight said it was running on defaults (OSK-21242).
+ */
+function describeBoundCommitments(count, status) {
+    return status === 'archived'
+        ? `Commitments bound to this compass: ${count} (not governed while the compass is archived)`
+        : `Commitments governed by this compass: ${count}`;
+}
+/**
+ * What `compass tactic` says back. Three outcomes, each in its own words: it used to print
+ * "Appended" for all of them, with a count that was always 0, and name nothing that rolled off.
+ * A server that does not report `tactic` is not guessed at.
+ */
+function renderTacticResult(compass, log) {
+    const tactic = compass.tactic;
+    if (!tactic) {
+        log(`Recorded. ${compass.id} is now v${compass.version}. This server did not report what changed; ` +
+            'run `compass show` to see the learned tactics.');
+        return;
+    }
+    const where = tactic.targetInvariantId ? `invariant ${tactic.targetInvariantId}` : 'its target';
+    const carries = `${compass.id} now carries ${tactic.count} learned tactic(s) on ${where}`;
+    if (tactic.outcome === 'unchanged') {
+        log(`No change — tactic already recorded. ${tactic.id} already reads that way on ${where}; ` +
+            `${compass.id} stays at v${compass.version}.`);
+    }
+    else if (tactic.outcome === 'updated') {
+        log(`Updated. ${tactic.id} on ${where} has the new text. ${carries} (v${compass.version}).`);
+    }
+    else {
+        log(`Appended. ${tactic.id} filed under ${where}. ${carries} (v${compass.version}).`);
+    }
+    for (const dropped of tactic.dropped ?? []) {
+        log(`Rolled off to stay within the cap: ${dropped.id} — "${dropped.description}"`);
+    }
+}
+const record = (value) => value && typeof value === 'object' && !Array.isArray(value)
+    ? value
+    : {};
+/**
+ * `compass effective-policy` in words (OSK-21150): the mode beside what was written when they
+ * differ, who chose it, the quiet hours that apply (or why none do), the communication defaults, and
+ * where each field came from. It used to print each of those as one JSON line, with a null mode and
+ * "derived" unexplained. `--json` is unchanged.
+ */
+function renderEffectivePolicy(policy, log) {
+    log(`Compass ${scalar(policy.compassId)}, revision ${scalar(policy.compassVersion)}: ${scalar(policy.status)}`);
+    log(`Applies to runtime: ${policy.appliesToRuntime === true ? 'yes' : 'no'}`);
+    const autonomy = record(policy.autonomy);
+    log('Autonomy');
+    const source = typeof autonomy.modeSource === 'string' ? autonomy.modeSource : undefined;
+    labelled('  Mode', [describeMode(autonomy.mode, autonomy.authoredMode)], log, 16);
+    if (source)
+        labelled('  Mode set by', [SOURCE_WORDS[source] ?? source], log, 16);
+    const applied = autonomy.quietHours;
+    const configured = autonomy.configuredQuietHours;
+    const issues = Array.isArray(autonomy.quietHoursIssues) ? autonomy.quietHoursIssues : [];
+    labelled('  Quiet hours', [
+        applied
+            ? describeQuietHours(applied)
+            : configured
+                ? `not applied (stored: ${describeQuietHours(configured)})`
+                : 'not set',
+    ], log, 16);
+    for (const issue of issues) {
+        const message = record(issue).message;
+        if (typeof message === 'string')
+            log(`  ! ${message} Quiet hours do not apply until this is fixed.`);
+    }
+    const communication = describeSettings(policy.communication);
+    log('Communication');
+    if (communication.length === 0)
+        log('  nothing set');
+    for (const line of communication)
+        log(`  ${line}`);
+    log(`Authority: ${scalar(policy.authority ?? 'unknown')}`);
+    const bySource = new Map();
+    for (const [path, entry] of Object.entries(record(policy.fieldProvenance))) {
+        const from = scalar(record(entry).source ?? 'unknown');
+        bySource.set(from, [...(bySource.get(from) ?? []), path]);
+    }
+    if (bySource.size === 0) {
+        log('Field provenance: none (no defaults are set)');
+    }
+    else {
+        log('Field provenance:');
+        for (const [from, paths] of bySource)
+            log(`  ${from}: ${paths.join(', ')}`);
     }
 }
 function renderRevisionList(rows, log) {
@@ -153,7 +325,7 @@ function renderRevisionList(rows, log) {
     }
     (0, format_1.renderTable)(rows.map((row) => ({
         revision: `v${row.revision}`,
-        type: row.revisionType ?? '—',
+        type: revisionTypeLabel(row),
         when: shortDate(row.createdAt),
         actor: row.actorUserId ?? '—',
         reason: row.reason ?? '—',
@@ -194,3 +366,51 @@ function renderCompassTrace(trace, log) {
     if (trace.has_more)
         log('More events exist; request a larger --limit (up to 500).');
 }
+/**
+ * The ledger's name for a row. A revert is stored as `auto_revert`, which reads as something the
+ * platform did on its own, so a person's `compass revert` is shown as `revert`, with the versions
+ * it moved between: `from v6 → v2` is the version it was at and the version whose content it took.
+ * Display only: the stored enum is unchanged.
+ */
+function revisionTypeLabel(row) {
+    // Reviving an archived compass has no ledger type of its own (the stored enum has no member for it),
+    // so it was recorded and shown as a plain `update`, indistinguishable from an edit. Each revision
+    // carries the status before and after (`status` is one of the captured config fields), so the
+    // lifecycle act is read from that; display only, the stored type is unchanged (OSK-21244).
+    if (row.revisionType === 'update' &&
+        row.previousConfig?.status === 'archived' &&
+        row.nextConfig?.status === 'active') {
+        return 'reactivate';
+    }
+    if (row.revisionType !== 'auto_revert')
+        return row.revisionType ?? '—';
+    const { fromVersion, toVersion } = row.metadata?.autoRevert ?? {};
+    return fromVersion !== undefined && toVersion !== undefined
+        ? `revert from v${fromVersion} → v${toVersion}`
+        : 'revert';
+}
+/**
+ * What `compass revert` says after it ran. Three things the old one-liner left out: whether
+ * anything was written, that the status is whatever it was (a revert never changes lifecycle), and
+ * which enforced rules the restored version no longer carries.
+ */
+function renderRevertResult(compass, toVersion, agentId, log) {
+    if (compass.unchanged) {
+        log(`Already at v${toVersion}'s content — nothing written. ${compass.id} stays at v${compass.version}.`);
+        log(`Status stays ${compass.status}.`);
+        return;
+    }
+    log(`Restored v${toVersion} as v${compass.version} — the intermediate versions stay in the ledger.`);
+    log(compass.status === 'archived'
+        ? `Status stays archived: a revert restores the configuration, never the lifecycle. ` +
+            `Reactivate it with \`compass update ${compass.id} --agent ${agentId} --status active\`.`
+        : `Status stays ${compass.status}.`);
+    const changed = compass.rulesChanged;
+    if (changed && (changed.to < changed.from || (changed.removed ?? []).length > 0)) {
+        const removed = changed.removed ?? [];
+        log(`Warning: rules went from ${changed.from} to ${changed.to}` +
+            `${removed.length ? ` (removed: ${removed.join(', ')})` : ''}. ` +
+            `A removed active rule is no longer enforced; ` +
+            `\`compass revert --to-version ${compass.version - 1}\` brings it back.`);
+    }
+}

package/dist/lib/followups.d.ts

@@ -69,10 +69,18 @@ export interface FollowUpRow {
     /** Who settled it: `trigger_fire` for the runtime, otherwise the actor. */
     terminalBy?: string | null;
     escalatedInitiativeId?: string | null;
-    /** The gate the fire passes: exempt_silent, exempt_user_directed, exempt_system, user_directed_guarded, autonomy_ladder, approval_ladder. */
+    /** The gate the fire passes: exempt_silent, exempt_user_directed, exempt_system, exempt_notification (a passive reminder), user_directed_guarded, autonomy_ladder, approval_ladder. */
     gate?: string | null;
     /** Set while its fire waits on an offline machine; it escalates after 60 minutes. */
     parkedAt?: string | null;
+    /** The SLA backstop of a paired event/poll watch: it escalates the watch when the wait outlives its deadline. */
+    slaFallback?: boolean;
+    /** Set while a fire was moved (quiet hours, working hours, an unavailable machine) instead of run. */
+    held?: {
+        until: string;
+        reason?: string | null;
+        note?: string | null;
+    } | null;
     capsule?: unknown;
     nextRunAt?: string | null;
     deadlineAt?: string | null;
@@ -100,6 +108,15 @@ export interface FollowUpCreateResponse {
 }
 /** One line telling a person the follow-up was recorded with weaker provenance than claimed. */
 export declare function producerDowngradeNotice(response: FollowUpCreateResponse): string | undefined;
+/**
+ * What a reused answer means for the person who asked, for the kinds whose lane a repeat
+ * declaration cannot move (an act, a watch): it armed nothing and changed neither the note nor
+ * the time they typed, and the row that holds the lane keeps ITS time, which may be weeks away.
+ * `Already armed … was not duplicated` alone let `act --in 5m` read as scheduled for five minutes
+ * while the existing act waited thirty days. Say what is armed and how to move it, as the
+ * check-in answer does (OSK-15411).
+ */
+export declare function reusedWithoutChangeMessage(row: FollowUpCreateResponse['followup'], what: string): string;
 export interface FollowUpObservability {
     generatedAt?: string;
     agents?: Array<{
@@ -123,6 +140,10 @@ export interface FollowUpObservability {
                 pool: string | null;
                 used: number;
                 limit: number | null;
+                /** Creations the platform dropped on purpose today (an Agent's own check-in); null when unreadable. */
+                droppedToday?: number | null;
+                /** Creations refused with FOLLOWUP_BUDGET_EXCEEDED today; null when unreadable. */
+                refusedToday?: number | null;
             } | null;
             silenceRate: number | null;
             silentFires: number | null;

package/dist/lib/followups.js

@@ -5,6 +5,7 @@ exports.whenFlagProblem = whenFlagProblem;
 exports.settledLine = settledLine;
 exports.recipeWatchBoundsRefusal = recipeWatchBoundsRefusal;
 exports.producerDowngradeNotice = producerDowngradeNotice;
+exports.reusedWithoutChangeMessage = reusedWithoutChangeMessage;
 exports.resolveFollowUpAgent = resolveFollowUpAgent;
 exports.parseSubjectRef = parseSubjectRef;
 exports.followupSummaryLine = followupSummaryLine;
@@ -135,6 +136,25 @@ function producerDowngradeNotice(response) {
         return undefined;
     return `Note: recorded as ${downgraded.recorded}, not ${downgraded.requested}. ${downgraded.note}`;
 }
+/**
+ * What a reused answer means for the person who asked, for the kinds whose lane a repeat
+ * declaration cannot move (an act, a watch): it armed nothing and changed neither the note nor
+ * the time they typed, and the row that holds the lane keeps ITS time, which may be weeks away.
+ * `Already armed … was not duplicated` alone let `act --in 5m` read as scheduled for five minutes
+ * while the existing act waited thirty days. Say what is armed and how to move it, as the
+ * check-in answer does (OSK-15411).
+ */
+function reusedWithoutChangeMessage(row, what) {
+    const lines = [
+        `Already armed: ${row?.id} — ${what} exists and was not duplicated.`,
+        'Nothing in this request was applied: it did not change the note or the time you gave.',
+    ];
+    if (row) {
+        lines.push(`Armed: ${row.why ? `"${row.why}"` : '(no note)'}, ${row.nextRunAt ? `next ${row.nextRunAt}` : 'waiting on its trigger'}.`);
+    }
+    lines.push(`To change the time: skrr followups reschedule ${row?.id ?? '<id>'} --at <instant> or --in <offset>.`);
+    return lines.join('\n');
+}
 /**
  * A trigger subject becomes a durable concurrency key, so it cannot be prose.
  * Keep this grammar aligned with TriggerEngine's subject validation and the
@@ -213,5 +233,5 @@ function followupSummaryLine(row) {
     const subject = row.subject ? `${row.subject.type}:${row.subject.externalKey}` : '—';
     const kindForm = row.form ? `${row.kind}/${row.form}` : (row.kind ?? '—');
     const when = row.state === 'settled' ? `settled:${row.terminal ?? '?'}` : `next:${fmtWhen(row.nextRunAt)}`;
-    return `${row.id}  [${row.state ?? '?'}] ${kindForm}  ${subject}  ${when}`;
+    return `${row.id}  [${row.state ?? '?'}] ${kindForm}${row.slaFallback ? ' (SLA fallback)' : ''}  ${subject}  ${when}`;
 }

package/dist/lib/format.d.ts

@@ -22,6 +22,17 @@ export declare function pad(s: string, width: number): string;
  * surrogate pair is never split down the middle into two replacement glyphs.
  */
 export declare function truncate(s: string, max: number): string;
+/**
+ * `truncate`, but never in the middle of a word.
+ *
+ * For a prose cell (a reason, a title), where `truncate` cuts a sentence at the
+ * column and leaves a half word that reads as a typo. The cut moves back to the
+ * last word boundary that fits, and loose punctuation is dropped before the
+ * ellipsis. A single token longer than the budget has no boundary to move to, so
+ * it is cut hard: a clipped word is better than an empty cell. A boundary so
+ * early it would throw away most of the budget is not taken for the same reason.
+ */
+export declare function truncateAtWord(s: string, max: number): string;
 /**
  * Render an arbitrary API value as a single table cell.
  *

package/dist/lib/format.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.displayWidth = displayWidth;
 exports.pad = pad;
 exports.truncate = truncate;
+exports.truncateAtWord = truncateAtWord;
 exports.formatCell = formatCell;
 exports.collapseWhitespace = collapseWhitespace;
 exports.renderTable = renderTable;
@@ -105,6 +106,34 @@ function truncate(s, max) {
     }
     return `${out}…`;
 }
+/**
+ * `truncate`, but never in the middle of a word.
+ *
+ * For a prose cell (a reason, a title), where `truncate` cuts a sentence at the
+ * column and leaves a half word that reads as a typo. The cut moves back to the
+ * last word boundary that fits, and loose punctuation is dropped before the
+ * ellipsis. A single token longer than the budget has no boundary to move to, so
+ * it is cut hard: a clipped word is better than an empty cell. A boundary so
+ * early it would throw away most of the budget is not taken for the same reason.
+ */
+function truncateAtWord(s, max) {
+    if (displayWidth(s) <= max)
+        return s;
+    if (max <= 1)
+        return '…';
+    const hard = truncate(s, max);
+    const kept = hard.slice(0, -1); // the longest prefix that leaves room for the ellipsis
+    const rest = s.slice(kept.length);
+    const trim = (value) => value.replace(/[\s,;:(\-—]+$/u, '');
+    // The cut already fell on a word boundary.
+    if (/^\s/u.test(rest))
+        return `${trim(kept)}…`;
+    const boundary = kept.search(/\s\S*$/u);
+    if (boundary > 0 && displayWidth(kept.slice(0, boundary)) >= max * 0.4) {
+        return `${trim(kept.slice(0, boundary))}…`;
+    }
+    return hard;
+}
 /**
  * Render an arbitrary API value as a single table cell.
  *

package/dist/lib/initiatives.d.ts

@@ -2,8 +2,15 @@ import { withQuery } from './triggers';
 /** The decisions `PATCH /api/initiatives/:id/action` accepts. */
 export declare const INITIATIVE_ACTIONS: readonly ["approve", "edit_then_approve", "always_allow_similar", "dismiss", "never_suggest_again", "mute_source", "not_now", "snooze", "reopen", "resolve", "wait", "follow_up", "undo", "grant_autonomy", "only_when_urgent"];
 export type InitiativeAction = (typeof INITIATIVE_ACTIONS)[number];
-/** States an Initiative moves through before and after a decision. */
-export declare const INITIATIVE_STATES: readonly ["detected", "proposed", "approved", "executing", "waiting", "completed", "dismissed", "failed"];
+/**
+ * States an Initiative moves through before and after a decision: exactly the stored
+ * vocabulary (`AGENT_INITIATIVE_STATES`, `@skrr-ai/data-schemas`; a spec holds the two
+ * equal). This list used to say `completed`, a state nothing stores and the server refuses
+ * (`unsupported initiative state(s): completed`), and omitted `resolved`, so a person could
+ * not list the cards that had been approved and finished, nor the snoozed, expired,
+ * reopened or followed-up ones.
+ */
+export declare const INITIATIVE_STATES: readonly ["detected", "proposed", "approved", "executing", "waiting", "followed_up", "reopened", "resolved", "dismissed", "snoozed", "expired", "failed"];
 export type InitiativeView = {
     id?: string;
     title?: string;

package/dist/lib/initiatives.js

@@ -39,15 +39,26 @@ exports.INITIATIVE_ACTIONS = [
     'grant_autonomy',
     'only_when_urgent',
 ];
-/** States an Initiative moves through before and after a decision. */
+/**
+ * States an Initiative moves through before and after a decision: exactly the stored
+ * vocabulary (`AGENT_INITIATIVE_STATES`, `@skrr-ai/data-schemas`; a spec holds the two
+ * equal). This list used to say `completed`, a state nothing stores and the server refuses
+ * (`unsupported initiative state(s): completed`), and omitted `resolved`, so a person could
+ * not list the cards that had been approved and finished, nor the snoozed, expired,
+ * reopened or followed-up ones.
+ */
 exports.INITIATIVE_STATES = [
     'detected',
     'proposed',
     'approved',
     'executing',
     'waiting',
-    'completed',
+    'followed_up',
+    'reopened',
+    'resolved',
     'dismissed',
+    'snoozed',
+    'expired',
     'failed',
 ];
 exports.initiativeApi = {

package/dist/lib/machines.d.ts

@@ -1,4 +1,4 @@
-import type { DaemonContactState, DaemonMaintenanceSummary } from '@skrr-ai/data-provider';
+import type { DaemonContactState, DaemonMaintenanceSummary, MachineIcon, MachineIconPatch } from '@skrr-ai/data-provider';
 /**
  * machines.ts — request client for `/api/machines`.
  *
@@ -134,6 +134,7 @@ export interface Machine {
         name?: string;
         description?: string;
         tags?: string[];
+        icon?: MachineIcon;
     };
     lease: Record<string, unknown> | null;
     controls: {
@@ -271,7 +272,19 @@ export interface MachinePreferencesPatch {
     name?: string;
     description?: string;
     tags?: string[];
+    /** A preset, or null for the default. An uploaded image is not set by a patch. */
+    icon?: MachineIconPatch;
 }
+/**
+ * The value of `--icon`: a preset's id, or `none` (also `default`) to go back to
+ * the default. Throws a sentence that names the valid ids, because the only other
+ * way to learn them would be to send a wrong one and read the server's refusal.
+ * An uploaded image is a different flag (`--icon-file`): a name that is not a
+ * preset is never guessed to be a path.
+ */
+export declare function parseMachineIconFlag(value: string): MachineIconPatch;
+/** What `machines show`/`update` print for an icon: the preset's id, or what kind of image. */
+export declare function describeMachineIcon(icon: MachineIcon | undefined): string;
 /**
  * How many of a machine's harnesses still represent a capability it has.
  *

package/dist/lib/machines.js

@@ -10,6 +10,8 @@ exports.harnessStateLabel = harnessStateLabel;
 exports.summarizeDaemons = summarizeDaemons;
 exports.isThisComputer = isThisComputer;
 exports.machineListView = machineListView;
+exports.parseMachineIconFlag = parseMachineIconFlag;
+exports.describeMachineIcon = describeMachineIcon;
 exports.liveHarnessCount = liveHarnessCount;
 exports.listMachines = listMachines;
 exports.getMachine = getMachine;
@@ -229,6 +231,28 @@ function machineListView(machine, options) {
         ...(hidden > 0 ? { hiddenHarnessCount: hidden } : {}),
     };
 }
+/**
+ * The value of `--icon`: a preset's id, or `none` (also `default`) to go back to
+ * the default. Throws a sentence that names the valid ids, because the only other
+ * way to learn them would be to send a wrong one and read the server's refusal.
+ * An uploaded image is a different flag (`--icon-file`): a name that is not a
+ * preset is never guessed to be a path.
+ */
+function parseMachineIconFlag(value) {
+    const id = value.trim().toLowerCase();
+    if (id === 'none' || id === 'default')
+        return null;
+    if ((0, data_provider_1.isMachineIconPresetId)(id))
+        return { kind: 'preset', id };
+    throw new Error(`--icon: "${value}" is not an icon. Choose one of ${data_provider_1.MACHINE_ICON_PRESET_IDS.join(', ')}, ` +
+        'or "none" to go back to the default. To use your own image, pass --icon-file <path>.');
+}
+/** What `machines show`/`update` print for an icon: the preset's id, or what kind of image. */
+function describeMachineIcon(icon) {
+    if (!icon)
+        return 'default';
+    return icon.kind === 'preset' ? icon.id : 'uploaded image';
+}
 /**
  * How many of a machine's harnesses still represent a capability it has.
  *