@skrr-ai/cli 0.1.127 → 0.1.129

package/dist/lib/commitment-attention-copy.js

@@ -0,0 +1,209 @@
+"use strict";
+/**
+ * The attention settings of a Commitment, said in words.
+ *
+ * `show`, `effective-policy` and `preflight` all print these, from this one
+ * file, so the three cannot phrase a setting three ways. A value is described
+ * from the RAW stored setting and never through a coercion: `null` is "no
+ * limit" and `0` is "muted", and `Number(null)` is `0`, which is exactly how a
+ * cap that was never set would read as a mute (the server documents the same
+ * trap at `policySchema.maxUserNudgesPerDay` in api/server/routes/commitments.js).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EVENT_SOURCES_HELP = exports.QUIET_HOURS_HELP = exports.CLOCK_TIME_HINT = exports.MAX_NUDGES_FLAG_HELP = void 0;
+exports.parseMaxNudgesFlag = parseMaxNudgesFlag;
+exports.describeNudgeCap = describeNudgeCap;
+exports.describeNudgeGap = describeNudgeGap;
+exports.describeNoReplyRule = describeNoReplyRule;
+exports.nudgeSettingsFromPolicy = nudgeSettingsFromPolicy;
+exports.nudgeSettingLines = nudgeSettingLines;
+exports.describeEventSources = describeEventSources;
+exports.quietHoursInputProblem = quietHoursInputProblem;
+exports.describeQuietHours = describeQuietHours;
+exports.describeQuietHoursEnd = describeQuietHoursEnd;
+/** What the owner can type for `--max-nudges`, as `--help` prints it. */
+exports.MAX_NUDGES_FLAG_HELP = 'Daily limit on messages that interrupt you: a whole number from 0 up (0 mutes it: ' +
+    'it never contacts you) or "unlimited" to remove the limit. Left unset it is unlimited';
+/**
+ * Parse `--max-nudges`: a whole number, or the word `unlimited` (stored as `null`).
+ * The server accepts 0 up to MAX_SAFE_INTEGER, so there is no 0..20 ceiling here.
+ */
+function parseMaxNudgesFlag(raw) {
+    if (raw === undefined)
+        return undefined;
+    const value = raw.trim().toLowerCase();
+    if (value === 'unlimited')
+        return null;
+    if (/^\d+$/.test(value)) {
+        const parsed = Number(value);
+        if (Number.isSafeInteger(parsed))
+            return parsed;
+    }
+    throw new Error(`--max-nudges must be a whole number (0 mutes it) or the word "unlimited"; got "${raw}".`);
+}
+/** `null` and an unset cap are "no daily limit"; `0` is a mute; N is "at most N a day". */
+function describeNudgeCap(value) {
+    if (value === null || value === undefined)
+        return 'no daily limit';
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        return `unreadable (${String(value)})`;
+    }
+    if (value <= 0)
+        return 'muted: it never contacts you';
+    return `at most ${value} a day`;
+}
+function durationWords(ms) {
+    if (ms < 60_000)
+        return `${Math.max(1, Math.round(ms / 1000))} s`;
+    const totalMinutes = Math.round(ms / 60_000);
+    const days = Math.floor(totalMinutes / 1440);
+    const hours = Math.floor((totalMinutes % 1440) / 60);
+    const minutes = totalMinutes % 60;
+    return [days ? `${days} d` : '', hours ? `${hours} h` : '', minutes ? `${minutes} min` : '']
+        .filter(Boolean)
+        .join(' ');
+}
+/** The least time the platform leaves between two nudges to you. */
+function describeNudgeGap(ms) {
+    if (ms === null || ms === undefined || ms === 0)
+        return 'no minimum gap between nudges';
+    if (typeof ms !== 'number' || !Number.isFinite(ms) || ms < 0) {
+        return `unreadable (${String(ms)})`;
+    }
+    return `at least ${durationWords(ms)} between nudges`;
+}
+/** The back-off for a person who is not answering. The server's default count is 2. */
+function describeNoReplyRule(noReply) {
+    if (noReply?.enabled !== true)
+        return 'off: it keeps nudging whether or not you answer';
+    const after = Number.isInteger(noReply.afterNudges) ? noReply.afterNudges : 2;
+    return `after ${after} unanswered nudge${after === 1 ? '' : 's'} it waits until you reply`;
+}
+/** Read the three settings out of a stored `policy`. */
+function nudgeSettingsFromPolicy(policy) {
+    return {
+        maxUserNudgesPerDay: policy.maxUserNudgesPerDay,
+        minUserNudgeIntervalMs: policy.minUserNudgeIntervalMs,
+        noReply: policy.attention?.noReply,
+    };
+}
+/**
+ * The lines that say how much a Commitment may interrupt its owner. A muted one
+ * prints the mute alone: a gap and a back-off on a Commitment that never speaks
+ * would only suggest it does. `withNoReply: false` leaves the back-off out when the
+ * stored rule could not be read, rather than claim it is off.
+ */
+function nudgeSettingLines(settings, { withNoReply = true } = {}) {
+    const lines = [`Nudges: ${describeNudgeCap(settings.maxUserNudgesPerDay)}`];
+    const muted = typeof settings.maxUserNudgesPerDay === 'number' && settings.maxUserNudgesPerDay <= 0;
+    if (muted)
+        return lines;
+    lines.push(`Min gap: ${describeNudgeGap(settings.minUserNudgeIntervalMs)}`);
+    if (withNoReply)
+        lines.push(`No reply: ${describeNoReplyRule(settings.noReply)}`);
+    return lines;
+}
+const CLOCK = /^(\d{1,2}):(\d{2})$/;
+/** What a time of day is, in the words a person can type. */
+exports.CLOCK_TIME_HINT = 'use HH:MM, 00:00-23:59, for example 22:00';
+/**
+ * How to set quiet hours, for the `--from-json` help of `create` and `update`. There is no flag for
+ * them, so without this sentence a user had to know the `policy.quietHours` key from outside the CLI
+ * (OSK-21123).
+ */
+exports.QUIET_HOURS_HELP = 'Quiet hours (no messages to you) go in the JSON as policy.quietHours: ' +
+    '{"enabled":true,"start":"22:00","end":"07:00","timezone":"America/Los_Angeles"}. ' +
+    'Times are 24-hour HH:MM (00:00-23:59); the window may cross midnight and its end is not ' +
+    'inside it; timezone is an IANA name, and when omitted it is UTC, not your local zone.';
+/**
+ * What `policy.executionBudget.allowedEventSources` means, for the same help. An empty list is the
+ * unrestricted case, which is the opposite of what `[]` suggests (OSK-21113).
+ */
+exports.EVENT_SOURCES_HELP = 'policy.executionBudget.allowedEventSources limits which event sources may wake the Commitment: ' +
+    'an empty or missing list allows every source (it is not "none"); name sources to restrict it.';
+/**
+ * The allowlist in words. An empty or missing list means every source is allowed
+ * (`sourceAllowed` in api/server/services/EventBus/commitmentWakeCapabilities.js and the check in
+ * WakeIntentResolver.js both treat it so); the stored form of "never set" is the same `[]`.
+ */
+function describeEventSources(allowed) {
+    return Array.isArray(allowed) && allowed.length
+        ? `limited to: ${allowed.map(String).join(', ')}`
+        : 'all allowed (the list is empty)';
+}
+function validClock(value) {
+    if (typeof value !== 'string')
+        return false;
+    const match = CLOCK.exec(value);
+    return Boolean(match) && Number(match[1]) <= 23 && Number(match[2]) <= 59;
+}
+/**
+ * The problem with the quiet-hours times in a `policy` about to be sent, or null. The server
+ * answered a bad time with its raw pattern (`must match pattern /^\d{1,2}:\d{2}$/`), which says
+ * nothing a person can type, and accepted `25:00` (a window that then never applies). Checked
+ * here, so the request never leaves with either.
+ */
+function quietHoursInputProblem(policy) {
+    const quietHours = policy?.quietHours;
+    if (!quietHours || typeof quietHours !== 'object')
+        return null;
+    for (const key of ['start', 'end']) {
+        const value = quietHours[key];
+        if (value !== undefined && !validClock(value)) {
+            return `policy.quietHours.${key} ${JSON.stringify(value)} is not a time of day: ${exports.CLOCK_TIME_HINT}.`;
+        }
+    }
+    return null;
+}
+/** `9:00` and `09:00` are the same time to the server; show the zero-padded form. */
+function clockText(value) {
+    const match = CLOCK.exec(String(value ?? '').trim());
+    return match ? `${match[1].padStart(2, '0')}:${match[2]}` : String(value ?? '');
+}
+/** An omitted timezone is UTC, and no text surface said so (OSK-21122). */
+const NO_TIMEZONE_NOTE = 'UTC (no timezone set, UTC is used)';
+/**
+ * The Commitment's own quiet-hours window in words. Without one of its own a Commitment uses its
+ * Agent's Compass window (`scheduleIssues.js` documents the same rule), so "none set" says where
+ * else a window may come from rather than claiming there is no quiet time at all.
+ */
+function describeQuietHours(quietHours) {
+    if (!quietHours) {
+        return "none set on this Commitment (a window in its Agent's Compass applies, if it has one)";
+    }
+    const zone = quietHours.timezone ? quietHours.timezone : NO_TIMEZONE_NOTE;
+    const window = quietHours.start && quietHours.end
+        ? `${clockText(quietHours.start)}-${clockText(quietHours.end)} ${zone}`
+        : null;
+    if (quietHours.enabled !== true) {
+        return window ? `off (${window} is saved but switched off)` : 'off';
+    }
+    if (!window)
+        return 'on, but start and end are not both set, so no quiet window applies';
+    if (clockText(quietHours.start) === clockText(quietHours.end)) {
+        return `${window}: start and end are the same time, so the window is empty and nothing is held`;
+    }
+    return window;
+}
+/** `2026-11-01T15:00:00.000Z` as `2026-11-01 15:00 UTC`. */
+function utcText(iso) {
+    const parsed = typeof iso === 'string' ? new Date(iso) : null;
+    if (!parsed || Number.isNaN(parsed.getTime()))
+        return null;
+    return `${parsed.toISOString().slice(0, 16).replace('T', ' ')} UTC`;
+}
+/**
+ * When a held message is released, for the preflight line "Held until your quiet hours end".
+ * The report's `quietHours` carries the end as typed, the zone, and the exact instant (`endsAt`,
+ * daylight saving included); null when it carries no instant, so the caller keeps its generic
+ * sentence rather than inventing a time.
+ */
+function describeQuietHoursEnd(quietHours) {
+    const utc = utcText(quietHours?.endsAt);
+    if (!utc)
+        return null;
+    const zone = quietHours?.timezone || 'UTC';
+    if (zone === 'UTC' || !quietHours?.end)
+        return `Held until your quiet hours end: ${utc}.`;
+    return `Held until your quiet hours end: ${clockText(quietHours.end)} ${zone}, ${utc}.`;
+}

package/dist/lib/commitment-ledgers.js

@@ -45,7 +45,9 @@ function renderActionHistory(page, log) {
             status: text(row.status),
             check: text(row.checkId),
             // A failed or refused action's reason is the point of reading history.
-            why: [text(row.errorCode, ''), brief(row.errorMessage ?? row.reason)]
+            // A skipped action says why in `skippedReason` (a zero budget, a fenced Check), which this column
+            // never read, so every skipped row printed an empty WHY (OSK-21610).
+            why: [text(row.errorCode, ''), brief(row.errorMessage ?? row.skippedReason ?? row.reason)]
                 .filter(Boolean)
                 .join(' · '),
         })), [

package/dist/lib/commitment-loop-status.d.ts

@@ -10,6 +10,12 @@
  */
 import { type CommitmentLoopStatus, type CommitmentRoster } from '@skrr-ai/data-provider';
 export declare function loopStateLabel(state: unknown): string;
+/**
+ * What an empty "next wakes" list means. "Nothing is scheduled" is true only of an unarmed loop: a held
+ * wake IS scheduled and is being refused, and the line above it says "armed" (OSK-21261). Unknown stays
+ * "could not be read" because cannot-see is not none.
+ */
+export declare function noNextWakeText(status: Pick<CommitmentLoopStatus, 'loopState' | 'loopReason'>): string;
 /** Roster table: one row per Commitment. */
 export declare function formatCommitmentRoster(roster: Partial<CommitmentRoster>): string[];
 /**

package/dist/lib/commitment-loop-status.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loopStateLabel = loopStateLabel;
+exports.noNextWakeText = noNextWakeText;
 exports.formatCommitmentRoster = formatCommitmentRoster;
 exports.formatLoopSummary = formatLoopSummary;
 exports.formatCommitmentLoopStatus = formatCommitmentLoopStatus;
@@ -64,6 +65,19 @@ function spend(status) {
     // A partial ledger is a lower bound; never print it as the whole answer.
     return status.cost?.spendKnown ? amount : `≥ ${amount} (some runs unpriced)`;
 }
+/**
+ * What an empty "next wakes" list means. "Nothing is scheduled" is true only of an unarmed loop: a held
+ * wake IS scheduled and is being refused, and the line above it says "armed" (OSK-21261). Unknown stays
+ * "could not be read" because cannot-see is not none.
+ */
+function noNextWakeText(status) {
+    if (status.loopState === 'unknown')
+        return 'could not be read';
+    if (status.loopReason === 'wake_control_blocked' || status.loopReason === 'wake_admission_blocked') {
+        return 'none while its wakes are held (see the loop line)';
+    }
+    return 'none — nothing is scheduled to wake it';
+}
 function nextWake(status) {
     const wake = status.nextWakes?.[0];
     return wake ? `${when(wake.at)} ${wake.kind}` : '-';
@@ -136,9 +150,7 @@ function formatLoopSummary(status) {
     const wake = status.nextWakes?.[0];
     lines.push(`next wake: ${wake
         ? `${when(wake.at)} ${wake.kind}`
-        : status.loopState === 'unknown'
-            ? 'could not be read'
-            : 'none — nothing is scheduled to wake it'}`);
+        : noNextWakeText(status)}`);
     if (status.lastStop) {
         const stop = status.lastStop;
         lines.push(`last stop: ${stop.question}${stop.reason ? ` — ${stop.reason}` : ''}${stop.detail ? `: ${stop.detail}` : ''}`);
@@ -189,9 +201,7 @@ function formatCommitmentLoopStatus(status) {
     const wakes = Array.isArray(status.nextWakes) ? status.nextWakes : [];
     lines.push('  Next wakes:');
     if (!wakes.length) {
-        lines.push(status.loopState === 'unknown'
-            ? '    (could not be read)'
-            : '    none — nothing is scheduled to wake it');
+        lines.push(status.loopState === 'unknown' ? '    (could not be read)' : `    ${noNextWakeText(status)}`);
     }
     for (const wake of wakes) {
         lines.push(`    ${when(wake.at)}  ${wake.kind}${wake.reason ? ` (${wake.reason})` : ''}`);

package/dist/lib/commitments.d.ts

@@ -60,6 +60,12 @@ export type CommitmentPreflightReport = {
         id: string;
         label: string;
         verdict: 'pass' | 'indeterminate' | 'block';
+        /**
+         * Whether this gate can stop a Run (`blocking`) or only informs (`advisory`). An advisory gate
+         * can still say `block` (a Pack that watches its Goal through a link, not a watched source,
+         * has "no observation source"); it stops nothing and never feeds the verdict.
+         */
+        admission?: 'blocking' | 'advisory';
         /** Short machine code for why a gate did NOT pass. */
         reason?: string | null;
         /**
@@ -96,7 +102,41 @@ export type CommitmentPreflightReport = {
         retired?: string[];
         retiredReason?: string;
     } & Record<string, unknown>;
+    /**
+     * Whether Resume / `create --activate` would be accepted, answered by the server's one activation
+     * rule (`CommitmentActivation`). Absent from an older server. A gate can be advisory for a run and
+     * still refuse activation, so this is the answer, not the gate list.
+     */
+    activation?: {
+        canActivate?: boolean;
+        blockers?: Array<{
+            gate: string;
+            label?: string;
+            reason?: string;
+            hint?: string;
+        }>;
+    } | null;
 };
+/**
+ * The lines preflight prints when the server says activation would be refused (OSK-21258). The gate
+ * list marks an advisory gate `info (advisory: does not stop a run)`, which is true of a run and false
+ * of activation: `resume` refused the same gate with a 409 while preflight read as if nothing stopped
+ * it. The server owns which gates refuse; this lays out its answer and never re-derives it. Nothing
+ * for an allowed activation or an older server that does not send the block.
+ */
+export declare function activationRefusalLines(activation: CommitmentPreflightReport['activation']): string[];
+/**
+ * Whether the server's activation answer names this gate as one that refuses activation (OSK-21258).
+ * A gate can be advisory for a run (`admission: 'advisory'`) and still be what `resume` refuses with a
+ * 409; the gate list printed it `info (advisory: does not stop a run)` right under an "Activation:
+ * would be refused" section naming the same gate. Matches on the gate id, and on the reason too when
+ * both sides carry one, so a gate advisory for one reason is not promoted by another. An older server
+ * that sends no answer promotes nothing.
+ */
+export declare function gateRefusesActivation(activation: CommitmentPreflightReport['activation'], gate: {
+    id?: string;
+    reason?: string | null;
+}): boolean;
 /**
  * The lines every Commitment read surface prints for "whose permissions does a
  * run use?" — `show`, `effective-policy` and `preflight` share it so the three
@@ -161,6 +201,8 @@ export type CommitmentPackPreflightResponse = {
 export type CommitmentPackDefinition = {
     id: string;
     version: string;
+    /** The Pack's name as the server sends it. `title` is not a field of the catalogue (OSK-21110). */
+    label?: string;
     title?: string;
     description?: string;
     [key: string]: unknown;
@@ -179,6 +221,17 @@ export type CommitmentPackPlanResponse = {
         agentId: string;
         holder?: 'space_lead' | 'explicit';
     };
+    /**
+     * What the plan cannot fix and `pack preflight` would report later: today only a holder whose
+     * runtime can never activate this loop. Beside the plan, outside its digest.
+     */
+    readiness?: Array<{
+        gate: string;
+        label: string;
+        verdict: 'block';
+        reason: string;
+        hint?: string;
+    }>;
     [key: string]: unknown;
 };
 export type CommitmentPackBindResponse = {
@@ -719,6 +772,21 @@ export declare function readCommitmentAgentDirective({ directive, file, }: {
     directive?: string;
     file?: string;
 }): Promise<string | undefined>;
+/**
+ * The top-level keys of a `--from-json` body that `create`/`preflight` will not send. A key within two edits
+ * of a real one is a `typo`; the rest are `ignored`. A server-owned dump field is neither.
+ */
+export declare function unrecognizedCreateKeys(src: Record<string, unknown>): {
+    typos: Array<{
+        key: string;
+        suggestion: string;
+    }>;
+    ignored: string[];
+};
+/** The keys of a `--from-json` body that are neither sent nor server-owned and not a typo: to be warned about. */
+export declare function ignoredCreateKeys(input: Record<string, unknown>): string[];
+/** The one sentence `create` and `preflight` print for them. */
+export declare function ignoredCreateKeysWarning(keys: string[]): string | null;
 /**
  * Normalize a `--from-json` body into something the create endpoint accepts.
  *
@@ -951,6 +1019,34 @@ export declare function commitmentWriteWarnings(response: unknown, fallback: {
 /** One `Warning:` line per authoring warning, after the write's own output. */
 export declare function renderCommitmentWriteWarnings(warnings: CommitmentAuthoringWarning[], warn: (line: string) => void): void;
 export declare function describeCommitmentRevision(revision: CommitmentRevisionReceipt | undefined): string;
+/**
+ * A commitment's priority, as one line: `high · weight 70 · from northstar`.
+ *
+ * Linking a commitment to a northstar rewrites its priority (`source: northstar`) and a governor
+ * reprioritization changes it again, so the place a person looks to confirm either is `show`, which
+ * printed everything but this and sent them to `--json`. An unset priority says so rather than
+ * printing nothing.
+ */
+export declare function describeCommitmentPriority(priority: CommitmentView['priority']): string;
+/**
+ * The `Compass:` line of a bound commitment. A commitment names its compass (`compassId`) but the
+ * read does not carry that compass's STATUS, and an archived one governs nothing (the commitment
+ * runs on defaults), so the id alone could be read as "governed by it". Only what is known is
+ * stated: the id, and the command that says whether it is active (OSK-21242).
+ */
+export declare function describeBoundCompass(commitment: Pick<CommitmentView, 'compassId' | 'agentId'>): string;
+/**
+ * The bound Compass, as `explain` prints it (OSK-21332). `explain` is where a person asks "why does
+ * this Commitment behave this way", and a bound Compass (or an archived one, which runs the
+ * Commitment on defaults) is part of the answer. The explain payload names neither the Compass nor
+ * its status, so the caller reads the Commitment itself, the same read `show` renders, and hands the
+ * result here: the line is `describeBoundCompass`, the one `show` prints, not a second wording.
+ *
+ * `null` means that read did not come back. It is said, not skipped: a silent skip is
+ * indistinguishable from "no Compass is bound". A Commitment bound to none prints nothing, as in
+ * `show`.
+ */
+export declare function explainCompassLines(commitmentId: string, commitment: Pick<CommitmentView, 'compassId' | 'agentId'> | null | undefined): string[];
 export declare function renderCommitmentSummary(commitment: CommitmentView, log: (line: string) => void, 
 /**
  * The most recent check, when the caller has one. Optional because pause /
@@ -1011,10 +1107,26 @@ export declare function hypothesisRefusalLines(run: {
         count: number;
     }>;
 }): string[];
+/**
+ * A wake the Agent asked for and the platform did not arm, in the server's words.
+ * The only record used to be `ledger --json`; the cycle read `advanced` (OSK-21132).
+ */
+export declare function wakeOutcomeLines(run: {
+    wake?: {
+        status?: string;
+        reason?: string;
+        detail?: string;
+        fix?: string;
+    };
+}): string[];
 export declare function formatCommitmentExplanation(explanation: Partial<CommitmentExplanationResponse>): string[];
 /**
  * Print the continuation hint for a paged `object:'list'` response — the line
  * that makes history beyond the newest page reachable instead of invisible.
+ *
+ * Text mode ONLY. Under `--json` stdout must be one JSON document, and the same
+ * facts are already in it as `has_more` / `next_cursor`: a caller that prints
+ * this after the JSON makes `| json.load` fail (OSK-21118).
  */
 export declare function renderListPageHint(page: {
     has_more?: boolean;