@skrr-ai/cli 0.1.131 → 0.1.132

package/dist/commands/agent/message/send.d.ts

@@ -118,6 +118,8 @@ export default class AgentMessageSend extends BaseCommand {
     private submitAsSession;
     private submitAsHuman;
 }
+/** Keep stdout machine-readable while making a slow delivery visible. */
+export declare function withSendWaitNotice<T>(send: () => Promise<T>): Promise<T>;
 export type NormalizedIntentPayload = {
     destination: CanonicalMessageDestination;
     content: {

package/dist/commands/agent/message/send.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EXIT_DELIVERY_FAILED = exports.EXIT_DELIVERY_RETRYABLE = exports.OWNER_DM_SEGMENTATION_SOFT_LIMIT = void 0;
+exports.withSendWaitNotice = withSendWaitNotice;
 exports.messageSegmentationAdvisory = messageSegmentationAdvisory;
 exports.buildSequencedRequests = buildSequencedRequests;
 exports.deliveryExitCode = deliveryExitCode;
@@ -308,30 +309,33 @@ class AgentMessageSend extends base_command_1.BaseCommand {
                 'session claim, not the request. To change it, run the task from a space in ' +
                 'the intended workspace.');
         }
-        const envelopes = [];
-        let halt;
-        for (const [index, requestPart] of requests.entries()) {
-            const envelope = sessionContext
-                ? await this.submitAsSession({
-                    sessionContext,
-                    request: requestPart,
-                    agentIdentity: agentIdentity,
-                    principalSource,
-                })
-                : await this.submitAsHuman({
-                    request: requestPart,
-                    agentIdentity: agentIdentity,
-                    principalSource,
-                });
-            envelopes.push(envelope);
-            // A part that did not reach the user must stop the sequence. Continuing
-            // would deliver thought 3 while thought 2 sits held for approval, and the
-            // user would read the update out of order — worse than not receiving the
-            // tail at all.
-            halt = sequenceHalt({ envelope, sentCount: index + 1, totalParts: requests.length });
-            if (halt)
-                break;
-        }
+        const { envelopes, halt } = await withSendWaitNotice(async () => {
+            const envelopes = [];
+            let halt;
+            for (const [index, requestPart] of requests.entries()) {
+                const envelope = sessionContext
+                    ? await this.submitAsSession({
+                        sessionContext,
+                        request: requestPart,
+                        agentIdentity: agentIdentity,
+                        principalSource,
+                    })
+                    : await this.submitAsHuman({
+                        request: requestPart,
+                        agentIdentity: agentIdentity,
+                        principalSource,
+                    });
+                envelopes.push(envelope);
+                // A part that did not reach the user must stop the sequence. Continuing
+                // would deliver thought 3 while thought 2 sits held for approval, and the
+                // user would read the update out of order — worse than not receiving the
+                // tail at all.
+                halt = sequenceHalt({ envelope, sentCount: index + 1, totalParts: requests.length });
+                if (halt)
+                    break;
+            }
+            return { envelopes, halt };
+        });
         if (flags.json) {
             // Branch on the REQUESTED part count, not the sent count: a sequence that
             // halted on its first part still has to report the parts it skipped.
@@ -524,6 +528,18 @@ class AgentMessageSend extends base_command_1.BaseCommand {
     }
 }
 exports.default = AgentMessageSend;
+/** Keep stdout machine-readable while making a slow delivery visible. */
+async function withSendWaitNotice(send) {
+    const timer = setTimeout(() => {
+        process.stderr.write('Waiting for the message outcome; the request is still in progress.\n');
+    }, 3000);
+    try {
+        return await send();
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 // Re-export the module-scope `request.post` under a local name so the transport
 // helper stays testable without pulling the whole data-provider surface into
 // scope inside every helper file.
@@ -750,6 +766,11 @@ function normalizeIntentPayload({ agentId, jsonBody, merged, }) {
     if (destinationKind !== 'slack_channel' && (overlayThreadTs || bodyDestination?.threadTs)) {
         throw invalidIntent('--thread-ts / destination.threadTs only applies to slack_channel.');
     }
+    if (destinationKind !== 'agent_email' &&
+        (merged.recipients !== undefined || merged.subject !== undefined ||
+            bodyDestination?.recipients !== undefined || bodyDestination?.subject !== undefined)) {
+        throw invalidIntent('--to / destination.recipients and --subject / destination.subject only apply to agent_email.');
+    }
     const destination = buildDestination({
         kind: destinationKind,
         bodyDestination,

package/dist/commands/agents/plan-day.d.ts

@@ -28,6 +28,7 @@ export default class AgentsPlanDay extends BaseCommand {
         'hours-start': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'hours-end': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         timezone: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'approve-next-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'save-hours': import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
@@ -44,10 +45,9 @@ export default class AgentsPlanDay extends BaseCommand {
     private fetchPending;
     private workingHoursOverride;
     /**
-     * Statuses that mean "the request ran out of time", not "the request was
-     * refused". Only these are recoverable by reading the durable draft: a 4xx
-     * means no generation started, and a 500 means the route itself failed, so
-     * polling would just report an absence as if it were a timeout.
+     * Gateway failures can interrupt a response after the planner started.
+     * Check the durable draft before suggesting another billable request; a
+     * 502 can also mean the planner never started, so do not assert that it did.
      */
     private static readonly TIMEOUT_STATUSES;
     /** Bounded, honest recovery poll. A daemon-run plan lands in ~2-4 minutes. */

package/dist/commands/agents/plan-day.js

@@ -45,6 +45,10 @@ class AgentsPlanDay extends base_command_1.BaseCommand {
         'hours-start': core_1.Flags.string({ description: 'Working-hours start (HH:MM) for the proposal' }),
         'hours-end': core_1.Flags.string({ description: 'Working-hours end (HH:MM) for the proposal' }),
         timezone: core_1.Flags.string({ description: 'IANA timezone for the working-hours window' }),
+        'approve-next-run': core_1.Flags.boolean({
+            description: 'With --approve, schedule the suggested next planning run',
+            dependsOn: ['approve'],
+        }),
         'save-hours': core_1.Flags.boolean({
             description: 'On --approve, persist the working-hours window as the agent default',
         }),
@@ -53,6 +57,14 @@ class AgentsPlanDay extends base_command_1.BaseCommand {
         this.requireAuth();
         const { args, flags } = await this.parse(AgentsPlanDay);
         const agentId = args.id;
+        if (!flags.dismiss && !flags.approve && flags.timezone) {
+            try {
+                new Intl.DateTimeFormat('en', { timeZone: flags.timezone });
+            }
+            catch {
+                this.error(`Invalid IANA timezone: ${flags.timezone}`, { exit: 1 });
+            }
+        }
         try {
             if (flags.dismiss) {
                 await this.runDismiss(agentId, flags.json);
@@ -120,12 +132,11 @@ class AgentsPlanDay extends base_command_1.BaseCommand {
         };
     }
     /**
-     * Statuses that mean "the request ran out of time", not "the request was
-     * refused". Only these are recoverable by reading the durable draft: a 4xx
-     * means no generation started, and a 500 means the route itself failed, so
-     * polling would just report an absence as if it were a timeout.
+     * Gateway failures can interrupt a response after the planner started.
+     * Check the durable draft before suggesting another billable request; a
+     * 502 can also mean the planner never started, so do not assert that it did.
      */
-    static TIMEOUT_STATUSES = new Set([408, 504, 524]);
+    static TIMEOUT_STATUSES = new Set([408, 502, 504, 524]);
     /** Bounded, honest recovery poll. A daemon-run plan lands in ~2-4 minutes. */
     static RECOVERY_ATTEMPTS = 12;
     static RECOVERY_INTERVAL_MS = 15_000;
@@ -141,9 +152,8 @@ class AgentsPlanDay extends base_command_1.BaseCommand {
             return null;
         }
         // stderr, so `--json` stdout stays a single parseable document.
-        this.warn(`Plan generation for ${agentId} outlived the request (HTTP ${status}). ` +
-            'The run is still finishing on the agent runtime and the draft is persisted when it ' +
-            'completes — waiting for it rather than starting a second run.');
+        this.warn(`The plan request for ${agentId} was interrupted (HTTP ${status}). ` +
+            'The run may still be finishing; checking for its saved draft before starting another.');
         for (let attempt = 1; attempt <= AgentsPlanDay.RECOVERY_ATTEMPTS; attempt += 1) {
             await new Promise((resolve) => setTimeout(resolve, AgentsPlanDay.RECOVERY_INTERVAL_MS));
             let pending = null;
@@ -181,6 +191,7 @@ class AgentsPlanDay extends base_command_1.BaseCommand {
             try {
                 generated = await schedule_1.scheduleApi.proposeSmartSchedule({
                     agentId,
+                    ...(flags.timezone ? { timezone: flags.timezone } : {}),
                     ...(this.workingHoursOverride(flags)
                         ? { workingHoursOverride: this.workingHoursOverride(flags) }
                         : {}),
@@ -216,6 +227,9 @@ class AgentsPlanDay extends base_command_1.BaseCommand {
         this.log('');
         this.log('This is a draft — nothing is scheduled yet.');
         this.log(`  Approve:  ${this.config.bin} agents plan-day ${agentId} --approve`);
+        if (proposal.nextRunSuggestion) {
+            this.log(`  Include next run: ${this.config.bin} agents plan-day ${agentId} --approve --approve-next-run`);
+        }
         this.log(`  Discard:  ${this.config.bin} agents plan-day ${agentId} --dismiss`);
     }
     async runApprove(agentId, flags) {
@@ -224,13 +238,20 @@ class AgentsPlanDay extends base_command_1.BaseCommand {
             this.error(`No pending plan for agent ${agentId}. Run \`${this.config.bin} agents plan-day ${agentId}\` first.`, { exit: 4 });
         }
         const todos = (0, schedule_1.proposalToApproveTodos)(proposal);
-        if (todos.length === 0) {
-            this.error('The pending proposal has no schedulable to-dos to approve.', { exit: 1 });
+        if (flags['approve-next-run'] && !proposal.nextRunSuggestion) {
+            this.error('The pending proposal has no suggested next run to approve.', { exit: 1 });
+        }
+        if (todos.length === 0 && !flags['approve-next-run']) {
+            const next = proposal.nextRunSuggestion
+                ? ` Use --approve --approve-next-run to schedule its suggested next run, or --dismiss to discard it.`
+                : ' Use --dismiss to discard it.';
+            this.error(`The pending proposal has no schedulable to-dos.${next}`, { exit: 1 });
         }
         const result = await schedule_1.scheduleApi.approveSmartSchedule({
             agentId,
             proposalId: proposal.proposalId,
             todos,
+            ...(flags['approve-next-run'] ? { approveNextRunSuggestion: true } : {}),
             ...(flags['save-hours']
                 ? { saveHoursAsDefault: true, workingHours: proposal.workingHours }
                 : {}),
@@ -254,6 +275,11 @@ class AgentsPlanDay extends base_command_1.BaseCommand {
         }
         this.log(`Approved plan ${proposal.proposalId}: created ${result.created.length} to-do(s).`);
         (0, schedule_1.renderCapacityWarning)(result.capacity, (line) => this.log(line));
+        if (flags['approve-next-run']) {
+            this.log(result.scheduledNextRun?.created
+                ? `Next planning run scheduled${result.scheduledNextRun.triggerId ? ` (${result.scheduledNextRun.triggerId})` : ''}.`
+                : `Next planning run was not created${result.scheduledNextRun?.message || result.scheduledNextRun?.skippedReason ? `: ${result.scheduledNextRun.message || result.scheduledNextRun.skippedReason}` : '.'}`);
+        }
         if (result.failed.length > 0) {
             this.log(`${result.failed.length} failed:`);
             for (const f of result.failed) {

package/dist/commands/agents/schedule-overview.d.ts

@@ -42,3 +42,17 @@ export declare function reflectionLine(reflection: TriggerDefinition): string;
  * else null. "active · next <time>" only says the loop is armed.
  */
 export declare function reflectionNoteLine(reflection: TriggerDefinition, bin: string): string | null;
+/** A trigger the Always-On control fence withholds, as `/api/upcoming` reports it. */
+export interface WithheldTrigger {
+    label?: string;
+    reason?: string;
+    reasonText?: string;
+    indeterminate?: boolean;
+}
+/**
+ * One withheld trigger as the text view prints it. The sentence the server wrote
+ * (`reasonText`: "Always-On is off for this agent") is printed rather than the code,
+ * because `disabled` alone reads as a property of the trigger when the cause is the
+ * agent's Always-On switch. A server that predates `reasonText` still prints the code.
+ */
+export declare function withheldLine(trigger: WithheldTrigger): string;

package/dist/commands/agents/schedule-overview.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.reflectionSummary = reflectionSummary;
 exports.reflectionLine = reflectionLine;
 exports.reflectionNoteLine = reflectionNoteLine;
+exports.withheldLine = withheldLine;
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../base-command");
@@ -126,7 +127,7 @@ class AgentsScheduleOverview extends base_command_1.BaseCommand {
             this.log('');
             this.log(`  ${blockedUpcoming.length} trigger(s) withheld — they will not fire as configured:`);
             for (const b of blockedUpcoming.slice(0, 8)) {
-                this.log(`    ${b.label ?? '(unlabeled)'} — ${b.reason ?? 'blocked'}`);
+                this.log(withheldLine(b));
             }
             if (blockedUpcoming.length > 8) {
                 this.log(`    … and ${blockedUpcoming.length - 8} more`);
@@ -214,6 +215,15 @@ function reflectionNoteLine(reflection, bin) {
     const note = (0, reflection_1.reflectionAutonomyNote)(reflection, bin);
     return note ? `  Note: ${note}` : null;
 }
+/**
+ * One withheld trigger as the text view prints it. The sentence the server wrote
+ * (`reasonText`: "Always-On is off for this agent") is printed rather than the code,
+ * because `disabled` alone reads as a property of the trigger when the cause is the
+ * agent's Always-On switch. A server that predates `reasonText` still prints the code.
+ */
+function withheldLine(trigger) {
+    return `    ${trigger.label ?? '(unlabeled)'} — ${trigger.reasonText ?? trigger.reason ?? 'blocked'}`;
+}
 function settledValue(result) {
     return result.status === 'fulfilled' ? result.value : undefined;
 }

package/dist/commands/agents/todos/list.d.ts

@@ -13,6 +13,7 @@ export default class AgentsTodosList extends BaseCommand {
     static flags: {
         json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         date: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        timezone: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
 }

package/dist/commands/agents/todos/list.js

@@ -21,14 +21,15 @@ class AgentsTodosList extends base_command_1.BaseCommand {
     };
     static flags = {
         json: core_1.Flags.boolean({ description: 'Output as JSON' }),
-        date: core_1.Flags.string({ description: 'Day to list (YYYY-MM-DD, UTC). Defaults to today.' }),
+        date: core_1.Flags.string({ description: 'Day to list (YYYY-MM-DD). Defaults to today in the selected timezone.' }),
+        timezone: core_1.Flags.string({ description: 'IANA timezone for the day (defaults to UTC)' }),
     };
     async run() {
         this.requireAuth();
         const { args, flags } = await this.parse(AgentsTodosList);
         let response;
         try {
-            response = await schedule_1.scheduleApi.listTodos(args.id, flags.date);
+            response = await schedule_1.scheduleApi.listTodos(args.id, flags.date, flags.timezone);
         }
         catch (err) {
             this.handleApiError(err);
@@ -37,6 +38,7 @@ class AgentsTodosList extends base_command_1.BaseCommand {
             this.printJsonResult((0, list_output_1.listResult)(response, 'todos'));
             return;
         }
+        this.log(`Day timezone: ${flags.timezone || 'UTC'}`);
         (0, schedule_1.renderTodoList)(response.todos ?? [], (line) => this.log(line));
     }
 }

package/dist/commands/commitments/create.js

@@ -107,6 +107,19 @@ function assertEventDrivenWatchedSource(payload) {
         hasEventCapableWatchedSource(payload)) {
         return;
     }
+    const sources = Array.isArray(payload.watchedSources) ? payload.watchedSources : [];
+    const hasInvalidEvents = sources.some((value) => {
+        const source = record(value);
+        const config = record(source?.config);
+        return source?.enabled !== false && Array.isArray(config?.events) &&
+            !hasStructurallyValidExplicitEvent(config);
+    });
+    if (hasInvalidEvents) {
+        throw new Error('Event-driven cadence requires at least one event-capable watched source. ' +
+            'An explicit config.events list must contain event objects with non-empty entityType and eventType, ' +
+            'for example {"entityType":"github","eventType":"check_run_failed"}. ' +
+            'Supply valid bindings, or remove config.events to use the source defaults (which may include more events).');
+    }
     throw new Error('Event-driven cadence (--event-driven or --cadence-mode event_plus_interval) requires at least one event-capable watched source. ' +
         'Add --watch github (or another event-capable source), or choose an interval-only cadence.');
 }

package/dist/commands/daemon/install.js

@@ -56,6 +56,15 @@ class DaemonInstall extends core_1.Command {
         // own comment records `skrr code run -m <model>` dying the same way. Same
         // mistake, one directory over.
         const argv = this.argv;
+        // A forwarded help request is read-only. Do not run installation preflight,
+        // bind a profile, or download software just to show the runtime's options.
+        if (argv.some((arg) => arg === '--help' || arg === '-h')) {
+            if (!(0, exec_runtime_binary_1.isCurrentRuntimeBinary)((0, exec_runtime_binary_1.findRuntimeBinary)())) {
+                this.log('The background service is not installed, so its detailed install options are unavailable. Run `skrr daemon install` to install it.');
+                return;
+            }
+            this.exit(await (0, exec_runtime_binary_1.execRuntimeBinary)(['install', '--help']));
+        }
         // Before fetching anything: a machine still carrying the previous product
         // identity's state is refused by the runtime's own install, so downloading a
         // release first only delays the same refusal (OSK-6895).

package/dist/generated/agent-guides.json

@@ -454,7 +454,7 @@
                         "id": "speaking",
                         "title": "A Commitment finds; its Agent speaks",
                         "readWhen": "a Commitment run found something and you must decide whether the owner hears of it",
-                        "tokens": 263,
+                        "tokens": 301,
                         "aliases": [],
                         "explains": []
                     },
@@ -709,7 +709,7 @@
                 ]
             }
         ],
-        "hash": "6d23de37b320e5257e7e2400c36bfc79063c76c2e3984771b96a90727e95980d",
+        "hash": "74f6b87c1bd1f851fbfe0b1ee5da04425d1b6fdafbf55445a39e121af9c4e65b",
         "tokens": 545
     },
     "routedIndex": {
@@ -1167,7 +1167,7 @@
                         "id": "speaking",
                         "title": "A Commitment finds; its Agent speaks",
                         "readWhen": "a Commitment run found something and you must decide whether the owner hears of it",
-                        "tokens": 263,
+                        "tokens": 301,
                         "aliases": [],
                         "explains": []
                     },
@@ -1353,7 +1353,7 @@
                 ]
             }
         ],
-        "hash": "c7cd104ee736aa524b486eb8858dce17a2de5f69036c7c61795ce5603ce1246e",
+        "hash": "6960740319e60127c5a1007fd32e77afada0b14442b5f6fb810a7fee1407cb63",
         "tokens": 494
     },
     "cards": {
@@ -1747,7 +1747,7 @@
             "routed": true,
             "aliases": [],
             "body": "## Concept model\n\n| Noun | Question it answers |\n| --- | --- |\n| **Compass** | What does good look like for this Agent, and what may it never trade away? |\n| **Northstar** | Which Commitments should exist, at what priority and on what budget? |\n| **Commitment** | Which outcome does this Agent keep true, and how does it keep checking? |\n| **Check** | What did one wake of a Commitment see, decide and do? |\n\nA Commitment is not a unit of work. A **Task** is one unit of work and a **Goal** is a dated\noutcome with key results; a Commitment watches both and may create Tasks, and is neither.\n\n## Decide\n\nFive mechanisms make something happen later, and the noun alone does not pick one:\n\n| Mechanism | What it is for | The signal that picks it |\n| --- | --- | --- |\n| **Follow-up** | Coming back to one thing, once or a bounded few times: a reminder, a watch, a check-in, an agreed action | The ask ends: \"look tomorrow\", \"tell me when CI is green\" |\n| **Trigger** | Running the Agent with a set prompt on a schedule, an event, once, or on demand | The person names when, and every run does the same work |\n| **Heartbeat** | Checking in on a conversation, group chat or Space at a frequency that backs off while unread | The person wants regular contact, not an outcome held |\n| **Commitment** | Keeping an outcome true: watched sources, a cadence and a loop that decides when to act | \"Keep X true\", \"watch this metric\": no end, and stale evidence matters |\n| **Workflow** | Running a durable graph of Tasks in order | Repeatable work whose steps depend on each other |\n\nA one-off \"look at it tomorrow\" is a follow-up, never a Commitment. Standing observation is a\nCommitment with a freshness contract, not a recurring trigger or a task board left running.\n\n## Workflow\n\n### Start a Commitment\n\n1. Read the Agent's Commitments first, and change one rather than add a near-duplicate.\n2. Create it and turn it on in one call: the outcome, what it watches, how often it checks, where\n   its work goes. Turning it on runs Preflight; a refusal keeps the draft and reports the code,\n   reason and fix.\n3. Leave it a draft only when the person asked to see it first.\n4. Read it back, and tell the person what it watches, how often, and whether it is on.\n\n## Authority\n\n| Actor | May do | Only a person may do |\n| --- | --- | --- |\n| Agent | Read the Commitments of an Agent it can view; create one, change it and turn it on; request a check; pause one; decide whether a finding is worth telling the owner | Lift a stop a person made; set or clear a concurrency limit; choose the Task review policy; approve an action proposal or a cadence change; configure a Northstar's governance or decide its intents |\n| Person | Everything in both columns | — |\n\nA Commitment grants no permission: its runs work under the Agent's own. A Check never writes an\nowner-facing message, and a Compass never creates, rewrites, pauses or archives a Commitment. The\nserver cannot always tell an Agent from the person whose login it holds, so an accepted call is\nnot permission: the right-hand column stays a person's.\n\n## Live state\n\n- `skrr commitments list --agent <agent-id>` — an Agent's Commitments, with status and assessment.\n- `skrr commitments show <commitment-id>` — the contract, its next check and the last one.\n- `skrr commitments roster --agent <agent-id>` — each loop: whether it is armed, its next wake, runs today.\n\n## Related guides\n\n- `tasks` — the Tasks a Commitment creates or watches.\n- `spaces` — Goals, and Workflows: durable graphs of Tasks.\n- `agents` — the Agent a Commitment belongs to, and where its runs execute.\n- `communication` — whether, what and how to tell the owner.",
-            "hash": "8a5ab2048ea5a6edacd881d4403a3481798876b4529f8a070d4953eebebd075f",
+            "hash": "197d9b84d1a4367ecf4b7a51687604d13814ec9e9265fe662883278a7738d2fa",
             "tokens": 1169,
             "sections": [
                 {
@@ -1824,7 +1824,7 @@
                     "id": "speaking",
                     "title": "A Commitment finds; its Agent speaks",
                     "readWhen": "a Commitment run found something and you must decide whether the owner hears of it",
-                    "tokens": 263,
+                    "tokens": 301,
                     "aliases": [],
                     "explains": []
                 },
@@ -5850,7 +5850,7 @@
                     "id": "speaking",
                     "title": "A Commitment finds; its Agent speaks",
                     "readWhen": "a Commitment run found something and you must decide whether the owner hears of it",
-                    "tokens": 263,
+                    "tokens": 301,
                     "aliases": [],
                     "explains": []
                 },
@@ -5966,7 +5966,7 @@
                     "id": "speaking",
                     "title": "A Commitment finds; its Agent speaks",
                     "readWhen": "a Commitment run found something and you must decide whether the owner hears of it",
-                    "tokens": 263,
+                    "tokens": 301,
                     "aliases": [],
                     "explains": []
                 },
@@ -6084,7 +6084,7 @@
                     "id": "speaking",
                     "title": "A Commitment finds; its Agent speaks",
                     "readWhen": "a Commitment run found something and you must decide whether the owner hears of it",
-                    "tokens": 263,
+                    "tokens": 301,
                     "aliases": [],
                     "explains": []
                 },
@@ -6206,7 +6206,7 @@
                     "id": "speaking",
                     "title": "A Commitment finds; its Agent speaks",
                     "readWhen": "a Commitment run found something and you must decide whether the owner hears of it",
-                    "tokens": 263,
+                    "tokens": 301,
                     "aliases": [],
                     "explains": []
                 },
@@ -6322,7 +6322,7 @@
                     "id": "speaking",
                     "title": "A Commitment finds; its Agent speaks",
                     "readWhen": "a Commitment run found something and you must decide whether the owner hears of it",
-                    "tokens": 263,
+                    "tokens": 301,
                     "aliases": [],
                     "explains": []
                 },
@@ -6438,7 +6438,7 @@
                     "id": "speaking",
                     "title": "A Commitment finds; its Agent speaks",
                     "readWhen": "a Commitment run found something and you must decide whether the owner hears of it",
-                    "tokens": 263,
+                    "tokens": 301,
                     "aliases": [],
                     "explains": []
                 },
@@ -6560,7 +6560,7 @@
                     "id": "speaking",
                     "title": "A Commitment finds; its Agent speaks",
                     "readWhen": "a Commitment run found something and you must decide whether the owner hears of it",
-                    "tokens": 263,
+                    "tokens": 301,
                     "aliases": [],
                     "explains": []
                 },
@@ -6598,9 +6598,9 @@
             "version": 4,
             "aliases": [],
             "explains": [],
-            "body": "Read this when a Commitment run found something and you must decide whether the owner hears of it.\n\nA Check never writes to the owner. When something it found may matter, the run is handed a brief\nunder \"Owner communication — your call.\": what was found, the evidence, why it may matter and a\nsuggested next step. Those are facts to judge, not a message to forward.\n\n- Decide with everything in view: what you already said, whether the owner replied, what another\n  surface already raised. One message, a different message or nothing are all valid outcomes, and\n  silence is often the right one.\n- To speak from the run, return a `message` or `status_update` action intent with its `text`, or a\n  `report` with its `text` for the Commitment's report destinations. Write the words yourself.\n- The owner's limits (mute, quiet hours, a daily nudge cap) decide whether a run is asked to speak\n  at all, and whatever you deliver counts against them, whichever way you send it.\n\n`skrr commitments reports <commitment-id>` lists where its reports go and on what condition; the\ndefault sends only on a material change.",
-            "hash": "f208f179f96c5f52058be9b4870b2591ef022e658745a7f3e44779bbde87ca10",
-            "tokens": 263,
+            "body": "Read this when a Commitment run found something and you must decide whether the owner hears of it.\n\nA Check never writes to the owner. When something it found may matter, the run is handed a brief\nunder \"Owner communication — your call.\": what was found, the evidence, why it may matter and a\nsuggested next step. Those are facts to judge, not a message to forward.\n\n- Decide with everything in view: what you already said, whether the owner replied, what another\n  surface already raised. One message, a different message or nothing are all valid outcomes, and\n  silence is often the right one.\n- To speak from the run, send it with `skrr agent message send` where the run allows it: it is\n  delivered under the owner's limits and counted for this Commitment. Otherwise return a\n  `status_update` or `report` action intent with its `text` for the Commitment's report\n  destinations. A `message` action intent is recorded but never delivered. Write the words yourself.\n- The owner's limits (mute, quiet hours, a daily nudge cap) decide whether a run is asked to speak\n  at all, and whatever you deliver counts against them, whichever way you send it.\n\n`skrr commitments reports <commitment-id>` lists where its reports go and on what condition; the\ndefault sends only on a material change.",
+            "hash": "45fa02a0344903cc355dff0b66eee45b14dab79a8f62fba8620106b29e11e8a9",
+            "tokens": 301,
             "sections": [
                 {
                     "id": "model",
@@ -6676,7 +6676,7 @@
                     "id": "speaking",
                     "title": "A Commitment finds; its Agent speaks",
                     "readWhen": "a Commitment run found something and you must decide whether the owner hears of it",
-                    "tokens": 263,
+                    "tokens": 301,
                     "aliases": [],
                     "explains": []
                 },
@@ -6796,7 +6796,7 @@
                     "id": "speaking",
                     "title": "A Commitment finds; its Agent speaks",
                     "readWhen": "a Commitment run found something and you must decide whether the owner hears of it",
-                    "tokens": 263,
+                    "tokens": 301,
                     "aliases": [],
                     "explains": []
                 },
@@ -6914,7 +6914,7 @@
                     "id": "speaking",
                     "title": "A Commitment finds; its Agent speaks",
                     "readWhen": "a Commitment run found something and you must decide whether the owner hears of it",
-                    "tokens": 263,
+                    "tokens": 301,
                     "aliases": [],
                     "explains": []
                 },

package/dist/lib/schedule.d.ts

@@ -68,6 +68,11 @@ export interface SmartScheduleProposal {
         truncated: boolean;
     };
     todos: ProposedTodo[];
+    nextRunSuggestion?: {
+        runAt: string;
+        reason?: string;
+        confidence?: number;
+    };
     /**
      * Agent-scope trigger budget at proposal time. Advisory — approval enforces
      * it for real — but it is the difference between a warning the user can act
@@ -105,6 +110,12 @@ export interface ApproveSmartScheduleResponse {
     }>;
     /** Post-write budget, so a caller approving several plans sees the wall coming. */
     capacity?: TriggerCapacity;
+    scheduledNextRun?: {
+        created?: boolean;
+        triggerId?: string;
+        skippedReason?: string;
+        message?: string;
+    } | null;
 }
 /**
  * The self-schedule TRACE — why the agent's day looks the way it does.
@@ -165,7 +176,7 @@ export declare const scheduleApi: {
         limit?: number;
         cursor?: string;
     }) => Promise<ScheduleTrace>;
-    listTodos: (agentId: string, date?: string) => Promise<ListTodosResponse>;
+    listTodos: (agentId: string, date?: string, timezone?: string) => Promise<ListTodosResponse>;
     getTodo: (todoId: string) => Promise<Todo>;
     createTodo: (input: CreateTodoInput) => Promise<Todo>;
     /** Cancel a To-Do (DELETE soft-cancels pending; see todos.js). */
@@ -173,6 +184,7 @@ export declare const scheduleApi: {
     proposeSmartSchedule: (input: {
         agentId: string;
         workingHoursOverride?: WorkingHoursWindow;
+        timezone?: string;
         regenerateHint?: string;
     }) => Promise<SmartScheduleProposal>;
     pendingProposal: (agentId: string) => Promise<{
@@ -182,6 +194,7 @@ export declare const scheduleApi: {
         agentId: string;
         proposalId: string;
         todos: ApproveTodoInput[];
+        approveNextRunSuggestion?: boolean;
         saveHoursAsDefault?: boolean;
         workingHours?: WorkingHoursWindow;
     }) => Promise<ApproveSmartScheduleResponse>;

package/dist/lib/schedule.js

@@ -52,13 +52,13 @@ function scheduleTracePath(params) {
     });
 }
 /** Build the `/api/todos` list query — agentId is required, date optional. */
-function todoListPath(agentId, date) {
-    return (0, triggers_1.withQuery)('/api/todos', { agentId, date });
+function todoListPath(agentId, date, timezone) {
+    return (0, triggers_1.withQuery)('/api/todos', { agentId, date, timezone });
 }
 exports.scheduleApi = {
     /** The self-schedule trace for one agent-day. See `scheduleTracePath`. */
     scheduleTrace: (params) => data_provider_1.request.get(scheduleTracePath(params)),
-    listTodos: (agentId, date) => data_provider_1.request.get(todoListPath(agentId, date)),
+    listTodos: (agentId, date, timezone) => data_provider_1.request.get(todoListPath(agentId, date, timezone)),
     getTodo: (todoId) => data_provider_1.request.get(`/api/todos/${encodeURIComponent(todoId)}`),
     createTodo: (input) => data_provider_1.request.post('/api/todos', input),
     /** Cancel a To-Do (DELETE soft-cancels pending; see todos.js). */
@@ -162,6 +162,9 @@ function renderProposal(proposal, log) {
     if (proposal.expiresAt)
         log(`Expires:     ${formatStamp(proposal.expiresAt)}`);
     renderCapacityWarning(proposal.capacity, log);
+    if (proposal.nextRunSuggestion) {
+        log(`Next run:    ${formatStamp(proposal.nextRunSuggestion.runAt)}${proposal.nextRunSuggestion.reason ? ` · ${proposal.nextRunSuggestion.reason}` : ''}`);
+    }
     log('');
     const live = proposal.todos.filter((t) => !t.dropped);
     if (live.length === 0) {

package/oclif.manifest.json

@@ -12225,6 +12225,15 @@
           "multiple": false,
           "type": "option"
         },
+        "approve-next-run": {
+          "dependsOn": [
+            "approve"
+          ],
+          "description": "With --approve, schedule the suggested next planning run",
+          "name": "approve-next-run",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "save-hours": {
           "description": "On --approve, persist the working-hours window as the agent default",
           "name": "save-hours",
@@ -16065,11 +16074,18 @@
           "type": "boolean"
         },
         "date": {
-          "description": "Day to list (YYYY-MM-DD, UTC). Defaults to today.",
+          "description": "Day to list (YYYY-MM-DD). Defaults to today in the selected timezone.",
           "name": "date",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "timezone": {
+          "description": "IANA timezone for the day (defaults to UTC)",
+          "name": "timezone",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
@@ -143170,5 +143186,5 @@
       ]
     }
   },
-  "version": "0.1.131"
+  "version": "0.1.132"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skrr-ai/cli",
-  "version": "0.1.131",
+  "version": "0.1.132",
   "description": "Command-line interface for skrr",
   "license": "ISC",
   "author": "skrr",