@skrr-ai/cli 0.1.36 → 0.1.38

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

@@ -0,0 +1,22 @@
+import { BaseCommand } from '../../../base-command';
+/**
+ * Edit one of the caller's own categories. Wraps `PATCH /api/agents/categories/:value`.
+ *
+ * `value` is the identity, not a field: agents point at it, so it is the ARG and
+ * cannot be changed here. Renaming means `--label`.
+ */
+export default class AgentsCategoriesUpdate extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        value: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        label: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        description: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        order: import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        active: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

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

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../../../base-command");
+/**
+ * Edit one of the caller's own categories. Wraps `PATCH /api/agents/categories/:value`.
+ *
+ * `value` is the identity, not a field: agents point at it, so it is the ARG and
+ * cannot be changed here. Renaming means `--label`.
+ */
+class AgentsCategoriesUpdate extends base_command_1.BaseCommand {
+    static description = 'Update a custom agent category';
+    static examples = [
+        '<%= config.bin %> agents categories update ops --label "Operations & on-call"',
+        '<%= config.bin %> agents categories update ops --no-active',
+    ];
+    static args = {
+        value: core_1.Args.string({ description: 'Category value', required: true, ignoreStdin: true }),
+    };
+    static flags = {
+        label: core_1.Flags.string({ description: 'New display name' }),
+        description: core_1.Flags.string({ description: 'New description' }),
+        order: core_1.Flags.integer({ description: 'New sort position' }),
+        active: core_1.Flags.boolean({
+            description: 'Whether the category is offered when choosing one',
+            allowNo: true,
+        }),
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(AgentsCategoriesUpdate);
+        const patch = {
+            ...(flags.label === undefined ? {} : { label: flags.label }),
+            ...(flags.description === undefined ? {} : { description: flags.description }),
+            ...(flags.order === undefined ? {} : { order: flags.order }),
+            ...(flags.active === undefined ? {} : { isActive: flags.active }),
+        };
+        if (Object.keys(patch).length === 0) {
+            this.error('Nothing to update. Pass at least one of --label, --description, --order, --active.', {
+                exit: 1,
+            });
+        }
+        let updated;
+        try {
+            updated = await data_provider_1.dataService.updateUserCategory(args.value, patch);
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(updated, null, 2));
+            return;
+        }
+        this.log(`Updated category ${args.value}`);
+    }
+}
+exports.default = AgentsCategoriesUpdate;

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.d.ts

@@ -104,6 +104,16 @@ export default class AgentsCreate extends BaseCommand {
         'hide-sequential-outputs': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         'is-collaborative': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         'recursion-limit': import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        avatar: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'conversation-starter': import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'todo-working-hours': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'reasoning-tool-escape': import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'commitment-responsibility': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'commitment-responsibility-ceiling': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'max-turns': import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'tool-resources': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'install-channel': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'auto-minor-updates': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
 }

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");
@@ -157,7 +158,10 @@ class AgentsCreate extends base_command_1.BaseCommand {
         instructions: core_1.Flags.string({
             description: 'Initial raw custom instructions (creates one inline block; use `agents instructions` to compose reusable blocks later)',
         }),
-        category: core_1.Flags.string({ description: 'Agent category' }),
+        category: core_1.Flags.string({
+            description: 'Agent category. `skrr agents categories` lists what this account accepts, and ' +
+                '`skrr agents categories create` adds one.',
+        }),
         target: core_1.Flags.string({
             description: 'Required execution target. Use a Harness id, Hosted Machine session, or Agent Worker. ' +
                 'Use hosted-machine, sbs_..., agent-worker, or a connected Harness id. ' +
@@ -192,7 +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: 'Scene background' }),
+        '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' }),
@@ -209,6 +213,45 @@ class AgentsCreate extends base_command_1.BaseCommand {
         'hide-sequential-outputs': core_1.Flags.boolean({ description: 'Hide sequential outputs' }),
         'is-collaborative': core_1.Flags.boolean({ description: 'Enable collaboration' }),
         'recursion-limit': core_1.Flags.integer({ description: 'Agent recursion limit' }),
+        avatar: core_1.Flags.string({
+            description: "The agent's face, as a reference rather than a file: default, preset:<id> " +
+                '(`skrr agents avatar presets`), asset:<id> (`skrr agents avatar library`), or ' +
+                'image:<filepath>@<source>. To upload a new image use `skrr agents avatar upload`.',
+        }),
+        'conversation-starter': core_1.Flags.string({
+            description: 'Suggested opening prompt shown on the agent (repeatable; replaces the list)',
+            multiple: true,
+        }),
+        'todo-working-hours': core_1.Flags.string({
+            description: 'When this agent schedules its own work: HH:MM-HH:MM[@<IANA timezone>], e.g. ' +
+                '09:00-18:00@America/Los_Angeles',
+        }),
+        'reasoning-tool-escape': core_1.Flags.string({
+            description: 'Tool a reasoning-only turn may still use (repeatable; replaces the list). ' +
+                'These are ESCAPES, not a fenced tool surface.',
+            options: [...agent_config_1.REASONING_TOOL_ESCAPES],
+            multiple: true,
+        }),
+        'commitment-responsibility': core_1.Flags.string({
+            description: "Default work authority for this agent's commitments",
+            options: [...agent_config_1.COMMITMENT_RESPONSIBILITY_LEVELS],
+        }),
+        'commitment-responsibility-ceiling': core_1.Flags.string({
+            description: 'Ceiling a commitment may not exceed, whatever it asks for',
+            options: [...agent_config_1.COMMITMENT_RESPONSIBILITY_LEVELS],
+        }),
+        'max-turns': core_1.Flags.integer({ description: 'Maximum turns in one agent run (1-500)' }),
+        'tool-resources': core_1.Flags.string({
+            description: 'Tool resources JSON object (file_search / context / image_edit bindings)',
+        }),
+        'install-channel': core_1.Flags.string({
+            description: 'Release policy: which channel installs of this agent follow',
+            options: [...agent_config_1.RELEASE_INSTALL_CHANNELS],
+        }),
+        'auto-minor-updates': core_1.Flags.boolean({
+            description: 'Release policy: allow installs to take minor updates automatically',
+            allowNo: true,
+        }),
     };
     async run() {
         this.requireAuth();
@@ -275,7 +318,16 @@ class AgentsCreate extends base_command_1.BaseCommand {
             // server seeds the full portfolio exactly as it always has.
             relationshipLoops: flags['no-relationship-loops'] ? false : undefined,
         });
-        payload = (0, agent_config_1.mergeAgentConfigFlags)(payload, flags);
+        // `mergeAgentConfigFlags` parses the typed flags (avatar, scene background,
+        // working hours, every JSON flag). A parse failure is the caller's input, so
+        // it is reported as a CLI error with the accepted forms — not as an unhandled
+        // throw, and not as a 400 from the server naming a zod path.
+        try {
+            payload = (0, agent_config_1.mergeAgentConfigFlags)(payload, flags);
+        }
+        catch (err) {
+            this.error(err.message, { exit: 1 });
+        }
         // agentCreateSchema (packages/api/src/agents/validation.ts) requires
         // provider and model, and a nameless agent is unusable (see
         // agentCreateMissingFields). We validate client-side so users get a clearer
@@ -330,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/ensure-default.d.ts

@@ -0,0 +1,27 @@
+import { BaseCommand } from '../../base-command';
+/**
+ * The agent a harness gets when nobody has configured one.
+ *
+ * Wraps `POST /api/agents/default`, the path a `skrr code` session takes on an
+ * unconfigured account. It is IDEMPOTENT — it returns the existing default
+ * rather than minting a second one — which is what makes it safe in a
+ * first-run script where `agents create` would not be.
+ *
+ * Deliberately a separate command from `agents create`: this one asks the server
+ * to CHOOSE (provider, model, placement, name), and `create` is where the caller
+ * chooses. Collapsing them would make `create` sometimes-not-create.
+ *
+ * `lib/first-party-harness-agent.ts` calls the same endpoint through its own
+ * private helper and keeps doing so: that path takes an `AbortSignal` and treats
+ * an abort as distinct from a refusal, which `dataService.ensureDefaultAgent`
+ * cannot express. Two call sites, one endpoint, for a stated reason — not drift.
+ */
+export default class AgentsEnsureDefault extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        harness: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/agents/ensure-default.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const auth_core_1 = require("@skrr-ai/auth-core");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../../base-command");
+const web_url_1 = require("../../lib/web-url");
+/**
+ * The agent a harness gets when nobody has configured one.
+ *
+ * Wraps `POST /api/agents/default`, the path a `skrr code` session takes on an
+ * unconfigured account. It is IDEMPOTENT — it returns the existing default
+ * rather than minting a second one — which is what makes it safe in a
+ * first-run script where `agents create` would not be.
+ *
+ * Deliberately a separate command from `agents create`: this one asks the server
+ * to CHOOSE (provider, model, placement, name), and `create` is where the caller
+ * chooses. Collapsing them would make `create` sometimes-not-create.
+ *
+ * `lib/first-party-harness-agent.ts` calls the same endpoint through its own
+ * private helper and keeps doing so: that path takes an `AbortSignal` and treats
+ * an abort as distinct from a refusal, which `dataService.ensureDefaultAgent`
+ * cannot express. Two call sites, one endpoint, for a stated reason — not drift.
+ */
+class AgentsEnsureDefault extends base_command_1.BaseCommand {
+    static description = "Return this account's default agent for a harness, creating it if there isn't one";
+    static examples = [
+        '<%= config.bin %> agents ensure-default',
+        '<%= config.bin %> agents ensure-default --harness <harness-id> --json',
+    ];
+    static flags = {
+        harness: core_1.Flags.string({
+            // Only a harness with a managed-inference capability can own a default
+            // agent, and today exactly one does. Defaulted rather than required
+            // because the bare call is otherwise refused with a message that quotes
+            // the literal string "undefined" — accurate about the body, useless about
+            // the fix. Read from FIRST_PARTY_HARNESS, never written as a literal.
+            description: `Harness the default belongs to (default: ${auth_core_1.FIRST_PARTY_HARNESS.provider})`,
+            default: auth_core_1.FIRST_PARTY_HARNESS.provider,
+        }),
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { flags } = await this.parse(AgentsEnsureDefault);
+        let result;
+        try {
+            result = await data_provider_1.dataService.ensureDefaultAgent({ harness: flags.harness });
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+        const agent = result.agent;
+        if (flags.json) {
+            this.log(JSON.stringify({ created: result.created, agent: (0, web_url_1.withAgentUrl)(this.cliConfig.baseURL, agent) }, null, 2));
+            return;
+        }
+        const agentId = String(agent.id ?? agent._id ?? '?');
+        this.log(result.created
+            ? `Created default agent ${agentId} — ${agent.name ?? '(no name)'}`
+            : `Default agent already exists: ${agentId} — ${agent.name ?? '(no name)'}`);
+        this.log(`URL: ${(0, web_url_1.withAgentUrl)(this.cliConfig.baseURL, agent).url ?? '-'}`);
+    }
+}
+exports.default = AgentsEnsureDefault;

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/mute.d.ts

@@ -0,0 +1,16 @@
+import { BaseCommand } from '../../base-command';
+/**
+ * Per-USER preference, not agent config: it changes your view of the agent and
+ * nobody else's. Idempotent over a toggle endpoint — see `lib/agent-pin-mute.ts`.
+ */
+export default class AgentsMute extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}