@skrr-ai/cli 0.1.37 → 0.1.38

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.js

@@ -46,7 +46,7 @@ class AgentsActionsCreate extends base_command_1.BaseCommand {
         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 (repeatable, any-of; implies --scope label)',
+            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({
@@ -70,7 +70,7 @@ class AgentsActionsCreate extends base_command_1.BaseCommand {
                 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: (0, agent_actions_1.resolveAgentActionScopeFlags)(flags),
+                scope: await (0, agent_actions_1.resolveAgentActionScopeFlags)(flags),
                 outcome: flags.outcome,
             });
         }
@@ -78,14 +78,17 @@ class AgentsActionsCreate extends base_command_1.BaseCommand {
             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'
@@ -140,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);
@@ -149,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.js

@@ -42,7 +42,7 @@ class AgentsActionsUpdate extends base_command_1.BaseCommand {
         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 (repeatable, any-of; implies --scope label)',
+            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({
@@ -63,7 +63,7 @@ class AgentsActionsUpdate extends base_command_1.BaseCommand {
                 config: (0, agent_actions_1.parseJsonObjectFlag)(flags.config, '--config'),
                 order: flags.order,
                 enabled: flags.enabled,
-                scope: (0, agent_actions_1.resolveAgentActionScopeFlags)(flags),
+                scope: await (0, agent_actions_1.resolveAgentActionScopeFlags)(flags),
                 outcome: flags.outcome,
             });
         }
@@ -125,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.js

@@ -165,9 +165,12 @@ class AgentsApiActionsAdd extends base_command_1.BaseCommand {
                     path: props.path,
                 })),
             };
+            // Say it was a dry run: the output used to be indistinguishable from what
+            // a real add would have printed, so a reader could not tell whether
+            // anything had been written.
             this.log(flags.json
-                ? JSON.stringify(preview, null, 2)
-                : `${preview.functions.length} operation(s) on ${domain}:\n` +
+                ? JSON.stringify({ dryRun: true, written: false, ...preview }, null, 2)
+                : `Dry run — nothing was written. ${preview.functions.length} operation(s) on ${domain}:\n` +
                     preview.functions
                         .map((f) => `  ${f.name}  ${f.method.toUpperCase()} ${f.path}`)
                         .join('\n'));

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

@@ -17,6 +17,17 @@ import { BaseCommand } from '../../../base-command';
  * the other two would break muscle memory for a surface that works, so this one
  * takes an unambiguous name and all three now say which concept they are.
  */
+/**
+ * The operation names an action exposes, parsed from its stored spec by the same
+ * parser `add` and the web builder use. The listing used to show id, agent,
+ * domain and auth — never what the action can DO — so answering "which tools does
+ * this give the agent" meant reading the raw spec.
+ */
+export declare function operationNames(action: {
+    metadata?: {
+        raw_spec?: string;
+    };
+}): string[];
 export default class AgentsApiActionsList extends BaseCommand {
     static description: string;
     static examples: string[];

package/dist/commands/agents/api-actions/index.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.operationNames = operationNames;
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../../base-command");
@@ -22,6 +23,21 @@ const format_1 = require("../../../lib/format");
  * the other two would break muscle memory for a surface that works, so this one
  * takes an unambiguous name and all three now say which concept they are.
  */
+/**
+ * The operation names an action exposes, parsed from its stored spec by the same
+ * parser `add` and the web builder use. The listing used to show id, agent,
+ * domain and auth — never what the action can DO — so answering "which tools does
+ * this give the agent" meant reading the raw spec.
+ */
+function operationNames(action) {
+    const raw = action.metadata?.raw_spec;
+    if (!raw)
+        return [];
+    const parsed = (0, data_provider_1.validateAndParseOpenAPISpec)(raw);
+    if (!parsed.status || !parsed.spec)
+        return [];
+    return Object.keys((0, data_provider_1.openapiToFunction)(parsed.spec).requestBuilders);
+}
 class AgentsApiActionsList extends base_command_1.BaseCommand {
     static description = 'List OpenAPI-backed Actions on agents you can edit (NOT `agents actions`, which is embedded buttons)';
     static examples = [
@@ -51,7 +67,15 @@ class AgentsApiActionsList extends base_command_1.BaseCommand {
             ? actions.filter((action) => action.agent_id === flags.agent)
             : actions;
         if (flags.json) {
-            this.log(JSON.stringify(rows, null, 2));
+            // Database internals (`_id`, `__v`) are not part of an action; a script
+            // reading this should not learn to depend on them.
+            const clean = rows.map((action) => {
+                const { _id, __v, ...rest } = action;
+                void _id;
+                void __v;
+                return { ...rest, operations: operationNames(action) };
+            });
+            this.log(JSON.stringify(clean, null, 2));
             return;
         }
         if (rows.length === 0) {
@@ -66,11 +90,13 @@ class AgentsApiActionsList extends base_command_1.BaseCommand {
             agentId: action.agent_id ?? '-',
             domain: action.metadata?.domain ?? '-',
             auth: action.metadata?.auth?.type ?? 'none',
+            operations: operationNames(action).join(', ') || '-',
         })), [
             { key: 'actionId', header: 'ACTION ID', verbatim: true },
             { key: 'agentId', header: 'AGENT ID', verbatim: true },
             { key: 'domain', header: 'DOMAIN', maxWidth: 40 },
             { key: 'auth', header: 'AUTH' },
+            { key: 'operations', header: 'OPERATIONS', maxWidth: 48 },
         ], (line) => this.log(line));
     }
 }

package/dist/commands/agents/avatar/default/index.d.ts

@@ -1,4 +1,15 @@
 import { BaseCommand } from '../../../../base-command';
+/**
+ * Which of the two states produced the policy line above it.
+ *
+ * The route sends `explicit` precisely because the policy alone cannot carry
+ * it: `resolveAgentAvatarDefaultPolicy` maps an absent field and a deliberate
+ * choice of the same shape onto one value. So "I picked random-from-all" and "I
+ * have never picked anything" printed identically, and they are not the same
+ * fact — only the second follows the shipped default if it ever changes, which
+ * is the whole reason clearing exists as a separate operation from choosing.
+ */
+export declare function describePolicyProvenance(explicit: boolean): string;
 /**
  * What face a NEW agent gets when its creator does not pick one.
  *

package/dist/commands/agents/avatar/default/index.js

@@ -1,8 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.describePolicyProvenance = describePolicyProvenance;
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../../../base-command");
+/**
+ * Which of the two states produced the policy line above it.
+ *
+ * The route sends `explicit` precisely because the policy alone cannot carry
+ * it: `resolveAgentAvatarDefaultPolicy` maps an absent field and a deliberate
+ * choice of the same shape onto one value. So "I picked random-from-all" and "I
+ * have never picked anything" printed identically, and they are not the same
+ * fact — only the second follows the shipped default if it ever changes, which
+ * is the whole reason clearing exists as a separate operation from choosing.
+ */
+function describePolicyProvenance(explicit) {
+    return explicit
+        ? '  You chose this. It stays until you change or clear it.'
+        : '  You have not chosen one, so this follows the shipped default — including if it changes.';
+}
 /**
  * What face a NEW agent gets when its creator does not pick one.
  *
@@ -36,6 +52,7 @@ class AgentsAvatarDefaultShow extends base_command_1.BaseCommand {
             return;
         }
         this.log((0, data_provider_1.describeAgentAvatarPolicy)(response.policy));
+        this.log(describePolicyProvenance(Boolean(response.explicit)));
         this.log('');
         this.log('Applies to agents created from now on. Existing agents keep the face they have —');
         this.log('`skrr agents avatar default apply` is the one path that changes them.');

package/dist/commands/agents/avatar/default/set.d.ts

@@ -12,7 +12,8 @@ export default class AgentsAvatarDefaultSet extends BaseCommand {
     static description: string;
     static examples: string[];
     static flags: {
-        mode: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        mode: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        clear: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         ref: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         scope: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         category: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;

package/dist/commands/agents/avatar/default/set.js

@@ -20,12 +20,18 @@ class AgentsAvatarDefaultSet extends base_command_1.BaseCommand {
         '<%= config.bin %> agents avatar default set --mode fixed --ref preset:kosmo',
         '<%= config.bin %> agents avatar default set --mode random --scope category --category illustrations',
         '<%= config.bin %> agents avatar default set --mode random --scope mine',
+        '<%= config.bin %> agents avatar default set --clear',
     ];
     static flags = {
         mode: core_1.Flags.string({
             description: 'platform = the shipped logo; fixed = one avatar; random = a different one each time',
             options: ['platform', 'fixed', 'random'],
-            required: true,
+            exclusive: ['clear'],
+        }),
+        clear: core_1.Flags.boolean({
+            description: 'Remove your policy entirely, so new agents follow whatever the workspace or the ' +
+                'platform ships. NOT the same as --mode platform, which pins the logo.',
+            exclusive: ['mode', 'ref', 'scope', 'category'],
         }),
         ref: core_1.Flags.string({
             description: '--mode fixed: which avatar. default, preset:<id>, asset:<id>, or image:<filepath>@<source>',
@@ -70,12 +76,22 @@ class AgentsAvatarDefaultSet extends base_command_1.BaseCommand {
     async run() {
         this.requireAuth();
         const { flags } = await this.parse(AgentsAvatarDefaultSet);
-        let policy;
-        try {
-            policy = this.buildPolicy(flags);
+        // `--mode` was `required`, which made the cleared state — the one the write
+        // route goes out of its way to support — unreachable from here: every value
+        // of `--mode` WRITES a policy, so once this command had been run there was
+        // no way back to "no opinion" short of calling the API by hand.
+        if (!flags.clear && !flags.mode) {
+            this.error('Choose --mode platform|fixed|random to set a policy, or --clear to remove yours so ' +
+                'new agents follow whatever the workspace or the platform ships.', { exit: 1 });
         }
-        catch (err) {
-            this.error(err.message, { exit: 1 });
+        let policy = null;
+        if (!flags.clear) {
+            try {
+                policy = this.buildPolicy(flags);
+            }
+            catch (err) {
+                this.error(err.message, { exit: 1 });
+            }
         }
         let response;
         try {
@@ -88,7 +104,16 @@ class AgentsAvatarDefaultSet extends base_command_1.BaseCommand {
             this.log(JSON.stringify(response, null, 2));
             return;
         }
-        this.log(`Default avatar policy: ${(0, data_provider_1.describeAgentAvatarPolicy)(response.policy)}`);
+        if (flags.clear) {
+            // Say what it FOLLOWS now, not just that something was removed — the
+            // value is the same one an explicit `--mode random --scope all` would
+            // print, and the difference between them is the whole point of clearing.
+            this.log(`Cleared. New agents follow the current default: ${(0, data_provider_1.describeAgentAvatarPolicy)(response.policy)}.`);
+            this.log('If that default changes later, this account follows it.');
+        }
+        else {
+            this.log(`Default avatar policy: ${(0, data_provider_1.describeAgentAvatarPolicy)(response.policy)}`);
+        }
         this.log('Existing agents are unchanged. `skrr agents avatar default apply` changes those.');
     }
 }