@skrr-ai/cli 0.1.111 → 0.1.113

package/docs/v1/README.md

@@ -9,6 +9,7 @@ This edition was reviewed on **2026-10-10** against CLI **0.1.95**, daemon **0.8
 | Sign in and create your first Task | [Quickstart](quickstart.md) |
 | Make a read-only HTTP request with a scoped key | [Public API](api.md) |
 | Fix sign-in, errors, quotas, permissions, or a failed upgrade | [Operations and recovery](operations.md) |
+| Schedule, inspect, revise or cancel 1–10 lookbacks | [Lookback plans](lookback-plans.md) |
 | Understand what changed in this guide | [Changelog](changelog.md) |
 
 The workspace CLI uses the account/workspace `/api` surface. The Managed Agents public API uses `/v1` and Space-scoped API keys. A personal access token for CLI automation is a different credential. Choose the surface before issuing a credential.

package/docs/v1/lookback-plans.md

@@ -0,0 +1,88 @@
+# Scheduled lookback plans
+
+A plan provides 1–10 opportunities to inspect fresh evidence. Each check may stay silent. It does not promise one message per check.
+
+## Create
+
+Read a conversation belonging to the intended agent:
+
+```sh
+skrr convos messages YOUR_CONVERSATION_ID --json
+```
+
+Choose a completed assistant reply (`isCreatedByUser: false`, `unfinished: false`). Copy its actual `messageId` and completion `updatedAt`. The source is immutable: do not substitute the current clock or a user message.
+
+Generate a template without signing in, then replace all three source placeholders:
+
+```sh
+skrr followups plans example > plan.json
+```
+
+The generated file contains:
+
+```json
+{
+  "objective": "Check deployment health",
+  "stopCondition": "Deployment is ready or the owner cancels",
+  "source": {
+    "conversationId": "YOUR_CONVERSATION_ID",
+    "messageId": "YOUR_COMPLETED_ASSISTANT_MESSAGE_ID",
+    "replyCompletedAt": "ACTUAL_REPLY_COMPLETION_ISO_TIMESTAMP"
+  },
+  "steps": [
+    {
+      "id": "health-check",
+      "instruction": "Read the latest original conversation. Report readiness once; otherwise stay silent.",
+      "when": { "kind": "relative", "offset": "10m" }
+    }
+  ]
+}
+```
+
+```sh
+skrr followups plans create --agent YOUR_AGENT_ID --from-json plan.json --json
+```
+
+Relative time is measured from that reply's completion, so ensure the resulting time is still in the future. An envelope can explicitly separate delivery from evidence:
+
+```json
+{
+  "agentId": "YOUR_AGENT_ID",
+  "pinnedConversationId": "YOUR_CONVERSATION_ID",
+  "plan": { "objective": "...", "stopCondition": "...", "source": {}, "steps": [] }
+}
+```
+
+The envelope's abbreviated `plan` is structural guidance; replace it with the complete authored plan above. Optional delivery fields are `endpointId` and `endpointTarget`; source identity remains independent. `armed: true` confirms timer registration. A saved/pending result does not, and an existing terminal plan remains terminal on replay.
+
+## Time forms
+
+Each step's `when` accepts one of these shapes. Replace example dates with future dates:
+
+```json
+{"kind":"relative","offset":"10m"}
+```
+
+```json
+{"kind":"absolute","at":"2026-10-21T12:00:00Z"}
+```
+
+```json
+{"kind":"local","dateTime":"2026-10-21T09:00:00","timezone":"America/Los_Angeles"}
+```
+
+Absolute timestamps require `Z` or a UTC offset. Local times require an IANA timezone; ambiguous and nonexistent DST times are refused. A step may also have `label` and `expiresAfter` (for example `"1h"`). After expiry, the check must not execute. Top-level `title` and `timezone` are optional.
+
+## Inspect, revise and cancel
+
+```sh
+skrr followups plans list --agent YOUR_AGENT_ID --json
+skrr followups plans show PLAN_ID --json
+skrr followups plans revise PLAN_ID --revision 1 --from-json revised-plan.json --json
+skrr followups plans cancel PLAN_ID --revision 2 --reason "No longer needed" --json
+skrr followups plans observability --agent YOUR_AGENT_ID --json
+```
+
+Use the current revision returned by `show`. A stale edit returns `LOOKBACK_CONFLICT` with HTTP 409; reread before deciding whether to edit again. Revision JSON is the full authored plan itself, with the exact original source and existing step IDs. Start from `plan.json`, preserve IDs from `show`, and edit pending instructions/times. Do not resubmit the full `show` response: server fields such as `state`, `runAt`, `expiresAt`, outcomes and claims are not authoring input. Completed evaluations consume the same lifetime allowance after edits.
+
+Cancellation is idempotent and fences remaining work; it does not retract a message already delivered. `observability` reports a bounded sample, not lifetime totals. Normal account authority, budgets, runtime support and delivery policies still apply. No feature-flag enrollment or special two-person activation is needed.

package/oclif.manifest.json

@@ -7406,6 +7406,17 @@
           "multiple": false,
           "type": "option"
         },
+        "initial-always-on": {
+          "description": "Start autonomous work after creation (default: on). Use off for a passive agent; explicit chat still works. Relationship-loop seeding is configured separately.",
+          "name": "initial-always-on",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "on",
+            "off"
+          ],
+          "type": "option"
+        },
         "no-relationship-loops": {
           "description": "Single-purpose agent: skip the system-managed relationship portfolio (conversation continuity, relationship pulse, commitment incubator, open-loop closer). Self-reflection is still seeded.",
           "name": "no-relationship-loops",
@@ -45552,7 +45563,7 @@
     "followups:plans:create": {
       "aliases": [],
       "args": {},
-      "description": "Schedule a bounded plan of 1–10 lookbacks, each free to stay silent",
+      "description": "Schedule a bounded plan of 1–10 lookbacks, each free to stay silent\n\nInput is authored Plan JSON with objective, stopCondition, source and 1–10 steps. Generate an editable JSON file:\n\nskrr followups plans example > plan.json\n\nReplace the three source placeholders with a real completed assistant reply belonging to this agent. `skrr convos messages <conversation-id> --json` reads its messageId and completion updatedAt. Never use the current clock as a replacement anchor.\n\nRelative time is measured from source.replyCompletedAt, not command invocation. Choose an offset whose resulting time is still in the future.\n\nEach when supports {\"kind\":\"relative\",\"offset\":\"10m\"}, {\"kind\":\"absolute\",\"at\":\"2026-10-21T12:00:00Z\"}, or {\"kind\":\"local\",\"dateTime\":\"2026-10-21T09:00:00\",\"timezone\":\"America/Los_Angeles\"}. Replace example dates with future dates. Absolute time requires Z or a UTC offset; ambiguous/nonexistent local DST times are refused.\n\nOptional fields: title, timezone; per step: id, label, expiresAfter (for example \"1h\"). Revision retains the exact source and existing step IDs. Do not submit the show response unchanged: remove lifecycle fields such as state, runAt and expiresAt.\n\nA check may remain silent. Only armed:true confirms timer registration; saved/pending is not armed. Full guide is shipped at docs/v1/lookback-plans.md in the installed CLI package.\n\nCreate also accepts {\"agentId\":\"...\",\"pinnedConversationId\":\"...\",\"plan\":{...}}. Source and delivery destination are separate; pin the original conversation to return there.",
       "examples": [
         "<%= config.bin %> followups plans create --from-json plan.json --agent agent_1 --json"
       ],
@@ -45631,6 +45642,67 @@
         "create.js"
       ]
     },
+    "followups:plans:example": {
+      "aliases": [],
+      "args": {},
+      "description": "Print an editable Plan JSON template without signing in\n\nReplace the source placeholders with a real completed assistant reply before creating a plan. This command schedules nothing.",
+      "examples": [
+        "<%= config.bin %> followups plans example > plan.json"
+      ],
+      "flags": {
+        "bare": {
+          "description": "Bare mode — ignore keychain/file credential sources. Token must come from env or --token.",
+          "name": "bare",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "token": {
+          "description": "Bearer token for this invocation (debugging/impersonation). Overrides env and stored creds.",
+          "name": "token",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "workspace": {
+          "description": "Workspace ID for workspace-scoped requests (also sets X-Workspace-Id).",
+          "name": "workspace",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "profile": {
+          "description": "Which stored session to use. Each profile keeps its own credential and deployment, so signing into one does not sign you out of another. Also OVERSKY_PROFILE. List them with `profiles list`.",
+          "name": "profile",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "raw": {
+          "description": "With --json, keep the Mongo storage fields (_id next to id, __v) that the CLI otherwise strips. Also OVERSKY_CLI_RAW=1.",
+          "name": "raw",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "followups:plans:example",
+      "pluginAlias": "@skrr-ai/cli",
+      "pluginName": "@skrr-ai/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "autonomousCredentialPolicy": "delegated",
+      "resolveSpaceFlag": true,
+      "isESM": false,
+      "relativePath": [
+        "dist",
+        "commands",
+        "followups",
+        "plans",
+        "example.js"
+      ]
+    },
     "followups:plans:list": {
       "aliases": [],
       "args": {},
@@ -45841,7 +45913,10 @@
           "required": true
         }
       },
-      "description": "Revise pending lookbacks using the original source and step IDs",
+      "description": "Revise pending lookbacks using the original source and step IDs\n\nInput is authored Plan JSON with objective, stopCondition, source and 1–10 steps. Generate an editable JSON file:\n\nskrr followups plans example > plan.json\n\nReplace the three source placeholders with a real completed assistant reply belonging to this agent. `skrr convos messages <conversation-id> --json` reads its messageId and completion updatedAt. Never use the current clock as a replacement anchor.\n\nRelative time is measured from source.replyCompletedAt, not command invocation. Choose an offset whose resulting time is still in the future.\n\nEach when supports {\"kind\":\"relative\",\"offset\":\"10m\"}, {\"kind\":\"absolute\",\"at\":\"2026-10-21T12:00:00Z\"}, or {\"kind\":\"local\",\"dateTime\":\"2026-10-21T09:00:00\",\"timezone\":\"America/Los_Angeles\"}. Replace example dates with future dates. Absolute time requires Z or a UTC offset; ambiguous/nonexistent local DST times are refused.\n\nOptional fields: title, timezone; per step: id, label, expiresAfter (for example \"1h\"). Revision retains the exact source and existing step IDs. Do not submit the show response unchanged: remove lifecycle fields such as state, runAt and expiresAt.\n\nA check may remain silent. Only armed:true confirms timer registration; saved/pending is not armed. Full guide is shipped at docs/v1/lookback-plans.md in the installed CLI package.\n\nRevise accepts the plan itself, not a create envelope. Use the current --revision from show; a stale revision returns LOOKBACK_CONFLICT (409).",
+      "examples": [
+        "<%= config.bin %> followups plans revise PLAN_ID --revision 1 --from-json revised-plan.json --json"
+      ],
       "flags": {
         "bare": {
           "description": "Bare mode — ignore keychain/file credential sources. Token must come from env or --token.",
@@ -137151,5 +137226,5 @@
       ]
     }
   },
-  "version": "0.1.111"
+  "version": "0.1.113"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skrr-ai/cli",
-  "version": "0.1.111",
+  "version": "0.1.113",
   "description": "Command-line interface for skrr",
   "license": "ISC",
   "author": "skrr",
@@ -558,7 +558,10 @@
         "description": "Your Agent Manager (HR Agent): create it, or repair an incomplete one"
       },
       "followups": {
-        "description": "Schedule an agent to come back once — reminders, watches, check-ins, and deferred actions"
+        "description": "Schedule agent follow-ups and bounded lookback plans"
+      },
+      "followups:plans": {
+        "description": "Schedule and manage bounded plans of 1–10 lookbacks"
       },
       "enterprise": {
         "description": "Enterprise deployment configuration for a workspace (admin)"