@skrr-ai/cli 0.1.47 → 0.1.48

package/dist/lib/commitments.d.ts

@@ -16,21 +16,14 @@
  * Two `kind`s: `achieve` (bounded, deadline-bearing) and `maintain` (perpetual
  * "hold this state", derived from a Compass invariant — not authored here).
  */
-import { COMMITMENT_WATCHED_SOURCES, COMMITMENT_TEMPLATE_IDS, COMMITMENT_CADENCE_MODES, COMMITMENT_CADENCE_TIME_PATTERN, COMMITMENT_CADENCE_MAX_TIMES, COMMITMENT_AUTONOMY_MODES, COMMITMENT_EXECUTION_ISOLATION_MODES } from '@skrr-ai/data-provider';
+import { COMMITMENT_WATCHED_SOURCES, COMMITMENT_TEMPLATE_IDS, COMMITMENT_CADENCE_MODES, COMMITMENT_CADENCE_TIME_PATTERN, COMMITMENT_CADENCE_MAX_TIMES, COMMITMENT_AUTONOMY_MODES, COMMITMENT_EXECUTION_ISOLATION_MODES, COMMITMENT_STATUSES, COMMITMENT_KIND_VALUES } from '@skrr-ai/data-provider';
 import type { CommitmentCheck, CommitmentChecksResponse, Commitment, CommitmentActionProposal, CommitmentListResponse, CommitmentPlanResponse, CommitmentStatusResponse, CommitmentWorkLink, CommitmentExecutionReceiptListResponse, CommitmentExecutionReceiptQuarterlyMetricsResponse, CommitmentCapabilitySource, CommitmentDeliveryPatchResponse, CommitmentDeliveryBundleResponse } from '@skrr-ai/data-provider';
 import { withQuery } from './triggers';
-export { COMMITMENT_WATCHED_SOURCES, COMMITMENT_TEMPLATE_IDS, COMMITMENT_CADENCE_MODES, COMMITMENT_CADENCE_TIME_PATTERN, COMMITMENT_CADENCE_MAX_TIMES, };
+export { COMMITMENT_WATCHED_SOURCES, COMMITMENT_TEMPLATE_IDS, COMMITMENT_CADENCE_MODES, COMMITMENT_CADENCE_TIME_PATTERN, COMMITMENT_CADENCE_MAX_TIMES, COMMITMENT_STATUSES, COMMITMENT_KIND_VALUES, };
 export type { CommitmentCheck, CommitmentChecksResponse, Commitment, CommitmentActionProposal, CommitmentListResponse, CommitmentPlanResponse, CommitmentStatusResponse, CommitmentWorkLink, };
 /** Derived from the installed compatibility vocabulary so the CLI remains
  * safe even while data-provider and CLI packages roll out separately. */
 export declare const COMMITMENT_AUTHORABLE_CADENCE_MODES: ("manual" | "daily" | "interval" | "event_plus_interval")[];
-/**
- * oclif's `options:` needs runtime arrays, but data-provider models these two as
- * union TYPES only. The values live here — and both directions of drift are a
- * COMPILE error: `satisfies` rejects an invalid or extra value, and the
- * `_Exhaustive*` guards fail to resolve if a canonical value is missing.
- */
-export declare const COMMITMENT_STATUSES: readonly ["draft", "active", "paused", "completed", "cancelled", "archived"];
 /**
  * Autonomy ladder — how much the commitment may act without asking.
  *
@@ -66,6 +59,12 @@ export declare const MAX_COMMITMENT_INTERVAL_MS: number;
  */
 export type CommitmentView = Partial<Commitment>;
 export type CommitmentCheckView = Partial<CommitmentCheck>;
+/** The `object:'list'` envelope every per-commitment read list now answers. */
+export type CommitmentListPage = {
+    data: unknown[];
+    has_more?: boolean;
+    next_cursor?: string | null;
+};
 export type CommitmentPreflightReport = {
     verdict: 'ready' | 'needs_review' | 'blocked';
     capabilities?: CommitmentCapabilitySource[];
@@ -204,6 +203,11 @@ export declare const commitmentApi: {
      * anything failing.
      */
     list: (query?: Parameters<typeof withQuery>[1]) => Promise<CommitmentListResponse>;
+    /**
+     * Fleet-level liveness sweep health (OSK-10958): when the reconciler last
+     * swept, how stale that is, and the tally it last persisted. Aggregate only.
+     */
+    livenessSweep: () => Promise<Record<string, unknown>>;
     manifest: (id: string) => Promise<Record<string, unknown>>;
     import: (body: Record<string, unknown>) => Promise<{
         commitment: {
@@ -249,10 +253,14 @@ export declare const commitmentApi: {
     }>;
     plan: (body: Record<string, unknown>) => Promise<CommitmentPlanResponse>;
     checkNow: (id: string) => Promise<Record<string, unknown>>;
-    checks: (id: string, limit?: number) => Promise<CommitmentChecksResponse>;
-    actionHistory: (id: string, limit?: number) => Promise<{
-        data: unknown[];
-    }>;
+    checks: (id: string, query?: {
+        limit?: number;
+        cursor?: string;
+    }) => Promise<CommitmentChecksResponse>;
+    actionHistory: (id: string, query?: {
+        limit?: number;
+        cursor?: string;
+    }) => Promise<CommitmentListPage>;
     actionProposals: (id: string, query?: {
         status?: string;
         limit?: number;
@@ -295,7 +303,11 @@ export declare const commitmentApi: {
     autonomy: (id: string, body: Record<string, unknown>) => Promise<Commitment>;
     mode: (id: string, body: Record<string, unknown>) => Promise<Commitment>;
     delivery: (id: string, body: Record<string, unknown>) => Promise<Commitment>;
-    receipts: (id: string, limit?: number) => Promise<CommitmentExecutionReceiptListResponse>;
+    receipts: (id: string, query?: {
+        limit?: number;
+        checkId?: string;
+        runId?: string;
+    } | number) => Promise<CommitmentExecutionReceiptListResponse>;
     receiptQuarterlyMetrics: (id: string, year: number, quarter: number) => Promise<CommitmentExecutionReceiptQuarterlyMetricsResponse>;
     deliveryPatch: (id: string, taskId: string) => Promise<CommitmentDeliveryPatchResponse>;
     deliveryBundle: (id: string, taskId: string) => Promise<CommitmentDeliveryBundleResponse>;
@@ -306,9 +318,8 @@ export declare const commitmentApi: {
     cases: (id: string, query?: {
         limit?: number;
         status?: string;
-    }) => Promise<{
-        data: unknown[];
-    }>;
+        cursor?: string;
+    }) => Promise<CommitmentListPage>;
     caseDetail: (id: string, caseId: string) => Promise<Record<string, unknown>>;
     remediationProposals: (id: string, query?: {
         caseId?: string;
@@ -329,19 +340,61 @@ export declare const commitmentApi: {
      * reference it stay resolvable. Refused for an active or system-managed
      * commitment — see CommitmentControl.deleteCommitment.
      */
-    remove: (id: string, reason?: string) => Promise<Record<string, unknown>>;
+    remove: (id: string, reason?: string, opts?: {
+        stopOpenWork?: boolean;
+    }) => Promise<Record<string, unknown>>;
+    /** What a delete would leave behind. Read-only. */
+    deletionPreview: (id: string) => Promise<Record<string, unknown>>;
+    /** Un-delete. Returns the Commitment PAUSED, never active. */
+    restore: (id: string) => Promise<Commitment>;
     trace: (id: string, query?: {
         limit?: number;
         cursor?: string;
     }) => Promise<Record<string, unknown>>;
     ledger: (id: string, query?: Record<string, string | number | undefined>) => Promise<Record<string, unknown>>;
     wakeCapabilities: (id: string) => Promise<CommitmentWakeCapabilities>;
-    dailyMetrics: (id: string, limit?: number) => Promise<{
-        data: unknown[];
-    }>;
+    dailyMetrics: (id: string, query?: {
+        limit?: number;
+        cursor?: string;
+    }) => Promise<CommitmentListPage>;
     cadenceDecisions: (id: string, limit?: number) => Promise<{
         data: unknown[];
     }>;
+    /**
+     * What the NEXT check would decide, computed without taking it.
+     *
+     * Every other read on this object is retrospective. This one stops at the
+     * DecisionEnvelope → Arbiter boundary — no Check row, no budget debit, no
+     * delivery gate, no contract write — so it is the only way to answer "what is
+     * this commitment about to do" before it does it. Worth its own command for
+     * the same reason `trigger-status` is: when a commitment is about to nudge
+     * somebody and nobody can say why, the posture and its policy trail are the
+     * answer, and re-running a real check to find out changes the thing you are
+     * trying to observe.
+     */
+    nextTick: (id: string) => Promise<CommitmentNextTickProjection>;
+    /**
+     * The accounting SHADOW readout behind allowance accounting.
+     *
+     * WORKSPACE-scoped despite hanging off one commitment's id: it aggregates
+     * every closed daily metric in the workspace, because the question it answers
+     * is "does this workspace have enough closed evidence to activate" rather than
+     * "what has this commitment spent". `cost` is the per-commitment question.
+     */
+    accountingReadout: (id: string) => Promise<CommitmentAccountingReadout>;
+    /**
+     * Closed-period spend for ONE commitment over a UTC day window.
+     *
+     * `costStatus` is the load-bearing field, not the dollar figure: `partial` and
+     * `unavailable` mean some runs carried no cost attribution at all, so the
+     * number understates the spend and a caller that printed it bare would be
+     * quietly wrong. The server refuses a window that is not on UTC day
+     * boundaries, so the caller builds one rather than passing a wall-clock time.
+     */
+    cost: (id: string, window: {
+        from: string;
+        to: string;
+    }) => Promise<CommitmentCostWindow>;
     /**
      * What this commitment's RUNS claim to have seen (agent-as-sensor).
      *
@@ -363,17 +416,15 @@ export declare const commitmentApi: {
         limit?: number;
         investigationKey?: string;
         status?: string;
-    }) => Promise<{
-        data: unknown[];
-    }>;
+        cursor?: string;
+    }) => Promise<CommitmentListPage>;
     observations: (id: string, query?: {
         limit?: number;
         declaredOnly?: boolean;
         changedOnly?: boolean;
         since?: string;
-    }) => Promise<{
-        data: unknown[];
-    }>;
+        cursor?: string;
+    }) => Promise<CommitmentListPage>;
     /** One-tap feedback on a check — the signal Reflection retunes cadence from. */
     checkFeedback: (id: string, checkId: string, body: Record<string, unknown>) => Promise<Record<string, unknown>>;
     /** Bounded, named corrections — never a free-form contract edit. */
@@ -383,6 +434,89 @@ export declare const commitmentApi: {
     linkGoal: (id: string, goalId: string) => Promise<Record<string, unknown>>;
     unlinkGoal: (id: string, goalId: string) => Promise<Record<string, unknown>>;
 };
+/**
+ * Shape of `GET /:id/next-tick`.
+ *
+ * `envelope` is the full DecisionEnvelope — large, versioned, and only useful
+ * under `--json` — so it stays `unknown` here rather than being half-typed into
+ * something a renderer would be tempted to trust.
+ */
+export interface CommitmentNextTickProjection {
+    object?: string;
+    commitmentId?: string;
+    projectedAt?: string;
+    envelope?: Record<string, unknown>;
+    /**
+     * OSK-11433 — the stored liveness verdict, carried alongside the projected
+     * envelope because the projection reads world-model delta, not run
+     * outcomes: a commitment whose dispatches are all refused still projects
+     * on_track, and without this field the two honest answers contradict
+     * silently across surfaces.
+     */
+    health?: string;
+    liveness?: {
+        observedAt?: string;
+        diagnosisKind?: string;
+        terminalDispositionCensus?: {
+            workFailures?: number;
+            budgetRefusals?: number;
+            terminal?: number;
+        };
+    };
+    decision?: {
+        posture?: string;
+        health?: string;
+        confidence?: number;
+        riskLevel?: string;
+        whyNow?: string;
+        actionPlan?: Array<{
+            kind?: string;
+            type?: string;
+            summary?: string;
+            title?: string;
+        }>;
+        policyTrace?: Array<{
+            rule?: string;
+            decision?: string;
+            reason?: string;
+        }>;
+    };
+}
+/** Shape of `GET /:id/accounting-readout`. */
+export interface CommitmentAccountingReadout {
+    windowDays?: number;
+    evidenceDays?: number;
+    source?: string;
+    attempts?: number;
+    advancements?: number;
+    netAdvancements?: number;
+    allowanceAttemptDivergence?: number;
+    costUsdMicros?: number;
+    costRunCount?: number;
+    costReportedRunCount?: number;
+    costUnavailableRunCount?: number;
+    costStatus?: 'reported' | 'partial' | 'unavailable' | 'not_applicable';
+    recommendedAttemptMultiplier?: number | null;
+    multiplierDerivation?: string;
+    canActivate?: boolean;
+    activationBlocker?: string | null;
+    noneByReason?: Record<string, number>;
+    advancementsByKind?: Record<string, number>;
+    /** The mode the workspace ASKED for, which `canActivate` may still withhold. */
+    requestedMode?: string;
+}
+/** Shape of `GET /:id/cost`. */
+export interface CommitmentCostWindow {
+    commitmentId?: string;
+    from?: string;
+    to?: string;
+    dayCount?: number;
+    costUsdMicros?: number;
+    runCount?: number;
+    reportedRunCount?: number;
+    unavailableRunCount?: number;
+    costStatus?: 'reported' | 'partial' | 'unavailable' | 'not_applicable';
+}
 /** Shape of `GET /:id/wake-capabilities`. */
 export interface CommitmentWakeCapabilities {
     workPromotionModel?: 'monitor_prepare_execute_v1';
@@ -481,6 +615,14 @@ export type EvidenceHealthView = {
  * is noise in a summary someone reads to find what is wrong.
  */
 export declare function describeEvidenceHealth(health?: EvidenceHealthView | null, criteriaCount?: number): string | undefined;
+/**
+ * `stalled` is a verdict, not a reason. Printed bare it reads like `unknown`
+ * with a harsher word, and the operator's next move is to go and read run
+ * history to find what the reconciler had already decided. Returns undefined
+ * for every other health value, including `unknown` — "nobody has judged" has
+ * no diagnosis to name.
+ */
+export declare function describeStalledHealth(commitment: CommitmentView): string | undefined;
 /** Render an interval back as a compact human string. */
 export declare function describeIntervalMs(ms: number | undefined): string;
 /**
@@ -619,10 +761,41 @@ type ReadModelRecord = Record<string, unknown>;
 export declare function renderCommitmentLedger(ledger: ReadModelRecord, log: (line: string) => void): void;
 /** Human view for the ordered commitment trace. */
 export declare function renderCommitmentTrace(trace: ReadModelRecord, log: (line: string) => void): void;
-export declare function renderCommitmentObservations(response: ReadModelRecord, log: (line: string) => void): void;
+/**
+ * Print the continuation hint for a paged `object:'list'` response — the line
+ * that makes history beyond the newest page reachable instead of invisible.
+ */
+export declare function renderListPageHint(page: {
+    has_more?: boolean;
+    next_cursor?: string | null;
+} | undefined, log: (line: string) => void): void;
+export declare function renderCommitmentObservations(response: ReadModelRecord, log: (line: string) => void, options?: {
+    emptyMessage?: string;
+}): void;
 /** Human view for causal hypotheses. */
-export declare function renderCommitmentHypotheses(response: ReadModelRecord, log: (line: string) => void): void;
+export declare function renderCommitmentHypotheses(response: ReadModelRecord, log: (line: string) => void, options?: {
+    emptyMessage?: string;
+}): void;
 /** Human view for the commitment → work lineage projection. */
 export declare function renderCommitmentLineage(lineage: ReadModelRecord, log: (line: string) => void): void;
 /** Human view for daily control-loop metrics. */
 export declare function renderCommitmentMetrics(response: ReadModelRecord, log: (line: string) => void): void;
+/** Human view for the case list — one row per durable problem case. */
+export declare function renderCommitmentCases(response: ReadModelRecord, log: (line: string) => void): void;
+/**
+ * Human view for one case — a bounded digest, never the raw document.
+ *
+ * A case accumulates factRefs, hypothesisRefs, actionRefs, and receipts with
+ * no per-case bound, and the route projects the whole thing again as `trace`.
+ * Printing the payload verbatim produced a 93k-line dump for a single case
+ * (OSK-10952); the summary counts and the most recent entries answer "what is
+ * this case and what happened last" in one screen, and `--json` stays the
+ * opt-in for the full document.
+ */
+export declare function renderCommitmentCaseDetail(response: ReadModelRecord, log: (line: string) => void, options?: {
+    maxEntries?: number;
+}): void;
+/** Human view for the remediation-proposal list. */
+export declare function renderCommitmentRemediationProposals(response: ReadModelRecord, log: (line: string) => void): void;
+/** Human view for one frozen remediation proposal. */
+export declare function renderCommitmentRemediationProposal(response: ReadModelRecord, log: (line: string) => void): void;