@skrr-ai/cli 0.1.36 → 0.1.38

package/dist/lib/agent-config.d.ts

@@ -1,2 +1,13 @@
+export declare const COMMITMENT_RESPONSIBILITY_LEVELS: readonly ["reasoning_only", "full_ownership"];
+export declare const REASONING_TOOL_ESCAPES: readonly ["bash", "browser"];
+export declare const RELEASE_INSTALL_CHANNELS: readonly ["latest", "manual"];
+/**
+ * `09:00-18:00` or `09:00-18:00@America/Los_Angeles`, or a JSON object.
+ *
+ * The stored shape is `{start, end, timezone}` with `start`/`end` REQUIRED, so
+ * the shorthand always supplies both and never a half-open window the schema
+ * would reject at write time with a message about a subdocument.
+ */
+export declare function parseWorkingHoursFlag(value: string): Record<string, unknown>;
 /** Apply the structured agent fields exposed by the web config editor. */
 export declare function mergeAgentConfigFlags(body: Record<string, unknown>, flags: Record<string, unknown>): Record<string, unknown>;

package/dist/lib/agent-config.js

@@ -1,7 +1,35 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.RELEASE_INSTALL_CHANNELS = exports.REASONING_TOOL_ESCAPES = exports.COMMITMENT_RESPONSIBILITY_LEVELS = void 0;
+exports.parseWorkingHoursFlag = parseWorkingHoursFlag;
 exports.mergeAgentConfigFlags = mergeAgentConfigFlags;
 const prompt_1 = require("./prompt");
+const agent_visual_refs_1 = require("./agent-visual-refs");
+exports.COMMITMENT_RESPONSIBILITY_LEVELS = ['reasoning_only', 'full_ownership'];
+exports.REASONING_TOOL_ESCAPES = ['bash', 'browser'];
+exports.RELEASE_INSTALL_CHANNELS = ['latest', 'manual'];
+/**
+ * `09:00-18:00` or `09:00-18:00@America/Los_Angeles`, or a JSON object.
+ *
+ * The stored shape is `{start, end, timezone}` with `start`/`end` REQUIRED, so
+ * the shorthand always supplies both and never a half-open window the schema
+ * would reject at write time with a message about a subdocument.
+ */
+function parseWorkingHoursFlag(value) {
+    const trimmed = value.trim();
+    if (trimmed.startsWith('{'))
+        return JSON.parse(trimmed);
+    const [window, timezone] = trimmed.split('@');
+    const match = /^([0-2]\d:[0-5]\d)-([0-2]\d:[0-5]\d)$/.exec(window ?? '');
+    if (!match) {
+        throw new Error(`--todo-working-hours: cannot read "${value}". ` +
+            'Write HH:MM-HH:MM, optionally @<IANA timezone> — for example ' +
+            '09:00-18:00@America/Los_Angeles. A JSON object is also accepted.');
+    }
+    return timezone
+        ? { start: match[1], end: match[2], timezone }
+        : { start: match[1], end: match[2] };
+}
 /** Apply the structured agent fields exposed by the web config editor. */
 function mergeAgentConfigFlags(body, flags) {
     const json = {
@@ -22,10 +50,21 @@ function mergeAgentConfigFlags(body, flags) {
         if (value !== undefined)
             parsed[field] = JSON.parse(String(value));
     }
+    /**
+     * `avatar` and `sceneBackground` are DISCRIMINATED UNIONS server-side, not
+     * strings — see `agent-visual-refs.ts`. `--scene-background` used to sit in
+     * the pass-through map below, which made it a flag with no value that could
+     * pass validation. Both go through the shared parser.
+     */
+    if (flags['scene-background'] !== undefined) {
+        parsed.sceneBackground = (0, agent_visual_refs_1.parseSceneBackgroundFlag)(String(flags['scene-background']));
+    }
+    if (flags.avatar !== undefined) {
+        parsed.avatar = (0, agent_visual_refs_1.parseAvatarRefFlag)(String(flags.avatar));
+    }
     const direct = {
         'network-mode': 'network_mode',
         'character-3d-id': 'character3DId',
-        'scene-background': 'sceneBackground',
         'tone-mode': 'toneMode',
         'tone-id': 'toneId',
         'tone-notes': 'toneNotes',
@@ -46,8 +85,51 @@ function mergeAgentConfigFlags(body, flags) {
         if (flags[flag] !== undefined)
             parsed[field] = flags[flag];
     }
-    if (flags['recursion-limit'] !== undefined)
-        parsed.recursion_limit = flags['recursion-limit'];
+    const integers = {
+        'recursion-limit': 'recursion_limit',
+        'max-turns': 'maxTurns',
+    };
+    for (const [flag, field] of Object.entries(integers)) {
+        if (flags[flag] !== undefined)
+            parsed[field] = flags[flag];
+    }
+    /* Fields the web config editor has always written and no flag reached. */
+    if (flags['conversation-starter'] !== undefined) {
+        parsed.conversation_starters = flags['conversation-starter'];
+    }
+    if (flags['todo-working-hours'] !== undefined) {
+        parsed.todoWorkingHours = parseWorkingHoursFlag(String(flags['todo-working-hours']));
+    }
+    if (flags['reasoning-tool-escape'] !== undefined) {
+        parsed.reasoningToolEscapes = flags['reasoning-tool-escape'];
+    }
+    if (flags['commitment-responsibility'] !== undefined) {
+        parsed.commitmentResponsibilityDefault = flags['commitment-responsibility'];
+    }
+    if (flags['commitment-responsibility-ceiling'] !== undefined) {
+        parsed.commitmentResponsibilityCeiling = flags['commitment-responsibility-ceiling'];
+    }
+    if (flags['tool-resources'] !== undefined) {
+        parsed.tool_resources = JSON.parse(String(flags['tool-resources']));
+    }
+    if (flags['project-id'] !== undefined)
+        parsed.projectIds = flags['project-id'];
+    if (flags['remove-project-id'] !== undefined) {
+        parsed.removeProjectIds = flags['remove-project-id'];
+    }
+    // Two flags, one stored object. Sent whole so a caller who sets only the
+    // channel does not silently clear `allowAutoMinorUpdates` — the server
+    // replaces the subdocument rather than merging into it.
+    if (flags['install-channel'] !== undefined || flags['auto-minor-updates'] !== undefined) {
+        const releasePolicy = {};
+        if (flags['install-channel'] !== undefined) {
+            releasePolicy.defaultInstallChannel = flags['install-channel'];
+        }
+        if (flags['auto-minor-updates'] !== undefined) {
+            releasePolicy.allowAutoMinorUpdates = flags['auto-minor-updates'];
+        }
+        parsed.releasePolicy = releasePolicy;
+    }
     // Cross-Space Task execution ceiling. `0` means unlimited, matching the
     // Space limits' convention so a user learns one spelling of "no cap".
     if (flags['max-concurrent-task-executions'] !== undefined) {

package/dist/lib/agent-pin-mute.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `pin` / `unpin` / `mute` / `unmute` on top of a TOGGLE endpoint.
+ *
+ * `PATCH /api/user/agent-preferences/:agentId/pin` flips the bit; it does not
+ * take a desired state. A CLI that exposed the flip directly would make
+ * `skrr agents pin X` mean "pin it, unless it already was, in which case unpin
+ * it" — fine for a button a human clicks while looking at the result, wrong for
+ * a command in a script, where the outcome would depend on state the script
+ * never read.
+ *
+ * So the desired state is sent, and the endpoint now takes one. It used to be
+ * read-then-flip-if-different, which made each command idempotent when run
+ * alone and inverted under concurrency: six `skrr agents pin` calls that each
+ * read "unpinned" sent six flips, and six flips from false is false — pinning an
+ * agent six times left it unpinned. That was never fixable from out here, as the
+ * previous version of this comment said; it needed the endpoint to accept a
+ * desired state, which is what `pinned`/`muted` in the body now is.
+ *
+ * `changed` comes from the server, which is the only place that can compare the
+ * old value with the new one without a second race.
+ */
+export type AgentFlag = 'pin' | 'mute';
+export interface FlagChange {
+    /** The value the server reports AFTER this call. */
+    value: boolean;
+    /** False when the flag already held the desired value and nothing was sent. */
+    changed: boolean;
+}
+export declare function setAgentFlag(agentId: string, flag: AgentFlag, desired: boolean): Promise<FlagChange>;

package/dist/lib/agent-pin-mute.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setAgentFlag = setAgentFlag;
+const data_provider_1 = require("@skrr-ai/data-provider");
+async function setAgentFlag(agentId, flag, desired) {
+    const current = await data_provider_1.dataService.getAgentPreferences(agentId);
+    const held = flag === 'pin' ? current.preferences?.isPinned : current.preferences?.isMuted;
+    // Nothing to send. True on every server version, and the one case where a
+    // write would be pure risk.
+    if (Boolean(held) === desired) {
+        return { value: desired, changed: false };
+    }
+    // The read stays, and it is NOT what the race was. The race was read-then-
+    // FLIP: the write depended on what was read, so two readers of the same value
+    // sent two flips. The write now carries the desired state, so any number of
+    // them land on it — the read only decides whether to speak at all.
+    //
+    // It also keeps this honest against a server that has not been deployed yet.
+    // A build without the desired-state branch ignores the body and flips; from a
+    // state we have just confirmed differs, one flip still reaches `desired`, so
+    // the reported outcome is true either way. Reporting the server's `changed`
+    // alone was not: an old server omits it, `?? false` read that as "nothing to
+    // do", and `skrr agents pin` said so while flipping the bit.
+    if (flag === 'pin') {
+        const result = await data_provider_1.dataService.toggleAgentPin(agentId, desired);
+        return { value: result.isPinned, changed: result.changed ?? true };
+    }
+    const result = await data_provider_1.dataService.toggleAgentMute(agentId, desired);
+    return { value: result.isMuted, changed: result.changed ?? true };
+}

package/dist/lib/agent-visual-refs.d.ts

@@ -0,0 +1,33 @@
+import type { AgentAvatarRef, AgentSceneBackground } from '@skrr-ai/data-provider';
+/**
+ * The `--scene-background` help, shared by `agents create` and `agents update`.
+ *
+ * It named three forms and no preset ids, while the refusal it led to named a
+ * fourth form (JSON) and listed all the ids — so the only way to learn the valid
+ * values was to type a wrong one on purpose. `--avatar`, one flag away, already
+ * did this right. Built from the shipped catalog so it cannot fall behind it.
+ */
+export declare const SCENE_BACKGROUND_FLAG_HELP: string;
+export declare function imageUploadMimeType(filePath: string): string | undefined;
+/** Preset ids this build ships, for an error message that can be acted on. */
+export declare function avatarPresetIds(): string[];
+export declare function sceneBackgroundPresetIds(): string[];
+export declare function parseAvatarRefFlag(value: string): AgentAvatarRef;
+export declare function parseSceneBackgroundFlag(value: string): AgentSceneBackground;
+/**
+ * The avatar line for `agents show` text output.
+ *
+ * `agents show` printed no avatar at all, so its output was byte-identical before
+ * and after `agents update --avatar preset:studio-halo`: "has the Halo preset"
+ * and "has no face whatsoever" could not be told apart without `--json` and
+ * knowing which raw field to decode. The coercion `--avatar` performs is the one
+ * thing a reader would want confirmed, and it was the one thing hidden.
+ *
+ * Rendered in the same shorthand `--avatar` accepts, so what is printed is what
+ * can be typed back. An ABSENT avatar is kept apart from an explicit
+ * `{type:'default'}`: both show the platform logo, but only the absent one was
+ * never chosen, and that is exactly what `agents avatar default apply` rewrites.
+ */
+export declare function agentAvatarLine(raw: unknown): string;
+/** The scene-background line, in the shorthand `--scene-background` accepts. */
+export declare function agentSceneBackgroundLine(raw: unknown): string;

package/dist/lib/agent-visual-refs.js

@@ -0,0 +1,267 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCENE_BACKGROUND_FLAG_HELP = void 0;
+exports.imageUploadMimeType = imageUploadMimeType;
+exports.avatarPresetIds = avatarPresetIds;
+exports.sceneBackgroundPresetIds = sceneBackgroundPresetIds;
+exports.parseAvatarRefFlag = parseAvatarRefFlag;
+exports.parseSceneBackgroundFlag = parseSceneBackgroundFlag;
+exports.agentAvatarLine = agentAvatarLine;
+exports.agentSceneBackgroundLine = agentSceneBackgroundLine;
+/**
+ * The two "how does this agent look" fields, parsed from a flag.
+ *
+ * WHY A PARSER AND NOT A PLAIN STRING
+ * ───────────────────────────────────
+ * `agent.avatar` and `agent.sceneBackground` are DISCRIMINATED UNIONS on the
+ * wire (`packages/api/src/agents/validation.ts`), because a face and a backdrop
+ * each have several possible origins — a built-in preset, the caller's own
+ * uploaded asset, an explicit "the platform default", a raw storage path — and
+ * a bare string cannot say which. `agentUpdateSchema.parse(req.body)` runs with
+ * no coercion, so a string reaches the server and is rejected.
+ *
+ * `--scene-background` shipped as a pass-through string for exactly that
+ * reason, which made it a flag with NO value that could ever succeed: every
+ * invocation was a 400 naming a zod path rather than the flag. The fix is to
+ * own the shorthand here, once, so both fields read the same way and neither
+ * can regress into a raw string again.
+ *
+ * THE SHORTHAND
+ * ─────────────
+ *   default                       → { type: 'default' }
+ *   preset:<id>                   → { type: 'preset', id }
+ *   asset:<id>                    → { type: 'asset', id }        (avatar only)
+ *   image:<filepath>@<source>     → { type: 'image', filepath, source }
+ *   {"type":"preset","id":"..."}  → parsed verbatim, the escape hatch
+ *
+ * A bare id is deliberately NOT accepted. `preset:studio` and an asset id are
+ * different namespaces, and guessing between them would make the failure mode
+ * "your avatar silently became someone else's" rather than a parse error.
+ */
+const data_provider_1 = require("@skrr-ai/data-provider");
+/**
+ * The `--scene-background` help, shared by `agents create` and `agents update`.
+ *
+ * It named three forms and no preset ids, while the refusal it led to named a
+ * fourth form (JSON) and listed all the ids — so the only way to learn the valid
+ * values was to type a wrong one on purpose. `--avatar`, one flag away, already
+ * did this right. Built from the shipped catalog so it cannot fall behind it.
+ */
+exports.SCENE_BACKGROUND_FLAG_HELP = 'Backdrop for the 3D view: default, preset:<id>, image:<filepath>@<source>, or a JSON ' +
+    `object such as {"type":"preset","id":"midnight"}. Presets: ${data_provider_1.AGENT_SCENE_BACKGROUND_PRESETS.map((preset) => preset.id).join(', ')}. For your own photo use \`skrr agents scene-background upload\` — ` +
+    '<filepath> is the storage path that command produces, not a file on disk.';
+/**
+ * The MIME type to send an image upload as, from its file extension.
+ *
+ * The upload routes gate on the multipart part's type, and a part built as
+ * `new Blob([bytes])` has none, so it arrives as `application/octet-stream` and
+ * is refused whatever its bytes are. `agents avatar upload` shipped that way and
+ * could not upload any file (OSK-9841). Returns undefined for anything that is
+ * not an image type the routes accept, so a caller can refuse locally.
+ */
+const UPLOAD_IMAGE_TYPES = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.webp': 'image/webp',
+    '.gif': 'image/gif',
+};
+function imageUploadMimeType(filePath) {
+    const dot = filePath.lastIndexOf('.');
+    return dot < 0 ? undefined : UPLOAD_IMAGE_TYPES[filePath.slice(dot).toLowerCase()];
+}
+/** `image:path/to.png@s3` — the `@` is the LAST one, so a path may contain `@`. */
+function parseImage(rest, flag) {
+    const at = rest.lastIndexOf('@');
+    if (at <= 0 || at === rest.length - 1) {
+        throw new Error(`${flag}: "image:" needs a storage source — write image:<filepath>@<source>, ` +
+            'for example image:images/123/face.png@s3.');
+    }
+    return { filepath: rest.slice(0, at), source: rest.slice(at + 1) };
+}
+/**
+ * A JSON object escape hatch, so a shape this grammar has not learned yet is
+ * still expressible without falling back to `--from-json` for the whole agent.
+ * Returns `undefined` when the value is not JSON at all, so the caller can go on
+ * to the shorthand rather than reporting a JSON syntax error for `preset:foo`.
+ */
+function parseJsonObject(value) {
+    const trimmed = value.trim();
+    if (!trimmed.startsWith('{'))
+        return undefined;
+    try {
+        const parsed = JSON.parse(trimmed);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Hold a JSON value to the same rules as the shorthand, for the shapes the
+ * grammar knows.
+ *
+ * The JSON form used to be returned unchecked, so the one form with no worked
+ * example was also the one with no local validation: `{"type":"preset"}` went to
+ * the server and came back as a raw zod dump
+ * (`sceneBackground.id: Invalid input: expected string, received undefined`),
+ * while `preset:` with no id got a sentence. A KNOWN `type` is now validated here
+ * exactly as its shorthand is. An unknown `type` still passes through untouched,
+ * because letting a shape this grammar has not learned reach the server is the
+ * reason the escape hatch exists.
+ */
+function checkJsonRef(json, flag, shorthand) {
+    const type = json.type;
+    const str = (value) => (typeof value === 'string' ? value : '');
+    if (type === 'default')
+        return;
+    if (type === 'preset' || type === 'asset') {
+        if (!str(json.id)) {
+            throw new Error(`${flag}: a JSON value of type "${type}" needs a string "id" — for example ` +
+                `{"type":"${type}","id":"<id>"}, or the shorthand ${type}:<id>.`);
+        }
+        shorthand(`${type}:${str(json.id)}`);
+        return;
+    }
+    if (type === 'image') {
+        if (!str(json.filepath) || !str(json.source)) {
+            throw new Error(`${flag}: a JSON value of type "image" needs string "filepath" and "source" — ` +
+                'for example {"type":"image","filepath":"<storage path>","source":"s3"}.');
+        }
+        return;
+    }
+    if (typeof type !== 'string' || !type) {
+        throw new Error(`${flag}: a JSON value needs a string "type" (default, preset, image, …).`);
+    }
+}
+/** Preset ids this build ships, for an error message that can be acted on. */
+function avatarPresetIds() {
+    return data_provider_1.AGENT_AVATAR_PRESETS.map((preset) => preset.id);
+}
+function sceneBackgroundPresetIds() {
+    return data_provider_1.AGENT_SCENE_BACKGROUND_PRESETS.map((preset) => preset.id);
+}
+/**
+ * Name a handful of valid ids rather than all of them.
+ *
+ * There are ~60 avatar presets. An error that prints every one buries the
+ * sentence that says what went wrong, so show a few and point at the command
+ * that lists the rest.
+ */
+function someOf(ids, limit = 6) {
+    const head = ids.slice(0, limit).join(', ');
+    return ids.length > limit ? `${head}, … (${ids.length} total)` : head;
+}
+function parseAvatarRefFlag(value) {
+    const json = parseJsonObject(value);
+    if (json) {
+        checkJsonRef(json, '--avatar', parseAvatarRefFlag);
+        return json;
+    }
+    const raw = value.trim();
+    if (raw === 'default')
+        return { type: 'default' };
+    const colon = raw.indexOf(':');
+    const kind = colon === -1 ? raw : raw.slice(0, colon);
+    const rest = colon === -1 ? '' : raw.slice(colon + 1);
+    if (kind === 'preset') {
+        if (!(0, data_provider_1.isAgentAvatarPresetId)(rest)) {
+            throw new Error(`--avatar: "${rest}" is not an avatar preset in this build. ` +
+                `Try one of: ${someOf(avatarPresetIds())}. ` +
+                'Run `skrr agents avatar presets` for the full catalog.');
+        }
+        return { type: 'preset', id: rest };
+    }
+    if (kind === 'asset') {
+        if (!rest) {
+            throw new Error('--avatar: "asset:" needs an id from your library — ' +
+                'run `skrr agents avatar library` to list them.');
+        }
+        return { type: 'asset', id: rest };
+    }
+    if (kind === 'image')
+        return { type: 'image', ...parseImage(rest, '--avatar') };
+    throw new Error(`--avatar: cannot read "${value}". Accepted: default, preset:<id>, asset:<id>, ` +
+        'image:<filepath>@<source>, or a JSON object. ' +
+        'To upload a new image file instead, use `skrr agents avatar upload --file <path>`.');
+}
+function parseSceneBackgroundFlag(value) {
+    const json = parseJsonObject(value);
+    if (json) {
+        checkJsonRef(json, '--scene-background', parseSceneBackgroundFlag);
+        return json;
+    }
+    const raw = value.trim();
+    if (raw === 'default')
+        return { type: 'default' };
+    const colon = raw.indexOf(':');
+    const kind = colon === -1 ? raw : raw.slice(0, colon);
+    const rest = colon === -1 ? '' : raw.slice(colon + 1);
+    if (kind === 'preset') {
+        if (!(0, data_provider_1.isAgentSceneBackgroundPresetId)(rest)) {
+            throw new Error(`--scene-background: "${rest}" is not a backdrop preset in this build. ` +
+                `Valid ids: ${sceneBackgroundPresetIds().join(', ')}.`);
+        }
+        return { type: 'preset', id: rest };
+    }
+    if (kind === 'image')
+        return { type: 'image', ...parseImage(rest, '--scene-background') };
+    // A bare preset id is the single most likely mistake here, because the
+    // backdrop catalog is short enough to remember. Say so instead of listing the
+    // grammar twice.
+    if ((0, data_provider_1.isAgentSceneBackgroundPresetId)(raw)) {
+        throw new Error(`--scene-background: "${raw}" is a preset id — write preset:${raw}. ` +
+            'A bare id is refused because preset and image live in different namespaces.');
+    }
+    throw new Error(`--scene-background: cannot read "${value}". Accepted: default, preset:<id>, ` +
+        `image:<filepath>@<source>, or a JSON object. Presets: ${sceneBackgroundPresetIds().join(', ')}.`);
+}
+/**
+ * The avatar line for `agents show` text output.
+ *
+ * `agents show` printed no avatar at all, so its output was byte-identical before
+ * and after `agents update --avatar preset:studio-halo`: "has the Halo preset"
+ * and "has no face whatsoever" could not be told apart without `--json` and
+ * knowing which raw field to decode. The coercion `--avatar` performs is the one
+ * thing a reader would want confirmed, and it was the one thing hidden.
+ *
+ * Rendered in the same shorthand `--avatar` accepts, so what is printed is what
+ * can be typed back. An ABSENT avatar is kept apart from an explicit
+ * `{type:'default'}`: both show the platform logo, but only the absent one was
+ * never chosen, and that is exactly what `agents avatar default apply` rewrites.
+ */
+function agentAvatarLine(raw) {
+    if (raw == null) {
+        return 'none chosen — shows the platform logo (`agents avatar default apply` would fill it)';
+    }
+    const ref = raw;
+    switch (ref.type) {
+        case 'default':
+            return 'default — the platform logo, chosen';
+        case 'preset': {
+            const id = typeof ref.id === 'string' ? ref.id : '';
+            const preset = (0, data_provider_1.getAgentAvatarPreset)(id);
+            return preset ? `preset:${id} (${preset.name})` : `preset:${id} (not in this build)`;
+        }
+        case 'asset':
+            return `asset:${typeof ref.id === 'string' ? ref.id : '?'} (from your avatar library)`;
+        case 'image':
+            return 'an uploaded image';
+        default:
+            return 'unrecognised value — see `--json`';
+    }
+}
+/** The scene-background line, in the shorthand `--scene-background` accepts. */
+function agentSceneBackgroundLine(raw) {
+    const ref = (raw ?? { type: 'default' });
+    if (ref.type === 'default')
+        return 'default';
+    if (ref.type === 'preset') {
+        const id = typeof ref.id === 'string' ? ref.id : '';
+        const preset = data_provider_1.AGENT_SCENE_BACKGROUND_PRESETS.find((candidate) => candidate.id === id);
+        return preset ? `preset:${id} (${preset.name})` : `preset:${id} (not in this build)`;
+    }
+    if (ref.type === 'image')
+        return 'an uploaded image';
+    return 'unrecognised value — see `--json`';
+}

package/dist/lib/agentic-stream.d.ts

@@ -1,3 +1,9 @@
+/**
+ * The answer a question gets when no terminal exists to ask it on. Written to the
+ * agent, so it says what happened and what to do rather than pretending a person
+ * replied.
+ */
+export declare const NON_INTERACTIVE_QUESTION_ANSWER: string;
 export type AgenticStreamEvent = {
     type: string;
     sessionId?: string;

package/dist/lib/agentic-stream.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AgenticStreamClient = exports.USER_CONNECTION_CAP_CODE = void 0;
+exports.AgenticStreamClient = exports.USER_CONNECTION_CAP_CODE = exports.NON_INTERACTIVE_QUESTION_ANSWER = void 0;
 exports.writeJsonLine = writeJsonLine;
 exports.envelopesText = envelopesText;
 exports.envelopeKey = envelopeKey;
@@ -19,6 +19,13 @@ const socket_io_client_1 = require("socket.io-client");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const config_1 = require("./config");
 const publicEndpoints_generated_1 = require("./publicEndpoints.generated");
+/**
+ * The answer a question gets when no terminal exists to ask it on. Written to the
+ * agent, so it says what happened and what to do rather than pretending a person
+ * replied.
+ */
+exports.NON_INTERACTIVE_QUESTION_ANSWER = 'No answer: this turn was started non-interactively (no terminal), so nobody can reply to ' +
+    'questions. Proceed with your best judgement, or finish by stating exactly what you need.';
 /**
  * Write exactly one complete JSON value on one line.
  *
@@ -667,10 +674,25 @@ class AgenticStreamClient {
     async handleQuestion(event) {
         if (this.closed)
             return;
+        // The same question can arrive twice (both delivery paths carry it — a
+        // non-interactive run showed two `question.requested` for one questionId,
+        // each answered). Answer it once, as tool events are emitted once.
+        if (!this.firstTimeSeen('question', event.questionId))
+            return;
         this.emit({ ...event, type: 'question.requested' });
+        // Nobody can answer a question in a run with no terminal. This used to
+        // prompt on stdin anyway: a scripted `agents chat --jsonl` printed the
+        // question and a `>` to stderr, read nothing, and the turn sat for the
+        // server's full 300-second question timeout — then ended with the agent told
+        // "Not answered … timed out", at the cost of the whole wait. Answer at once
+        // instead, saying why, so the agent proceeds or states what it needs. An
+        // explicit `input` (tests, an embedding caller) is treated as interactive.
+        const interactive = this.options.input !== undefined || Boolean(process.stdin.isTTY);
         const answers = {};
         for (const question of event.questions ?? []) {
-            const answer = await this.ask(`${question.header ?? 'Question'}: ${question.question}\n> `);
+            const answer = interactive
+                ? await this.ask(`${question.header ?? 'Question'}: ${question.question}\n> `)
+                : exports.NON_INTERACTIVE_QUESTION_ANSWER;
             answers[question.header ?? question.question] = answer;
         }
         if (event.questionId && this.socket) {
@@ -680,7 +702,12 @@ class AgenticStreamClient {
                 answers,
             });
         }
-        this.emit({ type: 'question.answered', questionId: event.questionId, answers });
+        this.emit({
+            type: 'question.answered',
+            questionId: event.questionId,
+            answers,
+            ...(interactive ? {} : { nonInteractive: true }),
+        });
     }
     ask(prompt) {
         // A prompt raised after close has nobody to answer it, and re-creating the
@@ -773,6 +800,10 @@ class AgenticStreamClient {
             output.write(`\n[${event.type}]\n`);
             this.renderedText = this.accumulated;
         }
+        else if (event.type === 'question.answered' && event.nonInteractive) {
+            output.write('\n[question] no terminal to answer on, so the agent was told to proceed without an answer\n');
+            this.renderedText = this.accumulated;
+        }
     }
     finish(status, event) {
         if (this.settled)

package/dist/lib/assignee-resolver.d.ts

@@ -33,7 +33,7 @@ export type ResolutionFailure = {
      * NO_SPACE   — the reference needs a membership list to match against, but
      *              the task/payload has no space, so only raw ids are possible.
      */
-    code: 'NOT_FOUND' | 'AMBIGUOUS' | 'NO_SPACE';
+    code: 'NOT_FOUND' | 'AMBIGUOUS' | 'NO_SPACE' | 'NOT_A_REFERENCE';
     query: string;
     kind: MemberKind;
     /** For AMBIGUOUS: the tied matches. For NOT_FOUND: everything available. */

package/dist/lib/assignee-resolver.js

@@ -7,6 +7,7 @@ exports.describeMember = describeMember;
 exports.describeCandidates = describeCandidates;
 exports.resolveAssigneeReferences = resolveAssigneeReferences;
 exports.formatResolutionFailure = formatResolutionFailure;
+const failed_lookup_1 = require("./failed-lookup");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const OBJECT_ID_RE = /^[0-9a-fA-F]{24}$/;
 const UUID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
@@ -84,6 +85,11 @@ function resolveMember(query, members, kind) {
     if (!q) {
         return { ok: false, code: 'NOT_FOUND', query: raw, kind, candidates: pool };
     }
+    // A failed lookup's output is refused before the name tiers can match it.
+    // See `failed-lookup.ts`.
+    if ((0, failed_lookup_1.isFailedLookupValue)(raw)) {
+        return { ok: false, code: 'NOT_A_REFERENCE', query: raw, kind, candidates: [] };
+    }
     const tiers = [
         // 1. Exact id. Case-sensitive on purpose — ids are opaque.
         (m) => m.id === raw,
@@ -186,6 +192,8 @@ function formatResolutionFailure(failure, bin = 'skrr') {
     const noun = failure.kind === 'user' ? 'person' : 'agent';
     const plural = failure.kind === 'user' ? 'people' : 'agents';
     switch (failure.code) {
+        case 'NOT_A_REFERENCE':
+            return (0, failed_lookup_1.describeFailedLookupValue)(failure.query, noun);
         case 'AMBIGUOUS':
             return (`"${failure.query}" matches ${failure.candidates.length} ${plural} in this space:\n` +
                 `${describeCandidates(failure.candidates)}\n` +

package/dist/lib/bulk-task-targets.d.ts

@@ -29,6 +29,18 @@ export type BulkApplyResult = {
  * semantics match `skrr tasks bulk-update`). `apply` returns whether the task
  * actually changed (already-satisfied tasks are reported as no-ops).
  */
+/**
+ * The server's reason for a failed per-task write, not the transport's.
+ *
+ * A bulk run used to record `err.message`, which for a dataService call is the
+ * transport line — `HTTP 400 Bad Request — PATCH https://…/api/tasks/<id>` — so
+ * `tasks actions attach --all-in-space` printed that once per task and named
+ * neither the ref nor the rule that refused it (OSK-9652). The same call made
+ * for a single task goes through `handleApiError`, which reads the body. This
+ * reads it the same way: `message`, then `error`, plus the first validation
+ * detail when the server sent one.
+ */
+export declare function bulkFailureMessage(err: unknown): string;
 export declare function applyToTaskTargets(targets: Array<{
     id: string;
     identifier?: string;