@skrr-ai/cli 0.1.36 → 0.1.38

package/dist/commands/spaces/actions/add.js

@@ -1,10 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const node_crypto_1 = require("node:crypto");
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../../base-command");
 const prompt_1 = require("../../../lib/prompt");
 const space_output_1 = require("../../../lib/space-output");
+const space_custom_actions_1 = require("../../../lib/space-custom-actions");
 class SpacesActionsAdd extends base_command_1.BaseCommand {
     static description = 'Add a custom action to a space';
     static args = {
@@ -13,11 +15,11 @@ class SpacesActionsAdd extends base_command_1.BaseCommand {
     static flags = {
         json: core_1.Flags.boolean({ description: 'Output as JSON' }),
         'from-json': core_1.Flags.string({ description: 'JSON action body' }),
-        id: core_1.Flags.string({ description: 'Action ID' }),
-        label: core_1.Flags.string({ description: 'Button label' }),
+        id: core_1.Flags.string({ description: 'Action ID (generated when omitted)' }),
+        label: space_custom_actions_1.spaceCustomActionLabelFlag,
         prompt: core_1.Flags.string({ description: 'Prompt sent when the action runs' }),
         color: core_1.Flags.string({ description: 'Color hex' }),
-        icon: core_1.Flags.string({ description: 'Lucide icon name' }),
+        icon: space_custom_actions_1.spaceCustomActionIconFlag,
         skill: core_1.Flags.string({ description: 'Optional skill ID' }),
     };
     async run() {
@@ -31,7 +33,10 @@ class SpacesActionsAdd extends base_command_1.BaseCommand {
             this.error(err.message, { exit: 1 });
         }
         const payload = (0, prompt_1.mergeDefined)(body, {
-            id: flags.id,
+            // Generated when omitted, as `agents actions create` does. Demanding the
+            // caller invent an id — with only "Action id is required." to go on — was
+            // the one required field nothing else could supply.
+            id: flags.id ?? (typeof body.id === 'string' && body.id ? body.id : `act_${(0, node_crypto_1.randomUUID)()}`),
             label: flags.label,
             prompt: flags.prompt,
             color: flags.color,
@@ -41,6 +46,9 @@ class SpacesActionsAdd extends base_command_1.BaseCommand {
         for (const field of ['id', 'label', 'prompt', 'color'])
             if (!payload[field] || typeof payload[field] !== 'string')
                 this.error(`Action ${field} is required.`, { exit: 1 });
+        const iconProblem = (0, space_custom_actions_1.spaceCustomActionIconProblem)(payload.icon);
+        if (iconProblem)
+            this.error(iconProblem, { exit: 1 });
         let result;
         try {
             result = await data_provider_1.dataService.addSpaceCustomAction({
@@ -51,10 +59,20 @@ class SpacesActionsAdd extends base_command_1.BaseCommand {
         catch (err) {
             this.handleApiError(err);
         }
+        // `--json` returns the action that was added, not the whole Space. The
+        // server answers with the full Space document — 117 lines in which the
+        // five-field action is buried — while `agents actions create --json`
+        // returns just the action. A create returns the thing it created.
+        const stored = (result?.customActions ?? []).find((action) => action.id === payload.id) ?? payload;
         if (flags.json)
-            this.log(JSON.stringify((0, space_output_1.withSpaceResourceUrls)(this.cliConfig.baseURL, args.id, 'actions', result, ['id']), null, 2));
+            this.log(JSON.stringify((0, space_output_1.withSpaceResourceUrls)(this.cliConfig.baseURL, args.id, 'actions', stored, ['id']), null, 2));
         else
             this.log(`Added custom action ${String(payload.id)}.`);
+        // On stderr, so `--json` stays parseable: the action was saved, and still
+        // cannot run until the space has a Leader (OSK-9641).
+        const unrunnable = (0, space_custom_actions_1.spaceActionsNotRunnableReason)({ id: args.id, leadAgentId: result?.leadAgentId }, this.config.bin);
+        if (unrunnable)
+            this.warn(unrunnable);
     }
 }
 exports.default = SpacesActionsAdd;

package/dist/commands/spaces/actions/available.js

@@ -51,7 +51,10 @@ class SpacesActionsAvailable extends base_command_1.BaseCommand {
             { key: 'ref', header: 'REF (agentId:actionId)' },
         ], (line) => this.log(line));
         this.log('');
+        // The REF is for two commands, and they need different rights: attaching
+        // works for any space member, running needs VIEW on the agent (OSK-9663).
         this.log('Attach to a task: skrr tasks actions attach <task-id> <agentId>:<actionId>');
+        this.log(`Run one in this space: skrr spaces actions run ${args.id} <agentId>:<actionId> (needs access to the agent; see what you can run with: skrr spaces actions list ${args.id} --all)`);
     }
 }
 exports.default = SpacesActionsAvailable;

package/dist/commands/spaces/actions/list.d.ts

@@ -4,8 +4,13 @@ export default class SpacesActionsList extends BaseCommand {
     static args: {
         id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
     };
+    static examples: string[];
     static flags: {
         json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        all: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
+    /** Say, on stderr, when none of the listed space actions can run. */
+    private noteUnrunnable;
+    private listAll;
 }

package/dist/commands/spaces/actions/list.js

@@ -4,13 +4,23 @@ 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");
+const space_custom_actions_1 = require("../../../lib/space-custom-actions");
 const space_output_1 = require("../../../lib/space-output");
 class SpacesActionsList extends base_command_1.BaseCommand {
     static description = 'List custom actions configured for a space';
     static args = {
         id: core_1.Args.string({ description: 'Space ID', required: true, ignoreStdin: true }),
     };
-    static flags = { json: core_1.Flags.boolean({ description: 'Output as JSON' }) };
+    static examples = [
+        '<%= config.bin %> spaces actions list <space-id>',
+        '<%= config.bin %> spaces actions list <space-id> --all',
+    ];
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+        all: core_1.Flags.boolean({
+            description: "Everything the space's action panel offers: its own actions and those of member agents you can view, each with the command that runs it",
+        }),
+    };
     async run() {
         this.requireAuth();
         const { args, flags } = await this.parse(SpacesActionsList);
@@ -22,12 +32,17 @@ class SpacesActionsList extends base_command_1.BaseCommand {
             this.handleApiError(err);
         }
         const actions = space.customActions ?? [];
+        if (flags.all)
+            return this.listAll(space, flags.json);
         if (flags.json)
             return void this.log(JSON.stringify((0, space_output_1.withSpaceResourceUrls)(this.cliConfig.baseURL, args.id, 'actions', { data: actions }, [
                 'id',
             ]), null, 2));
-        if (!actions.length)
-            return void this.log('No custom actions.');
+        if (!actions.length) {
+            this.log('No custom actions.');
+            this.log(`Agent actions offered here: ${this.config.bin} spaces actions list ${args.id} --all`);
+            return;
+        }
         (0, format_1.renderTable)(actions.map((a) => ({
             id: a.id,
             label: a.label,
@@ -41,6 +56,37 @@ class SpacesActionsList extends base_command_1.BaseCommand {
             { key: 'skill', header: 'SKILL' },
             { key: 'id', header: 'ID' },
         ], (line) => this.log(line));
+        this.noteUnrunnable(space);
+        this.log(`Agent actions offered here too: ${this.config.bin} spaces actions list ${args.id} --all`);
+    }
+    /** Say, on stderr, when none of the listed space actions can run. */
+    noteUnrunnable(space) {
+        const reason = (0, space_custom_actions_1.spaceActionsNotRunnableReason)(space, this.config.bin);
+        if (reason)
+            this.warn(reason);
+    }
+    async listAll(space, json) {
+        let members;
+        try {
+            members = await data_provider_1.dataService.listSpaceMemberActions(space.id);
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+        const rows = (0, space_custom_actions_1.spaceQuickActionRows)(space, members.agents, this.config.bin);
+        if (json)
+            return void this.log(JSON.stringify({ spaceId: space.id, data: rows }, null, 2));
+        if (!rows.length)
+            return void this.log('This space offers no quick actions.');
+        (0, format_1.renderTable)(rows, [
+            { key: 'source', header: 'SOURCE' },
+            { key: 'title', header: 'TITLE', maxWidth: 36 },
+            { key: 'owner', header: 'RUNS AS', maxWidth: 24 },
+            { key: 'type', header: 'TYPE' },
+            { key: 'run', header: 'RUN' },
+        ], (line) => this.log(line));
+        if (rows.some((row) => row.source === 'space'))
+            this.noteUnrunnable(space);
     }
 }
 exports.default = SpacesActionsList;

package/dist/commands/spaces/actions/run.d.ts

@@ -0,0 +1,28 @@
+import { BaseCommand } from '../../../base-command';
+/**
+ * Fire one of a space's quick actions, the way its Actions tab does.
+ *
+ * `spaces actions add` could create a space action and nothing on the CLI could
+ * run it (OSK-9641), and a space member handed `agentId:actionId` refs by
+ * `spaces actions available` had only `agents actions run`, which answers a
+ * member with 403 and opens a chat rather than working in the space (OSK-9663).
+ *
+ * The routing is the web runner's (`useSpaceQuickActionRunner`), not a new one:
+ * a prompt action runs as a task in this space, assigned to the Space Leader for
+ * a space's own action and to its agent for an agent's; a built-in action runs
+ * through the agent-action route. The task text comes from the same
+ * `spaceQuickActionTaskSpec` the web uses, so both surfaces hand the agent the
+ * same work.
+ */
+export default class SpacesActionsRun extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        space: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+        action: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/spaces/actions/run.js

@@ -0,0 +1,146 @@
+"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");
+const space_custom_actions_1 = require("../../../lib/space-custom-actions");
+const web_url_1 = require("../../../lib/web-url");
+/**
+ * Fire one of a space's quick actions, the way its Actions tab does.
+ *
+ * `spaces actions add` could create a space action and nothing on the CLI could
+ * run it (OSK-9641), and a space member handed `agentId:actionId` refs by
+ * `spaces actions available` had only `agents actions run`, which answers a
+ * member with 403 and opens a chat rather than working in the space (OSK-9663).
+ *
+ * The routing is the web runner's (`useSpaceQuickActionRunner`), not a new one:
+ * a prompt action runs as a task in this space, assigned to the Space Leader for
+ * a space's own action and to its agent for an agent's; a built-in action runs
+ * through the agent-action route. The task text comes from the same
+ * `spaceQuickActionTaskSpec` the web uses, so both surfaces hand the agent the
+ * same work.
+ */
+class SpacesActionsRun extends base_command_1.BaseCommand {
+    static description = "Run a space quick action: the space's own (by id) or a member agent's (agentId:actionId)";
+    static examples = [
+        '<%= config.bin %> spaces actions run <space-id> <action-id>',
+        '<%= config.bin %> spaces actions run <space-id> <agent-id>:<action-id> --json',
+    ];
+    static args = {
+        space: core_1.Args.string({ description: 'Space ID', required: true, ignoreStdin: true }),
+        action: core_1.Args.string({
+            description: "A space action id from 'spaces actions list', or agentId:actionId, both as 'spaces actions list --all' prints them",
+            required: true,
+            ignoreStdin: true,
+        }),
+    };
+    static flags = { json: core_1.Flags.boolean({ description: 'Output as JSON' }) };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(SpacesActionsRun);
+        const bin = this.config.bin;
+        let space;
+        try {
+            space = await data_provider_1.dataService.getSpace(args.space);
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+        const colon = args.action.indexOf(':');
+        const agentRef = colon > 0 && !args.action.startsWith('space-custom:')
+            ? { agentId: args.action.slice(0, colon), actionId: args.action.slice(colon + 1) }
+            : null;
+        let action;
+        let assigneeAgentId;
+        if (!agentRef) {
+            const found = (0, space_custom_actions_1.findSpaceCustomAction)(space, args.action);
+            if ('problem' in found)
+                this.error(found.problem, { exit: 4 });
+            const leaderProblem = (0, space_custom_actions_1.spaceActionsNotRunnableReason)(space, bin);
+            if (leaderProblem || !space.leadAgentId)
+                this.error(leaderProblem ?? '', { exit: 1 });
+            action = (0, data_provider_1.spaceCustomActionToAgentAction)(found.customAction, space, found.index);
+            assigneeAgentId = space.leadAgentId;
+        }
+        else {
+            let members;
+            try {
+                members = await data_provider_1.dataService.listSpaceMemberActions(args.space);
+            }
+            catch (err) {
+                this.handleApiError(err);
+            }
+            const member = members.agents.find(({ agent }) => agent.id === agentRef.agentId);
+            if (!member) {
+                this.error(`Agent ${agentRef.agentId} is not a member of this space that you can view, so you cannot ` +
+                    `run its actions here. Attaching one to a task needs only the space: ` +
+                    `\`${bin} tasks actions attach <task-id> ${args.action}\`. To run it, its owner has to share the agent with you.`, { exit: 1 });
+            }
+            const found = (member.agent.agentActions ?? []).find((a) => a.id === agentRef.actionId);
+            if (!found) {
+                this.error(`No action ${agentRef.actionId} on agent ${agentRef.agentId}. List what this space offers: \`${bin} spaces actions list ${args.space} --all\`.`, { exit: 4 });
+            }
+            if (!(0, data_provider_1.isAgentActionAvailableInSpace)(found, { spaceId: space.id, labelIds: space.labelIds })) {
+                this.error(`Action ${found.title} is not offered in this space (its scope is another space or a Label this space does not carry).`, { exit: 1 });
+            }
+            action = found;
+            assigneeAgentId = agentRef.agentId;
+        }
+        if ((0, data_provider_1.isBuiltinAgentAction)(action)) {
+            // A built-in is a typed platform operation owned by its agent, and runs
+            // through the agent-action route exactly as the web runner sends it.
+            let result;
+            try {
+                result = await data_provider_1.dataService.runAgentAction({
+                    agent_id: assigneeAgentId,
+                    action_id: action.id,
+                });
+            }
+            catch (err) {
+                this.handleApiError(err);
+            }
+            if (flags.json)
+                return void this.log(JSON.stringify(result, null, 2));
+            if (!result.ok)
+                this.error(result.error || result.reason || 'Action failed.', { exit: 1 });
+            this.log(`${action.title} ran.`);
+            return;
+        }
+        const outcome = (0, data_provider_1.agentActionOutcome)(action);
+        const spec = (0, data_provider_1.spaceQuickActionTaskSpec)(action, { id: space.id, title: space.title });
+        let created;
+        try {
+            created = await data_provider_1.dataService.createAndStartTask({
+                ...spec,
+                spaceId: space.id,
+                assigneeAgentIds: [assigneeAgentId],
+            });
+        }
+        catch (err) {
+            this.handleApiError(err, { subject: `Action ${action.title}` });
+        }
+        const taskUrl = (0, web_url_1.taskUrlFrom)(this.cliConfig.baseURL, created.task);
+        if (flags.json) {
+            this.log(JSON.stringify({ ...created, outcome, assigneeAgentId, ...(taskUrl ? { taskUrl } : {}) }, null, 2));
+        }
+        else {
+            const identifier = created.task.identifier ?? created.task.id;
+            this.log(created.started
+                ? `Started ${action.title} as task ${identifier}.`
+                : `Created task ${identifier} for ${action.title}, but it did not start: ${created.startError ?? 'no reason given'}.`);
+            if (taskUrl)
+                this.log(`Task: ${taskUrl}`);
+            if (created.conversationId)
+                this.log(`Conversation: ${created.conversationId}`);
+            if (created.started && outcome === 'ephemeral') {
+                // The web hides an ephemeral action's task when the run finishes, from
+                // the tab that fired it. The CLI does not wait for the run, so say what
+                // will be different rather than let the task's staying look like a bug.
+                this.log(`This action is ephemeral. The web app hides its task when the run finishes; from the CLI it stays until you hide it: \`${bin} tasks move ${created.task.id} --status hidden\`.`);
+            }
+        }
+        if (!created.started)
+            this.exit(1);
+    }
+}
+exports.default = SpacesActionsRun;

package/dist/commands/spaces/actions/update.js

@@ -5,6 +5,7 @@ const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../../base-command");
 const prompt_1 = require("../../../lib/prompt");
 const space_output_1 = require("../../../lib/space-output");
+const space_custom_actions_1 = require("../../../lib/space-custom-actions");
 class SpacesActionsUpdate extends base_command_1.BaseCommand {
     static description = 'Update a custom action in a space';
     static args = {
@@ -14,10 +15,10 @@ class SpacesActionsUpdate extends base_command_1.BaseCommand {
     static flags = {
         json: core_1.Flags.boolean({ description: 'Output as JSON' }),
         'from-json': core_1.Flags.string({ description: 'JSON action patch' }),
-        label: core_1.Flags.string({ description: 'Button label' }),
+        label: space_custom_actions_1.spaceCustomActionLabelFlag,
         prompt: core_1.Flags.string({ description: 'Prompt sent when the action runs' }),
         color: core_1.Flags.string({ description: 'Color hex' }),
-        icon: core_1.Flags.string({ description: 'Lucide icon name' }),
+        icon: space_custom_actions_1.spaceCustomActionIconFlag,
         skill: core_1.Flags.string({ description: 'Optional skill ID' }),
     };
     async run() {
@@ -30,21 +31,39 @@ class SpacesActionsUpdate extends base_command_1.BaseCommand {
         catch (err) {
             this.error(err.message, { exit: 1 });
         }
-        const payload = (0, prompt_1.mergeDefined)(body, {
+        const patch = (0, prompt_1.mergeDefined)(body, {
             label: flags.label,
             prompt: flags.prompt,
             color: flags.color,
             icon: flags.icon,
             skillId: flags.skill,
         });
-        if (!Object.keys(payload).length)
+        if (!Object.keys(patch).length)
             this.error('Nothing to update.', { exit: 1 });
+        const iconProblem = (0, space_custom_actions_1.spaceCustomActionIconProblem)(patch.icon);
+        if (iconProblem)
+            this.error(iconProblem, { exit: 1 });
         let result;
+        let leadAgentId;
         try {
+            // The server replaces the WHOLE element (`$set: {'customActions.$': action}`)
+            // and validates a complete action — `id`, `label`, `prompt`, `color` — whose
+            // `id` must equal the path's. This command sent only the changed flags, so
+            // every call failed that validation: `--label` alone, `--prompt` alone, all
+            // of them together, 400 "Invalid request data" every time (OSK-9646). The
+            // web editor never hit it because it always sends the full action.
+            //
+            // So the patch is applied over the stored action here and sent whole.
+            const space = await data_provider_1.dataService.getSpace(args.space);
+            leadAgentId = space.leadAgentId;
+            const current = (space.customActions ?? []).find((action) => action.id === args.id);
+            if (!current) {
+                this.error(`No custom action ${args.id} in space ${args.space}. List them with \`spaces actions list ${args.space}\`.`, { exit: 1 });
+            }
             result = await data_provider_1.dataService.updateSpaceCustomAction({
                 spaceId: args.space,
                 actionId: args.id,
-                action: payload,
+                action: { ...current, ...patch, id: args.id },
             });
         }
         catch (err) {
@@ -54,6 +73,9 @@ class SpacesActionsUpdate extends base_command_1.BaseCommand {
             this.log(JSON.stringify((0, space_output_1.withSpaceResourceUrls)(this.cliConfig.baseURL, args.space, 'actions', result, ['id']), null, 2));
         else
             this.log(`Updated custom action ${args.id}.`);
+        const unrunnable = (0, space_custom_actions_1.spaceActionsNotRunnableReason)({ id: args.space, leadAgentId }, this.config.bin);
+        if (unrunnable)
+            this.warn(unrunnable);
     }
 }
 exports.default = SpacesActionsUpdate;

package/dist/commands/spaces/create.d.ts

@@ -9,7 +9,10 @@ export default class SpacesCreate extends BaseCommand {
         description: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         status: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         color: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        icon: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'icon-color': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'lead-agent': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        team: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'target-date': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         goal: import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         label: import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;

package/dist/commands/spaces/create.js

@@ -5,6 +5,7 @@ const data_provider_1 = require("@skrr-ai/data-provider");
 const outbox_1 = require("../../lib/outbox");
 const api_fetch_1 = require("../../lib/api-fetch");
 const base_command_1 = require("../../base-command");
+const label_ref_1 = require("../../lib/label-ref");
 const web_url_1 = require("../../lib/web-url");
 const prompt_1 = require("../../lib/prompt");
 const created_line_1 = require("../../lib/created-line");
@@ -13,6 +14,7 @@ class SpacesCreate extends base_command_1.BaseCommand {
     static examples = [
         '<%= config.bin %> spaces create --title "Q2 Launch"',
         '<%= config.bin %> spaces create --title "Support" --status in_progress --color "#4f46e5"',
+        '<%= config.bin %> spaces create --title "Launch" --icon Rocket --icon-color "#2DD4BF"',
         '<%= config.bin %> spaces create --title "Research" --lead-agent <agent-id>',
         '<%= config.bin %> spaces create --title "Frontend" --parent <space-id>',
         '<%= config.bin %> spaces create --title "Private notes" --parent <space-id> --no-inherit-access',
@@ -27,11 +29,18 @@ class SpacesCreate extends base_command_1.BaseCommand {
         description: core_1.Flags.string({ description: 'Space description' }),
         status: core_1.Flags.string({ description: 'Space status', options: [...data_provider_1.SPACE_STATUSES] }),
         color: core_1.Flags.string({ description: 'Space color (hex, e.g. #4f46e5)' }),
+        icon: core_1.Flags.string({
+            description: 'Space icon — a curated icon name (e.g. Rocket, Star) or an emoji',
+        }),
+        'icon-color': core_1.Flags.string({
+            description: 'Color applied to the space icon (hex, e.g. #2DD4BF)',
+        }),
         'lead-agent': core_1.Flags.string({ description: 'Space Leader agent ID' }),
+        team: core_1.Flags.string({ description: 'Team ID to attach this space to' }),
         'target-date': core_1.Flags.string({ description: 'Target date (ISO string)' }),
         goal: core_1.Flags.string({ description: 'Goal ID to link (repeatable)', multiple: true }),
         label: core_1.Flags.string({
-            description: 'Label ID to attach (repeatable, max 50). Must be applicable to spaces. After creation use `spaces labels add/remove`.',
+            description: 'Label to attach (repeatable, max 50) — id, or a name from `skrr labels list --applicable-to space`. An unknown name is refused, never created. After creation use `spaces labels add/remove`.',
             multiple: true,
         }),
         'group-chat': core_1.Flags.string({ description: 'Group chat ID to link this space to' }),
@@ -53,15 +62,36 @@ class SpacesCreate extends base_command_1.BaseCommand {
         catch (err) {
             this.error(err.message, { exit: 1 });
         }
+        // A name is resolved against the DECLARED vocabulary before the create, so
+        // a typo fails here — cheaply, with the near misses named — rather than
+        // minting a second spelling of a label somebody already has.
+        let resolvedLabelIds;
+        try {
+            const ids = await (0, label_ref_1.resolveLabelRefs)(flags.label, {
+                applicableTo: 'space',
+                ...(process.env.OVERSKY_WORKSPACE_ID
+                    ? { workspaceId: process.env.OVERSKY_WORKSPACE_ID }
+                    : {}),
+            });
+            resolvedLabelIds = ids.length > 0 ? ids : undefined;
+        }
+        catch (err) {
+            if (err instanceof label_ref_1.LabelRefError)
+                this.error(err.message, { exit: 1 });
+            this.handleApiError(err);
+        }
         const payload = (0, prompt_1.mergeDefined)(body, {
             title: flags.title,
             description: flags.description,
             status: flags.status,
             color: flags.color,
+            icon: flags.icon,
+            iconColor: flags['icon-color'],
             leadAgentId: flags['lead-agent'],
+            teamId: flags.team,
             targetDate: flags['target-date'],
             goalIds: flags.goal,
-            labelIds: flags.label,
+            labelIds: resolvedLabelIds,
             groupChatId: flags['group-chat'],
             parentSpaceId: flags.parent,
             inheritAccess: flags['inherit-access'],

package/dist/commands/spaces/label-summaries.d.ts

@@ -0,0 +1,27 @@
+import { BaseCommand } from '../../base-command';
+/**
+ * `skrr spaces label-summaries` — the label DEFINITIONS carried by every Space
+ * you can view, in one request.
+ *
+ * The third of the sidebar's batch reads, beside `spaces member-summaries` and
+ * `spaces task-rollups`, and the one that was never bound. `Space.labelIds`
+ * already says which Space carries which label, so what a caller holding a list
+ * of Spaces is missing is only the name and colour to resolve those ids
+ * against — and `GET /api/labels` takes exactly ONE (scope, scopeId) pair, so
+ * resolving them otherwise costs a request per row.
+ *
+ * Deliberately a flat list, matching the endpoint: one map, not one map per row.
+ *
+ * A label whose row is not returned is one the caller genuinely cannot read —
+ * another user's private label attached to a shared Space. It is reported as
+ * unresolved rather than hidden, because "this Space has a label you cannot
+ * see" and "this Space has no labels" are different facts.
+ */
+export default class SpacesLabelSummaries extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/spaces/label-summaries.js

@@ -0,0 +1,64 @@
+"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");
+/**
+ * `skrr spaces label-summaries` — the label DEFINITIONS carried by every Space
+ * you can view, in one request.
+ *
+ * The third of the sidebar's batch reads, beside `spaces member-summaries` and
+ * `spaces task-rollups`, and the one that was never bound. `Space.labelIds`
+ * already says which Space carries which label, so what a caller holding a list
+ * of Spaces is missing is only the name and colour to resolve those ids
+ * against — and `GET /api/labels` takes exactly ONE (scope, scopeId) pair, so
+ * resolving them otherwise costs a request per row.
+ *
+ * Deliberately a flat list, matching the endpoint: one map, not one map per row.
+ *
+ * A label whose row is not returned is one the caller genuinely cannot read —
+ * another user's private label attached to a shared Space. It is reported as
+ * unresolved rather than hidden, because "this Space has a label you cannot
+ * see" and "this Space has no labels" are different facts.
+ */
+class SpacesLabelSummaries extends base_command_1.BaseCommand {
+    static description = 'Show the label definitions used across every space you can view';
+    static examples = [
+        '<%= config.bin %> spaces label-summaries',
+        '<%= config.bin %> spaces label-summaries --json',
+    ];
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { flags } = await this.parse(SpacesLabelSummaries);
+        let response;
+        try {
+            response = await data_provider_1.dataService.listSpaceLabelSummaries();
+        }
+        catch (err) {
+            this.handleApiError(err);
+            return;
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(response, null, 2));
+            return;
+        }
+        const labels = response.labels || [];
+        if (labels.length === 0) {
+            this.log('No labels on any space you can view.');
+            return;
+        }
+        const clip = (text, width) => text.length > width ? `${text.slice(0, width - 3)}...` : text;
+        this.log(`${'LABEL'.padEnd(28)} ${'SCOPE'.padEnd(10)} ${'COLOR'.padEnd(9)} ${'APPLIES TO'.padEnd(24)} ID`);
+        for (const label of labels) {
+            // `applicableTo` is what the label may be attached to, which is not the
+            // same as its scope — a workspace-scoped label can still be task-only.
+            const appliesTo = (label.applicableTo || []).join(', ') || '-';
+            this.log(`${clip(label.name, 28).padEnd(28)} ${String(label.scope ?? '-').padEnd(10)} ` +
+                `${String(label.color ?? '-').padEnd(9)} ${clip(appliesTo, 24).padEnd(24)} ${label.id}`);
+        }
+    }
+}
+exports.default = SpacesLabelSummaries;

package/dist/commands/spaces/labels/add.js

@@ -3,6 +3,7 @@ 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");
+const label_ref_1 = require("../../../lib/label-ref");
 const web_url_1 = require("../../../lib/web-url");
 class SpacesLabelsAdd extends base_command_1.BaseCommand {
     static description = 'Attach a label to a space';
@@ -16,7 +17,7 @@ class SpacesLabelsAdd extends base_command_1.BaseCommand {
     static flags = {
         json: core_1.Flags.boolean({ description: 'Output the updated space as JSON' }),
         label: core_1.Flags.string({
-            description: 'Label ID — must be applicable to spaces (see `skrr labels list --applicable-to space`)',
+            description: 'Label — id, or a name from `skrr labels list --applicable-to space`. An unknown name is refused, never created.',
             required: true,
         }),
     };
@@ -26,9 +27,25 @@ class SpacesLabelsAdd extends base_command_1.BaseCommand {
         // `spaces update` deliberately refuses labelIds — the server routes label
         // changes through this atomic $addToSet endpoint so concurrent edits can't
         // clobber each other. Re-attaching an already-attached label is a no-op.
+        // A name is resolved against the DECLARED vocabulary; an unknown one is
+        // refused with the near misses named, never created. See lib/label-ref.
+        let labelId = flags.label;
+        try {
+            [labelId] = await (0, label_ref_1.resolveLabelRefs)([flags.label], {
+                applicableTo: 'space',
+                ...(process.env.OVERSKY_WORKSPACE_ID
+                    ? { workspaceId: process.env.OVERSKY_WORKSPACE_ID }
+                    : {}),
+            });
+        }
+        catch (err) {
+            if (err instanceof label_ref_1.LabelRefError)
+                this.error(err.message, { exit: 1 });
+            this.handleApiError(err);
+        }
         let result;
         try {
-            result = await data_provider_1.dataService.addLabelToSpace({ spaceId: args.id, labelId: flags.label });
+            result = await data_provider_1.dataService.addLabelToSpace({ spaceId: args.id, labelId });
         }
         catch (err) {
             this.handleApiError(err);