@skrr-ai/cli 0.1.127 → 0.1.129

package/dist/lib/agent-trigger-listing.js

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * `skrr agenda trigger list <agent>` and the triggers it did not show (OSK-21454).
+ *
+ * `/api/agents/:id/triggers` is the legacy per-agent facade and lists `scope: 'agent'` rows only. A
+ * passive agent (`agents create --initial-always-on off`) still owns system-managed Commitment
+ * triggers - the daily self-reflection check is `commitment-check:obj_agent_reflection_*`, scope
+ * `commitment_watcher` - so the one command whose name says "list this agent's triggers" answered
+ * "No triggers." while `triggers list --ref-entity agent:<id>` and the web Upcoming page listed it.
+ *
+ * The universal list, filtered by the agent ref, is the truth; this reads it and returns the rows the
+ * facade left out, marked so a person can tell the platform's from their own.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSystemManaged = isSystemManaged;
+exports.triggersMissingFromAgentList = triggersMissingFromAgentList;
+exports.isSuspended = isSuspended;
+exports.sourceLabel = sourceLabel;
+exports.systemManagedLegend = systemManagedLegend;
+function idOf(row) {
+    return typeof row.id === 'string' ? row.id : '';
+}
+function scopeKindOf(row) {
+    const scope = row.scope;
+    return typeof scope?.kind === 'string' ? scope.kind : '';
+}
+/** Created and run by the platform for a Commitment, not authored by the person. */
+function isSystemManaged(row) {
+    return row.producerOwned === true || /^commitment-(check|reflect):/.test(idOf(row));
+}
+/**
+ * The universal-list rows the per-agent facade did not return, each tagged `systemManaged`.
+ * Rows already listed are not repeated; a row with no id cannot be matched and is kept.
+ */
+function triggersMissingFromAgentList(listed, universal) {
+    const known = new Set(listed.map(idOf).filter(Boolean));
+    return universal
+        .filter((row) => !idOf(row) || !known.has(idOf(row)))
+        .map((row) => ({ ...row, systemManaged: isSystemManaged(row) }));
+}
+/** The platform marked this managed trigger suspended (Always-On is off for the agent). */
+function isSuspended(row) {
+    const management = row.management;
+    return management?.suspended === true;
+}
+/** What the SOURCE column says: the platform, the scope it belongs to, a turn capture, or nothing. */
+function sourceLabel(row, unconfirmedTurnCapture) {
+    if (row.systemManaged === true)
+        return isSuspended(row) ? 'system, suspended' : 'system';
+    if (unconfirmedTurnCapture)
+        return 'turn*';
+    if (row.systemManaged === false)
+        return scopeKindOf(row) || '-';
+    return '-';
+}
+/** The legend printed under a table that includes platform-managed rows. */
+function systemManagedLegend(agentId, bin = 'skrr') {
+    return [
+        'system = created and run by the platform for a Commitment, not by you (for example the daily self-reflection check every agent is seeded with, passive or not).',
+        '         "suspended" = the platform is holding it because Always-On is off for this agent.',
+        `         Find the Commitment behind one with: ${bin} commitments list --agent ${agentId} --include-system`,
+    ];
+}

package/dist/lib/agentic-stream.d.ts

@@ -47,6 +47,14 @@ export type AgenticStreamResult = {
      * (OSK-13543). Absent on every ordinary run.
      */
     repaired?: true;
+    /**
+     * Tool calls refused because nobody could be asked and the run was not started with
+     * `--approve-tools`, as the same one-line description the streamed `[permission]` line uses.
+     * A quiet run discards the rendering, so without this a `--no-stream --json` turn read as a
+     * completed turn that did nothing, beside an agent telling the person to resend from another
+     * surface (which a CLI cannot offer). Absent when nothing was refused.
+     */
+    permissionDenials?: string[];
     lastEvent?: AgenticStreamEvent;
 };
 /**
@@ -605,6 +613,7 @@ export declare class AgenticStreamClient {
     private readonly openQuestionPrompts;
     /** Text already written to the terminal, for suffix-only rendering. */
     private renderedText;
+    private permissionDenials;
     /** The "still waiting" line for a terminal run with no output yet (OSK-20427). */
     private waitingTimer;
     private waitingStartedAt;

package/dist/lib/agentic-stream.js

@@ -206,7 +206,10 @@ async function discardTypeAhead(input, windowMs = exports.TYPE_AHEAD_DISCARD_MS)
         process.kill(process.pid, 'SIGINT');
 }
 const permissionGeneration = (event) => JSON.stringify([
-    event.sessionId, event.toolUseId, event.permissionBinding?.epoch, event.permissionBinding?.requestId,
+    event.sessionId,
+    event.toolUseId,
+    event.permissionBinding?.epoch,
+    event.permissionBinding?.requestId,
 ]);
 const PERMISSION_DETAIL_MAX = 400;
 /**
@@ -855,6 +858,7 @@ class AgenticStreamClient {
     openQuestionPrompts = new Map();
     /** Text already written to the terminal, for suffix-only rendering. */
     renderedText = '';
+    permissionDenials = [];
     /** The "still waiting" line for a terminal run with no output yet (OSK-20427). */
     waitingTimer = null;
     waitingStartedAt = 0;
@@ -1522,7 +1526,8 @@ class AgenticStreamClient {
                 return; // a pure re-delivery — drop it whole
             const scoped = { ...event, envelopes: fresh };
             if (fresh.some((env) => env?.ev?.t === 'text' &&
-                env.ev?.publicProjection === 'lookback_answer_v1'))
+                env.ev?.publicProjection ===
+                    'lookback_answer_v1'))
                 this.publicProjection = 'lookback_answer_v1';
             // Note what never arrived before folding this batch in (OSK-7631,
             // OSK-13518). Checked against the FRESH set: a re-delivery carries old
@@ -1686,7 +1691,8 @@ class AgenticStreamClient {
         socket.on('execution:aborted', (event) => {
             if (!match(event))
                 return;
-            if (typeof event.permissionEpoch === 'string' && this.permissionEpochs.has(this.options.sessionId) &&
+            if (typeof event.permissionEpoch === 'string' &&
+                this.permissionEpochs.has(this.options.sessionId) &&
                 this.permissionEpochs.get(this.options.sessionId) !== event.permissionEpoch)
                 return;
             if (this.handover)
@@ -1697,7 +1703,8 @@ class AgenticStreamClient {
         socket.on('execution:cancelled', (event) => {
             if (!match(event))
                 return;
-            if (typeof event.permissionEpoch === 'string' && this.permissionEpochs.has(this.options.sessionId) &&
+            if (typeof event.permissionEpoch === 'string' &&
+                this.permissionEpochs.has(this.options.sessionId) &&
                 this.permissionEpochs.get(this.options.sessionId) !== event.permissionEpoch)
                 return;
             if (this.handover)
@@ -1730,7 +1737,10 @@ class AgenticStreamClient {
                 return;
             if (event.toolUseId) {
                 this.openPermissionPrompts.get(event.toolUseId)?.abort();
-                this.permissionGenerations.set(event.toolUseId, { key: permissionGeneration(event), bound: !!event.permissionBinding });
+                this.permissionGenerations.set(event.toolUseId, {
+                    key: permissionGeneration(event),
+                    bound: !!event.permissionBinding,
+                });
                 if (event.permissionBinding)
                     this.permissionEpochs.set(this.options.sessionId, event.permissionBinding.epoch);
             }
@@ -1764,21 +1774,27 @@ class AgenticStreamClient {
         // Runtime-authored application consent is exclusively an interactive app
         // decision. A TTY or --approve-tools is not that authenticated human lane.
         // Recognize malformed runtime asks too, so they never fall into generic grants.
-        if (event.purpose === 'runtime-elicitation' || event.runtimeElicitation !== undefined || event.toolName === 'ComputerUse') {
+        if (event.purpose === 'runtime-elicitation' ||
+            event.runtimeElicitation !== undefined ||
+            event.toolName === 'ComputerUse') {
             let message = 'This Computer Use request cannot be verified. Wait for a new request in the app.';
             let requestValid = false;
             try {
                 const runtime = event.runtimeElicitation;
                 (0, computer_use_1.assertComputerUseElicitationRequest)(runtime);
-                if (event.purpose !== 'runtime-elicitation' || event.toolName !== 'ComputerUse' ||
-                    event.toolUseId !== runtime.requestId || runtime.context.sessionId !== this.options.sessionId ||
+                if (event.purpose !== 'runtime-elicitation' ||
+                    event.toolName !== 'ComputerUse' ||
+                    event.toolUseId !== runtime.requestId ||
+                    runtime.context.sessionId !== this.options.sessionId ||
                     runtime.expiresAt <= Date.now())
                     throw new Error('Mismatched runtime permission');
                 const display = (text) => describePermissionTarget({ command: text }) ?? '';
-                message = [display(runtime.message),
+                message = [
+                    display(runtime.message),
                     `Choices in the app: ${runtime.options.map((option) => display(option.label)).join(' | ')}`,
                     `Expires: ${new Date(runtime.expiresAt).toISOString()}`,
-                    'Answer in the signed-in app. This CLI cannot grant or decline application access.'].join('\n');
+                    'Answer in the signed-in app. This CLI cannot grant or decline application access.',
+                ].join('\n');
                 requestValid = true;
             }
             catch {
@@ -1790,10 +1806,17 @@ class AgenticStreamClient {
             if (approvalUrl)
                 message += `\nOpen ${approvalUrl} and choose Review pending decisions.`;
             else
-                message += '\nOpen this conversation in the signed-in app and choose Review pending decisions.';
+                message +=
+                    '\nOpen this conversation in the signed-in app and choose Review pending decisions.';
             if (event.toolUseId)
                 this.browserPermissionRequests.add(event.toolUseId);
-            this.emit({ ...event, type: 'permission.browser_required', requestValid, approvalUrl, message });
+            this.emit({
+                ...event,
+                type: 'permission.browser_required',
+                requestValid,
+                approvalUrl,
+                message,
+            });
             return;
         }
         if (!this.options.approveTools || !this.socket) {
@@ -1802,7 +1825,10 @@ class AgenticStreamClient {
             // response was admitted. Tool execution is not confirmed.", which read like an approval.
             this.emit({ ...event, type: 'permission.denied', reason: 'noninteractive_or_not_enabled' });
             if (event.toolUseId) {
-                if (await this.sendBoundPermissionDecision(event, false, { reason: 'CLI was not started with --approve-tools', automatic: true }))
+                if (await this.sendBoundPermissionDecision(event, false, {
+                    reason: 'CLI was not started with --approve-tools',
+                    automatic: true,
+                }))
                     return;
                 this.socket?.emit('permission:deny', {
                     sessionId: this.options.sessionId,
@@ -1876,14 +1902,22 @@ class AgenticStreamClient {
         this.emit({ ...event, type: approved ? 'permission.approved' : 'permission.denied' });
     }
     replayPermissionDecision(event) {
-        if (!event.permissionBinding || event.decisionStatus === undefined || event.purpose === 'task-command-once' ||
-            event.purpose === 'runtime-elicitation' || event.runtimeElicitation !== undefined || event.toolName === 'ComputerUse')
+        if (!event.permissionBinding ||
+            event.decisionStatus === undefined ||
+            event.purpose === 'task-command-once' ||
+            event.purpose === 'runtime-elicitation' ||
+            event.runtimeElicitation !== undefined ||
+            event.toolName === 'ComputerUse')
             return false;
         const generation = permissionGeneration(event);
         if (event.toolUseId) {
             this.openPermissionPrompts.get(event.toolUseId)?.abort();
             this.openPermissionPrompts.delete(event.toolUseId);
-            this.permissionGenerations.set(event.toolUseId, { key: generation, bound: true, readonly: true });
+            this.permissionGenerations.set(event.toolUseId, {
+                key: generation,
+                bound: true,
+                readonly: true,
+            });
             this.permissionEpochs.set(this.options.sessionId, event.permissionBinding.epoch);
         }
         this.firstTimeSeen('permission', generation);
@@ -1891,11 +1925,18 @@ class AgenticStreamClient {
         const status = event.decisionStatus === 'recorded' ? 'recorded' : 'delivery_unconfirmed';
         if (this.firstTimeSeen('permission-receipt', `${generation}:${valid ? status : 'unknown'}`))
             this.emit({
-                ...event, type: status === 'recorded' ? 'permission.response_recorded' : 'permission.delivery_unconfirmed',
-                status, previouslyRecorded: valid, executionConfirmed: false, readonly: true,
+                ...event,
+                type: status === 'recorded'
+                    ? 'permission.response_recorded'
+                    : 'permission.delivery_unconfirmed',
+                status,
+                previouslyRecorded: valid,
+                executionConfirmed: false,
+                readonly: true,
                 message: status === 'recorded'
                     ? 'Response recorded. Waiting for execution to admit this response; no tool execution or continuing permission grant is confirmed.'
-                    : valid ? 'Response recorded; delivery unconfirmed. Check execution or Stop before starting a new turn.'
+                    : valid
+                        ? 'Response recorded; delivery unconfirmed. Check execution or Stop before starting a new turn.'
                         : 'Your response could not be confirmed. Check execution or Stop before starting a new turn.',
             });
         return true;
@@ -1905,7 +1946,9 @@ class AgenticStreamClient {
         if (!event.permissionBinding)
             return false;
         const generation = permissionGeneration(event);
-        const current = () => !this.closed && !!event.toolUseId && this.permissionGenerations.get(event.toolUseId)?.key === generation &&
+        const current = () => !this.closed &&
+            !!event.toolUseId &&
+            this.permissionGenerations.get(event.toolUseId)?.key === generation &&
             !this.permissionGenerations.get(event.toolUseId)?.readonly;
         if (!current())
             return true;
@@ -1922,27 +1965,54 @@ class AgenticStreamClient {
             const timer = setTimeout(() => finish({ type: 'permission.delivery_unconfirmed', message: unknown }), 10_000);
             try {
                 if (!this.socket?.connected) {
-                    finish({ type: 'permission.response_refused', message: 'The connection is offline. No response was sent.' });
+                    finish({
+                        type: 'permission.response_refused',
+                        message: 'The connection is offline. No response was sent.',
+                    });
                     return;
                 }
                 this.socket.emit(approved ? 'permission:approve' : 'permission:deny', {
-                    sessionId: this.options.sessionId, toolUseId: event.toolUseId, toolName: event.toolName,
-                    permissionBinding: event.permissionBinding, ...extra,
+                    sessionId: this.options.sessionId,
+                    toolUseId: event.toolUseId,
+                    toolName: event.toolName,
+                    permissionBinding: event.permissionBinding,
+                    ...extra,
                 }, (receipt) => {
                     const result = receipt?.result;
-                    if (receipt?.ok === false && ['invalid', 'unauthorized'].includes(receipt.error?.code || ''))
-                        finish({ type: 'permission.response_refused', message: receipt.error?.message || 'The response was refused. No new permission was granted.' });
+                    if (receipt?.ok === false &&
+                        ['invalid', 'unauthorized'].includes(receipt.error?.code || ''))
+                        finish({
+                            type: 'permission.response_refused',
+                            message: receipt.error?.message ||
+                                'The response was refused. No new permission was granted.',
+                        });
                     else if (receipt?.ok === false)
                         finish({ type: 'permission.delivery_unconfirmed', message: unknown });
                     else if (!result || result.toolUseId !== event.toolUseId)
                         finish({ type: 'permission.delivery_unconfirmed', message: unknown });
                     else if (result.status === 'closed')
-                        finish({ type: 'permission.response_refused', status: 'closed', message: 'This approval request is closed. No new permission was granted.' });
+                        finish({
+                            type: 'permission.response_refused',
+                            status: 'closed',
+                            message: 'This approval request is closed. No new permission was granted.',
+                        });
                     else if (result.status === 'delivery_unconfirmed')
-                        finish({ type: 'permission.delivery_unconfirmed', status: result.status, previouslyRecorded: result.previouslyRecorded === true,
-                            message: result.previouslyRecorded === true ? 'Response recorded; delivery unconfirmed. Check execution or Stop before starting a new turn.' : unknown });
-                    else if (receipt.ok === true && result.accepted === true && ['recorded', 'admitted'].includes(result.status || ''))
-                        finish({ type: 'permission.response_recorded', status: result.status, message: 'Response recorded. This does not confirm tool execution or a continuing permission grant.' });
+                        finish({
+                            type: 'permission.delivery_unconfirmed',
+                            status: result.status,
+                            previouslyRecorded: result.previouslyRecorded === true,
+                            message: result.previouslyRecorded === true
+                                ? 'Response recorded; delivery unconfirmed. Check execution or Stop before starting a new turn.'
+                                : unknown,
+                        });
+                    else if (receipt.ok === true &&
+                        result.accepted === true &&
+                        ['recorded', 'admitted'].includes(result.status || ''))
+                        finish({
+                            type: 'permission.response_recorded',
+                            status: result.status,
+                            message: 'Response recorded. This does not confirm tool execution or a continuing permission grant.',
+                        });
                     else
                         finish({ type: 'permission.delivery_unconfirmed', message: unknown });
                 });
@@ -1952,7 +2022,12 @@ class AgenticStreamClient {
             }
         });
         if (current())
-            this.emit({ ...event, ...result, decision: approved ? 'allow' : 'deny', executionConfirmed: false });
+            this.emit({
+                ...event,
+                ...result,
+                decision: approved ? 'allow' : 'deny',
+                executionConfirmed: false,
+            });
         return true;
     }
     async handleQuestion(event) {
@@ -2020,7 +2095,8 @@ class AgenticStreamClient {
     handlePermissionCancel(event) {
         const toolUseId = typeof event.toolUseId === 'string' ? event.toolUseId : undefined;
         const generation = toolUseId ? this.permissionGenerations.get(toolUseId) : undefined;
-        if (generation && (generation.bound || event.permissionBinding) &&
+        if (generation &&
+            (generation.bound || event.permissionBinding) &&
             (!event.permissionBinding || generation.key !== permissionGeneration(event)))
             return;
         const open = toolUseId ? this.openPermissionPrompts.get(toolUseId) : undefined;
@@ -2058,8 +2134,17 @@ class AgenticStreamClient {
         if (questionId)
             this.openQuestionPrompts.delete(questionId);
         open?.abort();
+        // `answered` is the server telling every surface that SOMEONE answered. When
+        // this client's own answer comes back as one there is nothing to report (it
+        // already printed `question.answered`); when another surface answered while
+        // this prompt was open, the prompt was just closed and that is worth saying.
+        if (event.reason === 'answered' && !open)
+            return;
         this.emit({
             ...event,
+            ...(event.reason === 'answered' && !event.message
+                ? { message: 'This question was answered in another window.' }
+                : {}),
             type: 'question.cancelled',
             promptClosed: Boolean(open),
         });
@@ -2206,13 +2291,26 @@ class AgenticStreamClient {
         // result, so there the line goes to stderr (OSK-13543).
         if (!this.options.jsonl && this.renderHandoverStatus(event))
             return;
-        if (event.type === 'permission.browser_required' && (this.options.quiet || !this.options.jsonl)) {
+        if (event.type === 'permission.browser_required' &&
+            (this.options.quiet || !this.options.jsonl)) {
             const output = this.options.quiet
-                ? this.options.statusOutput ?? process.stderr
-                : this.options.output ?? process.stdout;
+                ? (this.options.statusOutput ?? process.stderr)
+                : (this.options.output ?? process.stdout);
             output.write(`\n[application permission] ${String(event.message)}\n`);
             return;
         }
+        if (event.type === 'permission.denied' && event.reason === 'noninteractive_or_not_enabled') {
+            const described = describePermission(event);
+            // The stream asks and is refused twice for one call (observed: both appear, identical), and
+            // the result should name a refused call once.
+            if (!this.permissionDenials.includes(described))
+                this.permissionDenials.push(described);
+            // A quiet run withholds the answer's rendering, not a refusal: say it on stderr, as the
+            // handover and browser-permission lines above do, so stdout stays the final result.
+            if (this.options.quiet && !this.options.jsonl) {
+                (this.options.statusOutput ?? process.stderr).write(`\n[permission] ${described} denied: nobody could be asked, and this run was not started with --approve-tools\n`);
+            }
+        }
         // Accumulation and `onEvent` still run — only the incremental rendering is
         // suppressed, so a quiet run is the same turn with a different display.
         if (this.options.quiet)
@@ -2279,7 +2377,11 @@ class AgenticStreamClient {
             output.write(`\n[${event.type}] ${describePermission(event)}\n`);
             this.renderedText = this.answerText();
         }
-        else if (['permission.response_recorded', 'permission.delivery_unconfirmed', 'permission.response_refused'].includes(event.type)) {
+        else if ([
+            'permission.response_recorded',
+            'permission.delivery_unconfirmed',
+            'permission.response_refused',
+        ].includes(event.type)) {
             output.write(`\n[permission] ${String(event.message ?? '')}\n`);
             this.renderedText = this.answerText();
         }
@@ -2304,7 +2406,8 @@ class AgenticStreamClient {
             output.write(`\n[question] ${why}\n`);
             this.renderedText = this.answerText();
         }
-        else if (event.type === 'permission.denied' && event.reason === 'noninteractive_or_not_enabled') {
+        else if (event.type === 'permission.denied' &&
+            event.reason === 'noninteractive_or_not_enabled') {
             // Said out loud, because nobody was asked and the agent will not say it plainly: this run
             // had no terminal to ask at and was not given --approve-tools, so the call was refused.
             output.write(`\n[permission] ${describePermission(event)} denied: nobody could be asked, and this run was not started with --approve-tools\n`);
@@ -2420,10 +2523,16 @@ class AgenticStreamClient {
             try {
                 const terminal = await reconcile();
                 if (terminal && typeof terminal.text === 'string' && terminal.text) {
-                    return { text: terminal.text, ...(terminal.publicProjection ? { publicProjection: terminal.publicProjection } : {}) };
+                    return {
+                        text: terminal.text,
+                        ...(terminal.publicProjection ? { publicProjection: terminal.publicProjection } : {}),
+                    };
                 }
                 if (terminal)
-                    empty = { text: '', ...(terminal.publicProjection ? { publicProjection: terminal.publicProjection } : {}) };
+                    empty = {
+                        text: '',
+                        ...(terminal.publicProjection ? { publicProjection: terminal.publicProjection } : {}),
+                    };
             }
             catch {
                 // No evidence either way; try again, then settle on the stream.
@@ -2485,8 +2594,9 @@ class AgenticStreamClient {
         // other way round).
         // (Compared as the reader sees it: the record holds a widget as its fallback sentence,
         // which is shorter than the block the stream carried, and the raw length would never lose.)
-        if (recorded && (recorded.publicProjection === 'lookback_answer_v1' ||
-            recorded.text.length > (0, widgetTerminalText_1.widgetsAsText)(this.accumulated, { final: true }).length)) {
+        if (recorded &&
+            (recorded.publicProjection === 'lookback_answer_v1' ||
+                recorded.text.length > (0, widgetTerminalText_1.widgetsAsText)(this.accumulated, { final: true }).length)) {
             this.accumulated = recorded.text;
             this.publicProjection = recorded.publicProjection;
         }
@@ -2522,6 +2632,7 @@ class AgenticStreamClient {
             text: this.accumulated,
             status,
             ...(status === 'completed' && event.repaired === true ? { repaired: true } : {}),
+            ...(this.permissionDenials.length ? { permissionDenials: [...this.permissionDenials] } : {}),
             lastEvent: event,
         };
         this.resolve(this.terminalResult);

package/dist/lib/command-miss.js

@@ -359,8 +359,17 @@ function nearestCommands(id, all, limit = 3) {
         // A third of the length keeps this to genuine near-misses; without a bound
         // every miss suggests three unrelated commands, which is noise wearing the
         // shape of help.
-        .filter(({ d }) => d <= Math.max(2, Math.floor(id.length / 3)))
-        .sort((x, y) => x.d - y.d)
+        // A command NESTED under what was typed (`northstars:intents` -> `northstars:intents:list`)
+        // is the correction the reader was reaching for, whatever its edit distance, so it is
+        // neither bound-filtered nor ranked by distance. Distance alone kept `intents:decide` out
+        // and put shorter siblings ahead of `intents:list`, so `northstars intents <id>` was
+        // answered with "Did you mean: northstars create, northstars delete, northstars intents
+        // list?" and the first guess a reader acts on was a destructive one.
+        .filter(({ d, candidate }) => candidate.startsWith(`${id}:`) || d <= Math.max(2, Math.floor(id.length / 3)))
+        .sort((x, y) => {
+        const nested = (c) => (c.startsWith(`${id}:`) ? 0 : 1);
+        return nested(x.candidate) - nested(y.candidate) || x.d - y.d;
+    })
         .slice(0, limit)
         .map(({ candidate }) => candidate));
 }

package/dist/lib/commitment-attention-copy.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 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).
+ */
+/** What the owner can type for `--max-nudges`, as `--help` prints it. */
+export declare const MAX_NUDGES_FLAG_HELP: string;
+/**
+ * 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.
+ */
+export declare function parseMaxNudgesFlag(raw: string | undefined): number | null | undefined;
+/** `null` and an unset cap are "no daily limit"; `0` is a mute; N is "at most N a day". */
+export declare function describeNudgeCap(value: unknown): string;
+/** The least time the platform leaves between two nudges to you. */
+export declare function describeNudgeGap(ms: unknown): string;
+/** The back-off for a person who is not answering. The server's default count is 2. */
+export declare function describeNoReplyRule(noReply: {
+    enabled?: boolean;
+    afterNudges?: number;
+} | null | undefined): string;
+export type NudgeSettings = {
+    /** `null` = unlimited, `0` = muted. `undefined` = never set, which is unlimited. */
+    maxUserNudgesPerDay?: number | null;
+    minUserNudgeIntervalMs?: number | null;
+    noReply?: {
+        enabled?: boolean;
+        afterNudges?: number;
+    } | null;
+};
+/** Read the three settings out of a stored `policy`. */
+export declare function nudgeSettingsFromPolicy(policy: Record<string, any>): NudgeSettings;
+/**
+ * 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.
+ */
+export declare function nudgeSettingLines(settings: NudgeSettings, { withNoReply }?: {
+    withNoReply?: boolean;
+}): string[];
+/** What a time of day is, in the words a person can type. */
+export declare const 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).
+ */
+export declare const QUIET_HOURS_HELP: string;
+/**
+ * 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).
+ */
+export declare const EVENT_SOURCES_HELP: string;
+/**
+ * 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 `[]`.
+ */
+export declare function describeEventSources(allowed: unknown): string;
+/**
+ * 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.
+ */
+export declare function quietHoursInputProblem(policy: unknown): string | null;
+type QuietHoursPolicy = {
+    enabled?: boolean;
+    start?: string;
+    end?: string;
+    timezone?: string;
+} | null;
+/**
+ * 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.
+ */
+export declare function describeQuietHours(quietHours: QuietHoursPolicy | undefined): string;
+/**
+ * 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.
+ */
+export declare function describeQuietHoursEnd(quietHours: {
+    end?: string;
+    endsAt?: string | null;
+    timezone?: string;
+} | null | undefined): string | null;
+export {};