@skrr-ai/cli 0.1.111 → 0.1.113

package/dist/commands/agents/create.d.ts

@@ -71,7 +71,8 @@ export declare function unappliedPayloadKeys(sent: Record<string, unknown>, crea
  * to claim a platform role that they had misspelled something.
  */
 export declare function unappliedPayloadKeysWarning(keys: readonly string[]): string;
-export declare function backgroundLoopLines(agentId: string, relationshipLoopsSkipped: boolean): string[];
+export declare function initialAutonomyReceipt(created: unknown, requested: unknown): boolean | 'unconfirmed';
+export declare function backgroundLoopLines(agentId: string, relationshipLoopsSkipped: boolean, initialAlwaysOn?: boolean | 'unconfirmed'): string[];
 /**
  * The flags `--from-spec` may be combined with: placement and identity for the
  * NEW row, which a spec document deliberately cannot carry (where an agent runs
@@ -96,6 +97,7 @@ export default class AgentsCreate extends BaseCommand {
         target: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'next-target': import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'working-directory': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'initial-always-on': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'no-relationship-loops': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         'default-permission-mode': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         tools: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;

package/dist/commands/agents/create.js

@@ -5,6 +5,7 @@ exports.agentCreateMissingFieldsMessage = agentCreateMissingFieldsMessage;
 exports.agentCreateMissingFields = agentCreateMissingFields;
 exports.unappliedPayloadKeys = unappliedPayloadKeys;
 exports.unappliedPayloadKeysWarning = unappliedPayloadKeysWarning;
+exports.initialAutonomyReceipt = initialAutonomyReceipt;
 exports.backgroundLoopLines = backgroundLoopLines;
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
@@ -121,7 +122,25 @@ function unappliedPayloadKeysWarning(keys) {
     return (`The server did not keep ${keys.join(', ')}: ${one ? 'it is not an agent field' : 'they are not agent fields'}, ` +
         `or only the server sets ${one ? 'it' : 'them'}. \`skrr agents show <id> --json\` shows what the agent stores.`);
 }
-function backgroundLoopLines(agentId, relationshipLoopsSkipped) {
+function initialAutonomyReceipt(created, requested) {
+    if (requested !== false)
+        return true;
+    const provisioning = created && typeof created === 'object'
+        ? created.proactiveProvisioning : null;
+    return provisioning && typeof provisioning === 'object' &&
+        provisioning.initialAlwaysOn === false ? false : 'unconfirmed';
+}
+function backgroundLoopLines(agentId, relationshipLoopsSkipped, initialAlwaysOn = true) {
+    if (initialAlwaysOn === 'unconfirmed')
+        return [
+            'Passive creation was requested, but the server did not acknowledge it. Autonomous state is unconfirmed.',
+            `  skrr agents show ${agentId} --json   # inspect actual runtime state`,
+        ];
+    if (!initialAlwaysOn)
+        return [
+            'Passive creation acknowledged. Legacy task/memory scans were omitted. Explicit chats still run; Always-On can enable the seeded managed portfolio later.',
+            `  skrr agents always-on enable ${agentId}   # start autonomous work later`,
+        ];
     if (relationshipLoopsSkipped) {
         return [
             'Background loops: relationship portfolio skipped (--no-relationship-loops). ' +
@@ -156,6 +175,7 @@ exports.FROM_SPEC_COMPATIBLE_FLAGS = Object.freeze([
     'working-directory',
     'default-permission-mode',
     'no-relationship-loops',
+    'initial-always-on',
 ]);
 class AgentsCreate extends base_command_1.BaseCommand {
     static description = 'Create a new agent in the selected workspace, or in your default workspace when --workspace is omitted (`skrr workspaces list` names it)';
@@ -224,6 +244,10 @@ class AgentsCreate extends base_command_1.BaseCommand {
         'working-directory': core_1.Flags.string({
             description: 'Default working directory for local Harness sessions',
         }),
+        'initial-always-on': core_1.Flags.string({
+            description: 'Start autonomous work after creation (default: on). Use off for a passive agent; explicit chat still works. Relationship-loop seeding is configured separately.',
+            options: ['on', 'off'],
+        }),
         'no-relationship-loops': core_1.Flags.boolean({
             description: 'Single-purpose agent: skip the system-managed relationship portfolio (conversation continuity, relationship pulse, commitment incubator, open-loop closer). Self-reflection is still seeded.',
         }),
@@ -361,6 +385,7 @@ class AgentsCreate extends base_command_1.BaseCommand {
             // so an ordinary create carries no `relationshipLoops` key and the
             // server seeds the full portfolio exactly as it always has.
             relationshipLoops: flags['no-relationship-loops'] ? false : undefined,
+            initialAlwaysOn: flags['initial-always-on'] === undefined ? undefined : flags['initial-always-on'] === 'on',
         });
         // `mergeAgentConfigFlags` parses the typed flags (avatar, scene background,
         // working hours, every JSON flag). A parse failure is the caller's input, so
@@ -412,6 +437,7 @@ class AgentsCreate extends base_command_1.BaseCommand {
         // definition-field round-trip warning.
         const unapplied = unappliedPayloadKeys(payload, created, [
             'relationshipLoops',
+            'initialAlwaysOn',
             ...(0, agent_config_1.deprecatedFieldNames)(created),
         ]);
         for (const warning of (0, agent_config_1.deprecatedFieldsWarnings)(created))
@@ -426,6 +452,9 @@ class AgentsCreate extends base_command_1.BaseCommand {
             bin: this.config.bin,
             warn: (message) => this.warn(message),
         });
+        if (initialAutonomyReceipt(created, payload.initialAlwaysOn) === 'unconfirmed') {
+            this.warn('Passive creation was requested but not acknowledged by the server. Autonomous state is unconfirmed; inspect agents show before relying on it.');
+        }
         if (flags.json) {
             this.log(JSON.stringify((0, web_url_1.withAgentUrl)(this.cliConfig.baseURL, created), null, 2));
             return;
@@ -447,7 +476,7 @@ class AgentsCreate extends base_command_1.BaseCommand {
             this.log(`Avatar: ${(0, agent_visual_refs_1.agentAvatarLine)(a.avatar)}`);
             this.log('  Decided by your default-avatar policy — `skrr agents avatar default` shows or changes it.');
         }
-        for (const line of backgroundLoopLines(agentId, flags['no-relationship-loops'] === true)) {
+        for (const line of backgroundLoopLines(agentId, flags['no-relationship-loops'] === true, initialAutonomyReceipt(created, payload.initialAlwaysOn))) {
             this.log(line);
         }
         this.log(`URL: ${(0, web_url_1.withAgentUrl)(this.cliConfig.baseURL, a).url ?? '-'}`);
@@ -568,6 +597,7 @@ class AgentsCreate extends base_command_1.BaseCommand {
             workingDirectory: flags['working-directory'],
             defaultPermissionMode: flags['default-permission-mode'],
             relationshipLoops: flags['no-relationship-loops'] ? false : undefined,
+            initialAlwaysOn: flags['initial-always-on'] === undefined ? undefined : flags['initial-always-on'] === 'on',
         });
         let created;
         try {
@@ -605,6 +635,9 @@ class AgentsCreate extends base_command_1.BaseCommand {
                 details: { agentId, rolledBack: !rollback.includes('NOT'), issues: refusal?.issues },
             });
         }
+        if (initialAutonomyReceipt(created, payload.initialAlwaysOn) === 'unconfirmed') {
+            this.warn('Passive creation was requested but not acknowledged by the server. Autonomous state is unconfirmed; inspect agents show before relying on it.');
+        }
         if (flags.json) {
             this.log(JSON.stringify({
                 agent: (0, web_url_1.withAgentUrl)(this.cliConfig.baseURL, created),
@@ -628,7 +661,7 @@ class AgentsCreate extends base_command_1.BaseCommand {
             this.log(`Not taken from the file, because the server derives it from other fields: ${derived.join(', ')}.`);
         }
         this.log(`Keep the file in step: \`skrr agents push ${agentId} --file ${source === '-' ? '<file>' : source}\`.`);
-        for (const line of backgroundLoopLines(agentId, flags['no-relationship-loops'] === true)) {
+        for (const line of backgroundLoopLines(agentId, flags['no-relationship-loops'] === true, initialAutonomyReceipt(created, payload.initialAlwaysOn))) {
             this.log(line);
         }
         this.log(`URL: ${(0, web_url_1.withAgentUrl)(this.cliConfig.baseURL, created).url ?? '-'}`);

package/dist/commands/followups/plans/create.js

@@ -4,8 +4,10 @@ const core_1 = require("@oclif/core");
 const base_command_1 = require("../../../base-command");
 const prompt_1 = require("../../../lib/prompt");
 const lookbackPlans_1 = require("../../../lib/lookbackPlans");
+const lookbackPlanHelp_1 = require("../../../lib/lookbackPlanHelp");
 class LookbackPlansCreate extends base_command_1.BaseCommand {
-    static description = 'Schedule a bounded plan of 1–10 lookbacks, each free to stay silent';
+    static description = 'Schedule a bounded plan of 1–10 lookbacks, each free to stay silent\n\n' + lookbackPlanHelp_1.LOOKBACK_PLAN_INPUT_HELP +
+        '\n\nCreate also accepts {"agentId":"...","pinnedConversationId":"...","plan":{...}}. Source and delivery destination are separate; pin the original conversation to return there.';
     static examples = ['<%= config.bin %> followups plans create --from-json plan.json --agent agent_1 --json'];
     static flags = {
         'from-json': core_1.Flags.string({ description: 'Plan or create envelope JSON file; - reads stdin', required: true }),
@@ -20,7 +22,7 @@ class LookbackPlansCreate extends base_command_1.BaseCommand {
             body = (0, lookbackPlans_1.lookbackCreateBody)(await (0, prompt_1.readJsonBody)(flags['from-json']), flags.agent);
         }
         catch (err) {
-            this.failWithCliError({ message: err instanceof Error ? err.message : String(err), code: 'LOOKBACK_INVALID_FIELD', exit: 2, retryable: false });
+            this.failWithCliError((0, lookbackPlans_1.lookbackInputFailure)(err));
             return;
         }
         try {

package/dist/commands/followups/plans/example.d.ts

@@ -0,0 +1,6 @@
+import { BaseCommand } from '../../../base-command';
+export default class LookbackPlanExample extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/followups/plans/example.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const base_command_1 = require("../../../base-command");
+const lookbackPlanHelp_1 = require("../../../lib/lookbackPlanHelp");
+class LookbackPlanExample extends base_command_1.BaseCommand {
+    static 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.';
+    static examples = ['<%= config.bin %> followups plans example > plan.json'];
+    async run() {
+        this.log(JSON.stringify(lookbackPlanHelp_1.LOOKBACK_PLAN_EXAMPLE, null, 2));
+    }
+}
+exports.default = LookbackPlanExample;

package/dist/commands/followups/plans/revise.d.ts

@@ -1,6 +1,7 @@
 import { BaseCommand } from '../../../base-command';
 export default class LookbackPlansRevise extends BaseCommand {
     static description: string;
+    static examples: string[];
     static args: {
         id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
     };

package/dist/commands/followups/plans/revise.js

@@ -4,8 +4,11 @@ const core_1 = require("@oclif/core");
 const base_command_1 = require("../../../base-command");
 const prompt_1 = require("../../../lib/prompt");
 const lookbackPlans_1 = require("../../../lib/lookbackPlans");
+const lookbackPlanHelp_1 = require("../../../lib/lookbackPlanHelp");
 class LookbackPlansRevise extends base_command_1.BaseCommand {
-    static description = 'Revise pending lookbacks using the original source and step IDs';
+    static description = 'Revise pending lookbacks using the original source and step IDs\n\n' + lookbackPlanHelp_1.LOOKBACK_PLAN_INPUT_HELP +
+        '\n\nRevise accepts the plan itself, not a create envelope. Use the current --revision from show; a stale revision returns LOOKBACK_CONFLICT (409).';
+    static examples = ['<%= config.bin %> followups plans revise PLAN_ID --revision 1 --from-json revised-plan.json --json'];
     static args = { id: lookbackPlans_1.lookbackPlanIdArg };
     static flags = {
         revision: core_1.Flags.integer({ description: 'Expected current revision; stale edits are refused', min: 1, required: true }),
@@ -20,7 +23,7 @@ class LookbackPlansRevise extends base_command_1.BaseCommand {
             plan = (0, lookbackPlans_1.lookbackInput)(await (0, prompt_1.readJsonBody)(flags['from-json']), true);
         }
         catch (err) {
-            this.failWithCliError({ message: err instanceof Error ? err.message : String(err), code: 'LOOKBACK_INVALID_FIELD', exit: 2, retryable: false });
+            this.failWithCliError((0, lookbackPlans_1.lookbackInputFailure)(err));
             return;
         }
         try {

package/dist/lib/lookbackPlanHelp.d.ts

@@ -0,0 +1,19 @@
+/** Authored input, not a copy of the server's normalized Plan projection. */
+export declare const LOOKBACK_PLAN_EXAMPLE: {
+    objective: string;
+    stopCondition: string;
+    source: {
+        conversationId: string;
+        messageId: string;
+        replyCompletedAt: string;
+    };
+    steps: {
+        id: string;
+        instruction: string;
+        when: {
+            kind: string;
+            offset: string;
+        };
+    }[];
+};
+export declare const LOOKBACK_PLAN_INPUT_HELP: string;

package/dist/lib/lookbackPlanHelp.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOOKBACK_PLAN_INPUT_HELP = exports.LOOKBACK_PLAN_EXAMPLE = void 0;
+/** Authored input, not a copy of the server's normalized Plan projection. */
+exports.LOOKBACK_PLAN_EXAMPLE = {
+    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' },
+        }],
+};
+exports.LOOKBACK_PLAN_INPUT_HELP = [
+    'Input is authored Plan JSON with objective, stopCondition, source and 1–10 steps. Generate an editable JSON file:',
+    'skrr followups plans example > plan.json',
+    'Replace 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.',
+    'Relative time is measured from source.replyCompletedAt, not command invocation. Choose an offset whose resulting time is still in the future.',
+    'Each 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.',
+    'Optional 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.',
+    'A 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.',
+].join('\n\n');

package/dist/lib/lookbackPlans.d.ts

@@ -1,5 +1,14 @@
 import { lookbackPlansApi, type CreateLookbackPlanRequest, type LookbackPlan, type LookbackPlanInput } from '@skrr-ai/data-provider';
 export { lookbackPlansApi };
+export declare function lookbackInputFailure(error: unknown): {
+    exit: number;
+    retryable: boolean;
+    details?: {
+        field: string;
+    } | undefined;
+    code: "LOOKBACK_INVALID_FIELD" | "LOOKBACK_INVALID_TIME" | "LOOKBACK_INVALID_TIMEZONE" | "LOOKBACK_AMBIGUOUS_TIME" | "LOOKBACK_NONEXISTENT_TIME" | "LOOKBACK_LIMIT_EXCEEDED";
+    message: string;
+};
 export declare const lookbackPlanIdArg: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
 /** JSON can be the plan itself or the canonical create envelope. Never copy identity fields. */
 export declare function lookbackCreateBody(input: Record<string, unknown>, explicitAgentId?: string): CreateLookbackPlanRequest;

package/dist/lib/lookbackPlans.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.lookbackPlanIdArg = exports.lookbackPlansApi = void 0;
+exports.lookbackInputFailure = lookbackInputFailure;
 exports.lookbackCreateBody = lookbackCreateBody;
 exports.lookbackInput = lookbackInput;
 exports.lookbackPlanSummary = lookbackPlanSummary;
@@ -9,6 +10,22 @@ const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 Object.defineProperty(exports, "lookbackPlansApi", { enumerable: true, get: function () { return data_provider_1.lookbackPlansApi; } });
 const followups_1 = require("./followups");
+class LookbackValidationError extends Error {
+    issue;
+    constructor(issue) {
+        super(`${issue.code}: ${issue.field}: ${issue.message}`);
+        this.issue = issue;
+    }
+}
+function lookbackInputFailure(error) {
+    return {
+        code: error instanceof LookbackValidationError ? error.issue.code : 'LOOKBACK_INVALID_FIELD',
+        message: error instanceof Error ? error.message : String(error),
+        ...(error instanceof LookbackValidationError ? { details: { field: error.issue.field } } : {}),
+        exit: 2,
+        retryable: false,
+    };
+}
 exports.lookbackPlanIdArg = core_1.Args.string({
     description: 'Lookback plan id', required: true, ignoreStdin: true,
     parse: async (value) => {
@@ -52,7 +69,7 @@ function lookbackCreateBody(input, explicitAgentId) {
 function lookbackInput(raw, allowPast = false) {
     const parsed = (0, data_provider_1.normalizeLookbackPlanInput)(raw, { allowPast });
     if (!parsed.ok)
-        throw new Error(`${parsed.code}: ${parsed.message}`);
+        throw new LookbackValidationError(parsed);
     // Send only authored fields. The server fixes normalized times, generated
     // step IDs, lifecycle and ownership; CLI must not forge those projections.
     return raw;
@@ -63,6 +80,9 @@ function lookbackPlanSummary(plan) {
         `  ${plan.steps.length} lookbacks${next ? `  next:${next.runAt}` : ''}`;
 }
 function lookbackArmingLine(result) {
+    if (['cancelled', 'completed', 'failed'].includes(result.plan.state)) {
+        return `Lookback plan ${result.plan.id}: ${result.plan.state} (r${result.plan.revision})${result.reused ? ' (existing plan)' : ''}.`;
+    }
     const status = result.armed ? 'armed' : 'saved; scheduling is pending';
     return `Lookback plan ${result.plan.id} ${status}${result.reused ? ' (existing plan)' : ''}.`;
 }