@skrr-ai/cli 0.1.130 → 0.1.132

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/exec-runtime-binary.js

@@ -75,9 +75,10 @@ function forwardedFlagsNote(verb, opts = {}) {
     // daemon cannot silently end up on a different deployment than the CLI that
     // installed it (OSK-279). Saying so is the difference between a flag you may
     // pass and a flag that is already being passed for you.
+    const help = `${base} If \`skrrd\` is not on your PATH, use its installed path instead (typically \`~/.skrr/bin/skrrd\` on macOS and Linux).`;
     return opts.binds
-        ? `${base} \`--server\` and \`--profile\` are filled in from your CLI session unless you pass them.`
-        : base;
+        ? `${help} \`--server\` and \`--profile\` are filled in from your CLI session unless you pass them.`
+        : help;
 }
 /** Extra well-known install locations for one runtime name, checked after PATH. */
 function fallbackPathsForRuntime(name) {

package/dist/lib/harnesses.d.ts

@@ -243,7 +243,7 @@ export declare function forgetHarness(id: string): Promise<unknown>;
  * server (`pruneSupersededHarnesses.js`, `REASONS`) and worded once, in
  * `harnessPruneReasonSentence`, so the table and `--json` never disagree.
  */
-export type HarnessPruneReason = 'recent' | 'latest_registration' | 'no_live_sibling' | 'pinned' | 'granted' | 'default' | 'aliased' | 'changed_since_plan';
+export type HarnessPruneReason = 'recent' | 'latest_registration' | 'no_live_sibling' | 'has_usage' | 'pinned' | 'granted' | 'default' | 'aliased' | 'changed_since_plan';
 export interface HarnessPruneRow {
     id: string;
     daemonId: string | null;
@@ -257,6 +257,8 @@ export interface HarnessPruneRow {
         daemonId: string | null;
         lastSeenAt: string | null;
     };
+    /** The gone lease a row this call removes (or would) belonged to (`--include-gone-leases`). */
+    goneLease?: string;
     /** Set on kept rows. */
     reason?: HarnessPruneReason;
     /** For `pinned`: who holds the pin. Other people's agents are a count, never named. */
@@ -300,6 +302,7 @@ export declare function pruneHarnesses(options?: {
     dryRun: boolean;
     limit?: number;
     minUnseenMs?: number;
+    includeGoneLeases?: boolean;
 }): Promise<HarnessPruneResult>;
 /**
  * `--older-than` takes a whole number with a unit: `90m`, `36h`, `7d`. A bare

package/dist/lib/harnesses.js

@@ -192,6 +192,7 @@ async function pruneHarnesses(options = { dryRun: true }) {
             dryRun: options.dryRun,
             ...(options.limit !== undefined ? { limit: options.limit } : {}),
             ...(options.minUnseenMs !== undefined ? { minUnseenMs: options.minUnseenMs } : {}),
+            ...(options.includeGoneLeases ? { includeGoneLeases: true } : {}),
         },
     });
 }
@@ -219,6 +220,8 @@ function harnessPruneReasonSentence(row) {
             return 'the newest registration of its provider on that machine';
         case 'no_live_sibling':
             return 'nothing has replaced it - no daemon on that machine is online for this provider';
+        case 'has_usage':
+            return 'usage is recorded against it, so the row keeps the name that usage is attributed to';
         case 'pinned': {
             const names = (row.detail?.agents ?? []).map((a) => a.name ?? a.id);
             const more = row.detail?.moreAgents ?? 0;

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.
@@ -145,6 +156,8 @@ export interface ScheduleTrace {
     has_more?: boolean;
     next_cursor?: string | null;
 }
+/** Calendar day at an instant in the zone used for the schedule query. */
+export declare function scheduleTraceToday(now: Date, timezone: string): string;
 export declare function scheduleTracePath(params: {
     agentId: string;
     date: string;
@@ -163,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). */
@@ -171,6 +184,7 @@ export declare const scheduleApi: {
     proposeSmartSchedule: (input: {
         agentId: string;
         workingHoursOverride?: WorkingHoursWindow;
+        timezone?: string;
         regenerateHint?: string;
     }) => Promise<SmartScheduleProposal>;
     pendingProposal: (agentId: string) => Promise<{
@@ -180,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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.scheduleApi = void 0;
+exports.scheduleTraceToday = scheduleTraceToday;
 exports.scheduleTracePath = scheduleTracePath;
 exports.isSmartScheduleProposal = isSmartScheduleProposal;
 exports.describeNonProposal = describeNonProposal;
@@ -29,6 +30,17 @@ exports.proposalToApproveTodos = proposalToApproveTodos;
 const data_provider_1 = require("@skrr-ai/data-provider");
 const format_1 = require("./format");
 const triggers_1 = require("./triggers");
+/** Calendar day at an instant in the zone used for the schedule query. */
+function scheduleTraceToday(now, timezone) {
+    const parts = new Intl.DateTimeFormat('en-CA', {
+        timeZone: timezone,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+    }).formatToParts(now);
+    const part = (type) => parts.find((item) => item.type === type)?.value;
+    return `${part('year')}-${part('month')}-${part('day')}`;
+}
 function scheduleTracePath(params) {
     return (0, triggers_1.withQuery)('/api/todos/smart-schedule/trace', {
         agentId: params.agentId,
@@ -40,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). */
@@ -150,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) {