@skrr-ai/cli 0.1.8

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

@@ -0,0 +1,279 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_command_1 = require("../../base-command");
+const schedule_1 = require("../../lib/schedule");
+/**
+ * `skrr agents plan-day <agent-id>` — Smart Schedule ("Plan my day").
+ *
+ * The web Schedule Board's "Plan my day" button is a propose → review → approve
+ * flow. This command exposes the same lifecycle non-interactively:
+ *
+ *   skrr agents plan-day <id>            # propose (or show the pending plan)
+ *   skrr agents plan-day <id> --approve  # materialize the pending plan as To-Dos
+ *   skrr agents plan-day <id> --dismiss  # discard the pending plan
+ *   skrr agents plan-day <id> --regenerate "focus on the launch"  # fresh plan
+ *
+ * A proposal is a DRAFT — nothing is scheduled until `--approve`. Re-running the
+ * bare command recovers the pending proposal rather than regenerating it (mirrors
+ * the board, which recovers a pending plan into the review modal).
+ */
+class AgentsPlanDay extends base_command_1.BaseCommand {
+    static description = "Smart Schedule an agent's day: propose a plan, then approve or dismiss it";
+    static examples = [
+        '<%= config.bin %> agents plan-day <agent-id>',
+        '<%= config.bin %> agents plan-day <agent-id> --approve',
+        '<%= config.bin %> agents plan-day <agent-id> --dismiss',
+        '<%= config.bin %> agents plan-day <agent-id> --regenerate "prioritize the Q2 launch" --hours-start 09:00 --hours-end 17:00',
+    ];
+    static args = {
+        id: core_1.Args.string({ description: 'Agent ID', required: true, ignoreStdin: true }),
+    };
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+        approve: core_1.Flags.boolean({
+            description: 'Approve the pending proposal — creates a To-Do for each proposed item',
+            exclusive: ['dismiss'],
+        }),
+        dismiss: core_1.Flags.boolean({
+            description: 'Discard the pending proposal without creating anything',
+            exclusive: ['approve'],
+        }),
+        regenerate: core_1.Flags.string({
+            description: 'Propose a FRESH plan (replacing any pending one), optionally with a hint',
+        }),
+        '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' }),
+        'save-hours': core_1.Flags.boolean({
+            description: 'On --approve, persist the working-hours window as the agent default',
+        }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(AgentsPlanDay);
+        const agentId = args.id;
+        try {
+            if (flags.dismiss) {
+                await this.runDismiss(agentId, flags.json);
+                return;
+            }
+            if (flags.approve) {
+                await this.runApprove(agentId, flags);
+                return;
+            }
+            await this.runProposeOrShow(agentId, flags);
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+    }
+    /**
+     * The single point where a proposal-shaped response becomes a proposal.
+     *
+     * Every exit from this command is now one of: a rendered proposal, or a
+     * structured failure carrying a code and a non-zero exit. There is no third
+     * branch that prints nothing and exits 0 — which is what `--regenerate
+     * --json` did when the transport handed back an unparseable body (OSK-2803).
+     */
+    requireProposal(value, agentId, operation) {
+        if ((0, schedule_1.isSmartScheduleProposal)(value))
+            return value;
+        this.failWithCliError({
+            message: `Smart Schedule ${operation} for agent ${agentId} returned no proposal ` +
+                `(${(0, schedule_1.describeNonProposal)(value)}). Nothing was scheduled. ` +
+                `Check service health with \`${this.config.bin} doctor\` and retry.`,
+            code: 'SMART_SCHEDULE_NO_PROPOSAL',
+            exit: 1,
+            retryable: true,
+            details: { agentId, operation },
+        });
+    }
+    /** `{proposal}` envelope reader that survives a body-less response. */
+    async fetchPending(agentId) {
+        const pending = (await schedule_1.scheduleApi.pendingProposal(agentId));
+        if (pending == null || typeof pending !== 'object') {
+            this.failWithCliError({
+                message: `Could not read the pending Smart Schedule plan for agent ${agentId} ` +
+                    `(${(0, schedule_1.describeNonProposal)(pending)}).`,
+                code: 'SMART_SCHEDULE_UNREADABLE',
+                exit: 1,
+                retryable: true,
+                details: { agentId },
+            });
+        }
+        const proposal = pending.proposal;
+        // An explicit `null` is a real answer — "no pending plan" — and every
+        // caller here already handles it. Anything else that is not a proposal is
+        // a broken response, not an empty one.
+        if (proposal == null)
+            return null;
+        return this.requireProposal(proposal, agentId, 'pending');
+    }
+    workingHoursOverride(flags) {
+        if (!flags['hours-start'] || !flags['hours-end'])
+            return undefined;
+        return {
+            start: flags['hours-start'],
+            end: flags['hours-end'],
+            ...(flags.timezone ? { timezone: flags.timezone } : {}),
+        };
+    }
+    /**
+     * 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.
+     */
+    static TIMEOUT_STATUSES = new Set([408, 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;
+    /**
+     * After a timed-out propose, collect the draft the server persisted anyway.
+     * Returns null when the failure was not a timeout, or when nothing landed —
+     * in both cases the caller rethrows the original error rather than inventing
+     * a friendlier one.
+     */
+    async recoverProposalAfterTimeout(agentId, err, json) {
+        const status = err?.status;
+        if (typeof status !== 'number' || !AgentsPlanDay.TIMEOUT_STATUSES.has(status)) {
+            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.');
+        for (let attempt = 1; attempt <= AgentsPlanDay.RECOVERY_ATTEMPTS; attempt += 1) {
+            await new Promise((resolve) => setTimeout(resolve, AgentsPlanDay.RECOVERY_INTERVAL_MS));
+            let pending = null;
+            try {
+                pending = (await schedule_1.scheduleApi.pendingProposal(agentId));
+            }
+            catch {
+                // A read failing mid-recovery is not itself the answer — keep waiting
+                // until the attempt budget is spent, then surface the ORIGINAL error.
+                continue;
+            }
+            const candidate = pending?.proposal;
+            if (candidate != null && (0, schedule_1.isSmartScheduleProposal)(candidate)) {
+                if (!json) {
+                    this.log(`Recovered the plan after ${attempt * (AgentsPlanDay.RECOVERY_INTERVAL_MS / 1000)}s.`);
+                }
+                return candidate;
+            }
+        }
+        this.warn(`No plan for ${agentId} became readable within ` +
+            `${(AgentsPlanDay.RECOVERY_ATTEMPTS * AgentsPlanDay.RECOVERY_INTERVAL_MS) / 1000}s. ` +
+            'Check `skrr agents plan-day ' +
+            agentId +
+            '` again before regenerating — a second propose starts a second billable run.');
+        return null;
+    }
+    async runProposeOrShow(agentId, flags) {
+        let proposal = null;
+        // Recover a pending draft unless the caller explicitly wants a fresh one.
+        if (flags.regenerate === undefined) {
+            proposal = await this.fetchPending(agentId);
+        }
+        if (!proposal) {
+            let generated;
+            try {
+                generated = await schedule_1.scheduleApi.proposeSmartSchedule({
+                    agentId,
+                    ...(this.workingHoursOverride(flags)
+                        ? { workingHoursOverride: this.workingHoursOverride(flags) }
+                        : {}),
+                    ...(flags.regenerate ? { regenerateHint: flags.regenerate } : {}),
+                });
+            }
+            catch (err) {
+                // Generating a plan is a real agent turn. On a local daemon runtime it
+                // routinely outlives the edge's request budget, and the gateway answers
+                // 504 while the server keeps generating and then PERSISTS the draft —
+                // which is exactly what `GET /smart-schedule/pending` exists to hand
+                // back. Reported as a transport failure this read as "service outage …
+                // Nothing was changed", which was wrong three times over: the service
+                // was up, the command was the cause, and a billable run had happened.
+                //
+                // Recovering the durable draft is also why this must never re-POST
+                // propose: a blind retry starts a SECOND run the user pays for while
+                // the first one is still finishing.
+                const recovered = await this.recoverProposalAfterTimeout(agentId, err, flags.json);
+                if (!recovered)
+                    throw err;
+                proposal = recovered;
+            }
+            if (!proposal) {
+                proposal = this.requireProposal(generated, agentId, 'propose');
+            }
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(proposal, null, 2));
+            return;
+        }
+        (0, schedule_1.renderProposal)(proposal, (line) => this.log(line));
+        this.log('');
+        this.log('This is a draft — nothing is scheduled yet.');
+        this.log(`  Approve:  ${this.config.bin} agents plan-day ${agentId} --approve`);
+        this.log(`  Discard:  ${this.config.bin} agents plan-day ${agentId} --dismiss`);
+    }
+    async runApprove(agentId, flags) {
+        const proposal = await this.fetchPending(agentId);
+        if (!proposal) {
+            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 });
+        }
+        const result = await schedule_1.scheduleApi.approveSmartSchedule({
+            agentId,
+            proposalId: proposal.proposalId,
+            todos,
+            ...(flags['save-hours']
+                ? { saveHoursAsDefault: true, workingHours: proposal.workingHours }
+                : {}),
+        });
+        // Same contract as propose: a body-less or unparseable response is a
+        // failure, not a quiet success (OSK-2803).
+        if (!result || typeof result !== 'object' || !Array.isArray(result.created)) {
+            this.failWithCliError({
+                message: `Approval of plan ${proposal.proposalId} returned no result ` +
+                    `(${(0, schedule_1.describeNonProposal)(result)}). Re-check with \`${this.config.bin} agents todos list ${agentId}\` ` +
+                    'before retrying — some to-dos may already exist.',
+                code: 'SMART_SCHEDULE_APPROVE_UNREADABLE',
+                exit: 1,
+                retryable: true,
+                details: { agentId, proposalId: proposal.proposalId },
+            });
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        this.log(`Approved plan ${proposal.proposalId}: created ${result.created.length} to-do(s).`);
+        (0, schedule_1.renderCapacityWarning)(result.capacity, (line) => this.log(line));
+        if (result.failed.length > 0) {
+            this.log(`${result.failed.length} failed:`);
+            for (const f of result.failed) {
+                this.log(`  - ${f.tempId ?? '?'}: ${f.code} ${f.message}`);
+            }
+        }
+        this.log(`See them with: ${this.config.bin} agents todos list ${agentId}`);
+    }
+    async runDismiss(agentId, json) {
+        const proposal = await this.fetchPending(agentId);
+        if (!proposal) {
+            this.log(`No pending plan for agent ${agentId}.`);
+            return;
+        }
+        const result = await schedule_1.scheduleApi.dismissProposal(proposal.proposalId, agentId);
+        if (json) {
+            this.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        this.log(`Dismissed plan ${proposal.proposalId}.`);
+    }
+}
+exports.default = AgentsPlanDay;

package/dist/commands/agents/preferences/show.d.ts

@@ -0,0 +1,11 @@
+import { BaseCommand } from '../../../base-command';
+export default class AgentsPreferencesShow extends BaseCommand {
+    static description: string;
+    static args: {
+        agentId: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/agents/preferences/show.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../../../base-command");
+class AgentsPreferencesShow extends base_command_1.BaseCommand {
+    static description = "Show an agent's per-user mini-computer preferences";
+    static args = { agentId: core_1.Args.string({ required: true, ignoreStdin: true }) };
+    static flags = { json: core_1.Flags.boolean({ description: 'Output JSON' }) };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(AgentsPreferencesShow);
+        const result = await data_provider_1.dataService.getAgentPreferences(args.agentId);
+        if (flags.json)
+            return this.log(this.agentJson(args.agentId, result));
+        this.log(JSON.stringify(result.preferences ?? {}, null, 2));
+        this.printAgentUrl(args.agentId);
+    }
+}
+exports.default = AgentsPreferencesShow;

package/dist/commands/agents/preferences/update.d.ts

@@ -0,0 +1,14 @@
+import { BaseCommand } from '../../../base-command';
+export default class AgentsPreferencesUpdate extends BaseCommand {
+    static description: string;
+    static args: {
+        agentId: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        pins: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        wallpaper: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'from-json': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/agents/preferences/update.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../../../base-command");
+const prompt_1 = require("../../../lib/prompt");
+class AgentsPreferencesUpdate extends base_command_1.BaseCommand {
+    static description = "Update an agent's per-user mini-computer preferences";
+    static args = { agentId: core_1.Args.string({ required: true, ignoreStdin: true }) };
+    static flags = {
+        pins: core_1.Flags.string({ description: 'Landing pins JSON object' }),
+        wallpaper: core_1.Flags.string({ description: 'Wallpaper JSON value, or null' }),
+        'from-json': core_1.Flags.string({ description: 'JSON file or -' }),
+        json: core_1.Flags.boolean({ description: 'Output JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(AgentsPreferencesUpdate);
+        const body = await (0, prompt_1.readJsonBody)(flags['from-json']);
+        const overrides = {};
+        if (flags.pins !== undefined)
+            overrides.landingPins = JSON.parse(flags.pins);
+        if (flags.wallpaper !== undefined)
+            overrides.wallpaper = JSON.parse(flags.wallpaper);
+        const result = await data_provider_1.dataService.updateAgentPreferences(args.agentId, (0, prompt_1.mergeDefined)(body, overrides));
+        if (flags.json)
+            this.log(this.agentJson(args.agentId, result));
+        else {
+            this.log(`Updated preferences for agent ${args.agentId}`);
+            this.printAgentUrl(args.agentId);
+        }
+    }
+}
+exports.default = AgentsPreferencesUpdate;

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

@@ -0,0 +1,20 @@
+import { BaseCommand } from '../../base-command';
+/**
+ * `agents query` backs the editor's selection helper. It deliberately does
+ * not start an Agent session or persist a conversation, so its user-facing
+ * contract must never look like a durable chat turn. Keep the explanation in
+ * one exported function so text and JSON consumers cannot silently diverge.
+ */
+export declare function quickQueryNotice(agentId: string): string;
+export default class AgentsQuery extends BaseCommand {
+    static description: string;
+    static args: {
+        agentId: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        prompt: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        context: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/agents/query.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.quickQueryNotice = quickQueryNotice;
+const core_1 = require("@oclif/core");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../../base-command");
+const web_url_1 = require("../../lib/web-url");
+/**
+ * `agents query` backs the editor's selection helper. It deliberately does
+ * not start an Agent session or persist a conversation, so its user-facing
+ * contract must never look like a durable chat turn. Keep the explanation in
+ * one exported function so text and JSON consumers cannot silently diverge.
+ */
+function quickQueryNotice(agentId) {
+    return ('[ephemeral] Persona-only quick query — this answer is not saved to the agent history and ' +
+        'did not use the agent runtime, tools, or session. For a durable real turn, use: ' +
+        `skrr agents chat ${agentId} --prompt "…" --no-stream`);
+}
+class AgentsQuery extends base_command_1.BaseCommand {
+    static description = 'Run an ephemeral persona-only quick query (not saved to the agent conversation history)';
+    static args = { agentId: core_1.Args.string({ required: true, ignoreStdin: true }) };
+    static flags = {
+        prompt: core_1.Flags.string({ required: true }),
+        context: core_1.Flags.string(),
+        json: core_1.Flags.boolean({ description: 'Output JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(AgentsQuery);
+        const result = await data_provider_1.dataService.quickQueryAgent({
+            agent_id: args.agentId,
+            prompt: flags.prompt,
+            context: flags.context,
+        });
+        if (flags.json) {
+            this.log(JSON.stringify({
+                ...result,
+                mode: 'quick',
+                executed: false,
+                persisted: false,
+                note: quickQueryNotice(args.agentId),
+                url: (0, web_url_1.agentUrlFrom)(this.cliConfig.baseURL, { id: args.agentId }),
+            }, null, 2));
+            return;
+        }
+        this.log(String(result.response ?? result));
+        this.log(quickQueryNotice(args.agentId));
+        this.printAgentUrl(args.agentId);
+    }
+}
+exports.default = AgentsQuery;

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

@@ -0,0 +1,36 @@
+import { BaseCommand } from '../../base-command';
+/**
+ * `skrr agents reflect <agent-id>` — the agent's self-reflection ("meta cadence")
+ * loop: a single recurring trigger that fires a SILENT agent turn on a chosen
+ * cadence (default every 6h) whose job is to review the agent's own schedule and
+ * RETUNE its own cadence.
+ *
+ *   skrr agents reflect <id>                    # status of the loop
+ *   skrr agents reflect <id> --enable           # start it at the default 6h
+ *   skrr agents reflect <id> --set-cadence 8h   # start/retune to a new interval
+ *   skrr agents reflect <id> --disable          # pause the loop
+ *
+ * The cognition is all prompt (`REFLECTION_PROMPT`) — no bespoke server logic.
+ * The loop is one `scope:agent, kind:schedule, mode:run_only` trigger (the same
+ * shape personal-agent heartbeats use), located idempotently by its `label` so
+ * re-running retunes the existing loop instead of stacking duplicates.
+ */
+export default class AgentsReflect extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        enable: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        'set-cadence': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        disable: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        prompt: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        timezone: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+    private runDisable;
+    private runEnableOrRetune;
+    private runStatus;
+}

package/dist/commands/agents/reflect.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_command_1 = require("../../base-command");
+const triggers_1 = require("../../lib/triggers");
+const reflection_1 = require("../../lib/reflection");
+/**
+ * `skrr agents reflect <agent-id>` — the agent's self-reflection ("meta cadence")
+ * loop: a single recurring trigger that fires a SILENT agent turn on a chosen
+ * cadence (default every 6h) whose job is to review the agent's own schedule and
+ * RETUNE its own cadence.
+ *
+ *   skrr agents reflect <id>                    # status of the loop
+ *   skrr agents reflect <id> --enable           # start it at the default 6h
+ *   skrr agents reflect <id> --set-cadence 8h   # start/retune to a new interval
+ *   skrr agents reflect <id> --disable          # pause the loop
+ *
+ * The cognition is all prompt (`REFLECTION_PROMPT`) — no bespoke server logic.
+ * The loop is one `scope:agent, kind:schedule, mode:run_only` trigger (the same
+ * shape personal-agent heartbeats use), located idempotently by its `label` so
+ * re-running retunes the existing loop instead of stacking duplicates.
+ */
+class AgentsReflect extends base_command_1.BaseCommand {
+    static description = "Manage an agent's self-reflection loop — a recurring silent turn that reviews and retunes its own cadence";
+    static examples = [
+        '<%= config.bin %> agents reflect <agent-id>',
+        '<%= config.bin %> agents reflect <agent-id> --enable',
+        '<%= config.bin %> agents reflect <agent-id> --set-cadence 8h',
+        '<%= config.bin %> agents reflect <agent-id> --set-cadence 90m --timezone America/New_York',
+        '<%= config.bin %> agents reflect <agent-id> --disable',
+    ];
+    static args = {
+        id: core_1.Args.string({ description: 'Agent ID', required: true, ignoreStdin: true }),
+    };
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+        enable: core_1.Flags.boolean({
+            description: `Start the loop at the default cadence (${(0, reflection_1.describeCadenceMinutes)(reflection_1.DEFAULT_REFLECTION_CADENCE_MINUTES)}) if it does not exist`,
+            exclusive: ['disable'],
+        }),
+        'set-cadence': core_1.Flags.string({
+            description: 'Start or retune the loop to this interval (e.g. "6h", "90m", "2h30m", "360")',
+            exclusive: ['disable'],
+        }),
+        disable: core_1.Flags.boolean({
+            description: 'Pause the loop (disables its trigger; safe to re-enable later)',
+            exclusive: ['enable', 'set-cadence'],
+        }),
+        prompt: core_1.Flags.string({
+            description: 'Override the reflection prompt the fired turn receives',
+        }),
+        timezone: core_1.Flags.string({ description: 'IANA timezone for the schedule' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(AgentsReflect);
+        const agentId = args.id;
+        let existing;
+        try {
+            const list = await triggers_1.triggerApi.list((0, triggers_1.withQuery)('/api/triggers', {
+                scope: 'agent',
+                refEntity: (0, triggers_1.agentRefEntity)(agentId),
+                limit: 200,
+            }));
+            existing = (0, reflection_1.findReflectionTrigger)(list.triggers ?? []);
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+        try {
+            if (flags.disable) {
+                await this.runDisable(agentId, existing, flags.json);
+                return;
+            }
+            if (flags['set-cadence'] !== undefined || flags.enable) {
+                await this.runEnableOrRetune(agentId, existing, flags);
+                return;
+            }
+            this.runStatus(agentId, existing, flags.json);
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+    }
+    async runDisable(agentId, existing, json) {
+        if (!existing?.id) {
+            if (json) {
+                this.log(JSON.stringify({ ok: true, agentId, disabled: false, reason: 'no_loop' }, null, 2));
+                return;
+            }
+            this.log(`No self-reflection loop set for agent ${agentId}. Nothing to disable.`);
+            return;
+        }
+        const updated = await triggers_1.triggerApi.setEnabled(existing.id, false);
+        if (json) {
+            this.log(JSON.stringify({ ok: true, agentId, disabled: true, trigger: updated }, null, 2));
+            return;
+        }
+        this.log(`Self-reflection loop paused for agent ${agentId} (trigger ${existing.id}).`);
+        this.log('Re-enable it with:  ' + `${this.config.bin} agents reflect ${agentId} --enable`);
+    }
+    async runEnableOrRetune(agentId, existing, flags) {
+        // Resolve the target cadence: explicit --set-cadence, else keep the existing
+        // interval when just --enabling, else the default.
+        let minutes;
+        if (flags['set-cadence'] !== undefined) {
+            minutes = (0, reflection_1.clampCadenceMinutes)((0, reflection_1.parseCadenceToMinutes)(flags['set-cadence']));
+        }
+        else {
+            minutes =
+                (existing && (0, reflection_1.reflectionCadenceMinutes)(existing)) || reflection_1.DEFAULT_REFLECTION_CADENCE_MINUTES;
+        }
+        const cadence = (0, reflection_1.describeCadenceMinutes)(minutes);
+        if (existing?.id) {
+            const patch = {
+                enabled: true,
+                schedule: {
+                    intervalMs: minutes * 60_000,
+                    ...(flags.timezone ? { timezone: flags.timezone } : {}),
+                },
+            };
+            if (flags.prompt && flags.prompt.trim()) {
+                patch.execution = { mode: 'run_only', promptTemplate: flags.prompt };
+            }
+            const updated = await triggers_1.triggerApi.update(existing.id, patch);
+            if (flags.json) {
+                this.log(JSON.stringify({ ok: true, agentId, action: 'retuned', cadence, trigger: updated }, null, 2));
+                return;
+            }
+            this.log(`Self-reflection loop retuned — agent ${agentId} now reflects every ${cadence}.`);
+            this.log(`Trigger: ${existing.id}`);
+            return;
+        }
+        const payload = (0, reflection_1.buildReflectionTriggerPayload)(agentId, {
+            intervalMinutes: minutes,
+            prompt: flags.prompt,
+            timezone: flags.timezone,
+        });
+        const created = await triggers_1.triggerApi.create(payload);
+        if (flags.json) {
+            this.log(JSON.stringify({ ok: true, agentId, action: 'enabled', cadence, trigger: created }, null, 2));
+            return;
+        }
+        this.log(`Self-reflection loop enabled — agent ${agentId} will reflect every ${cadence}.`);
+        this.log(`Trigger: ${created.id ?? '(created)'}`);
+        this.log(`Next run: ${(0, triggers_1.nextRunLabel)(created)}`);
+    }
+    runStatus(agentId, existing, json) {
+        if (!existing) {
+            if (json) {
+                this.log(JSON.stringify({ ok: true, agentId, enabled: false, exists: false }, null, 2));
+                return;
+            }
+            this.log(`No self-reflection loop set for agent ${agentId}.`);
+            this.log('Enable it with:  ' + `${this.config.bin} agents reflect ${agentId} --set-cadence 6h`);
+            return;
+        }
+        const minutes = (0, reflection_1.reflectionCadenceMinutes)(existing);
+        const cadence = minutes ? (0, reflection_1.describeCadenceMinutes)(minutes) : 'unknown';
+        if (json) {
+            this.log(JSON.stringify({
+                ok: true,
+                agentId,
+                exists: true,
+                enabled: existing.enabled !== false,
+                cadence,
+                cadenceMinutes: minutes ?? null,
+                nextRun: (0, triggers_1.nextRunLabel)(existing),
+                trigger: existing,
+            }, null, 2));
+            return;
+        }
+        this.log(`Self-reflection loop for agent ${agentId}:`);
+        this.log(`  Status:   ${existing.enabled === false ? 'paused' : 'active'}`);
+        this.log(`  Cadence:  every ${cadence}`);
+        this.log(`  Next run: ${(0, triggers_1.nextRunLabel)(existing)}`);
+        this.log(`  Trigger:  ${existing.id ?? '-'}`);
+        if (existing.enabled === false) {
+            this.log('');
+            this.log('Re-enable it with:  ' + `${this.config.bin} agents reflect ${agentId} --enable`);
+        }
+    }
+}
+exports.default = AgentsReflect;