@skrr-ai/cli 0.1.110 → 0.1.113

package/dist/lib/dedicated-ssh.js

@@ -301,8 +301,11 @@ function runSshProxy(options) {
         let closing = false;
         let lastKeepaliveAt = 0;
         let pendingInput = null;
-        const identityAuth = () => ({ ...(0, data_provider_1.getClientIdentityAuth)(), clientPlatform: 'cli',
-            clientOs: process.platform === 'darwin' ? 'macos' : process.platform });
+        const identityAuth = () => ({
+            ...(0, data_provider_1.getClientIdentityAuth)(),
+            clientPlatform: 'cli',
+            clientOs: process.platform === 'darwin' ? 'macos' : process.platform,
+        });
         const wsOrigin = (0, agentic_stream_1.toWebSocketOrigin)(options.baseURL);
         const handshakeAuth = (token, callback) => {
             // Resolve a fresh proof after token renewal on every reconnect. Never
@@ -315,20 +318,30 @@ function runSshProxy(options) {
         };
         const socket = connect(wsOrigin, {
             path: '/ws/agentic',
-            auth: options.getToken ? (callback) => {
-                void options.getToken().then((token) => handshakeAuth(token, callback), () => {
-                    finish(1, 'Could not renew SSH authentication. Restore skrr login and connect again.');
-                });
-            } : (0, dpop_auth_1.socketAuthWithDpop)({ token: options.token, ...identityAuth() }, wsOrigin),
-            transports: ['websocket'], reconnection: true,
-            reconnectionDelay: 1000, reconnectionDelayMax: 2000,
+            auth: options.getToken
+                ? (callback) => {
+                    void options.getToken().then((token) => handshakeAuth(token, callback), () => {
+                        finish(1, 'Could not renew SSH authentication. Restore skrr login and connect again.');
+                    });
+                }
+                : (0, dpop_auth_1.socketAuthWithDpop)({ token: options.token, ...identityAuth() }, wsOrigin),
+            transports: ['websocket'],
+            reconnection: true,
+            reconnectionDelay: 1000,
+            reconnectionDelayMax: 2000,
         });
         const startTimer = setTimeout(() => finish(1, 'The machine did not answer the SSH channel in time. Its daemon may be busy or offline.'), exports.SSH_START_TIMEOUT_MS);
         function sendPendingInput() {
             if (closing || !online || !attached || !pendingInput || finished)
                 return;
-            socket.emit('dedicated:ssh:data', { channelId, data: pendingInput.bytes.toString('base64'),
-                resumeV2: true, epoch, generation, offset: pendingInput.offset });
+            socket.emit('dedicated:ssh:data', {
+                channelId,
+                data: pendingInput.bytes.toString('base64'),
+                resumeV2: true,
+                epoch,
+                generation,
+                offset: pendingInput.offset,
+            });
         }
         function pumpInput() {
             if (closing || !started || !resumable || !online || !attached || pendingInput || finished)
@@ -351,11 +364,23 @@ function runSshProxy(options) {
         };
         function sendResume() {
             if (online && started && resumable && !attached && !finished) {
-                socket.emit('dedicated:ssh:resume', { leaseId: options.leaseId, channelId, resumeProof, epoch, generation, attachmentSeq });
+                socket.emit('dedicated:ssh:resume', {
+                    leaseId: options.leaseId,
+                    channelId,
+                    resumeProof,
+                    epoch,
+                    generation,
+                    attachmentSeq,
+                });
             }
         }
         function keepalive() {
-            if (started && resumable && attached && online && !finished && Date.now() - lastKeepaliveAt >= 10_000) {
+            if (started &&
+                resumable &&
+                attached &&
+                online &&
+                !finished &&
+                Date.now() - lastKeepaliveAt >= 10_000) {
                 lastKeepaliveAt = Date.now();
                 socket.emit('dedicated:ssh:keepalive', { channelId, epoch });
             }
@@ -376,6 +401,10 @@ function runSshProxy(options) {
             keepalive();
         }, 2000);
         ticker.unref?.();
+        const signals = options.signalSource ?? process;
+        const onTermination = () => finish(0);
+        signals.on('SIGHUP', onTermination);
+        signals.on('SIGTERM', onTermination);
         const onInputEnded = () => finish(0);
         const onOutputError = () => finish(1);
         input.once('end', onInputEnded);
@@ -397,10 +426,24 @@ function runSshProxy(options) {
             if (notice)
                 errorOutput.write(`${notice}\n`);
             // Never queue an offline stop that might arrive after another attachment.
-            if (started && online)
-                socket.emit('dedicated:ssh:stop', { channelId, ...(resumable ? { epoch } : {}) });
-            socket.disconnect();
-            resolve(code);
+            const disconnected = () => {
+                signals.off('SIGHUP', onTermination);
+                signals.off('SIGTERM', onTermination);
+                socket.disconnect();
+                resolve(code);
+            };
+            if (started && online) {
+                // OpenSSH may SIGHUP its ProxyCommand before stdio reaches EOF. Keep
+                // the transport alive until the API has forwarded stop. A bounded
+                // fallback also supports older servers without this receipt.
+                const closeTimer = setTimeout(disconnected, 1000);
+                socket.emit('dedicated:ssh:stop', { channelId, ...(resumable ? { epoch } : {}) }, () => {
+                    clearTimeout(closeTimer);
+                    disconnected();
+                });
+            }
+            else
+                disconnected();
         }
         socket.on('connect_error', (error) => {
             if (finished || (started && resumable))
@@ -420,9 +463,16 @@ function runSshProxy(options) {
                 return;
             }
             startSent = true;
-            socket.emit('dedicated:ssh:start', { leaseId: options.leaseId, channelId,
-                keyType: identity.keyType, keyBlob: identity.keyBlob, receiverAckV1: true,
-                resumeV2: true, resumeProof, epoch });
+            socket.emit('dedicated:ssh:start', {
+                leaseId: options.leaseId,
+                channelId,
+                keyType: identity.keyType,
+                keyBlob: identity.keyBlob,
+                receiverAckV1: true,
+                resumeV2: true,
+                resumeProof,
+                epoch,
+            });
         });
         socket.on('dedicated:ssh:start:ack', (ack) => {
             if (!ack || ack.channelId !== channelId || started || finished)
@@ -432,7 +482,9 @@ function runSshProxy(options) {
                 return;
             }
             if (ack.resumeV2 === true) {
-                if (ack.epoch !== epoch || !Number.isSafeInteger(ack.generation) || Number(ack.generation) < 1 ||
+                if (ack.epoch !== epoch ||
+                    !Number.isSafeInteger(ack.generation) ||
+                    Number(ack.generation) < 1 ||
                     (generation !== null && generation !== ack.generation)) {
                     finish(1, 'Invalid SSH stream admission.');
                     return;
@@ -458,7 +510,13 @@ function runSshProxy(options) {
             }
         });
         socket.on('dedicated:ssh:resume:ack', (ack) => {
-            if (!ack || ack.channelId !== channelId || ack.epoch !== epoch || !started || !resumable || finished || attached)
+            if (!ack ||
+                ack.channelId !== channelId ||
+                ack.epoch !== epoch ||
+                !started ||
+                !resumable ||
+                finished ||
+                attached)
                 return;
             if (!ack.ok) {
                 if (ack.retryable === true)
@@ -483,8 +541,14 @@ function runSshProxy(options) {
             pumpInput();
         });
         socket.on('dedicated:ssh:input:ack', (ack) => {
-            if (finished || !resumable || !pendingInput || !attached || ack?.channelId !== channelId ||
-                ack.epoch !== epoch || ack.generation !== generation || ack.offset !== pendingInput.offset)
+            if (finished ||
+                !resumable ||
+                !pendingInput ||
+                !attached ||
+                ack?.channelId !== channelId ||
+                ack.epoch !== epoch ||
+                ack.generation !== generation ||
+                ack.offset !== pendingInput.offset)
                 return;
             if (!ack.ok) {
                 finish(1, ack.error || 'The SSH input stream was refused.');
@@ -499,19 +563,25 @@ function runSshProxy(options) {
             pumpInput();
         });
         socket.on('dedicated:ssh:data', async (frame, receipt) => {
-            if (!frame || frame.channelId !== channelId || finished || typeof frame.data !== 'string' || !frame.data.length)
+            if (!frame ||
+                frame.channelId !== channelId ||
+                finished ||
+                typeof frame.data !== 'string' ||
+                !frame.data.length)
                 return;
             try {
                 const bytes = Buffer.from(frame.data, 'base64');
                 if (frame.resumeV2 === true) {
                     if (frame.epoch !== epoch)
                         return;
-                    if (!Number.isSafeInteger(frame.generation) || Number(frame.generation) < 1 ||
-                        (generation !== null && frame.generation !== generation) || bytes.toString('base64') !== frame.data) {
+                    if (!Number.isSafeInteger(frame.generation) ||
+                        Number(frame.generation) < 1 ||
+                        (generation !== null && frame.generation !== generation) ||
+                        bytes.toString('base64') !== frame.data) {
                         throw new Error('invalid SSH output frame');
                     }
                     generation ??= frame.generation;
-                    const nextOffset = await receiver.receive(frame.offset, bytes, (value) => new Promise((done, reject) => output.write(value, (error) => error ? reject(error) : done())));
+                    const nextOffset = await receiver.receive(frame.offset, bytes, (value) => new Promise((done, reject) => output.write(value, (error) => (error ? reject(error) : done()))));
                     receipt?.({ channelId, ok: !finished, epoch: frame.epoch, nextOffset });
                 }
                 else {

package/dist/lib/json-output.d.ts

@@ -53,4 +53,37 @@ export declare function stripStorageFieldsFromText(text: string): string;
 export declare function withOk<T>(value: T, ok?: boolean): T | ({
     ok: boolean;
 } & Record<string, unknown>);
+export type CliOperationMode = 'execute' | 'dry_run' | 'verify';
+export type CliWriteState = 'confirmed' | 'not_attempted' | 'unknown';
+export type CliResourceIdentity = {
+    kind: string;
+    id?: string | null;
+};
+export type CliTaskIdentity = {
+    id?: string | null;
+};
+export type CliOperationOptions = {
+    command: string;
+    mode: CliOperationMode;
+    /** Command outcome, not a claim that an unsuccessful write did not commit. */
+    outcome: 'succeeded' | 'failed';
+    /** Use only the identity returned by a native read/write, never a requested ref. */
+    resource?: CliResourceIdentity | null;
+    task?: CliTaskIdentity | null;
+    /** Include only when the native response explicitly establishes replay. */
+    replayed?: boolean;
+    writeState?: CliWriteState;
+};
+/**
+ * An opt-in result contract for commands whose native record is not the Task.
+ * Legacy payload paths remain in place; `_cli` is the CLI-owned v1 namespace.
+ * In particular, an Update's id never becomes the enclosing Task's id. Missing
+ * native identities stay null rather than being guessed from positional refs.
+ *
+ * Arrays/primitives remain unchanged. This helper never wraps arbitrary `log`
+ * output, inspects a command name to infer a record, or invents a created ID
+ * for dry-run/verification. `writeState:unknown` on an error is deliberate:
+ * a failed HTTP response is not proof that a server-side write did not commit.
+ */
+export declare function withCliOperation<T>(value: T, options: CliOperationOptions): T | Record<string, unknown>;
 export {};

package/dist/lib/json-output.js

@@ -21,6 +21,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.stripStorageFields = stripStorageFields;
 exports.stripStorageFieldsFromText = stripStorageFieldsFromText;
 exports.withOk = withOk;
+exports.withCliOperation = withCliOperation;
 function usableId(value) {
     return (typeof value === 'string' && value.length > 0) || typeof value === 'number';
 }
@@ -106,3 +107,39 @@ function withOk(value, ok = true) {
         return value;
     return { ok, ...value };
 }
+/**
+ * An opt-in result contract for commands whose native record is not the Task.
+ * Legacy payload paths remain in place; `_cli` is the CLI-owned v1 namespace.
+ * In particular, an Update's id never becomes the enclosing Task's id. Missing
+ * native identities stay null rather than being guessed from positional refs.
+ *
+ * Arrays/primitives remain unchanged. This helper never wraps arbitrary `log`
+ * output, inspects a command name to infer a record, or invents a created ID
+ * for dry-run/verification. `writeState:unknown` on an error is deliberate:
+ * a failed HTTP response is not proof that a server-side write did not commit.
+ */
+function withCliOperation(value, options) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return value;
+    const id = (candidate) => typeof candidate === 'string' && candidate.trim() ? candidate : null;
+    const resourceId = id(options.resource?.id);
+    const taskId = id(options.task?.id);
+    const outcome = value.ok === false ? 'failed' : options.outcome;
+    return {
+        ...withOk(value, outcome === 'succeeded'),
+        _cli: {
+            schemaVersion: 1,
+            command: options.command,
+            mode: options.mode,
+            outcome,
+            resource: resourceId && options.resource?.kind
+                ? { kind: options.resource.kind, id: resourceId }
+                : null,
+            task: taskId ? { id: taskId } : null,
+            ...(options.replayed !== undefined ? { replayed: options.replayed } : {}),
+            writeState: options.mode !== 'execute'
+                ? 'not_attempted'
+                : options.writeState ?? (outcome === 'succeeded' ? 'confirmed' : 'unknown'),
+        },
+    };
+}

package/dist/lib/list-output.d.ts

@@ -18,7 +18,8 @@ export type ListEnvelope = {
  * Documented in docs/cli/SKRR_TASKS.md (List output for agents).
  */
 export declare const COMPACT_FIELDS: {
-    readonly task: readonly ["id", "identifier", "ref", "title", "status", "statusType", "priority", "estimate", "assigneeAgentIds", "assigneeUserIds", "parentId", "spaceId", "projectId", "goalId", "dueDate", "scheduledFor", "labelIds", "tags", "externalKey", "version", "executionMode", "nextAction", "economicsRank", "createdAt", "updatedAt", "url"];
+    readonly agent: readonly ["id", "name", "description", "harnessId", "harnessName", "harnessProvider", "harnessStatus", "executionReadiness", "updatedAt", "url"];
+    readonly task: readonly ["id", "identifier", "ref", "title", "status", "statusType", "priority", "estimate", "assigneeAgentIds", "assigneeUserIds", "parentId", "spaceId", "projectId", "goalId", "dueDate", "scheduledFor", "labelIds", "tags", "externalKey", "version", "executionMode", "nextAction", "actionability", "execution", "economicsRank", "createdAt", "updatedAt", "url"];
     readonly space: readonly ["id", "identifier", "title", "status", "parentSpaceId", "leadAgentId", "labelIds", "archivedAt", "createdAt", "updatedAt", "url"];
     readonly project: readonly ["id", "identifier", "title", "spaceId", "externalKey", "taskCounts", "archivedAt", "createdAt", "updatedAt", "url"];
 };
@@ -38,11 +39,15 @@ export type ListOutputFlags = {
 export declare function parseFields(raw: string | undefined): string[] | undefined;
 export declare function projectRow(row: Record<string, unknown>, fields: readonly string[]): Record<string, unknown>;
 /**
- * Normalize any list response to the shared envelope. `data` is where rows live
- * for every list command; `projects` (an older serialization) is folded into it.
+ * Normalize a list response to the shared envelope. Each command explicitly
+ * supplies its legacy row key when needed; named keys remain compatible.
+ * The original projects adapter continues folding its old key into `data`.
  * A response that is not list-shaped is returned untouched (never invent rows).
  */
-export declare function toListEnvelope(response: unknown): ListEnvelope | undefined;
+export declare function toListEnvelope(response: unknown, rowKey?: string): ListEnvelope | undefined;
+/** Explicit command boundary: retain unknown responses rather than inventing empty rows.
+ * Named row keys remain available for existing consumers during migration. */
+export declare function listResult(response: unknown, rowKey?: string): unknown;
 export type ShapeListOptions = ListOutputFlags & {
     resource: ListResource;
     /** What the caller asked for with --limit (undefined when the command has none). */

package/dist/lib/list-output.js

@@ -4,6 +4,7 @@ exports.listOutputFlags = exports.COMPACT_FIELDS = void 0;
 exports.parseFields = parseFields;
 exports.projectRow = projectRow;
 exports.toListEnvelope = toListEnvelope;
+exports.listResult = listResult;
 exports.shapeListResponse = shapeListResponse;
 exports.limitNote = limitNote;
 exports.warningLines = warningLines;
@@ -38,6 +39,7 @@ const json_output_1 = require("./json-output");
  * Documented in docs/cli/SKRR_TASKS.md (List output for agents).
  */
 exports.COMPACT_FIELDS = {
+    agent: ['id', 'name', 'description', 'harnessId', 'harnessName', 'harnessProvider', 'harnessStatus', 'executionReadiness', 'updatedAt', 'url'],
     task: [
         'id',
         'identifier',
@@ -61,6 +63,8 @@ exports.COMPACT_FIELDS = {
         'version',
         'executionMode',
         'nextAction',
+        'actionability',
+        'execution',
         // Present only on a `--rank economics` page: the score the row was sorted by (OSK-16476).
         'economicsRank',
         'createdAt',
@@ -146,13 +150,15 @@ function projectRow(row, fields) {
     return out;
 }
 /**
- * Normalize any list response to the shared envelope. `data` is where rows live
- * for every list command; `projects` (an older serialization) is folded into it.
+ * Normalize a list response to the shared envelope. Each command explicitly
+ * supplies its legacy row key when needed; named keys remain compatible.
+ * The original projects adapter continues folding its old key into `data`.
  * A response that is not list-shaped is returned untouched (never invent rows).
  */
-function toListEnvelope(response) {
+function toListEnvelope(response, rowKey) {
     if (Array.isArray(response)) {
         return {
+            ok: true,
             object: 'list',
             data: response,
             has_more: false,
@@ -162,25 +168,44 @@ function toListEnvelope(response) {
     if (!response || typeof response !== 'object')
         return undefined;
     const r = response;
-    const rows = Array.isArray(r.data) ? r.data : Array.isArray(r.projects) ? r.projects : undefined;
+    const rows = Array.isArray(r.data)
+        ? r.data
+        : rowKey && Array.isArray(r[rowKey])
+            ? r[rowKey]
+            : Array.isArray(r.projects)
+                ? r.projects
+                : undefined;
     if (!rows)
         return undefined;
+    const nextCursor = r.next_cursor ?? r.nextCursor ?? r.nextAfterId ?? r.after;
     const { projects: _legacy, ...rest } = r;
     void _legacy;
     return {
-        ...rest,
+        ...(0, json_output_1.withOk)(rest),
         object: 'list',
         data: rows,
-        has_more: typeof r.has_more === 'boolean' ? r.has_more : Boolean(r.next_cursor),
-        next_cursor: typeof r.next_cursor === 'string' ? r.next_cursor : null,
+        has_more: typeof r.has_more === 'boolean'
+            ? r.has_more
+            : typeof r.hasMore === 'boolean'
+                ? r.hasMore
+                : Boolean(nextCursor),
+        next_cursor: typeof nextCursor === 'string' ? nextCursor : null,
     };
 }
+/** Explicit command boundary: retain unknown responses rather than inventing empty rows.
+ * Named row keys remain available for existing consumers during migration. */
+function listResult(response, rowKey) {
+    return toListEnvelope(response, rowKey) ?? (0, json_output_1.withOk)(response);
+}
 /** Pure: envelope + projection + notes. Returns the response untouched if not a list. */
 function shapeListResponse(response, options) {
     const envelope = toListEnvelope(response);
     if (!envelope)
         return response;
-    const warnings = [...(options.warnings ?? [])];
+    const warnings = [
+        ...(Array.isArray(envelope.warnings) ? envelope.warnings : []),
+        ...(options.warnings ?? []),
+    ];
     const fields = parseFields(options.fields);
     let data = envelope.data;
     if (fields) {
@@ -279,7 +304,9 @@ function renderListOutput(shaped, ndjson) {
     if (!envelope || !Array.isArray(envelope.data)) {
         return { stdout: [JSON.stringify(shaped)], stderr: [] };
     }
-    const { data, ...meta } = envelope;
+    const { data, ...metadata } = envelope;
+    // Compatibility row aliases are not metadata and must not duplicate the rows.
+    const meta = Object.fromEntries(Object.entries(metadata).filter(([, value]) => value !== data));
     return {
         stdout: data.map((row) => JSON.stringify(row)),
         stderr: [JSON.stringify({ _meta: meta })],

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

@@ -0,0 +1,22 @@
+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;
+/** Validate time forms locally; admission time and authorization remain server authoritative. */
+export declare function lookbackInput(raw: unknown, allowPast?: boolean): LookbackPlanInput;
+export declare function lookbackPlanSummary(plan: LookbackPlan): string;
+export declare function lookbackArmingLine(result: {
+    plan: LookbackPlan;
+    reused?: boolean;
+    armed: boolean;
+}): string;

package/dist/lib/lookbackPlans.js

@@ -0,0 +1,88 @@
+"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;
+exports.lookbackArmingLine = lookbackArmingLine;
+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) => {
+        if (!value.trim())
+            throw new Error('Plan id is empty; see `skrr followups plans list`');
+        return value.trim();
+    },
+});
+/** JSON can be the plan itself or the canonical create envelope. Never copy identity fields. */
+function lookbackCreateBody(input, explicitAgentId) {
+    const envelope = Object.prototype.hasOwnProperty.call(input, 'plan');
+    const allowed = envelope
+        ? ['agentId', 'plan', 'endpointId', 'endpointTarget', 'pinnedConversationId']
+        : ['title', 'objective', 'stopCondition', 'timezone', 'source', 'steps'];
+    const unknown = Object.keys(input).filter((key) => !allowed.includes(key));
+    if (unknown.length)
+        throw new Error(`Unknown lookback input fields: ${unknown.join(', ')}`);
+    if (envelope) {
+        for (const field of ['agentId', 'endpointId', 'endpointTarget', 'pinnedConversationId']) {
+            if (input[field] !== undefined && (typeof input[field] !== 'string' || !input[field].trim())) {
+                throw new Error(`${field} must be a non-empty string`);
+            }
+        }
+    }
+    const inputAgent = typeof input.agentId === 'string' ? input.agentId : undefined;
+    if (explicitAgentId && inputAgent && explicitAgentId !== inputAgent) {
+        throw new Error('--agent conflicts with agentId in the input');
+    }
+    const agent = (0, followups_1.resolveFollowUpAgent)(explicitAgentId || inputAgent);
+    return {
+        agentId: agent.id,
+        producer: agent.boundToSession ? 'agent_in_turn' : 'user_explicit',
+        plan: lookbackInput(envelope ? input.plan : input),
+        ...(envelope && input.endpointId !== undefined ? { endpointId: input.endpointId } : {}),
+        ...(envelope && input.endpointTarget !== undefined ? { endpointTarget: input.endpointTarget } : {}),
+        ...(envelope && input.pinnedConversationId !== undefined
+            ? { pinnedConversationId: input.pinnedConversationId } : {}),
+    };
+}
+/** Validate time forms locally; admission time and authorization remain server authoritative. */
+function lookbackInput(raw, allowPast = false) {
+    const parsed = (0, data_provider_1.normalizeLookbackPlanInput)(raw, { allowPast });
+    if (!parsed.ok)
+        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;
+}
+function lookbackPlanSummary(plan) {
+    const next = plan.steps.find((step) => step.state === 'pending');
+    return `${plan.id}  [${plan.state}] r${plan.revision}  ${plan.title || plan.objective}` +
+        `  ${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)' : ''}.`;
+}