@skrr-ai/cli 0.1.36 → 0.1.38

package/README.md

@@ -839,8 +839,10 @@ cat space.json | sky spaces create --from-json -
 sky spaces create --from-json template.json --title "Override title"
 ```
 
-Flags: `--title`, `--description`, `--status`, `--color`, `--lead-agent`,
-`--target-date`, `--group-chat`, `--from-json <file|->`, `--json`.
+Flags: `--title`, `--description`, `--status`, `--color`, `--icon`,
+`--icon-color`, `--lead-agent`, `--team`, `--target-date`, `--goal`,
+`--label`, `--group-chat`, `--parent`, `--no-inherit-access`,
+`--from-json <file|->`, `--json`.
 
 ### `sky spaces update <id>`
 
@@ -852,8 +854,19 @@ sky spaces update <space-id> --status active --color "#4f46e5"
 sky spaces update <space-id> --from-json patch.json
 ```
 
-Flags: `--title`, `--description`, `--status`, `--color`, `--lead-agent`,
-`--target-date`, `--from-json <file|->`, `--json`.
+Flags: `--title`, `--description`, `--status`, `--color`, `--icon`,
+`--icon-color`, `--lead-agent`, `--target-date`, `--goal`,
+`--no-inherit-access`, `--estimate-scale`, `--estimate-migration`,
+`--default-estimate`, `--no-use-default-estimate`, `--default-expect`,
+`--delivery-mode`, `--integration-branch`, `--auto-merge-tier`,
+`--worktree-isolation`, `--no-auto-start-on-backlog-exit`,
+`--triage-external-intake`, `--default-task-template`,
+`--from-json <file|->`, `--json`.
+
+Nullable fields accept `none` (or `null`) to clear: `--icon none` restores
+the default folder, `--icon-color none` the neutral icon color,
+`--lead-agent none` removes the Leader, `--target-date none` clears the
+date, and `--default-task-template none` removes the default template.
 
 ### `sky spaces delete <id>`
 

package/bin/dev-fallback.js

@@ -48,6 +48,116 @@ function sourceTreeDigest(fileSystem, sourceRoot) {
   return hash.digest('hex');
 }
 
+/**
+ * Every relative specifier a source imports, re-exports, or dynamically loads.
+ *
+ * Deliberately a scan rather than a parse: this runs before the CLI starts, so
+ * it may not cost a TypeScript program, and over-collecting is harmless — an
+ * extra file in the closure can only make the guard more conservative, never
+ * less.
+ */
+function relativeSpecifiers(text) {
+  const found = [];
+  const patterns = [
+    /(?:^|[\s;}])(?:import|export)[\s\S]{0,400}?from\s*['"](\.[^'"]*)['"]/g,
+    /\bimport\s*\(\s*['"](\.[^'"]*)['"]\s*\)/g,
+    /\brequire\s*\(\s*['"](\.[^'"]*)['"]\s*\)/g,
+    /(?:^|[\s;}])import\s+['"](\.[^'"]*)['"]/g,
+  ];
+  for (const pattern of patterns) {
+    let match;
+    while ((match = pattern.exec(text)) !== null) found.push(match[1]);
+  }
+  return found;
+}
+
+/** Resolve a relative specifier the way tsc does, extensionless first. */
+function resolveSourceSpecifier(fileSystem, fromDirectory, specifier) {
+  const base = path.resolve(fromDirectory, specifier);
+  const candidates = [
+    base,
+    `${base}.ts`,
+    `${base}.tsx`,
+    `${base}.json`,
+    path.join(base, 'index.ts'),
+    path.join(base, 'index.tsx'),
+  ];
+  for (const candidate of candidates) {
+    try {
+      if (fileSystem.statSync(candidate).isFile()) return candidate;
+    } catch {
+      // try the next shape
+    }
+  }
+  return null;
+}
+
+/**
+ * The digest of everything a single command is compiled FROM: its own source
+ * plus the transitive closure of the relative imports it reaches.
+ *
+ * This replaces a digest over the whole of `src` as the freshness test for one
+ * command, and the difference is not an optimisation — it is the difference
+ * between a true statement and a false one. The whole-tree digest answers "has
+ * anything in the CLI changed", and that was used to answer "is THIS command's
+ * build current". In a checkout where another session is editing a different
+ * command — routine here, see root CLAUDE.md on ~35 worktrees sharing one
+ * checkout — those answers disagree constantly, and the launcher then refuses a
+ * command whose own build it can prove is byte-current, or silently delegates it
+ * to whatever older CLI is on PATH. A dogfood run spent its first twenty minutes
+ * concluding that a shipped feature had not shipped, because the commands under
+ * test were being answered by a build that predated them.
+ *
+ * Commands do import other commands (`tasks update` imports `tasks create`), so
+ * the closure is walked rather than assuming command sources are independent —
+ * that assumption is false here, and a guard built on it would call a genuinely
+ * stale command fresh, which is the failure worth avoiding.
+ *
+ * An unresolvable specifier is hashed as its own text. The build script and this
+ * launcher run this same function, so they agree on that value; and a specifier
+ * that starts resolving later changes the digest, which is the correct verdict.
+ */
+function commandClosureDigest(fileSystem, sourceRoot, entrySource) {
+  const seen = new Set();
+  const unresolved = [];
+  const pending = [path.resolve(entrySource)];
+  while (pending.length) {
+    const current = pending.pop();
+    if (seen.has(current)) continue;
+    seen.add(current);
+    let text;
+    try {
+      text = fileSystem.readFileSync(current, 'utf8');
+    } catch {
+      continue;
+    }
+    for (const specifier of relativeSpecifiers(text)) {
+      const resolved = resolveSourceSpecifier(fileSystem, path.dirname(current), specifier);
+      if (resolved) {
+        if (!seen.has(resolved)) pending.push(resolved);
+      } else {
+        unresolved.push(`${path.relative(sourceRoot, current)}:${specifier}`);
+      }
+    }
+  }
+  const hash = crypto.createHash('sha256');
+  for (const file of [...seen].sort()) {
+    hash.update(path.relative(sourceRoot, file).split(path.sep).join('/'));
+    hash.update('\0');
+    try {
+      hash.update(fileSystem.readFileSync(file));
+    } catch {
+      hash.update('<unreadable>');
+    }
+    hash.update('\0');
+  }
+  for (const miss of unresolved.sort()) {
+    hash.update(miss.split(path.sep).join('/'));
+    hash.update('\0');
+  }
+  return hash.digest('hex');
+}
+
 function findAlternateCli({
   commandName,
   currentEntry,
@@ -143,9 +253,17 @@ function missingLocalCommandBuild({ cliRoot, argv, fileSystem = fs, verifySource
   } catch {
     commandBuildManifest = null;
   }
-  const currentSourceTreeDigest = commandBuildManifest
-    ? sourceTreeDigest(fileSystem, path.join(cliRoot, 'src'))
-    : null;
+  // Lazily, because the closure test below almost always settles the question
+  // first and this one reads every `.ts` under `src` — 1,300 files here, on a
+  // path that runs before any command starts.
+  let sourceTreeDigestCache;
+  const currentSourceTreeDigest = () => {
+    if (!commandBuildManifest) return null;
+    if (sourceTreeDigestCache === undefined) {
+      sourceTreeDigestCache = sourceTreeDigest(fileSystem, path.join(cliRoot, 'src'));
+    }
+    return sourceTreeDigestCache;
+  };
   const commandParts = [];
   for (const value of argv) {
     if (String(value).startsWith('-')) break;
@@ -165,11 +283,26 @@ function missingLocalCommandBuild({ cliRoot, argv, fileSystem = fs, verifySource
     if (!verifySourceIdentity) return null;
     try {
       const relative = path.relative(sourceCommandsDirectory, source).split(path.sep).join('/');
+      // What this command is actually compiled from: its own source plus the
+      // transitive closure of its relative imports. Scoped to the command
+      // because a change to an unrelated one cannot reach it, and walked rather
+      // than assumed because commands here do import each other.
+      const builtClosure = commandBuildManifest?.closures?.[relative];
+      if (typeof builtClosure === 'string') {
+        return builtClosure === commandClosureDigest(fileSystem, path.join(cliRoot, 'src'), source)
+          ? null
+          : compiled;
+      }
       const builtDigest = commandBuildManifest?.commands?.[relative];
+      // A manifest written before closures existed. Fall back to the old, wider
+      // test rather than trusting a per-file digest that cannot see an edited
+      // import — an over-cautious verdict is recoverable, a wrong "fresh" is
+      // what this launcher exists to prevent.
+      //
       // Git checkouts and partial builds can make old JS newer than its source.
       // Content identity is authoritative; no digest means the development
       // build is unproved and the installed CLI is safer.
-      return commandBuildManifest?.sourceTreeDigest === currentSourceTreeDigest &&
+      return commandBuildManifest?.sourceTreeDigest === currentSourceTreeDigest() &&
         typeof builtDigest === 'string' &&
         builtDigest === sourceDigest(fileSystem, source)
         ? null
@@ -188,6 +321,35 @@ function missingLocalCommandBuild({ cliRoot, argv, fileSystem = fs, verifySource
     if (incomplete) return incomplete;
     break;
   }
+  /*
+   * `--version` must report the binary that will actually RUN.
+   *
+   * It names no command, so the loop above never ran and this returned null —
+   * meaning `skrr --version` answered from the local checkout while every real
+   * command silently delegated to a different build. Someone verifying a change
+   * saw the version they expected and tested code they had not written, which is
+   * the precise failure this launcher exists to prevent, wearing a reassuring
+   * number.
+   *
+   * The whole-tree digest is the right test here: a stale tree means SOME
+   * command would fall back, so the version the user is about to rely on is not
+   * this one.
+   */
+  if (argv.some((value) => value === '--version' || value === '-v')) {
+    // A STALE tree and a MISSING build are the same answer to the user's
+    // question. The digest comparison covers the first and skipped the second,
+    // because a wiped or half-written `dist` has no manifest to compare — so
+    // `--version` still answered from the checkout while every command fell
+    // back. Observed twice in one dogfood session, both times right after a
+    // rebuild left `dist` incomplete.
+    if (verifySourceIdentity && !commandBuildManifest) return commandsDirectory;
+    if (
+      verifySourceIdentity &&
+      commandBuildManifest.sourceTreeDigest !== currentSourceTreeDigest()
+    ) {
+      return commandsDirectory;
+    }
+  }
   if (argv.some((value) => value === '--help' || value === '-h')) {
     const sourceDirectory = path.join(sourceCommandsDirectory, ...commandParts);
     const pending = [sourceDirectory];
@@ -215,6 +377,7 @@ function missingLocalCommandBuild({ cliRoot, argv, fileSystem = fs, verifySource
 
 module.exports = {
   COMMAND_BUILD_MANIFEST,
+  commandClosureDigest,
   findAlternateCli,
   missingLocalCommandBuild,
   sourceTreeDigest,

package/dist/base-command.js

@@ -16,6 +16,7 @@ exports.isTypedServerRefusal = isTypedServerRefusal;
 exports.isRetryableFailure = isRetryableFailure;
 const core_1 = require("@oclif/core");
 Object.defineProperty(exports, "Flags", { enumerable: true, get: function () { return core_1.Flags; } });
+const failed_lookup_1 = require("./lib/failed-lookup");
 // Re-exported from its home in `lib/keychain`, beside the other profile
 // functions. It lived here while `init()` was its only caller; a lib module
 // needing it would otherwise have to import the command base class, and with
@@ -112,7 +113,8 @@ class BaseCommand extends core_1.Command {
         }),
         profile: core_1.Flags.string({
             description: 'Which stored session to use. Each profile keeps its own credential and deployment, ' +
-                'so signing into one does not sign you out of another. Also OVERSKY_PROFILE.',
+                'so signing into one does not sign you out of another. Also OVERSKY_PROFILE. ' +
+                'List them with `profiles list`.',
         }),
     };
     cliConfig;
@@ -391,6 +393,14 @@ class BaseCommand extends core_1.Command {
         // UUID, so refs go through the same exact-match resolution as titles.
         if (!query || (0, space_resolver_1.looksLikeCanonicalSpaceId)(query))
             return query;
+        if ((0, failed_lookup_1.isFailedLookupValue)(query)) {
+            this.failWithCliError({
+                message: (0, failed_lookup_1.describeFailedLookupValue)(query, 'Space'),
+                code: space_resolver_1.SPACE_CLI_ERROR_CODE.NOT_A_REFERENCE,
+                exit: 2,
+                retryable: false,
+            });
+        }
         const normalizedQuery = (0, space_resolver_1.normalizeSpaceRef)(query);
         const load = async (includeArchived) => {
             let response;
@@ -489,6 +499,16 @@ class BaseCommand extends core_1.Command {
         const query = value.trim();
         if (!query)
             return query;
+        // Before the search, not after it: `null` from a failed `jq -r` must never
+        // reach the title tiers, and it should not cost a request to say so.
+        if ((0, failed_lookup_1.isFailedLookupValue)(query)) {
+            this.failWithCliError({
+                message: (0, failed_lookup_1.describeFailedLookupValue)(query, 'task'),
+                code: task_ref_resolver_1.TASK_REF_CLI_ERROR_CODE.NOT_A_REFERENCE,
+                exit: 2,
+                retryable: false,
+            });
+        }
         let response;
         try {
             response = await data_provider_1.dataService.listTasks({ q: query, limit: 50 });
@@ -690,6 +710,7 @@ class BaseCommand extends core_1.Command {
                 AMBIGUOUS: 'ASSIGNEE_AMBIGUOUS',
                 NO_SPACE: 'ASSIGNEE_NO_SPACE_CONTEXT',
                 NOT_FOUND: 'ASSIGNEE_NOT_FOUND',
+                NOT_A_REFERENCE: 'ASSIGNEE_NOT_A_REFERENCE',
             };
             this.failWithCliError({
                 message: outcome.failures
@@ -1231,7 +1252,21 @@ class BaseCommand extends core_1.Command {
         //
         // Field-level validation is appended for the same reason: the server names
         // the offending field and only `--json` callers could read it.
-        this.error(`${message}${formatValidationIssues(details)}`, { exit, code });
+        //
+        // And the REMEDY, when the message does not already carry one. This CLI's
+        // convention is a `→` remedy line inside the message (103 sites), with
+        // `details.suggestion` as its machine-readable twin for `--json`. Where a
+        // call site wrote the remedy ONLY into `details.suggestion`, it reached
+        // `--json` alone, and a person at a terminal was told what was wrong and
+        // never what to do — `followups list` without an agent, OSK-9670. oclif
+        // renders `suggestions` as its own "Try this:" block. Skipped when the
+        // message opens a `→` line, so those do not print the remedy twice.
+        const suggestion = hasRemedyLine(message) ? undefined : authoredSuggestion(details);
+        this.error(`${message}${formatValidationIssues(details)}`, {
+            exit,
+            code,
+            ...(suggestion ? { suggestions: [suggestion] } : {}),
+        });
     }
     writeJsonCliError({ message, code, status, exit, retryable, details, }) {
         this.log(JSON.stringify({
@@ -1612,6 +1647,15 @@ function isRetryableFailure(status, body) {
         return false;
     return status === 408 || status === 425 || status === 429 || !!(status && status >= 500);
 }
+/** True when a message already carries this CLI's `→` remedy line. */
+function hasRemedyLine(message) {
+    return /^\s*→/m.test(message);
+}
+/** The remedy a call site wrote into `details.suggestion`, if it wrote one. */
+function authoredSuggestion(details) {
+    const suggestion = details?.suggestion;
+    return typeof suggestion === 'string' && suggestion.trim() ? suggestion.trim() : undefined;
+}
 /**
  * Render server-supplied field validation into the human error.
  *

package/dist/commands/agents/actions/create.d.ts

@@ -18,6 +18,11 @@ export default class AgentsActionsCreate extends BaseCommand {
         embeds: 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>;
         enabled: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        scope: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        space: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'space-title': 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>;
+        outcome: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
 }

package/dist/commands/agents/actions/create.js

@@ -39,6 +39,20 @@ class AgentsActionsCreate extends base_command_1.BaseCommand {
         embeds: core_1.Flags.string({ description: 'Embedded built-in actions JSON array' }),
         order: core_1.Flags.integer({ description: 'Display order (defaults to end of list)' }),
         enabled: core_1.Flags.boolean({ description: 'Create enabled or disabled', allowNo: true }),
+        scope: core_1.Flags.string({
+            description: 'Where the action is offered. Implied by --space / --label; pass "general" to offer it everywhere.',
+            options: [...agent_actions_1.AGENT_ACTION_SCOPE_CHOICES],
+        }),
+        space: core_1.Flags.string({ description: 'Offer only in this space (implies --scope space)' }),
+        'space-title': core_1.Flags.string({ description: 'Denormalized space title for the scope chip' }),
+        label: core_1.Flags.string({
+            description: 'Offer in every space carrying this Label — a Label id or name from `labels list` (repeatable, any-of; implies --scope label). Not button text: that is `spaces actions add --label`.',
+            multiple: true,
+        }),
+        outcome: core_1.Flags.string({
+            description: "What a run leaves behind: 'ephemeral' hides the run's task once it answers, 'durable' keeps it on the board. Default ephemeral.",
+            options: [...agent_actions_1.AGENT_ACTION_OUTCOME_CHOICES],
+        }),
     };
     async run() {
         this.requireAuth();
@@ -54,27 +68,40 @@ class AgentsActionsCreate extends base_command_1.BaseCommand {
                 config: (0, agent_actions_1.parseJsonObjectFlag)(flags.config, '--config'),
                 order: flags.order,
                 enabled: flags.enabled,
+                // Flags win over --from-json, and a JSON body may still carry these
+                // directly. Both paths land on the same two fields below.
+                scope: await (0, agent_actions_1.resolveAgentActionScopeFlags)(flags),
+                outcome: flags.outcome,
             });
         }
         catch (err) {
             this.error(err.message, { exit: 1 });
         }
         let created;
+        let replayed = false;
         try {
-            const agent = await (0, agent_actions_1.fetchAgentForActionEdit)(args.agentId);
-            const actions = (0, agent_actions_1.getAgentActions)(agent);
             const title = typeof body.title === 'string' ? body.title.trim() : '';
             if (!title)
                 this.error('Action title is required. Pass --title or include title.', { exit: 1 });
             const kind = body.kind === 'builtin' ? 'builtin' : 'prompt';
-            const order = typeof body.order === 'number' ? body.order : (0, agent_actions_1.nextActionOrder)(actions);
+            // No read of the library: position is assigned by the server at the
+            // moment of the append, so it cannot be computed from a stale copy. An
+            // explicit --order is still honoured.
+            const explicitOrder = typeof body.order === 'number' ? body.order : undefined;
+            const order = explicitOrder ?? 0;
             const enabled = typeof body.enabled === 'boolean' ? body.enabled : true;
+            const scope = body.scope;
+            const outcome = body.outcome === 'durable' || body.outcome === 'ephemeral'
+                ? body.outcome
+                : undefined;
             if (kind === 'builtin') {
                 const builtinType = body.builtinType;
                 if (!agent_actions_1.BUILTIN_ACTION_TYPES.includes(builtinType)) {
                     this.error(`--builtin-type is required for built-in actions.`, { exit: 1 });
                 }
                 created = (0, agent_actions_1.makeBuiltinAction)({
+                    scope,
+                    outcome,
                     title,
                     description: typeof body.description === 'string' ? body.description : undefined,
                     builtinType: builtinType,
@@ -104,6 +131,8 @@ class AgentsActionsCreate extends base_command_1.BaseCommand {
                     this.error(err.message, { exit: 1 });
                 }
                 created = (0, agent_actions_1.makePromptAction)({
+                    scope,
+                    outcome,
                     title,
                     description: typeof body.description === 'string' ? body.description : undefined,
                     prompt,
@@ -114,7 +143,13 @@ class AgentsActionsCreate extends base_command_1.BaseCommand {
                     sourceListingId: typeof body.sourceListingId === 'string' ? body.sourceListingId : undefined,
                 });
             }
-            await (0, agent_actions_1.updateAgentActions)(args.agentId, [...actions, created]);
+            if (explicitOrder === undefined) {
+                delete created.order;
+            }
+            const appended = await (0, agent_actions_1.appendAgentAction)(args.agentId, created);
+            // Report what the server stored, not what we sent.
+            created = appended.action;
+            replayed = !appended.created;
         }
         catch (err) {
             this.handleApiError(err);
@@ -123,7 +158,9 @@ class AgentsActionsCreate extends base_command_1.BaseCommand {
             this.log(JSON.stringify(created, null, 2));
             return;
         }
-        this.log(`Created action on agent ${args.agentId}:`);
+        this.log(replayed
+            ? `Action ${created.id} was already on agent ${args.agentId} (nothing added):`
+            : `Created action on agent ${args.agentId}:`);
         (0, agent_actions_1.renderAction)(created, (line) => this.log(line));
     }
 }

package/dist/commands/agents/actions/delete.d.ts

@@ -8,6 +8,7 @@ export default class AgentsActionsDelete extends BaseCommand {
     };
     static flags: {
         yes: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
 }

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

@@ -16,6 +16,9 @@ class AgentsActionsDelete extends base_command_1.BaseCommand {
     };
     static flags = {
         yes: core_1.Flags.boolean({ char: 'y', description: 'Skip confirmation prompt' }),
+        // The only sibling (create, update, list, show) without --json, so a script
+        // driving the five broke on the fifth.
+        json: core_1.Flags.boolean({ description: 'Output the result as JSON' }),
     };
     async run() {
         this.requireAuth();
@@ -37,6 +40,10 @@ class AgentsActionsDelete extends base_command_1.BaseCommand {
         catch (err) {
             this.handleApiError(err);
         }
+        if (flags.json) {
+            this.log(JSON.stringify({ deleted: true, agentId: args.agentId, actionId: args.actionId }, null, 2));
+            return;
+        }
         this.log(`Deleted action ${args.actionId} from agent ${args.agentId}.`);
     }
 }

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

@@ -17,6 +17,11 @@ export default class AgentsActionsUpdate extends BaseCommand {
         'replace-config': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         order: import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         enabled: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        scope: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        space: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'space-title': 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>;
+        outcome: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
 }

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

@@ -35,6 +35,20 @@ class AgentsActionsUpdate extends base_command_1.BaseCommand {
         }),
         order: core_1.Flags.integer({ description: 'Display order' }),
         enabled: core_1.Flags.boolean({ description: 'Enable or disable the action', allowNo: true }),
+        scope: core_1.Flags.string({
+            description: 'Where the action is offered. Implied by --space / --label; pass "general" to offer it everywhere.',
+            options: [...agent_actions_1.AGENT_ACTION_SCOPE_CHOICES],
+        }),
+        space: core_1.Flags.string({ description: 'Offer only in this space (implies --scope space)' }),
+        'space-title': core_1.Flags.string({ description: 'Denormalized space title for the scope chip' }),
+        label: core_1.Flags.string({
+            description: 'Offer in every space carrying this Label — a Label id or name from `labels list` (repeatable, any-of; implies --scope label). Not button text: that is `spaces actions add --label`.',
+            multiple: true,
+        }),
+        outcome: core_1.Flags.string({
+            description: "What a run leaves behind: 'ephemeral' hides the run's task once it answers, 'durable' keeps it on the board.",
+            options: [...agent_actions_1.AGENT_ACTION_OUTCOME_CHOICES],
+        }),
     };
     async run() {
         this.requireAuth();
@@ -49,6 +63,8 @@ class AgentsActionsUpdate extends base_command_1.BaseCommand {
                 config: (0, agent_actions_1.parseJsonObjectFlag)(flags.config, '--config'),
                 order: flags.order,
                 enabled: flags.enabled,
+                scope: await (0, agent_actions_1.resolveAgentActionScopeFlags)(flags),
+                outcome: flags.outcome,
             });
         }
         catch (err) {
@@ -76,6 +92,14 @@ class AgentsActionsUpdate extends base_command_1.BaseCommand {
                 next.order = patch.order;
             if (typeof patch.enabled === 'boolean')
                 next.enabled = patch.enabled;
+            // A scope is replaced wholesale, never merged: `{kind:'space'}` and
+            // `{kind:'label'}` carry disjoint fields, so a shallow merge would leave
+            // a `labelIds` behind on a space scope and produce a shape the write gate
+            // rejects. Absent means "leave the existing scope alone".
+            if (patch.scope !== undefined)
+                next.scope = patch.scope;
+            if (patch.outcome !== undefined)
+                next.outcome = patch.outcome;
             if (current.kind === 'builtin') {
                 const builtin = next;
                 if (patch.builtinType !== undefined) {
@@ -101,7 +125,9 @@ class AgentsActionsUpdate extends base_command_1.BaseCommand {
             }
             actions[index] = next;
             updated = next;
-            await (0, agent_actions_1.updateAgentActions)(args.agentId, actions);
+            const savedAgent = await (0, agent_actions_1.updateAgentActions)(args.agentId, actions);
+            // Report what the server stored, not what we sent — see storedActionOrLocal.
+            updated = (0, agent_actions_1.storedActionOrLocal)(savedAgent, updated);
         }
         catch (err) {
             this.handleApiError(err);

package/dist/commands/agents/api-actions/add.d.ts

@@ -0,0 +1,41 @@
+import { BaseCommand } from '../../../base-command';
+/**
+ * Attach (or re-attach) an OpenAPI document to an agent as a tool surface.
+ *
+ * The derivation is the SAME code the web builder runs —
+ * `validateAndParseOpenAPISpec` then `openapiToFunction`, both from
+ * `@skrr-ai/data-provider`. That matters more than it looks: the server stores
+ * `functions` verbatim and never re-reads the spec, so a CLI that derived them
+ * its own way would produce actions subtly unlike the ones the web produces from
+ * the same document, and the difference would only show up at call time.
+ *
+ * The spec is validated LOCALLY before anything is sent, because the endpoint's
+ * failure for a malformed document is `400 No functions provided` — true, and
+ * useless for finding the line that is wrong.
+ */
+export default class AgentsApiActionsAdd extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        agentId: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        spec: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'action-id': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        auth: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'api-key': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'authorization-type': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'custom-auth-header': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'oauth-client-id': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'oauth-client-secret': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'oauth-authorization-url': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'oauth-client-url': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'oauth-scope': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'oauth-token-exchange-method': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'dry-run': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    private readSpec;
+    private buildAuth;
+    run(): Promise<void>;
+}