@skrr-ai/cli 0.1.37 → 0.1.38

package/dist/commands/agents/avatar/upload.js

@@ -5,6 +5,7 @@ const promises_1 = require("node:fs/promises");
 const node_path_1 = require("node:path");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../../base-command");
+const agent_visual_refs_1 = require("../../../lib/agent-visual-refs");
 class AgentsAvatarUpload extends base_command_1.BaseCommand {
     static description = 'Upload an agent avatar';
     static args = { agentId: core_1.Args.string({ required: true, ignoreStdin: true }) };
@@ -15,9 +16,14 @@ class AgentsAvatarUpload extends base_command_1.BaseCommand {
     async run() {
         this.requireAuth();
         const { args, flags } = await this.parse(AgentsAvatarUpload);
+        const type = (0, agent_visual_refs_1.imageUploadMimeType)(flags.file);
+        if (!type) {
+            this.error(`--file must be a .png, .jpg, .jpeg, .webp or .gif image (got ${(0, node_path_1.basename)(flags.file)}).`, { exit: 1 });
+        }
         const bytes = await (0, promises_1.readFile)(flags.file);
         const form = new FormData();
-        form.append('file', new Blob([bytes]), (0, node_path_1.basename)(flags.file));
+        // Typed, or the route refuses it as application/octet-stream (OSK-9841).
+        form.append('file', new Blob([new Uint8Array(bytes)], { type }), (0, node_path_1.basename)(flags.file));
         const result = await data_provider_1.dataService.uploadAgentAvatar({ agent_id: args.agentId, formData: form });
         this.log(flags.json
             ? this.agentJson(args.agentId, result)

package/dist/commands/agents/categories/delete.js

@@ -27,7 +27,15 @@ class AgentsCategoriesDelete extends base_command_1.BaseCommand {
             this.log(JSON.stringify(result, null, 2));
             return;
         }
+        const outcome = result;
         this.log(`Deleted category ${args.value}`);
+        // Say where its agents went, because the alternative a reader assumes is
+        // that they went with it — and until the server moved them, they did not go
+        // anywhere: they kept pointing at a category that no longer existed.
+        if (outcome.reassigned) {
+            const noun = outcome.reassigned === 1 ? 'agent' : 'agents';
+            this.log(`Moved ${outcome.reassigned} ${noun} to ${outcome.reassignedTo}.`);
+        }
     }
 }
 exports.default = AgentsCategoriesDelete;

package/dist/commands/agents/categories/index.d.ts

@@ -1,12 +1,27 @@
 import { BaseCommand } from '../../../base-command';
+export declare function categoryDisplayLabel(row: {
+    value?: unknown;
+    label?: unknown;
+}): string;
+export declare function categoryDisplayDescription(row: {
+    description?: unknown;
+}): string;
 /**
  * The vocabulary `--category` accepts.
  *
- * Three reads, because they answer three different questions and the server
- * keeps them apart: the GLOBAL catalog with marketplace counts, the caller's
- * view (global + their own), and the caller's own rows alone. `--mine` is the
- * one most people want, so the flags name the other two rather than making the
- * common case the odd one out.
+ * The plain command used to read the GLOBAL marketplace catalog, which answers a
+ * different question: it listed `promoted`, `general` and `all` — three rows —
+ * while this account's agents actually sat in twelve categories, including the
+ * custom one the sibling `create` command had just minted. Two of the three were
+ * not categories at all but marketplace browse filters the endpoint injects. And
+ * `--mine`, described as a view, returned MORE than the default, so a flag that
+ * reads like a filter was a superset. The command's own description — "the
+ * categories `--category` accepts" — was true of none of it.
+ *
+ * So the default is now that vocabulary: the global categories plus your own,
+ * without the browse filters. The marketplace view, with its counts and filters,
+ * is `--marketplace`, named for what it is. `--mine` still works, as the default
+ * it always should have been, so nothing that scripted it breaks.
  */
 export default class AgentsCategoriesList extends BaseCommand {
     static description: string;
@@ -14,6 +29,7 @@ export default class AgentsCategoriesList extends BaseCommand {
     static flags: {
         mine: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         'custom-only': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        marketplace: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;

package/dist/commands/agents/categories/index.js

@@ -1,33 +1,80 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.categoryDisplayLabel = categoryDisplayLabel;
+exports.categoryDisplayDescription = categoryDisplayDescription;
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../../base-command");
 const format_1 = require("../../../lib/format");
+/**
+ * Global default categories are seeded with LOCALIZATION KEYS as their label and
+ * description (`com_agents_category_general`), because the web translates them.
+ * The CLI has no translations and printed the keys: the category most agents are
+ * in read `com_agents_category_general` / `com_agents_category_general_description`,
+ * in text and `--json` alike.
+ *
+ * Copying the translations here would be a second source that drifts. A key
+ * label renders as the title-cased value instead — for `general`, the one global
+ * default left, that is exactly its English translation — and a key description
+ * renders as nothing rather than as a key. `--json` keeps the raw row; only the
+ * human rendering is touched.
+ */
+const LOCALIZATION_KEY = /^com_[a-z0-9_]+$/;
+function categoryDisplayLabel(row) {
+    const label = typeof row.label === 'string' ? row.label : '';
+    if (label && !LOCALIZATION_KEY.test(label))
+        return label;
+    const value = typeof row.value === 'string' ? row.value : '';
+    if (!value)
+        return label || '-';
+    return value
+        .split(/[-_\s]+/)
+        .filter(Boolean)
+        .map((word) => word[0].toUpperCase() + word.slice(1))
+        .join(' ');
+}
+function categoryDisplayDescription(row) {
+    const description = typeof row.description === 'string' ? row.description : '';
+    return LOCALIZATION_KEY.test(description) ? '' : description;
+}
 /**
  * The vocabulary `--category` accepts.
  *
- * Three reads, because they answer three different questions and the server
- * keeps them apart: the GLOBAL catalog with marketplace counts, the caller's
- * view (global + their own), and the caller's own rows alone. `--mine` is the
- * one most people want, so the flags name the other two rather than making the
- * common case the odd one out.
+ * The plain command used to read the GLOBAL marketplace catalog, which answers a
+ * different question: it listed `promoted`, `general` and `all` — three rows —
+ * while this account's agents actually sat in twelve categories, including the
+ * custom one the sibling `create` command had just minted. Two of the three were
+ * not categories at all but marketplace browse filters the endpoint injects. And
+ * `--mine`, described as a view, returned MORE than the default, so a flag that
+ * reads like a filter was a superset. The command's own description — "the
+ * categories `--category` accepts" — was true of none of it.
+ *
+ * So the default is now that vocabulary: the global categories plus your own,
+ * without the browse filters. The marketplace view, with its counts and filters,
+ * is `--marketplace`, named for what it is. `--mine` still works, as the default
+ * it always should have been, so nothing that scripted it breaks.
  */
 class AgentsCategoriesList extends base_command_1.BaseCommand {
     static description = 'List the agent categories `--category` accepts';
     static examples = [
         '<%= config.bin %> agents categories',
-        '<%= config.bin %> agents categories --mine',
         '<%= config.bin %> agents categories --custom-only --json',
+        '<%= config.bin %> agents categories --marketplace',
     ];
     static flags = {
         mine: core_1.Flags.boolean({
-            description: 'Your view: the global catalog plus your own custom categories',
-            exclusive: ['custom-only'],
+            description: 'Deprecated: the default already lists your categories',
+            exclusive: ['custom-only', 'marketplace'],
+            hidden: true,
         }),
         'custom-only': core_1.Flags.boolean({
             description: 'Only the custom categories you created',
-            exclusive: ['mine'],
+            exclusive: ['mine', 'marketplace'],
+        }),
+        marketplace: core_1.Flags.boolean({
+            description: 'The global marketplace catalog with agent counts, including its browse filters ' +
+                '(`promoted`, `all`) — not a list of values `--category` takes',
+            exclusive: ['mine', 'custom-only'],
         }),
         json: core_1.Flags.boolean({ description: 'Output as JSON' }),
     };
@@ -39,11 +86,11 @@ class AgentsCategoriesList extends base_command_1.BaseCommand {
             if (flags['custom-only']) {
                 rows = (await data_provider_1.dataService.getUserCustomCategories());
             }
-            else if (flags.mine) {
-                rows = (await data_provider_1.dataService.getUserAgentCategories());
+            else if (flags.marketplace) {
+                rows = (await data_provider_1.dataService.getAgentCategories());
             }
             else {
-                rows = (await data_provider_1.dataService.getAgentCategories());
+                rows = (await data_provider_1.dataService.getUserAgentCategories()).filter((row) => !(0, data_provider_1.isAgentCategoryBrowseFilter)(row.value));
             }
         }
         catch (err) {
@@ -62,12 +109,12 @@ class AgentsCategoriesList extends base_command_1.BaseCommand {
         }
         (0, format_1.renderTable)(items.map((row) => ({
             value: String(row.value ?? '-'),
-            label: String(row.label ?? '-'),
+            label: categoryDisplayLabel(row),
             custom: row.custom ? 'yes' : 'no',
             count: row.count === undefined
                 ? '-'
                 : String(row.count),
-            description: String(row.description ?? ''),
+            description: categoryDisplayDescription(row),
         })), [
             { key: 'value', header: 'VALUE', verbatim: true },
             { key: 'label', header: 'LABEL', maxWidth: 28 },
@@ -76,7 +123,13 @@ class AgentsCategoriesList extends base_command_1.BaseCommand {
             { key: 'description', header: 'DESCRIPTION', maxWidth: 48 },
         ], (line) => this.log(line));
         this.log('');
-        this.log('VALUE is what `skrr agents create --category <value>` takes.');
+        if (flags.marketplace) {
+            this.log('Marketplace view. `promoted` and `all` are browse filters, not categories — ' +
+                'run without --marketplace for the values `--category` takes.');
+        }
+        else {
+            this.log('VALUE is what `skrr agents create --category <value>` takes.');
+        }
     }
 }
 exports.default = AgentsCategoriesList;

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

@@ -24,6 +24,18 @@ export declare const DETACH_EXIT_CODE = 130;
  * answers true.
  */
 export declare const STREAM_LOST_EXIT_CODE = 75;
+/**
+ * Exit code for a streamed run that reached its terminal state: 1 when it
+ * failed, 0 otherwise.
+ *
+ * The streaming modes share this line. `--jsonl` used to print `run.result
+ * {status: "failed"}` and exit 0 while the human mode exited 1 for the same run
+ * — and `--jsonl` is the mode a script branches on (OSK-9779). Empty text is not
+ * a failure here, unlike `--no-stream`: a turn that only ran tools is a success.
+ */
+export declare function streamedResultExitCode(result: {
+    status?: string;
+}): number;
 /**
  * What to say when the user pressed Ctrl-C and the run did not stop.
  *
@@ -124,6 +136,8 @@ export default class AgentsChat extends BaseCommand {
         jsonl: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         'approve-tools': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        'local-skill': import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        daemon: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         task: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
     };
     /**
@@ -138,5 +152,12 @@ export default class AgentsChat extends BaseCommand {
      * mid-run costs a session.
      */
     private static readonly TASK_REF_IN_PROMPT;
+    /**
+     * `--local-skill` names → the references the server resolves, from the daemon
+     * that will run the turn. Any name that does not resolve stops the command:
+     * the server fails a turn whose picked skill did not load, so sending it
+     * would only move the same error later (OSK-9478).
+     */
+    private resolveLocalSkills;
     run(): Promise<void>;
 }

package/dist/commands/agents/chat.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.STREAM_LOST_EXIT_CODE = exports.DETACH_EXIT_CODE = void 0;
+exports.streamedResultExitCode = streamedResultExitCode;
 exports.interruptedDetachMessage = interruptedDetachMessage;
 exports.reconcileTerminalFromMessages = reconcileTerminalFromMessages;
 exports.inspectTurnCommand = inspectTurnCommand;
@@ -13,6 +14,7 @@ const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../base-command");
 const agentic_stream_1 = require("../../lib/agentic-stream");
 const web_url_1 = require("../../lib/web-url");
+const local_skills_1 = require("../../lib/local-skills");
 /**
  * Exit code for a run the USER stopped watching, by pressing Ctrl-C.
  *
@@ -37,6 +39,18 @@ exports.DETACH_EXIT_CODE = 130;
  * answers true.
  */
 exports.STREAM_LOST_EXIT_CODE = 75;
+/**
+ * Exit code for a streamed run that reached its terminal state: 1 when it
+ * failed, 0 otherwise.
+ *
+ * The streaming modes share this line. `--jsonl` used to print `run.result
+ * {status: "failed"}` and exit 0 while the human mode exited 1 for the same run
+ * — and `--jsonl` is the mode a script branches on (OSK-9779). Empty text is not
+ * a failure here, unlike `--no-stream`: a turn that only ran tools is a success.
+ */
+function streamedResultExitCode(result) {
+    return result.status === 'failed' ? 1 : 0;
+}
 /**
  * What to say when the user pressed Ctrl-C and the run did not stop.
  *
@@ -84,18 +98,17 @@ function reconcileTerminalFromMessages(messages, responseMessageId) {
         [...messages].reverse().find((m) => m && m.isCreatedByUser === false);
     if (!row)
         return null;
-    const agentic = row.metadata?.agentic;
-    const recordedError = typeof agentic?.error === 'string' ? agentic.error : undefined;
-    const text = typeof row.text === 'string' ? row.text : '';
-    if (row.error === true) {
+    const failure = (0, data_provider_1.resolveMessageFailure)(row);
+    if (failure) {
         return {
             status: 'failed',
-            ...(text ? { text } : {}),
+            ...(failure.answer ? { text: failure.answer } : {}),
             // The reason exists on the row; it simply never reached the surface. Say
             // it, rather than the transport error that masked it (OSK-7595).
-            error: recordedError ?? 'The run failed. No reason was recorded on the message.',
+            error: failure.reason ?? 'The run failed. No reason was recorded on the message.',
         };
     }
+    const text = typeof row.text === 'string' ? row.text : '';
     // `unfinished: false` is the persister's terminal marker; an empty body with
     // it set is a turn that ended having produced nothing, which is still
     // terminal and still better reported than waited on.
@@ -183,6 +196,7 @@ class AgentsChat extends base_command_1.BaseCommand {
         '<%= config.bin %> agents chat <agent-id> --prompt "Deploy the fix" --approve-tools',
         '<%= config.bin %> agents chat <agent-id> --prompt "Summarize" --jsonl',
         '<%= config.bin %> agents chat <agent-id> --prompt "Summarize" --no-stream --json',
+        '<%= config.bin %> agents chat <agent-id> --prompt "Review this diff" --local-skill code-review',
     ];
     static args = {
         agentId: core_1.Args.string({ description: 'Agent ID', required: true, ignoreStdin: true }),
@@ -222,6 +236,16 @@ class AgentsChat extends base_command_1.BaseCommand {
         'approve-tools': core_1.Flags.boolean({
             description: 'Prompt interactively before approving tool calls',
         }),
+        'local-skill': core_1.Flags.string({
+            description: 'Invoke a skill on your machine on this turn, as `skrr skills local` lists it: its ' +
+                'name, or <root>/<name> when two roots share one. The turn runs on that machine. ' +
+                'Repeatable.',
+            multiple: true,
+        }),
+        daemon: core_1.Flags.string({
+            description: 'The machine whose skills --local-skill names. Defaults to your only connected daemon.',
+            dependsOn: ['local-skill'],
+        }),
         task: core_1.Flags.string({
             description: 'Bind this turn to a task (UUID or OSK-####). Injects the canonical task id, ' +
                 'identifier, space and completion instructions into the turn. This is a CHAT ' +
@@ -241,6 +265,49 @@ class AgentsChat extends base_command_1.BaseCommand {
      * mid-run costs a session.
      */
     static TASK_REF_IN_PROMPT = /\b(?:OSK-\d+|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\b/;
+    /**
+     * `--local-skill` names → the references the server resolves, from the daemon
+     * that will run the turn. Any name that does not resolve stops the command:
+     * the server fails a turn whose picked skill did not load, so sending it
+     * would only move the same error later (OSK-9478).
+     */
+    async resolveLocalSkills(requested, daemonFlag) {
+        if (!requested?.length)
+            return null;
+        let daemonId = daemonFlag;
+        if (!daemonId) {
+            let daemons;
+            try {
+                daemons = await data_provider_1.dataService.getDaemons();
+            }
+            catch (err) {
+                this.handleApiError(err);
+            }
+            const choice = (0, local_skills_1.chooseDaemon)(daemons.active ?? []);
+            if (!('daemonId' in choice)) {
+                const listed = choice.candidates.map((d) => `  --daemon ${d.daemonId}${d.deviceName ? `  (${d.deviceName})` : ''}`);
+                this.error([choice.problem, ...listed].join('\n'), { exit: 2 });
+            }
+            daemonId = choice.daemonId;
+        }
+        let inventory;
+        try {
+            inventory = await data_provider_1.dataService.getDaemonSkills(daemonId);
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+        if (!inventory.online) {
+            this.error(`${daemonId} is not connected, so no skill on it can load. Start it and retry.`, {
+                exit: 2,
+            });
+        }
+        const { refs, problems } = (0, local_skills_1.resolveLocalSkillRefs)(inventory.skills ?? [], requested);
+        if (problems.length > 0) {
+            this.error(problems.join('\n'), { exit: 2 });
+        }
+        return { daemonId, refs };
+    }
     async run() {
         this.requireAuth();
         const { args, flags } = await this.parse(AgentsChat);
@@ -258,6 +325,10 @@ class AgentsChat extends base_command_1.BaseCommand {
                 'response and streams no events. Use --quick --json for a machine-readable ' +
                 'one-shot, or drop --quick for a real streamed turn.', { exit: 2 });
         }
+        if (flags.quick && flags['local-skill']?.length) {
+            this.error('--local-skill has no meaning with --quick: the persona-only summarizer runs no ' +
+                'runtime, so no skill on your machine can load. Drop --quick for a real turn.', { exit: 2 });
+        }
         if (flags['approve-tools'] && !process.stdin.isTTY) {
             this.error('--approve-tools requires an interactive terminal.', { exit: 2 });
         }
@@ -371,13 +442,28 @@ class AgentsChat extends base_command_1.BaseCommand {
         const contextParts = [taskContextBlock, flags.context ? `Context: ${flags.context}` : null]
             .filter(Boolean)
             .join('\n\n');
+        const localSkills = await this.resolveLocalSkills(flags['local-skill'], flags.daemon);
+        const prompt = localSkills
+            ? (0, local_skills_1.withSkillInvocations)(flags.prompt, localSkills.refs)
+            : flags.prompt;
         let started;
         try {
             started = await data_provider_1.dataService.startAgenticChat({
                 agentId: args.agentId,
-                text: contextParts ? `${contextParts}\n\n${flags.prompt}` : flags.prompt,
+                text: contextParts ? `${contextParts}\n\n${prompt}` : prompt,
                 conversationId: threadConversationId,
                 workspaceId: process.env.OVERSKY_WORKSPACE_ID,
+                // The server resolves each ref against the session's daemon, so the
+                // turn is asked to run on the machine that listed them. An agent whose
+                // execution policy places it elsewhere keeps that placement, and the
+                // run fails saying why rather than running without the skill.
+                ...(localSkills
+                    ? {
+                        skillRefs: localSkills.refs,
+                        executionEnvironment: 'local',
+                        preferredDaemonId: localSkills.daemonId,
+                    }
+                    : {}),
             });
         }
         catch (err) {
@@ -573,6 +659,7 @@ class AgentsChat extends base_command_1.BaseCommand {
                 // makes shell consumers able to find the final text without replaying
                 // the event reducer.
                 (0, agentic_stream_1.writeJsonLine)(process.stdout, { type: 'run.result', ...result });
+                process.exitCode = streamedResultExitCode(result);
             }
             else if (quiet && flags.json) {
                 // A real executed turn — the metadata says so, unlike `--quick`.

package/dist/commands/agents/create.js

@@ -6,6 +6,7 @@ exports.unappliedPayloadKeys = unappliedPayloadKeys;
 exports.backgroundLoopLines = backgroundLoopLines;
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
+const agent_visual_refs_1 = require("../../lib/agent-visual-refs");
 const base_command_1 = require("../../base-command");
 const execution_target_1 = require("../../lib/execution-target");
 const prompt_1 = require("../../lib/prompt");
@@ -195,10 +196,7 @@ class AgentsCreate extends base_command_1.BaseCommand {
         'network-agent-ids': core_1.Flags.string({ description: 'Network agent IDs JSON array' }),
         'network-include-public': core_1.Flags.boolean({ description: 'Include public agents in network' }),
         'character-3d-id': core_1.Flags.string({ description: '3D character ID' }),
-        'scene-background': core_1.Flags.string({
-            description: 'Backdrop for the 3D view: default, preset:<id>, or image:<filepath>@<source>. ' +
-                'A bare string is refused — the stored field is a typed reference, not a name.',
-        }),
+        'scene-background': core_1.Flags.string({ description: agent_visual_refs_1.SCENE_BACKGROUND_FLAG_HELP }),
         'tone-mode': core_1.Flags.string({ description: 'Tone mode' }),
         'tone-id': core_1.Flags.string({ description: 'Tone ID' }),
         'tone-notes': core_1.Flags.string({ description: 'Per-agent tone notes' }),
@@ -384,6 +382,15 @@ class AgentsCreate extends base_command_1.BaseCommand {
         if (appliedDefaults.length > 0) {
             this.log(`Defaults applied: ${appliedDefaults.join(', ')}`);
         }
+        // The face is a default too, and the one people most often notice later:
+        // eight agents created in a row all came out faceless, nothing said a policy
+        // had decided that, and the natural conclusion was that the random default
+        // did not work. When `--avatar` was not given, say what the agent got and
+        // what decided it.
+        if (!flags.avatar) {
+            this.log(`Avatar: ${(0, agent_visual_refs_1.agentAvatarLine)(a.avatar)}`);
+            this.log('  Decided by your default-avatar policy — `skrr agents avatar default` shows or changes it.');
+        }
         for (const line of backgroundLoopLines(agentId, flags['no-relationship-loops'] === true)) {
             this.log(line);
         }

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

@@ -7,6 +7,21 @@ import { BaseCommand } from '../../base-command';
  * arrives populated instead of scalar would otherwise print `[object Object]`
  * (OSK-2044), and a missing one would print the literal `undefined`.
  */
+/**
+ * Pinned agents first, as the web sidebar orders them — the rest in the order
+ * the server returned.
+ *
+ * `skrr agents pin` says it pins an agent "to the top of your list", and this
+ * list never read pins: an agent sat at row 17 of 200 pinned or not, and nothing
+ * in `agents list` or `agents show` said it was pinned at all. The only way to
+ * see the effect of the command was `agents preferences show`, which omits the
+ * field entirely until the first pin.
+ */
+export declare function orderPinnedFirst<T extends Record<string, unknown>>(items: readonly T[], preferences: Readonly<Record<string, {
+    isPinned?: boolean;
+} | undefined>>): Array<T & {
+    pinned: boolean;
+}>;
 export declare function agentRow(a: Record<string, unknown>): {
     id: string;
     name: string;

package/dist/commands/agents/list.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.orderPinnedFirst = orderPinnedFirst;
 exports.agentRow = agentRow;
 exports.noAgentsEmptyMessage = noAgentsEmptyMessage;
 const core_1 = require("@oclif/core");
@@ -15,6 +16,25 @@ const web_url_1 = require("../../lib/web-url");
  * arrives populated instead of scalar would otherwise print `[object Object]`
  * (OSK-2044), and a missing one would print the literal `undefined`.
  */
+/**
+ * Pinned agents first, as the web sidebar orders them — the rest in the order
+ * the server returned.
+ *
+ * `skrr agents pin` says it pins an agent "to the top of your list", and this
+ * list never read pins: an agent sat at row 17 of 200 pinned or not, and nothing
+ * in `agents list` or `agents show` said it was pinned at all. The only way to
+ * see the effect of the command was `agents preferences show`, which omits the
+ * field entirely until the first pin.
+ */
+function orderPinnedFirst(items, preferences) {
+    return items
+        .map((item, index) => {
+        const id = String(item.id ?? item._id ?? '');
+        return { item: { ...item, pinned: Boolean(preferences[id]?.isPinned) }, index };
+    })
+        .sort((a, b) => Number(b.item.pinned) - Number(a.item.pinned) || a.index - b.index)
+        .map(({ item }) => item);
+}
 function agentRow(a) {
     return {
         id: (0, format_1.formatCell)(a.id ?? a._id),
@@ -76,11 +96,21 @@ class AgentsList extends base_command_1.BaseCommand {
             this.log(noAgentsEmptyMessage(this.config.bin));
             return;
         }
-        const rows = items.map((item) => ({
+        // Best-effort: a list that cannot read pins still lists, unordered by them.
+        let preferences = {};
+        try {
+            preferences = (await data_provider_1.dataService.getAllAgentPreferences())?.agentPreferences ?? {};
+        }
+        catch {
+            preferences = {};
+        }
+        const rows = orderPinnedFirst(items, preferences).map((item) => ({
+            pinned: item.pinned ? 'pinned' : '',
             ...agentRow(item),
             url: (0, web_url_1.agentUrlFrom)(this.cliConfig.baseURL, item) ?? '-',
         }));
         (0, format_1.renderTable)(rows, [
+            { key: 'pinned', header: 'PINNED' },
             { key: 'id', header: 'ID' },
             { key: 'name', header: 'NAME', maxWidth: 30 },
             { key: 'description', header: 'DESCRIPTION', maxWidth: 60 },

package/dist/commands/agents/scene-background/upload.d.ts

@@ -0,0 +1,30 @@
+import { BaseCommand } from '../../../base-command';
+/**
+ * Upload an image as an agent's 3D backdrop.
+ *
+ * `--scene-background image:<filepath>@<source>` was documented and had no value
+ * that could succeed from the CLI. The server accepts an image backdrop only from
+ * the writer's own WALLPAPER upload namespace (`/images/<userId>/wallpaper-…`),
+ * and the only thing that writes there is `POST /api/files/images/wallpaper` —
+ * which nothing in `skrr` called. Every attempt ended in
+ * "Scene background image must be one you uploaded", and the flag's word
+ * `<filepath>` read like a path on disk, which sent people looking in the wrong
+ * place.
+ *
+ * This is that upload, followed by setting it, so the documented form finally
+ * has a producer. `--upload-only` prints the `--scene-background` value instead,
+ * for scripts that set it later or on several agents.
+ */
+export default class AgentsSceneBackgroundUpload extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        agentId: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        file: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'upload-only': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}