@skrr-ai/cli 0.1.126 → 0.1.128

package/dist/lib/commitments.js

@@ -1,10 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.COMMITMENT_CLI_EVALUATORS = exports.COMMITMENT_CREATE_KEYS = exports.COMMITMENT_REMEDIATION_ACTIONS = exports.COMMITMENT_FEEDBACK_KINDS = exports.commitmentApi = exports.commitmentPackApi = exports.MAX_COMMITMENT_INTERVAL_MS = exports.MIN_COMMITMENT_INTERVAL_MS = exports.COMMITMENT_EXECUTION_ISOLATION_MODES = exports.COMMITMENT_AUTHORABLE_CADENCE_MODES = exports.COMMITMENT_KIND_VALUES = exports.COMMITMENT_STATUSES = exports.COMMITMENT_CADENCE_MAX_TIMES = exports.COMMITMENT_CADENCE_TIME_PATTERN = exports.COMMITMENT_CADENCE_MODES = exports.COMMITMENT_TEMPLATE_IDS = exports.COMMITMENT_WATCHED_SOURCES = void 0;
+exports.activationRefusalLines = activationRefusalLines;
 exports.permissionLines = permissionLines;
 exports.scheduleIssueLines = scheduleIssueLines;
 exports.retiredFieldsLine = retiredFieldsLine;
 exports.readCommitmentAgentDirective = readCommitmentAgentDirective;
+exports.unrecognizedCreateKeys = unrecognizedCreateKeys;
+exports.ignoredCreateKeys = ignoredCreateKeys;
+exports.ignoredCreateKeysWarning = ignoredCreateKeysWarning;
 exports.normalizeCreateBody = normalizeCreateBody;
 exports.parseCommitmentConcurrencyLimit = parseCommitmentConcurrencyLimit;
 exports.commitmentConcurrencyEnvelopePatch = commitmentConcurrencyEnvelopePatch;
@@ -29,6 +33,8 @@ exports.withLiveAssessment = withLiveAssessment;
 exports.commitmentWriteWarnings = commitmentWriteWarnings;
 exports.renderCommitmentWriteWarnings = renderCommitmentWriteWarnings;
 exports.describeCommitmentRevision = describeCommitmentRevision;
+exports.describeCommitmentPriority = describeCommitmentPriority;
+exports.describeBoundCompass = describeBoundCompass;
 exports.renderCommitmentSummary = renderCommitmentSummary;
 exports.describeWakeDecision = describeWakeDecision;
 exports.renderCheckList = renderCheckList;
@@ -37,6 +43,7 @@ exports.renderCommitmentTrace = renderCommitmentTrace;
 exports.renderProactivenessScorecard = renderProactivenessScorecard;
 exports.formatCommitmentCycles = formatCommitmentCycles;
 exports.hypothesisRefusalLines = hypothesisRefusalLines;
+exports.wakeOutcomeLines = wakeOutcomeLines;
 exports.formatCommitmentExplanation = formatCommitmentExplanation;
 exports.renderListPageHint = renderListPageHint;
 exports.describeObservationArtifacts = describeObservationArtifacts;
@@ -80,6 +87,7 @@ Object.defineProperty(exports, "COMMITMENT_EXECUTION_ISOLATION_MODES", { enumera
 Object.defineProperty(exports, "COMMITMENT_STATUSES", { enumerable: true, get: function () { return data_provider_2.COMMITMENT_STATUSES; } });
 Object.defineProperty(exports, "COMMITMENT_KIND_VALUES", { enumerable: true, get: function () { return data_provider_2.COMMITMENT_KIND_VALUES; } });
 const commitment_product_1 = require("./commitment-product");
+const commitment_attention_copy_1 = require("./commitment-attention-copy");
 const instruction_input_1 = require("./instruction-input");
 const format_1 = require("./format");
 const triggers_1 = require("./triggers");
@@ -95,6 +103,27 @@ exports.COMMITMENT_AUTHORABLE_CADENCE_MODES = data_provider_2.COMMITMENT_CADENCE
  */
 exports.MIN_COMMITMENT_INTERVAL_MS = 60_000;
 exports.MAX_COMMITMENT_INTERVAL_MS = 365 * 24 * 60 * 60 * 1000;
+/**
+ * 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.
+ */
+function activationRefusalLines(activation) {
+    if (!activation || activation.canActivate !== false)
+        return [];
+    const blockers = activation.blockers ?? [];
+    if (!blockers.length)
+        return ['Activation: would be refused (the server named no gate)'];
+    const lines = ['Activation: would be refused'];
+    for (const blocker of blockers) {
+        lines.push(`  - ${blocker.label || blocker.gate}${blocker.reason ? ` (${blocker.reason})` : ''}`);
+        if (blocker.hint)
+            lines.push(`    ${blocker.hint}`);
+    }
+    return lines;
+}
 /**
  * The lines every Commitment read surface prints for "whose permissions does a
  * run use?" — `show`, `effective-policy` and `preflight` share it so the three
@@ -414,6 +443,86 @@ async function readCommitmentAgentDirective({ directive, file, }) {
     }
     return (0, instruction_input_1.readInstructionBody)({ body: directive, file });
 }
+/**
+ * What a contract dumped from `show`/`list --json` carries that is the server's, not the author's. These are
+ * dropped on purpose and never reported.
+ */
+const SERVER_OWNED_CONTRACT_KEYS = new Set([
+    'id',
+    'ownerUserId',
+    'workspaceId',
+    'version',
+    'createdAt',
+    'updatedAt',
+    'createdBy',
+    'updatedBy',
+    'state',
+    'firstActivatedAt',
+    'executionEpoch',
+    'alwaysOnGeneration',
+    'requiresAlwaysOn',
+    'assessment',
+    'abilities',
+    'url',
+    'latestCheck',
+    'operatingState',
+    'triggerPlan',
+    'executorHandovers',
+    'priority',
+    'proposal',
+    'rationale',
+    'droppedFields',
+    'warnings',
+]);
+function editDistance(a, b) {
+    const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i += 1) {
+        let diagonal = row[0];
+        row[0] = i;
+        for (let j = 1; j <= b.length; j += 1) {
+            const above = row[j];
+            row[j] = Math.min(row[j] + 1, row[j - 1] + 1, diagonal + (a[i - 1] === b[j - 1] ? 0 : 1));
+            diagonal = above;
+        }
+    }
+    return row[b.length];
+}
+/**
+ * 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.
+ */
+function unrecognizedCreateKeys(src) {
+    const known = exports.COMMITMENT_CREATE_KEYS;
+    const typos = [];
+    const ignored = [];
+    for (const key of Object.keys(src || {})) {
+        if (known.includes(key) || SERVER_OWNED_CONTRACT_KEYS.has(key))
+            continue;
+        const near = key.length >= 4
+            ? known.find((candidate) => candidate.length >= 4 && editDistance(key.toLowerCase(), candidate.toLowerCase()) <= 2)
+            : undefined;
+        if (near)
+            typos.push({ key, suggestion: near });
+        else
+            ignored.push(key);
+    }
+    return { typos, ignored };
+}
+/** The keys of a `--from-json` body that are neither sent nor server-owned and not a typo: to be warned about. */
+function ignoredCreateKeys(input) {
+    const envelope = input;
+    const src = envelope && typeof envelope.proposal === 'object' && envelope.proposal !== null
+        ? envelope.proposal
+        : input || {};
+    return unrecognizedCreateKeys(src).ignored;
+}
+/** The one sentence `create` and `preflight` print for them. */
+function ignoredCreateKeysWarning(keys) {
+    if (keys.length === 0)
+        return null;
+    return (`--from-json: ${keys.map((key) => `"${key}"`).join(', ')} ${keys.length === 1 ? 'is' : 'are'} not sent ` +
+        "(the CLI does not forward it), so the Commitment is built without it.");
+}
 /**
  * Normalize a `--from-json` body into something the create endpoint accepts.
  *
@@ -433,6 +542,16 @@ function normalizeCreateBody(input) {
     const src = envelope && typeof envelope.proposal === 'object' && envelope.proposal !== null
         ? envelope.proposal
         : input || {};
+    // Dropping a key the body does not declare is deliberate for what a dumped contract carries (id, version,
+    // state, ...). It is not for a typo of a real field: `cadance` was dropped and the Commitment created with
+    // the default manual cadence, exit 0, while the same body over REST is a 400 (dogfood
+    // df-261031-commitment-authoring, OSK-21246).
+    const { typos } = unrecognizedCreateKeys(src);
+    if (typos.length > 0) {
+        throw new Error(`--from-json has ${typos.length === 1 ? 'a field' : 'fields'} the API does not know: ` +
+            `${typos.map((t) => `"${t.key}" (did you mean "${t.suggestion}"?)`).join(', ')}. ` +
+            'Nothing was sent: the API refuses unknown fields, and dropping them here would create the Commitment without them.');
+    }
     const out = {};
     for (const key of exports.COMMITMENT_CREATE_KEYS) {
         if (src[key] !== undefined)
@@ -976,6 +1095,12 @@ function describeExecutorBlocked(commitment) {
  * operation and reason is printed as it always was.
  */
 function describeOperation(operation, reason) {
+    // "Cannot tell" travels as `blocked` + this reason (the server's `storedOperation`: no status
+    // recorded yet for this version of the contract, or the recorded one expired). A Commitment that
+    // was turned on a moment ago is in exactly that state, and `blocked` read as a refused activation
+    // while `show` said `ready` seconds later (OSK-21105).
+    if (reason === 'operation_read_unavailable')
+        return 'not read yet — no status is recorded for the current contract, which is not a failure; `skrr commitments show` reads it live';
     const lifecycle = typeof reason === 'string' ? /^lifecycle_([a-z_]+)$/.exec(reason) : null;
     if (!lifecycle)
         return `${operation ?? 'blocked'}${reason ? ` — ${reason}` : ''}`;
@@ -1135,6 +1260,37 @@ function describeCommitmentRevision(revision) {
     }
     return `Updated commitment (version ${revision.previousVersion} -> ${revision.version}):`;
 }
+/**
+ * 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.
+ */
+function describeCommitmentPriority(priority) {
+    const parts = [];
+    if (priority?.tier)
+        parts.push(priority.tier);
+    if (typeof priority?.weight === 'number')
+        parts.push(`weight ${priority.weight}`);
+    if (priority?.source === 'northstar')
+        parts.push('from northstar');
+    else if (priority?.source === 'manual')
+        parts.push('set manually');
+    return parts.length ? parts.join(' · ') : 'not set';
+}
+/**
+ * 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).
+ */
+function describeBoundCompass(commitment) {
+    const id = commitment.compassId ?? '-';
+    const agent = commitment.agentId ?? '<agent-id>';
+    return `Compass:   ${id} — status not shown here; an archived compass governs nothing: \`skrr compass show ${id} --agent ${agent}\``;
+}
 function renderCommitmentSummary(commitment, log, 
 /**
  * The most recent check, when the caller has one. Optional because pause /
@@ -1174,6 +1330,9 @@ scheduleIssues) {
         log(`Goal:      ${commitment.goalId}`);
     if (commitment.northstarId)
         log(`Northstar: ${commitment.northstarId}`);
+    if (commitment.compassId)
+        log(describeBoundCompass(commitment));
+    log(`Priority:  ${describeCommitmentPriority(commitment.priority)}`);
     if (commitment.target?.outcome)
         log(`Outcome:   ${commitment.target.outcome}`);
     if (commitment.target?.deadlineAt)
@@ -1184,6 +1343,13 @@ scheduleIssues) {
     log(`Delivery:  ${(0, commitment_product_1.deliveryLabel)(commitment.delivery?.mode)}${commitment.delivery?.repo ? ` · ${commitment.delivery.repo}` : ''}${commitment.delivery?.baseBranch ? ` → ${commitment.delivery.baseBranch}` : ''}`);
     log(`Concurrency: ${describeCommitmentConcurrency(commitment)}`);
     log(`Evidence gate: ${describeEvidenceGate(commitment)}`);
+    // How much it may interrupt the owner (OSK-21120). A server that sent no policy prints
+    // nothing, rather than a guess that reads as "unlimited".
+    if (commitment.policy) {
+        for (const line of (0, commitment_attention_copy_1.nudgeSettingLines)((0, commitment_attention_copy_1.nudgeSettingsFromPolicy)(commitment.policy)))
+            log(line);
+        log(`Quiet hours: ${(0, commitment_attention_copy_1.describeQuietHours)(commitment.policy.quietHours)}`);
+    }
     const criteria = commitment.target?.successCriteria || [];
     const evidenceHealth = latestCheck?.inputs?.evidenceHealth;
     const evidenceLine = describeEvidenceHealth(evidenceHealth, criteria.length);
@@ -1730,6 +1896,8 @@ function formatCommitmentCycles(page) {
                 lines.push(`             run ${run.id} report: ${run.reportPayload.status === 'rejected' ? 'structured report rejected; plain summary used' : 'structured report validated (delivery tracked separately)'}`);
             for (const line of hypothesisRefusalLines(run))
                 lines.push(`             ${line}`);
+            for (const line of wakeOutcomeLines(run))
+                lines.push(`             ${line}`);
             if (!['machine', 'contract', 'work'].includes(run.failureClass))
                 continue;
             const owner = run.failureOwner === 'model' ? 'model' : run.failureOwner || 'work';
@@ -1784,6 +1952,20 @@ const HYPOTHESIS_REFUSAL_REASON = {
 function hypothesisRefusalLines(run) {
     return (run.hypothesisRefusals || []).map((refusal) => `${refusal.count} ${refusal.count === 1 ? 'hypothesis' : 'hypotheses'} not recorded: ${HYPOTHESIS_REFUSAL_REASON[refusal.reason] || refusal.reason} (${refusal.reason})`);
 }
+/**
+ * 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).
+ */
+function wakeOutcomeLines(run) {
+    const wake = run.wake;
+    if (!wake?.detail)
+        return [];
+    const label = wake.status === 'awaiting_approval' ? 'wake request waiting' : 'wake not armed';
+    return [
+        `${label}: ${wake.detail}${wake.reason ? ` (${wake.reason})` : ''}`,
+        ...(wake.fix ? [`  Fix: ${wake.fix}`] : []),
+    ];
+}
 function formatCommitmentExplanation(explanation) {
     const cycle = explanation.cycle;
     const lines = [
@@ -1819,6 +2001,8 @@ function formatCommitmentExplanation(explanation) {
                 lines.push(`  run ${run.id} report: ${run.reportPayload.status === 'rejected' ? 'structured report rejected; plain summary used' : 'structured report validated (delivery tracked separately)'}`);
             for (const line of hypothesisRefusalLines(run))
                 lines.push(`  ${line}`);
+            for (const line of wakeOutcomeLines(run))
+                lines.push(`  ${line}`);
         }
     }
     lines.push(...permissionLines(explanation.permissions));
@@ -1827,6 +2011,10 @@ function formatCommitmentExplanation(explanation) {
 /**
  * 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).
  */
 function renderListPageHint(page, log) {
     if (page?.has_more === true && page.next_cursor) {

package/dist/lib/compass-body-help.d.ts

@@ -0,0 +1,20 @@
+/**
+ * What `--json-body` takes on `skrr compass create` and `skrr compass update` (OSK-21154).
+ *
+ * The flag's help said only "a JSON file with the full body", so the field names, the
+ * invariant-target limit and the quiet-hours rules were found by guessing and by being refused. One
+ * declaration, read by both commands' help so they cannot drift apart. The server owns every rule
+ * stated here (`api/server/services/AgentCompass/CompassPolicyContract.js` and the route schemas); the
+ * limits are written out because a help screen is read before the first request is sent, and
+ * `docs/cli/SKRR_COMPASS.md` ("Body shape") carries the same table.
+ *
+ * ONE SHORT LINE PER FIELD, each beginning with its full path. oclif runs a description through
+ * `wrap-ansi` (hard wrap at the terminal width minus 2, 80 when not a terminal) which TRIMS every
+ * line's leading spaces, so the indentation this list used to carry collapsed (`id` and
+ * `description` read as top-level fields) and its long lines broke mid-sentence. A path prefix is
+ * not whitespace, so the nesting survives, and no line is longer than 77 characters, so none wraps
+ * (`help.spec.ts` runs the real wrap over it) (OSK-21243).
+ */
+export declare const COMPASS_BODY_HELP: string;
+/** An example body: two targets (one domain-scoped, one general) and a quiet-hours window. */
+export declare const COMPASS_BODY_EXAMPLE = "# compass.json\n{\n  \"title\": \"Production reliability\",\n  \"invariantTargets\": [\n    { \"id\": \"api-latency\", \"domainKind\": \"reliability\", \"description\": \"p99 API latency stays under 300 ms\" },\n    { \"id\": \"general\", \"description\": \"Nothing the owner has not seen ships on a Friday\" }\n  ],\n  \"autonomyDefaults\": {\n    \"mode\": \"ask_first\",\n    \"quietHours\": { \"enabled\": true, \"start\": \"22:00\", \"end\": \"07:00\", \"timezone\": \"America/New_York\" }\n  }\n}";

package/dist/lib/compass-body-help.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMPASS_BODY_EXAMPLE = exports.COMPASS_BODY_HELP = void 0;
+/**
+ * What `--json-body` takes on `skrr compass create` and `skrr compass update` (OSK-21154).
+ *
+ * The flag's help said only "a JSON file with the full body", so the field names, the
+ * invariant-target limit and the quiet-hours rules were found by guessing and by being refused. One
+ * declaration, read by both commands' help so they cannot drift apart. The server owns every rule
+ * stated here (`api/server/services/AgentCompass/CompassPolicyContract.js` and the route schemas); the
+ * limits are written out because a help screen is read before the first request is sent, and
+ * `docs/cli/SKRR_COMPASS.md` ("Body shape") carries the same table.
+ *
+ * ONE SHORT LINE PER FIELD, each beginning with its full path. oclif runs a description through
+ * `wrap-ansi` (hard wrap at the terminal width minus 2, 80 when not a terminal) which TRIMS every
+ * line's leading spaces, so the indentation this list used to carry collapsed (`id` and
+ * `description` read as top-level fields) and its long lines broke mid-sentence. A path prefix is
+ * not whitespace, so the nesting survives, and no line is longer than 77 characters, so none wraps
+ * (`help.spec.ts` runs the real wrap over it) (OSK-21243).
+ */
+exports.COMPASS_BODY_HELP = [
+    '--json-body takes the API body as a JSON file; the flags are merged over it.',
+    'Each line below names one field by its full path:',
+    'title, domain, reason: strings (reason is what the revision ledger shows)',
+    'invariantTargets[]: what the agent keeps true',
+    'invariantTargets[]: AT MOST 25: more is refused with the count sent',
+    'invariantTargets[].id: optional, unique in the list (a repeat is refused)',
+    'invariantTargets[].id: default invariant_<position>',
+    'invariantTargets[].description: required on create',
+    'invariantTargets[].domainKind: optional; leave it off ONE target',
+    'invariantTargets[].domainKind: the target without one is the general fallback',
+    'invariantTargets[].maintainedState[]: list of strings',
+    'invariantTargets[].successMetrics[]: list of strings',
+    'invariantTargets[].boundaries[]: list of strings',
+    'invariantTargets[].cadence, .escalation, .stateMonitor: advanced',
+    'invariantTargets[].learnedTactics[]: advanced; see docs/cli/SKRR_COMPASS.md',
+    'autonomyDefaults.mode: off | suggestions_only | ask_first | auto_run_limited',
+    'autonomyDefaults.mode: auto_run (short forms: suggest, auto)',
+    'autonomyDefaults.quietHours = {"enabled":true,"start":"22:00","end":"07:00"}',
+    'autonomyDefaults.quietHours.start, .end: HH:MM, 00:00 to 23:59',
+    'autonomyDefaults.quietHours: start must differ from end; refused otherwise',
+    'autonomyDefaults.quietHours.timezone: an IANA zone, e.g. America/New_York',
+    'communicationDefaults: mode, destination, fallbackDestination, quietHours',
+    'communicationDefaults.allowedDestinations[]: list of strings',
+    'communicationDefaults.requireApprovalRiskLevels[]: list of strings',
+    'communicationDefaults: any other key is stored as a note and never read',
+    'rules[]: owner-enforced, Agent owner only; see docs/cli/SKRR_COMPASS.md',
+].join('\n');
+/** An example body: two targets (one domain-scoped, one general) and a quiet-hours window. */
+exports.COMPASS_BODY_EXAMPLE = `# compass.json
+{
+  "title": "Production reliability",
+  "invariantTargets": [
+    { "id": "api-latency", "domainKind": "reliability", "description": "p99 API latency stays under 300 ms" },
+    { "id": "general", "description": "Nothing the owner has not seen ships on a Friday" }
+  ],
+  "autonomyDefaults": {
+    "mode": "ask_first",
+    "quietHours": { "enabled": true, "start": "22:00", "end": "07:00", "timezone": "America/New_York" }
+  }
+}`;

package/dist/lib/compass-refusals.d.ts

@@ -0,0 +1,35 @@
+/**
+ * compass-refusals.ts — the words for the two Compass refusals a person acts on.
+ *
+ * `COMPASS_VERSION_CONFLICT` (409) and `COMPASS_REVISION_NOT_FOUND` (404) used to reach the
+ * terminal as `HTTP_409` and `NOT_FOUND`, with the one fact that makes each actionable dropped:
+ * where the Compass is now, and which version was missing (OSK-21162, OSK-21152).
+ *
+ * The route sends the code in upper-case `error` (and now in `code` too). `refusalCodeOf` does
+ * not read the first as a code, and widening it for every route is not this module's call, so
+ * `compassRefusalCode` reads both spellings here, for these two codes only. No imports: this is
+ * pure, and `base-command` loads it.
+ */
+export declare const COMPASS_VERSION_CONFLICT = "COMPASS_VERSION_CONFLICT";
+export declare const COMPASS_REVISION_NOT_FOUND = "COMPASS_REVISION_NOT_FOUND";
+export type CompassRefusalCode = typeof COMPASS_VERSION_CONFLICT | typeof COMPASS_REVISION_NOT_FOUND;
+/**
+ * What the failing request was about, for a refusal whose remedy is a command that names it. The
+ * command sets this before it sends, as it sets `requestFieldFlags`. The server's own body wins
+ * where it carries the same fact; these cover a server that does not send it yet.
+ */
+export interface CompassRefusalContext {
+    compassId?: string;
+    agentId?: string;
+    /** The version the caller based the change on. */
+    expectedVersion?: number;
+    /** The version a revert asked for. */
+    toVersion?: number;
+}
+/** The Compass refusal an API error body carries, under `code` or the legacy `error`. */
+export declare function compassRefusalCode(body: Record<string, unknown> | null | undefined): CompassRefusalCode | undefined;
+/**
+ * The refusal as a sentence, then the command to run next on its own line (the shape
+ * `COMMITMENT_ACTIVATION_BLOCKED` uses: `→`).
+ */
+export declare function describeCompassRefusal(code: CompassRefusalCode, body: Record<string, unknown> | null | undefined, context: CompassRefusalContext, bin: string): string;

package/dist/lib/compass-refusals.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * compass-refusals.ts — the words for the two Compass refusals a person acts on.
+ *
+ * `COMPASS_VERSION_CONFLICT` (409) and `COMPASS_REVISION_NOT_FOUND` (404) used to reach the
+ * terminal as `HTTP_409` and `NOT_FOUND`, with the one fact that makes each actionable dropped:
+ * where the Compass is now, and which version was missing (OSK-21162, OSK-21152).
+ *
+ * The route sends the code in upper-case `error` (and now in `code` too). `refusalCodeOf` does
+ * not read the first as a code, and widening it for every route is not this module's call, so
+ * `compassRefusalCode` reads both spellings here, for these two codes only. No imports: this is
+ * pure, and `base-command` loads it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMPASS_REVISION_NOT_FOUND = exports.COMPASS_VERSION_CONFLICT = void 0;
+exports.compassRefusalCode = compassRefusalCode;
+exports.describeCompassRefusal = describeCompassRefusal;
+exports.COMPASS_VERSION_CONFLICT = 'COMPASS_VERSION_CONFLICT';
+exports.COMPASS_REVISION_NOT_FOUND = 'COMPASS_REVISION_NOT_FOUND';
+/** The Compass refusal an API error body carries, under `code` or the legacy `error`. */
+function compassRefusalCode(body) {
+    for (const key of ['code', 'error']) {
+        const value = body?.[key];
+        if (value === exports.COMPASS_VERSION_CONFLICT || value === exports.COMPASS_REVISION_NOT_FOUND)
+            return value;
+    }
+    return undefined;
+}
+function versionOf(value) {
+    return typeof value === 'number' && Number.isInteger(value) ? value : undefined;
+}
+/**
+ * The refusal as a sentence, then the command to run next on its own line (the shape
+ * `COMMITMENT_ACTIVATION_BLOCKED` uses: `→`).
+ */
+function describeCompassRefusal(code, body, context, bin) {
+    const compassId = context.compassId ?? '<compass-id>';
+    const agentId = context.agentId ?? '<agent-id>';
+    const current = versionOf(body?.currentVersion);
+    if (code === exports.COMPASS_VERSION_CONFLICT) {
+        const sent = versionOf(body?.expectedVersion) ?? context.expectedVersion;
+        const where = current !== undefined ? `it is at v${current} now` : 'it changed while this was being saved';
+        return (`Compass version conflict: ${where}${sent !== undefined ? `, and this change was based on v${sent}` : ''}.\n` +
+            `  → Re-read it with \`${bin} compass show ${compassId} --agent ${agentId}\`, review what changed, and retry.`);
+    }
+    const asked = versionOf(body?.toVersion) ?? context.toVersion;
+    return (`Compass revision ${asked !== undefined ? `v${asked} ` : ''}not found` +
+        `${current !== undefined ? `: the Compass is at v${current}` : ''}.\n` +
+        `  → List its versions with \`${bin} compass revisions ${compassId} --agent ${agentId}\`, then pass one as --to-version.`);
+}

package/dist/lib/compasses.d.ts

@@ -16,6 +16,21 @@ export interface CompassInvariantTarget {
     cadence?: Record<string, unknown>;
     escalation?: Record<string, unknown>;
 }
+/** What a tactic write did, as the API reports it (`POST /api/compasses/:id/tactics`). */
+export interface CompassTacticResult {
+    outcome: 'appended' | 'updated' | 'unchanged';
+    id: string;
+    description: string;
+    /** The invariant target the tactic lives on. */
+    targetInvariantId: string | null;
+    /** Tactics on that target after the write. */
+    count: number;
+    /** Tactics that rolled off the end to stay within the cap. */
+    dropped: Array<{
+        id: string;
+        description: string;
+    }>;
+}
 export interface Compass {
     id: string;
     agentId: string;
@@ -41,14 +56,20 @@ export interface Compass {
         id: string | null;
         issues: string[];
     }>;
+    /** `compass revert` only: the enforced rules before and after, and which ids were removed. */
+    rulesChanged?: {
+        from: number;
+        to: number;
+        removed?: string[];
+    };
+    /** `compass revert` only: true when the version restored held the current content, so nothing was written. */
+    unchanged?: boolean;
     invariantTargets?: CompassInvariantTarget[];
     autonomyDefaults?: Record<string, unknown>;
     communicationDefaults?: Record<string, unknown>;
-    learnedTactics?: Array<{
-        id?: string;
-        description?: string;
-    }>;
     commitments?: Array<Record<string, unknown>>;
+    /** What `compass tactic` did; present only on that response. */
+    tactic?: CompassTacticResult;
     updatedBy?: string;
     createdAt?: string;
     updatedAt?: string;
@@ -65,6 +86,12 @@ export interface CompassRevision {
     createdAt?: string;
     previousConfig?: Record<string, unknown>;
     nextConfig?: Record<string, unknown>;
+    metadata?: {
+        autoRevert?: {
+            fromVersion?: number;
+            toVersion?: number;
+        };
+    } & Record<string, unknown>;
 }
 export interface CompassTraceEvent {
     id: string;
@@ -100,9 +127,13 @@ export declare const compassApi: {
         ok: boolean;
         id: string;
         status: string;
+        /** True when the compass was archived already and nothing was written. */
+        alreadyArchived?: boolean;
     }>;
     revisions: (id: string, query: Parameters<typeof withQuery>[1]) => Promise<{
         data: CompassRevision[];
+        /** True when the ledger holds rows older than this page. */
+        has_more?: boolean;
     }>;
     trace: (id: string, query: Parameters<typeof withQuery>[1]) => Promise<CompassTrace>;
     revert: (id: string, body: Record<string, unknown>) => Promise<Compass>;
@@ -112,6 +143,51 @@ export declare const compassApi: {
     }>;
 };
 export declare function renderCompassList(rows: Compass[], log: (line: string) => void): void;
+/**
+ * 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).
+ */
+export declare function describeSettings(value: unknown, prefix?: string): string[];
+/** A quiet-hours window in words: the hours and the zone, `off`, or `not set`. */
+export declare function describeQuietHours(window: unknown): string;
+/**
+ * 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).
+ */
+export declare function describeMode(mode: unknown, authoredMode: unknown): string;
 export declare function renderCompass(compass: Compass, log: (line: string) => void): void;
+/**
+ * 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).
+ */
+export declare function describeBoundCommitments(count: number, status: string | undefined): string;
+/**
+ * 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.
+ */
+export declare function renderTacticResult(compass: Compass, log: (line: string) => void): void;
+/**
+ * `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.
+ */
+export declare function renderEffectivePolicy(policy: Record<string, unknown>, log: (line: string) => void): void;
 export declare function renderRevisionList(rows: CompassRevision[], log: (line: string) => void): void;
 export declare function renderCompassTrace(trace: CompassTrace, log: (line: string) => void): void;
+/**
+ * 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.
+ */
+export declare function revisionTypeLabel(row: CompassRevision): string;
+/**
+ * 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.
+ */
+export declare function renderRevertResult(compass: Compass, toVersion: number, agentId: string, log: (line: string) => void): void;