@skrr-ai/cli 0.1.21 → 0.1.23

package/dist/base-command.js

@@ -10,6 +10,7 @@ exports.describeAssigneeNotInSpace = describeAssigneeNotInSpace;
 exports.describeForbidden = describeForbidden;
 exports.isDaemonScopedCredential = isDaemonScopedCredential;
 exports.describeDaemonScopedCredential = describeDaemonScopedCredential;
+exports.isTypedServerRefusal = isTypedServerRefusal;
 exports.isRetryableFailure = isRetryableFailure;
 const core_1 = require("@oclif/core");
 Object.defineProperty(exports, "Flags", { enumerable: true, get: function () { return core_1.Flags; } });
@@ -936,6 +937,29 @@ class BaseCommand extends core_1.Command {
                     retryable: true,
                 });
             }
+            else if (isTypedServerRefusal(body)) {
+                // A 5xx the server DELIBERATELY produced and described in its own
+                // words. Reaching the outage branch below made the CLI announce a
+                // platform outage for a per-conversation condition: "https://skrr.ai is
+                // not serving requests right now. This is a service outage, not a
+                // problem with your account or this command" — for
+                // `CONVERSATION_ADMISSION_OUTCOME_UNCONFIRMED`, while skrr.ai served
+                // every other command in the same minute, with the outer `retryable`
+                // reading true over an inner `false` (retrying was futile for ~35
+                // minutes). The reader is sent to a status page instead of learning
+                // that one conversation is parked (OSK-7719).
+                //
+                // So: the server's code, the server's words, and the server's verdict
+                // on whether retrying can help.
+                this.failWithCliError({
+                    message: say(bodyMessage || e.message),
+                    code: bodyCode || `HTTP_${e.status}`,
+                    status: e.status,
+                    exit: 1,
+                    retryable: isRetryableFailure(e.status, body),
+                    details: body ?? undefined,
+                });
+            }
             else if ((0, outbox_1.isOutageFailure)(e)) {
                 // A gateway/unavailable status is an OUTAGE, and saying so is the whole
                 // point. During the OSK-2806 incident these surfaced as bare
@@ -955,11 +979,17 @@ class BaseCommand extends core_1.Command {
                 // predicate is what made a single route's 500 read as a platform
                 // outage.
                 this.noteControlPlaneOutage(e.status);
+                const method = e.method?.toUpperCase();
+                const readOnlyRequest = method === 'GET' || method === 'HEAD' || method === 'OPTIONS';
+                const outcome = readOnlyRequest
+                    ? 'No write was attempted by this request; retry once the service recovers.'
+                    : 'For a write, the gateway may have timed out after the server committed it. ' +
+                        'The outcome is unknown — check the target or reconcile by idempotency key before retrying.';
                 this.failWithCliError({
                     message: say(`${this.cliConfig.baseURL} is not serving requests right now` +
                         `${e.status ? ` (HTTP ${e.status})` : ''}. ` +
                         'This is a service outage, not a problem with your account or this command. ' +
-                        'Nothing was changed — retry once it recovers.'),
+                        outcome),
                     code: 'CONTROL_PLANE_UNAVAILABLE',
                     status: e.status,
                     exit: 5,
@@ -1093,15 +1123,16 @@ class BaseCommand extends core_1.Command {
             });
         }
         // Same discipline as `handleApiError`: only a real outage gets outage
-        // wording, and only an outage lets us say nothing was written. A 500 is
-        // queued too, but the server ran our request before failing, so what it did
-        // with it is unknown — and a replay is safe on the idempotency key rather
-        // than on an assumption that nothing landed.
+        // wording. Even an edge 504 can arrive AFTER the application committed a
+        // write, so neither branch claims nothing landed. A replay is safe because
+        // the queued record carries an idempotency key, not because the first
+        // attempt is assumed absent.
         const outage = (0, outbox_1.isOutageFailure)(err);
         const statusSuffix = e.status ? ` (HTTP ${e.status})` : '';
         const lead = outage
             ? `${this.cliConfig.baseURL} is not serving requests right now${statusSuffix}. ` +
-                `Your ${write.summary} was queued locally as ${queuedId} — nothing has been written yet.`
+                `Your ${write.summary} was queued locally as ${queuedId}; whether the server already ` +
+                'applied the timed-out attempt is unknown, so verify before replaying.'
             : `${this.cliConfig.baseURL} did not accept this write${statusSuffix}. ` +
                 `Your ${write.summary} was queued locally as ${queuedId}; whether the server applied ` +
                 'any of it is not reported, so verify before replaying.';
@@ -1341,15 +1372,23 @@ function describeAssigneeNotInSpace(serverMessage, bin = 'skrr') {
  * Server-declared TERMINAL refusals: a state conflict the caller must resolve
  * by doing something DIFFERENT, never by repeating the identical request.
  *
- * `skrr tasks move --status done` on a checked-out task with no approved
- * TASK_OUTPUT returns 409 `task_output_required`. 409 used to be in the
+ * `skrr tasks move --status done` with no current Result or independent Review
+ * returns a typed 409. 409 used to be in the
  * transient set below, so the JSON envelope said `retryable: true` — and
  * `daemon/CLAUDE.md` tells daemon-hosted agents to retry retryable errors, so
  * they looped on a refusal that can never succeed on retry. The refusal names
- * the supported path (`POST /:taskId/complete` / `skrr tasks complete`); the
+ * the supported path (`skrr tasks complete`, Result, then Review); the
  * envelope has to agree that the ONLY way forward is that path.
  */
-const TERMINAL_ERROR_CODES = new Set(['task_output_required', 'task_output_not_approved']);
+const TERMINAL_ERROR_CODES = new Set([
+    'TASK_RESULT_REQUIRED',
+    'TASK_CURRENT_RESULT_MISSING',
+    'TASK_RESULT_SPEC_VERSION_MISMATCH',
+    'TASK_EXPECTATIONS_NOT_MET',
+    'TASK_RESULT_CHANGES_REQUESTED',
+    'TASK_RESULT_REVIEW_REQUIRED',
+    'TASK_DELIVERY_NOT_INTEGRATED',
+]);
 /**
  * Whether an automated retry of the IDENTICAL request could plausibly succeed.
  *
@@ -1451,6 +1490,28 @@ function describeDaemonScopedCredential(bin, scope = 'daemon', source) {
     return (`${subject}, which cannot access user API commands. ` +
         `Run \`${bin} login\` to create a CLI credential. For the local runtime itself, use \`${bin} daemon login\`.`);
 }
+/**
+ * Did the server MEAN this 5xx, or did it fall over?
+ *
+ * An outage and a designed refusal arrive with the same status and want
+ * opposite reactions — wait for recovery, versus act on a condition. The
+ * discriminator is whether the server authored an answer: a typed `code` plus
+ * either an explanation it wrote (`cause` / `remedy`, both of which the 5xx
+ * redaction boundary deliberately lets through) or an explicit verdict that
+ * retrying will not help.
+ *
+ * Deliberately NOT folded into `isOutageFailure`: that predicate also gates the
+ * outbox queue decision and `noteControlPlaneOutage`, and those ask a different
+ * question. Merging the two is the mistake its own comment warns about.
+ */
+function isTypedServerRefusal(body) {
+    if (!body || typeof body !== 'object')
+        return false;
+    const code = stringProp(body, 'code') || stringProp(body, 'errorType');
+    if (!code)
+        return false;
+    return (typeof body.cause === 'string' || typeof body.remedy === 'string' || body.retryable === false);
+}
 function isRetryableFailure(status, body) {
     const declared = body?.retryable;
     if (typeof declared === 'boolean')

package/dist/commands/agents/attach-harness.d.ts

@@ -1,15 +1,52 @@
 import { BaseCommand } from '../../base-command';
+/**
+ * Sort two positionals into (harness, agent), whichever order they were typed.
+ *
+ * The discriminator is the id SHAPE, not the position: an agent id is
+ * `agent_…`, and nothing else this command accepts is. That covers the reported
+ * mistake exactly — `attach-harness <agent> <harness>` — without guessing when
+ * neither value looks like an agent.
+ *
+ * Returns `{ error }` rather than picking, when the two sources disagree.
+ */
+export declare function resolveAttachPositionals(first: string, second: string | undefined, agentFlag: string | undefined): {
+    harness: string;
+    agent?: string;
+    error?: undefined;
+} | {
+    error: string;
+    harness?: undefined;
+};
 export default class AgentsAttachHarness extends BaseCommand {
     static description: string;
     static examples: string[];
+    /**
+     * Which positional is which, when a caller gave two.
+     *
+     * This is the ONLY command in the `agents` topic whose positional is not the
+     * agent — every neighbour is `agents <verb> <agent-id> [args]`, and the
+     * space's own Execution Map documents `attach-harness <agent> <harness>`. A
+     * caller writing that shape had their agent id silently accepted AS THE
+     * HARNESS and the real harness rejected with `Unexpected argument:
+     * 6a985ed2…` — an error that names the argument it does not want, never says
+     * what it does want, and does not notice that the value it accepted is
+     * obviously an `agent_…` id (OSK-7686).
+     *
+     * So both orders work, decided by the shape of the ids rather than by
+     * position. An explicit `--agent` still wins, and a conflict is refused
+     * rather than silently resolved — being attached to the wrong machine is the
+     * wrong way to find out which one was meant.
+     */
     static args: {
         harness: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+        agent: import("@oclif/core/lib/interfaces").Arg<string | undefined, Record<string, unknown>>;
     };
     static flags: {
         json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         agent: 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>;
         'advance-on': import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'strict-order': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         'rebind-tasks': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;

package/dist/commands/agents/attach-harness.js

@@ -1,10 +1,50 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveAttachPositionals = resolveAttachPositionals;
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../base-command");
 const execution_target_1 = require("../../lib/execution-target");
 const agent_resolver_1 = require("../../lib/agent-resolver");
+/**
+ * Sort two positionals into (harness, agent), whichever order they were typed.
+ *
+ * The discriminator is the id SHAPE, not the position: an agent id is
+ * `agent_…`, and nothing else this command accepts is. That covers the reported
+ * mistake exactly — `attach-harness <agent> <harness>` — without guessing when
+ * neither value looks like an agent.
+ *
+ * Returns `{ error }` rather than picking, when the two sources disagree.
+ */
+function resolveAttachPositionals(first, second, agentFlag) {
+    const isAgentId = (value) => !!value && value.startsWith('agent_');
+    let harness = first;
+    let agent = second;
+    if (second && isAgentId(first) && !isAgentId(second)) {
+        harness = second;
+        agent = first;
+    }
+    else if (second && isAgentId(first) && isAgentId(second)) {
+        return {
+            error: `Both positionals look like agent ids ("${first}", "${second}"). ` +
+                'Pass one agent and one harness: `agents attach-harness <harness> --agent <agent>`.',
+        };
+    }
+    if (agent && agentFlag && agent !== agentFlag) {
+        return {
+            error: `Conflicting agents: "${agent}" (positional) and "${agentFlag}" (--agent). Pass one. ` +
+                'Attaching to the wrong machine is the wrong way to find out which was meant.',
+        };
+    }
+    if (isAgentId(harness)) {
+        return {
+            error: `"${harness}" is an agent id, not a harness. This command takes the harness first: ` +
+                '`agents attach-harness <harness> --agent <agent>`. ' +
+                'List harnesses with `skrr harnesses list --all`.',
+        };
+    }
+    return { harness, ...(agent ? { agent } : {}) };
+}
 class AgentsAttachHarness extends base_command_1.BaseCommand {
     static description = 'Attach a harness to an agent';
     static examples = [
@@ -18,6 +58,23 @@ class AgentsAttachHarness extends base_command_1.BaseCommand {
     // local-daemon user — a dead end at the exact moment the id is needed.
     // `harnesses list` is the command that surfaces daemon-registered harness
     // _ids (see cli/src/commands/harnesses/list.ts).
+    /**
+     * Which positional is which, when a caller gave two.
+     *
+     * This is the ONLY command in the `agents` topic whose positional is not the
+     * agent — every neighbour is `agents <verb> <agent-id> [args]`, and the
+     * space's own Execution Map documents `attach-harness <agent> <harness>`. A
+     * caller writing that shape had their agent id silently accepted AS THE
+     * HARNESS and the real harness rejected with `Unexpected argument:
+     * 6a985ed2…` — an error that names the argument it does not want, never says
+     * what it does want, and does not notice that the value it accepted is
+     * obviously an `agent_…` id (OSK-7686).
+     *
+     * So both orders work, decided by the shape of the ids rather than by
+     * position. An explicit `--agent` still wins, and a conflict is refused
+     * rather than silently resolved — being attached to the wrong machine is the
+     * wrong way to find out which one was meant.
+     */
     static args = {
         harness: core_1.Args.string({
             description: 'Harness id. Use sbs_... for a Hosted Machine session, hosted-machine for the default Hosted Machine product, agent-worker for the cloud worker, or a harness id. ' +
@@ -25,6 +82,12 @@ class AgentsAttachHarness extends base_command_1.BaseCommand {
             required: true,
             ignoreStdin: true,
         }),
+        agent: core_1.Args.string({
+            description: 'Optional second positional, so `agents attach-harness <agent> <harness>` — the shape ' +
+                'every other agents command uses — works. Equivalent to --agent.',
+            required: false,
+            ignoreStdin: true,
+        }),
     };
     static flags = {
         json: core_1.Flags.boolean({ description: 'Output the attachment result as JSON' }),
@@ -36,10 +99,23 @@ class AgentsAttachHarness extends base_command_1.BaseCommand {
             multiple: true,
         }),
         'advance-on': core_1.Flags.string({
-            description: 'Failure category that permits the current target to advance to the next target.',
+            description: 'Failure category that permits EACH non-final target to advance to the next one. ' +
+                // The flag read as an explicit opt-in, so omitting it looked like
+                // opting into nothing — and the server was writing
+                // `["offline","unavailable"]` on a target the caller had explicitly
+                // pinned, with nothing in --help or in either command's output saying
+                // so (OSK-7669).
+                'Defaults to `offline unavailable` when omitted and a next target exists; ' +
+                'pass --strict-order for a chain no failure may advance. ' +
+                'Applies to every non-final target, not only the one named here.',
             multiple: true,
             options: [...execution_target_1.EXECUTION_TARGET_ADVANCE_REASONS],
         }),
+        'strict-order': core_1.Flags.boolean({
+            description: 'No failure category permits an advance. The declared next targets stay recorded but ' +
+                'the chain never moves — previously only expressible by hand-writing executionPolicy ' +
+                'through --from-json.',
+        }),
         'rebind-tasks': core_1.Flags.boolean({
             description: 'Publish the updated agent release and migrate dormant assigned task pins to it. Running, review, and completed tasks are never changed.',
         }),
@@ -47,9 +123,20 @@ class AgentsAttachHarness extends base_command_1.BaseCommand {
     async run() {
         this.requireAuth();
         const { args, flags } = await this.parse(AgentsAttachHarness);
+        const positional = resolveAttachPositionals(args.harness, args.agent, flags.agent);
+        if (positional.error) {
+            this.failWithCliError({
+                message: positional.error,
+                code: 'ATTACH_HARNESS_ARGUMENTS',
+                exit: 2,
+                retryable: false,
+            });
+        }
+        const harnessArg = positional.harness;
+        const agentArg = positional.agent;
         let agentIdentity;
         try {
-            agentIdentity = await (0, agent_resolver_1.resolveAgentIdentity)(flags.agent);
+            agentIdentity = await (0, agent_resolver_1.resolveAgentIdentity)(flags.agent || agentArg);
         }
         catch (err) {
             const failure = (0, agent_resolver_1.agentResolutionFailure)(err);
@@ -66,8 +153,9 @@ class AgentsAttachHarness extends base_command_1.BaseCommand {
         let patch;
         try {
             patch = (0, execution_target_1.buildExecutionOrderPatch)({
-                selectors: [args.harness, ...(flags['next-target'] || [])],
+                selectors: [harnessArg, ...(flags['next-target'] || [])],
                 advanceOn: flags['advance-on'],
+                strict: flags['strict-order'],
             });
         }
         catch (err) {
@@ -110,6 +198,17 @@ class AgentsAttachHarness extends base_command_1.BaseCommand {
             this.log(`Agent resolved from ${agentIdentity.source}.`);
         }
         this.log(`Execution order: ${targets.map(executionTargetSelector).join(' → ')}`);
+        // Print the policy that was actually written. A default the operator did
+        // not ask for and cannot see is one they will not know they have — the
+        // only way to find it was to diff the returned JSON against what was typed
+        // (OSK-7669).
+        for (const [index, target] of targets.entries()) {
+            const advance = Array.isArray(target.advanceOn) ? target.advanceOn : [];
+            this.log(`  ${index + 1}. ${executionTargetSelector(target)} — ` +
+                (advance.length > 0
+                    ? `may advance on: ${advance.join(', ')}`
+                    : 'strict: no failure permits an advance'));
+        }
         const migration = updated?.harnessAttachment;
         if (migration) {
             this.log(`Published release ${migration.releaseId || 'unknown'} and rebound ` +

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

@@ -1,5 +1,73 @@
 import { BaseCommand } from '../../base-command';
-import { type AgenticStreamResult } from '../../lib/agentic-stream';
+import { type AgenticStreamResult, type ReconciledTerminal } from '../../lib/agentic-stream';
+/**
+ * Exit code for a run the USER stopped watching, by pressing Ctrl-C.
+ *
+ * OSK-2944 established that exiting 1 on a lost stream made "the run failed"
+ * and "we lost the view of a live run" indistinguishable, and invited duplicate
+ * execution. So a detach gets its own non-zero code.
+ *
+ * It must be non-zero on EVERY output mode. The `--jsonl` branch used to
+ * `return` here, which leaves the exit code at 0, so a script driving the CLI
+ * read a detached — possibly already-failed — run as a success. That is the
+ * mode automation actually uses.
+ */
+export declare const DETACH_EXIT_CODE = 130;
+/**
+ * Exit code for a detach nobody asked for — the stream was lost, or could not
+ * be attached at all.
+ *
+ * 130 is the conventional "killed by SIGINT" code, and it was returned for a
+ * detach that no signal caused: a script reading it concludes the user pressed
+ * Ctrl-C, which is the opposite of what happened (OSK-7660). Reserving 130 for
+ * an actual interrupt and giving the unattended case its own code keeps both
+ * answers true.
+ */
+export declare const STREAM_LOST_EXIT_CODE = 75;
+/**
+ * What to say when the user pressed Ctrl-C and the run did not stop.
+ *
+ * A cancel is REQUESTED over the session; whether the harness honours it is not
+ * something this process can guarantee. Measured on a local harness, where the
+ * answer is checkable with `ps`: the CLI exited, and the shell and the `sleep
+ * 200` it had spawned were still alive at +10s, +26s and +53s — while the CLI
+ * said nothing about it at all (OSK-7733). Three things compound there: work
+ * the user asked to stop keeps consuming their machine and their vendor tokens;
+ * they are not told, so they will not go and kill it; and the record is left
+ * `unfinished: true` with no error, so the cancellation is invisible in history
+ * too.
+ *
+ * Silence is the one unacceptable option, because the user will believe they
+ * cancelled. This says what was asked, what is not guaranteed, and how to look.
+ */
+export declare function interruptedDetachMessage(input: {
+    sessionId: string;
+    conversationId?: string | null;
+}): string;
+/**
+ * What the durable record says about a turn, read from its messages.
+ *
+ * The stream is not the only witness and must not be the only one consulted: a
+ * run refused during admission writes `error: true` plus the reason on the
+ * response message and never closes the session stream, so a joined subscriber
+ * waits forever for an event that will not come (OSK-7624, OSK-7635, OSK-7720,
+ * OSK-7735). Exported as a pure function so the mapping from a message row to a
+ * terminal verdict is testable without a socket.
+ *
+ * Returns null while the row is still in flight — the caller keeps waiting,
+ * because a long tool call is silence, not a failure.
+ */
+export declare function reconcileTerminalFromMessages(messages: ReadonlyArray<Record<string, unknown>>, responseMessageId?: string): ReconciledTerminal | null;
+/**
+ * How to look at a turn the CLI is no longer watching.
+ *
+ * NOT `skrr agents chat --conversation <id>`, which is what this used to print:
+ * that command requires the `agentId` argument and `--prompt`, so it exits with
+ * `Missing 1 required arg: agentId` and never reattaches. A recovery
+ * instruction that cannot be run is worse than none — it costs the reader a
+ * round trip to discover the product was wrong.
+ */
+export declare function inspectTurnCommand(conversationId?: string | null): string;
 /**
  * A terminal run that produced no text is NOT a success to report silently.
  *