@skrr-ai/cli 0.1.36 → 0.1.38

package/dist/commands/tasks/update.js

@@ -42,6 +42,9 @@ class TasksUpdate extends base_command_1.BaseCommand {
             description: 'Path to a JSON file (or "-" for stdin) to use as the patch body; may include taskId',
         }),
         title: core_1.Flags.string({ description: 'New title' }),
+        yes: core_1.Flags.boolean({
+            description: 'Skip the confirmation when changing Expectations revokes assessments already recorded',
+        }),
         expect: core_1.Flags.string({
             multiple: true,
             description: tasks_1.EXPECT_FLAG_HELP +
@@ -227,6 +230,86 @@ class TasksUpdate extends base_command_1.BaseCommand {
                 }
             }
         }
+        /**
+         * Say what the edit costs BEFORE making it.
+         *
+         * `expectations` is a TaskSpecFence field, and assessments are matched by
+         * exact `specVersion` — so rewriting the list bumps the version and every
+         * judgement already recorded against the old one stops counting. Assess
+         * five, fix a typo in the sixth, and the five are gone.
+         *
+         * Disclosure, not a block: the edit is legitimate and must stay possible.
+         * The point is only that its price should not be discovered afterwards, by
+         * a Task that will not close. `--yes` states the intent in the command line
+         * where it can be reviewed, which is also what a non-TTY caller needs.
+         */
+        /*
+         * The trigger is the PAYLOAD, not the flag that produced it.
+         *
+         * The first version guarded only `--expect`, so `--from-json
+         * '{"expectations": [...]}'` — exactly what an agent batching edits uses —
+         * rewrote the list and revoked the assessments with no warning at all.
+         * Same write, same price: the disclosure belongs on the effective change.
+         */
+        /*
+         * The DESCRIPTION is a spec field too.
+         *
+         * `TaskSpecFence.TASK_SPEC_FIELDS` is `['description', 'expectations']`, and
+         * both advance `specVersion` — which revokes every assessment, because they
+         * are matched by exact version. The disclosure was wired to the Expectations
+         * payload alone, so fixing a typo in the prose voided a reviewer's sign-off
+         * with no warning and no receipt. Same write, same price, same disclosure.
+         */
+        const changesSpec = expectationsPatch !== undefined ||
+            body.expectations !== undefined ||
+            flags.description !== undefined ||
+            body.description !== undefined;
+        if (changesSpec) {
+            let settled = [];
+            let unreadable = false;
+            try {
+                const acceptance = await data_provider_1.dataService.getTaskAcceptance(taskIdentity.id);
+                settled = acceptance.expectations.filter((e) => e.assessmentId);
+            }
+            catch {
+                // An unreadable acceptance is not a reason to refuse the edit. Warn
+                // without a number rather than inventing one or blocking the write.
+                unreadable = true;
+            }
+            if ((unreadable || settled.length > 0) && !flags.yes) {
+                const noun = settled.length === 1 ? 'assessment' : 'assessments';
+                const count = unreadable ? 'Any existing' : `${settled.length} existing`;
+                const field = expectationsPatch !== undefined || body.expectations !== undefined
+                    ? 'Changing Expectations'
+                    : 'Changing the description';
+                this.log(`${field} advances the Task specification, so ${count} ${noun} ` +
+                    'will stop counting and must be recorded again.');
+                /*
+                 * NAME them. The count alone made the warning unactionable — and it is
+                 * task-WIDE, so Expectations you are not touching lose their judgements
+                 * too, which a bare number actively hides.
+                 */
+                for (const row of settled) {
+                    this.log(`  ${row.id}  ${row.sentence || row.text || ''}`);
+                }
+                if (settled.length > 0) {
+                    this.log('Revocation covers every Expectation on this Task, including ones this edit ' +
+                        'does not touch.');
+                }
+                const ok = await this.confirm('Continue? [y/N] ');
+                if (!ok) {
+                    /*
+                     * Non-zero, because the edit did NOT happen.
+                     *
+                     * This printed "No change made." and exited 0, so `skrr tasks update
+                     * … && echo applied` printed `applied`. The guard exists to protect
+                     * the non-interactive path, and the non-interactive path is precisely
+                     * the one that cannot see a message — it can only read the exit code.
+                     */
+                    this.error('No change made — re-run with `--yes` to accept the revocation.', { exit: 2 });
+                }
+            }
+        }
         const payload = (0, prompt_1.mergeDefined)((0, task_resolver_1.stripTaskIdentityFields)(body), {
             title: flags.title,
             expectations: expectationsPatch === null ? [] : (expectationsPatch ?? undefined),

package/dist/commands/tasks/updates/add.js

@@ -42,7 +42,7 @@ class TasksUpdatesAdd extends base_command_1.BaseCommand {
                 'fields are required even when empty. ' +
                 'progress {completedSinceLast:[],nextActions:[],currentFocus?} · ' +
                 'finding {finding,evidenceRefs:[],impact?,severity?} · ' +
-                'decision {decision,rationale,alternativesConsidered?} · ' +
+                'decision {decision,rationale,alternativesConsidered?:[]} · ' +
                 'blocker {cause,requiredAction,nextOwner} · ' +
                 'verification {claim,result:passed|failed|inconclusive,evidenceRefs:[]}. ' +
                 'nextOwner is a principal object like {"kind":"human","userId":"..."}, not a name. ' +

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

@@ -0,0 +1,22 @@
+import { BaseCommand } from '../../base-command';
+/**
+ * `skrr token list`
+ *
+ * The other half of `token mint`. Minting binds a long-lived refresh session to
+ * a machine and records the `--label` with it — which reads as a promise that
+ * the credential can be found again — and there was no way to see it: `token`
+ * had only `mint`, and `list-tokens` shows CI tokens, a different credential
+ * type, so `revoke-token` had nothing to aim at. The only remedy was
+ * `logout --all-devices`, which signs every machine out.
+ *
+ * `GET /api/auth/sessions/refresh` has served exactly this list all along; it
+ * was simply not reachable from the CLI.
+ */
+export default class TokenList extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/token/list.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_command_1 = require("../../base-command");
+const api_fetch_1 = require("../../lib/api-fetch");
+const format_1 = require("../../lib/format");
+/**
+ * `skrr token list`
+ *
+ * The other half of `token mint`. Minting binds a long-lived refresh session to
+ * a machine and records the `--label` with it — which reads as a promise that
+ * the credential can be found again — and there was no way to see it: `token`
+ * had only `mint`, and `list-tokens` shows CI tokens, a different credential
+ * type, so `revoke-token` had nothing to aim at. The only remedy was
+ * `logout --all-devices`, which signs every machine out.
+ *
+ * `GET /api/auth/sessions/refresh` has served exactly this list all along; it
+ * was simply not reachable from the CLI.
+ */
+class TokenList extends base_command_1.BaseCommand {
+    static description = 'List the active sessions a minted token belongs to — the other half of `token mint`';
+    static examples = [
+        '<%= config.bin %> token list',
+        '<%= config.bin %> token list --json',
+    ];
+    static flags = { json: core_1.Flags.boolean({ description: 'Output JSON' }) };
+    async run() {
+        this.requireAuth();
+        const { flags } = await this.parse(TokenList);
+        let data = null;
+        try {
+            data = await (0, api_fetch_1.apiFetch)('/api/auth/sessions/refresh', {
+                method: 'GET',
+                credential: this.resolvedCredential,
+            });
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+        const sessions = data?.sessions || [];
+        if (flags.json)
+            return this.log(JSON.stringify({ sessions, count: sessions.length }, null, 2));
+        if (!sessions.length)
+            return this.log('No active sessions.');
+        (0, format_1.renderTable)(sessions.map((session) => ({
+            id: session.id,
+            kind: session.kind,
+            // The operator's own name for the credential wins over a derived
+            // device string — it is what they would search by.
+            device: session.label || session.device || '-',
+            ip: session.ip || '-',
+            lastActive: session.lastActiveAt || session.createdAt || '-',
+            // The session you are typing in. Revoking it signs THIS machine out,
+            // which is the one outcome nobody means when they revoke a credential.
+            current: session.current ? 'yes' : '',
+        })), [
+            { key: 'id', header: 'ID' },
+            { key: 'kind', header: 'KIND' },
+            { key: 'device', header: 'DEVICE', maxWidth: 34 },
+            { key: 'ip', header: 'IP' },
+            { key: 'lastActive', header: 'LAST ACTIVE' },
+            { key: 'current', header: 'CURRENT' },
+        ], (line) => this.log(line));
+        this.log('');
+        this.log('Retire one with: skrr token revoke <id>');
+    }
+}
+exports.default = TokenList;

package/dist/commands/token/revoke.d.ts

@@ -0,0 +1,23 @@
+import { BaseCommand } from '../../base-command';
+/**
+ * `skrr token revoke <id>`
+ *
+ * Retire ONE session — the credential `token mint` handed to one machine —
+ * without signing every other machine out. `logout --all-devices` was the only
+ * way to do this, which is a blunt instrument for "that one CI box is
+ * decommissioned".
+ *
+ * Owner-gated server-side: a row that is not the caller's returns
+ * `{ revoked: false }` rather than an error, so ids cannot be enumerated.
+ */
+export default class TokenRevoke extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/token/revoke.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_command_1 = require("../../base-command");
+const api_fetch_1 = require("../../lib/api-fetch");
+/**
+ * `skrr token revoke <id>`
+ *
+ * Retire ONE session — the credential `token mint` handed to one machine —
+ * without signing every other machine out. `logout --all-devices` was the only
+ * way to do this, which is a blunt instrument for "that one CI box is
+ * decommissioned".
+ *
+ * Owner-gated server-side: a row that is not the caller's returns
+ * `{ revoked: false }` rather than an error, so ids cannot be enumerated.
+ */
+class TokenRevoke extends base_command_1.BaseCommand {
+    static description = 'Revoke one session by id — see `skrr token list` for the ids';
+    static examples = ['<%= config.bin %> token revoke 665f1c2e9a4b3d0011aa77bc'];
+    static args = {
+        id: core_1.Args.string({
+            required: true,
+            ignoreStdin: true,
+            description: 'Session id from `skrr token list`',
+        }),
+    };
+    static flags = { json: core_1.Flags.boolean({ description: 'Output JSON' }) };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(TokenRevoke);
+        let data = null;
+        try {
+            data = await (0, api_fetch_1.apiFetch)(`/api/auth/sessions/refresh/${encodeURIComponent(args.id)}/revoke`, {
+                method: 'POST',
+                credential: this.resolvedCredential,
+                body: {},
+            });
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+        if (flags.json)
+            return this.log(JSON.stringify(data, null, 2));
+        if (data?.revoked)
+            return this.log(`Revoked session ${args.id}. Other machines stay signed in.`);
+        // The server does not distinguish "already gone" from "not yours" on
+        // purpose, so neither does this — saying "not found" would leak the
+        // difference and let somebody probe for ids.
+        this.log(`Nothing to revoke for ${args.id} — it is already revoked, or it is not one of your sessions.`);
+        this.log('List what is active with: skrr token list');
+    }
+}
+exports.default = TokenRevoke;

package/dist/lib/agent-actions.d.ts

@@ -1,34 +1,115 @@
-import type { Agent, AgentAction, BuiltinActionConfig, BuiltinActionType, BuiltinAgentAction, EmbeddedActionRef, PromptAgentAction } from '@skrr-ai/data-provider';
-export declare const BUILTIN_ACTION_TYPES: readonly ["slack_send_message", "slack_tool", "group_chat_message", "space_create_task", "space_post_update", "task_create", "task_mark_done", "task_assign", "goal_create", "goal_mark_done", "smart_schedule_plan", "smart_schedule_delta_watch"];
+import type { Agent, AgentAction, AgentActionOutcome, AgentActionScope, BuiltinActionConfig, BuiltinActionType, BuiltinAgentAction, EmbeddedActionRef, PromptAgentAction } from '@skrr-ai/data-provider';
+export { BUILTIN_ACTION_TYPES } from '@skrr-ai/data-provider';
 export declare const ACTION_TARGET_TYPES: readonly ["group-chats", "spaces", "tasks", "goals", "slack-channels", "slack-users"];
 export type ActionTargetType = (typeof ACTION_TARGET_TYPES)[number];
 export declare function parseJsonObjectFlag(value: string | undefined, flagName: string): Record<string, unknown> | undefined;
 export declare function fetchAgentForActionEdit(agentId: string): Promise<Agent>;
 export declare function getAgentActions(agent: Agent): AgentAction[];
 export declare function findAgentAction(agent: Agent, actionId: string): AgentAction | undefined;
+/**
+ * The row as the SERVER stored it, not as we sent it.
+ *
+ * `updateAgentActions` returns the updated Agent, and both editors used to
+ * discard it and print the object they had just built — so the output was the
+ * input, restated. That is not a cosmetic difference: the server normalizes
+ * `agentActions` through an allowlist before persisting, so a field it drops is
+ * echoed back by the CLI as though it had been saved. A `label` scope and
+ * `outcome: durable` were both silently discarded that way and the CLI reported
+ * success with the values the caller had typed (OSK-9628).
+ *
+ * Falling back to the local object keeps the command working if the write
+ * succeeds but the response is unexpectedly shaped; it cannot make the output
+ * wrong in a way it was not already.
+ */
+export declare function storedActionOrLocal(agent: Agent | null | undefined, local: AgentAction): AgentAction;
+export type AppendedAgentAction = {
+    /** The action as the server stored it. */
+    action: AgentAction;
+    /** False when this id was already in the library — a replayed request. */
+    created: boolean;
+    total: number;
+};
+/**
+ * Append ONE action atomically.
+ *
+ * `agents actions create` used to read the agent, append in memory and write
+ * the whole library back through `updateAgentActions`. Two concurrent creates
+ * therefore each read the same library and the later write erased the earlier
+ * action — six parallel creates all printed success and left one (OSK-9673).
+ * This endpoint appends with a single conditional `$push` on the server, so
+ * concurrent creates all land, the cap is enforced at the instant of the write,
+ * and a retried request whose id already landed returns `created: false`
+ * instead of adding a second copy. The client-generated id is what makes that
+ * retry safe, so it is sent rather than left for the server to assign.
+ *
+ * Update and delete still use `updateAgentActions` and still read-modify-write.
+ */
+export declare function appendAgentAction(agentId: string, action: AgentAction): Promise<AppendedAgentAction>;
 export declare function updateAgentActions(agentId: string, actions: AgentAction[]): Promise<Agent>;
-export declare function makePromptAction(input: {
+/**
+ * Fields every action shape carries regardless of kind.
+ *
+ * `scope` and `outcome` are listed HERE rather than threaded through each
+ * factory's own parameter list, because the previous version enumerated the
+ * fields it copied and simply omitted `scope` — so a space-scoped action was
+ * unauthorable from the CLI even via `--from-json`, and the omission was
+ * invisible (the row wrote fine, it was just offered everywhere).
+ */
+export type AgentActionCommonInput = {
     title: string;
     description?: string;
-    prompt: string;
     order: number;
     enabled: boolean;
     id?: string;
     sourceListingId?: string;
+    scope?: AgentActionScope;
+    outcome?: AgentActionOutcome;
+};
+export declare function makePromptAction(input: AgentActionCommonInput & {
+    prompt: string;
     /** Structured built-in actions embedded in the prompt — the chip source of truth. */
     embeddedActions?: EmbeddedActionRef[];
 }): PromptAgentAction;
-export declare function makeBuiltinAction(input: {
-    title: string;
-    description?: string;
+export declare function makeBuiltinAction(input: AgentActionCommonInput & {
     builtinType: BuiltinActionType;
     config: BuiltinActionConfig | Record<string, unknown>;
     prompt?: string;
-    order: number;
-    enabled: boolean;
-    id?: string;
-    sourceListingId?: string;
 }): BuiltinAgentAction;
+export declare const AGENT_ACTION_SCOPE_CHOICES: readonly ["general", "space", "label"];
+export declare const AGENT_ACTION_OUTCOME_CHOICES: readonly ["ephemeral", "durable"];
+export type AgentActionScopeFlags = {
+    scope?: string;
+    space?: string;
+    'space-title'?: string;
+    label?: string[];
+};
+/**
+ * Turn the scope flags into a stored scope, or `undefined` when the caller said
+ * nothing about scope (so an update leaves the existing one alone).
+ *
+ * `--space <id>` and `--label <id>` imply their kind, because typing
+ * `--scope space --space s1` twice is the kind of ceremony people skip and then
+ * wonder why the action is everywhere. An explicit `--scope general` clears it.
+ */
+/**
+ * `--label` accepts an id OR a name, like every other `--label` in the CLI.
+ *
+ * It used to take the value verbatim as a `labelId`. A name was therefore
+ * stored as though it were an id, matched no space's `labelIds`, and produced
+ * an action offered NOWHERE — silently, with the create reporting success. That
+ * is exactly the "an action that disappears reads as deletion" hazard the label
+ * tier was designed around, arriving through the CLI instead of through a card
+ * that forgot to pass its labels. An unknown name was accepted too, so a typo
+ * was indistinguishable from a working scope.
+ *
+ * `resolveLabelRefs` is the same resolver `spaces create --label` uses: it
+ * short-circuits when every value already looks like an id (so a scripted
+ * caller pays no request), refuses an unknown name with the near misses named,
+ * and refuses an ambiguous one rather than guessing.
+ */
+export declare function resolveAgentActionScopeFlags(flags: AgentActionScopeFlags): Promise<AgentActionScope | undefined>;
+/** Human-readable one-liner for a scope, used by list/show renderers. */
+export declare function describeAgentActionScope(scope?: AgentActionScope | null): string;
 export declare function nextActionOrder(actions: AgentAction[]): number;
 export declare function actionKind(action: AgentAction): 'prompt' | 'builtin';
 export declare function renderActions(actions: AgentAction[], log: (line: string) => void): void;

package/dist/lib/agent-actions.js

@@ -1,13 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ACTION_TARGET_TYPES = exports.BUILTIN_ACTION_TYPES = void 0;
+exports.AGENT_ACTION_OUTCOME_CHOICES = exports.AGENT_ACTION_SCOPE_CHOICES = exports.ACTION_TARGET_TYPES = exports.BUILTIN_ACTION_TYPES = void 0;
 exports.parseJsonObjectFlag = parseJsonObjectFlag;
 exports.fetchAgentForActionEdit = fetchAgentForActionEdit;
 exports.getAgentActions = getAgentActions;
 exports.findAgentAction = findAgentAction;
+exports.storedActionOrLocal = storedActionOrLocal;
+exports.appendAgentAction = appendAgentAction;
 exports.updateAgentActions = updateAgentActions;
 exports.makePromptAction = makePromptAction;
 exports.makeBuiltinAction = makeBuiltinAction;
+exports.resolveAgentActionScopeFlags = resolveAgentActionScopeFlags;
+exports.describeAgentActionScope = describeAgentActionScope;
 exports.nextActionOrder = nextActionOrder;
 exports.actionKind = actionKind;
 exports.renderActions = renderActions;
@@ -15,22 +19,13 @@ exports.renderAction = renderAction;
 const node_crypto_1 = require("node:crypto");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const format_1 = require("./format");
-exports.BUILTIN_ACTION_TYPES = [
-    'slack_send_message',
-    'slack_tool',
-    'group_chat_message',
-    'space_create_task',
-    'space_post_update',
-    'task_create',
-    'task_mark_done',
-    'task_assign',
-    'goal_create',
-    'goal_mark_done',
-    'smart_schedule_plan',
-    'smart_schedule_delta_watch',
-];
-const _builtinActionTypesAreExhaustive = true;
-void _builtinActionTypesAreExhaustive;
+const label_ref_1 = require("./label-ref");
+const api_fetch_1 = require("./api-fetch");
+// The vocabulary is owned by `@skrr-ai/data-provider`, which also proves it
+// complete against `BuiltinActionType`. This file used to hold a second copy
+// with its own guard (OSK-9668).
+var data_provider_2 = require("@skrr-ai/data-provider");
+Object.defineProperty(exports, "BUILTIN_ACTION_TYPES", { enumerable: true, get: function () { return data_provider_2.BUILTIN_ACTION_TYPES; } });
 exports.ACTION_TARGET_TYPES = [
     'group-chats',
     'spaces',
@@ -64,40 +59,182 @@ function getAgentActions(agent) {
 function findAgentAction(agent, actionId) {
     return getAgentActions(agent).find((action) => action.id === actionId);
 }
+/**
+ * The row as the SERVER stored it, not as we sent it.
+ *
+ * `updateAgentActions` returns the updated Agent, and both editors used to
+ * discard it and print the object they had just built — so the output was the
+ * input, restated. That is not a cosmetic difference: the server normalizes
+ * `agentActions` through an allowlist before persisting, so a field it drops is
+ * echoed back by the CLI as though it had been saved. A `label` scope and
+ * `outcome: durable` were both silently discarded that way and the CLI reported
+ * success with the values the caller had typed (OSK-9628).
+ *
+ * Falling back to the local object keeps the command working if the write
+ * succeeds but the response is unexpectedly shaped; it cannot make the output
+ * wrong in a way it was not already.
+ */
+function storedActionOrLocal(agent, local) {
+    if (!agent)
+        return local;
+    return findAgentAction(agent, local.id) ?? local;
+}
+/**
+ * Append ONE action atomically.
+ *
+ * `agents actions create` used to read the agent, append in memory and write
+ * the whole library back through `updateAgentActions`. Two concurrent creates
+ * therefore each read the same library and the later write erased the earlier
+ * action — six parallel creates all printed success and left one (OSK-9673).
+ * This endpoint appends with a single conditional `$push` on the server, so
+ * concurrent creates all land, the cap is enforced at the instant of the write,
+ * and a retried request whose id already landed returns `created: false`
+ * instead of adding a second copy. The client-generated id is what makes that
+ * retry safe, so it is sent rather than left for the server to assign.
+ *
+ * Update and delete still use `updateAgentActions` and still read-modify-write.
+ */
+async function appendAgentAction(agentId, action) {
+    try {
+        return await (0, api_fetch_1.apiFetch)(`/api/agents/${encodeURIComponent(agentId)}/agent-actions`, { method: 'POST', body: { action } });
+    }
+    catch (err) {
+        if (!isMissingRoute(err))
+            throw err;
+        return appendAgentActionByRewrite(agentId, action);
+    }
+}
+/**
+ * The server predates the append route.
+ *
+ * A released CLI is not guaranteed a server that has every route it knows —
+ * a self-hosted instance, or production mid-rollout — and without this,
+ * `agents actions create` against such a server simply failed. A missing ROUTE
+ * answers 404 with no `code` and a "No API route matches" message; a missing
+ * AGENT answers 404 with `code: 'agent_not_found'`, which must NOT fall back.
+ */
+function isMissingRoute(err) {
+    return (err instanceof api_fetch_1.ApiFetchError &&
+        err.status === 404 &&
+        !err.code &&
+        typeof err.body === 'string' &&
+        err.body.includes('No API route matches'));
+}
+/**
+ * The pre-append behaviour, kept only for servers without the route: read the
+ * library, append in memory, write it back. It is NOT safe under concurrency —
+ * that is the defect the route exists to fix — but it is correct for a single
+ * writer, which beats refusing to create anything.
+ */
+async function appendAgentActionByRewrite(agentId, action) {
+    const agent = await fetchAgentForActionEdit(agentId);
+    const actions = getAgentActions(agent);
+    const earlier = actions.find((candidate) => candidate.id === action.id);
+    if (earlier) {
+        return { action: earlier, created: false, total: actions.length };
+    }
+    const placed = typeof action.order === 'number' ? action : { ...action, order: nextActionOrder(actions) };
+    const saved = await updateAgentActions(agentId, [...actions, placed]);
+    return {
+        action: storedActionOrLocal(saved, placed),
+        created: true,
+        total: getAgentActions(saved).length || actions.length + 1,
+    };
+}
 async function updateAgentActions(agentId, actions) {
     return data_provider_1.dataService.updateAgent({
         agent_id: agentId,
         data: { agentActions: actions },
     });
 }
-function makePromptAction(input) {
+function commonActionFields(input) {
     return {
         id: input.id ?? (0, node_crypto_1.randomUUID)(),
         title: input.title,
         description: input.description,
         order: input.order,
         enabled: input.enabled,
+        ...(input.scope ? { scope: input.scope } : {}),
+        ...(input.outcome ? { outcome: input.outcome } : {}),
+        ...(input.sourceListingId ? { sourceListingId: input.sourceListingId } : {}),
+    };
+}
+function makePromptAction(input) {
+    return {
+        ...commonActionFields(input),
         prompt: input.prompt,
         ...(input.embeddedActions && input.embeddedActions.length > 0
             ? { embeddedActions: input.embeddedActions }
             : {}),
-        ...(input.sourceListingId ? { sourceListingId: input.sourceListingId } : {}),
     };
 }
 function makeBuiltinAction(input) {
     return {
-        id: input.id ?? (0, node_crypto_1.randomUUID)(),
+        ...commonActionFields(input),
         kind: 'builtin',
-        title: input.title,
-        description: input.description,
-        order: input.order,
-        enabled: input.enabled,
         builtinType: input.builtinType,
         config: input.config,
         ...(input.prompt ? { prompt: input.prompt } : {}),
-        ...(input.sourceListingId ? { sourceListingId: input.sourceListingId } : {}),
     };
 }
+/* ── scope + outcome flags (shared by `create` and `update`) ─────────────── */
+exports.AGENT_ACTION_SCOPE_CHOICES = ['general', 'space', 'label'];
+exports.AGENT_ACTION_OUTCOME_CHOICES = ['ephemeral', 'durable'];
+/**
+ * Turn the scope flags into a stored scope, or `undefined` when the caller said
+ * nothing about scope (so an update leaves the existing one alone).
+ *
+ * `--space <id>` and `--label <id>` imply their kind, because typing
+ * `--scope space --space s1` twice is the kind of ceremony people skip and then
+ * wonder why the action is everywhere. An explicit `--scope general` clears it.
+ */
+/**
+ * `--label` accepts an id OR a name, like every other `--label` in the CLI.
+ *
+ * It used to take the value verbatim as a `labelId`. A name was therefore
+ * stored as though it were an id, matched no space's `labelIds`, and produced
+ * an action offered NOWHERE — silently, with the create reporting success. That
+ * is exactly the "an action that disappears reads as deletion" hazard the label
+ * tier was designed around, arriving through the CLI instead of through a card
+ * that forgot to pass its labels. An unknown name was accepted too, so a typo
+ * was indistinguishable from a working scope.
+ *
+ * `resolveLabelRefs` is the same resolver `spaces create --label` uses: it
+ * short-circuits when every value already looks like an id (so a scripted
+ * caller pays no request), refuses an unknown name with the near misses named,
+ * and refuses an ambiguous one rather than guessing.
+ */
+async function resolveAgentActionScopeFlags(flags) {
+    const labelRefs = (flags.label ?? []).map((value) => value.trim()).filter(Boolean);
+    const spaceId = flags.space?.trim();
+    const declared = flags.scope?.trim();
+    const kind = declared ?? (spaceId ? 'space' : labelRefs.length ? 'label' : undefined);
+    if (!kind)
+        return undefined;
+    if (kind === 'general')
+        return { kind: 'general' };
+    if (kind === 'space') {
+        if (!spaceId)
+            throw new Error('--scope space requires --space <space-id>.');
+        const spaceTitle = flags['space-title']?.trim();
+        return { kind: 'space', spaceId, ...(spaceTitle ? { spaceTitle } : {}) };
+    }
+    if (kind === 'label') {
+        if (!labelRefs.length)
+            throw new Error('--scope label requires at least one --label <label-id-or-name>.');
+        const labelIds = await (0, label_ref_1.resolveLabelRefs)(labelRefs, { applicableTo: 'space' });
+        return { kind: 'label', labelIds };
+    }
+    throw new Error(`--scope must be one of ${exports.AGENT_ACTION_SCOPE_CHOICES.join(', ')}.`);
+}
+/** Human-readable one-liner for a scope, used by list/show renderers. */
+function describeAgentActionScope(scope) {
+    if (scope?.kind === 'space')
+        return `space:${scope.spaceId}`;
+    if (scope?.kind === 'label')
+        return `label:${scope.labelIds.join('|')}`;
+    return 'general';
+}
 function nextActionOrder(actions) {
     if (actions.length === 0)
         return 0;
@@ -122,12 +259,19 @@ function renderActions(actions, log) {
         target: action.kind === 'builtin'
             ? action.builtinType
             : `${(action.prompt || '').trim().length} chars`,
+        // Where an action is offered and what it leaves behind decide whether
+        // a person ever sees it fire. A listing that omits both makes a
+        // mis-scoped action indistinguishable from a working one.
+        scope: describeAgentActionScope(action.scope),
+        outcome: action.outcome ?? 'ephemeral',
         order: String(action.order),
     })), [
         { key: 'id', header: 'ID', verbatim: true },
         { key: 'title', header: 'Title', maxWidth: 30 },
         { key: 'kind', header: 'Kind' },
         { key: 'target', header: 'Target', maxWidth: 24 },
+        { key: 'scope', header: 'Scope', maxWidth: 24 },
+        { key: 'outcome', header: 'Outcome' },
         { key: 'enabled', header: 'On' },
         { key: 'order', header: 'Order' },
     ], log);
@@ -137,6 +281,8 @@ function renderAction(action, log) {
     log(`Title:       ${action.title}`);
     log(`Kind:        ${actionKind(action)}`);
     log(`Enabled:     ${action.enabled === false ? 'no' : 'yes'}`);
+    log(`Scope:       ${describeAgentActionScope(action.scope)}`);
+    log(`Outcome:     ${action.outcome ?? 'ephemeral'}`);
     log(`Order:       ${action.order}`);
     if (action.description) {
         log(`Description: ${action.description}`);