@skrr-ai/cli 0.1.36 → 0.1.37

package/dist/commands/tasks/review-queue.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../../base-command");
+const task_closure_1 = require("../../lib/task-closure");
+const web_url_1 = require("../../lib/web-url");
+/**
+ * Everything in one Space that is waiting on a judgement, in one pass.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * An agent fans out. One session routinely produces nine Tasks carrying twenty
+ * or more Expectations, and every surface for settling them was built for one
+ * Task at a time — so the cost of CLOSING the work grew linearly with how well
+ * the work was DECOMPOSED, which punishes exactly the decomposition the product
+ * wants. Finding what was owed meant knowing that `tasks expectations` exists
+ * and running it per Task, having first worked out which Tasks to run it on.
+ *
+ * This is a read. It changes nothing, it names every outstanding judgement in
+ * the Space with the evidence already bound to it, and it prints the exact
+ * command that settles each one — so a reviewer can work down a list instead of
+ * reconstructing it.
+ */
+class TasksReviewQueue extends base_command_1.BaseCommand {
+    static description = 'Every Expectation in a Space still awaiting a judgement, with its evidence and the command that settles it';
+    static examples = [
+        '<%= config.bin %> tasks review-queue --space <space-id>',
+        '<%= config.bin %> tasks review-queue --space <space-id> --json',
+        '<%= config.bin %> tasks review-queue --space <space-id> --actionable',
+    ];
+    static flags = {
+        space: core_1.Flags.string({ description: 'Space id', required: true }),
+        actionable: core_1.Flags.boolean({
+            description: 'Only Tasks where a Result is already in — the ones a reviewer can act on',
+        }),
+        limit: core_1.Flags.integer({ description: 'Maximum Tasks to inspect (default 100)', default: 100 }),
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { flags } = await this.parse(TasksReviewQueue);
+        /**
+         * `response.data`, read from the TYPE rather than guessed.
+         *
+         * The first version of this read `response.tasks`, which does not exist —
+         * and the failure was silent in the worst possible direction: an empty array
+         * printed "Nothing is awaiting a judgement" for a Space with twenty-three
+         * unassessed Expectations. A reviewer would have believed they were done.
+         *
+         * `COMMAND_INDEX.md` warns about exactly this ("read the wrong key and you
+         * get an empty result rather than an error, which looks exactly like 'no
+         * rows matched'"). So the shape is taken from `TaskListResponse` and a
+         * missing envelope is an ERROR, never an empty queue: this command's whole
+         * value is telling someone there is nothing left, and it may only say that
+         * when it actually looked.
+         */
+        /*
+         * Follow the cursor — a truncated list is the same silent false negative
+         * as a misread envelope, one page later. This command's whole value is
+         * "there is nothing left," and a tail it never saw breaks that claim.
+         * `--limit` caps how many Tasks get inspected, not how many pages get read.
+         */
+        if (flags.limit < 1) {
+            // Inspecting zero Tasks and then saying "nothing is owed" is the exact
+            // unlooked-for empty answer this command refuses to give.
+            this.error('--limit must be at least 1.', { exit: 1 });
+        }
+        const tasks = [];
+        try {
+            let cursor;
+            for (;;) {
+                const response = await data_provider_1.dataService.listTasks({
+                    spaceId: flags.space,
+                    limit: Math.min(100, flags.limit - tasks.length),
+                    ...(cursor ? { cursor } : {}),
+                });
+                if (!response || !Array.isArray(response.data)) {
+                    this.error('The task list came back in a shape this command does not recognise, so it cannot ' +
+                        'say whether anything is owed. Refusing to report an empty queue.', { exit: 1 });
+                }
+                tasks.push(...response.data);
+                if (!response.has_more || !response.next_cursor || tasks.length >= flags.limit)
+                    break;
+                cursor = response.next_cursor;
+            }
+        }
+        catch (error) {
+            this.handleApiError(error);
+            return;
+        }
+        /**
+         * Acceptance is read per Task, and a Task whose acceptance cannot be read is
+         * REPORTED rather than dropped. A queue that silently omitted a row would be
+         * worse than no queue: the reviewer would believe they had seen everything.
+         */
+        const rows = [];
+        for (const task of tasks) {
+            const taskId = String(task.id ?? task._id ?? '');
+            if (!taskId)
+                continue;
+            const base = {
+                taskId,
+                identifier: String(task.identifier ?? taskId),
+                title: String(task.title ?? '(untitled)'),
+                status: String(task.status ?? '-'),
+                hasResult: Boolean(task.currentResultId),
+            };
+            try {
+                const acceptance = await data_provider_1.dataService.getTaskAcceptance(taskId);
+                const awaiting = acceptance.expectations.filter((e) => e.gating && !e.met);
+                if (awaiting.length > 0)
+                    rows.push({ ...base, awaiting });
+            }
+            catch (error) {
+                rows.push({ ...base, awaiting: [], error: error?.message || 'unreadable' });
+            }
+        }
+        const visible = flags.actionable ? rows.filter((row) => row.hasResult || row.error) : rows;
+        if (flags.json) {
+            this.log(JSON.stringify({ space: flags.space, tasks: visible }, null, 2));
+            return;
+        }
+        if (visible.length === 0) {
+            this.log(`Nothing in ${flags.space} is awaiting a judgement.`);
+            return;
+        }
+        let total = 0;
+        for (const row of visible) {
+            this.log('');
+            this.log(`${row.identifier}  ${row.title}`);
+            if (row.error) {
+                this.log(`  could not read its Expectations: ${row.error}`);
+                continue;
+            }
+            // A Task with no Result yet is listed but marked: its Expectations are
+            // owed, and settling them still leaves it unclosable. Saying so here stops
+            // a reviewer working through a list that cannot finish.
+            if (!row.hasResult) {
+                this.log('  no Result submitted yet — settling these will not close it');
+            }
+            for (const expectation of row.awaiting) {
+                total += 1;
+                const settledBy = expectation.assessedByKind
+                    ? ` [last judged by ${(0, task_closure_1.describeAssessor)(expectation.assessedByKind)}]`
+                    : '';
+                this.log(`  ${expectation.id}  ${expectation.sentence || expectation.text || ''}${settledBy}`);
+                if (expectation.evidenceLevel) {
+                    this.log(`      evidence: ${expectation.evidenceLevel}${expectation.requiredEvidence ? ` (asked for ${expectation.requiredEvidence})` : ''}`);
+                }
+            }
+            const url = (0, web_url_1.taskUrlFrom)(this.cliConfig.baseURL, { id: row.taskId });
+            if (url)
+                this.log(`  ${url}`);
+        }
+        this.log('');
+        this.log(`${total} Expectation(s) awaiting a judgement across ${visible.length} Task(s).`);
+        this.log('');
+        this.log('Settle one:   skrr tasks expectations assess <task-id> <expectation-id> \\');
+        this.log('                --decision met --reason "..."');
+        this.log('Settle a Task: skrr tasks expectations assess <task-id> --all \\');
+        this.log('                --decision met --reason "..."');
+    }
+}
+exports.default = TasksReviewQueue;

package/dist/commands/tasks/show.js

@@ -173,6 +173,20 @@ class TasksShow extends base_command_1.BaseCommand {
         // question and this is the answer to it.
         for (const line of taskFailureLines(t, this.config.bin))
             this.log(line);
+        /*
+         * Closing is the actor's call — a Task may be `done` with work still
+         * outstanding, and `resolution.closure` is where the server recorded what
+         * it stood on at close. Show it so a bare "done" never reads as "clean."
+         */
+        const resolution = t.resolution;
+        if (resolution?.closure && resolution.closure.closable === false) {
+            const parts = [];
+            const unmet = resolution.closure.expectations?.unmet?.length ?? 0;
+            if (unmet > 0)
+                parts.push(`${unmet} Expectation${unmet === 1 ? '' : 's'} still unmet`);
+            parts.push(...(resolution.closure.blockers || []).filter((c) => c !== 'TASK_EXPECTATIONS_NOT_MET'));
+            this.log(`Resolution:  ${resolution.kind ?? '-'} — closed over ${parts.join('; ') || 'outstanding items'}`);
+        }
         this.log(`Executor:    ${t.executionMode ?? 'legacy / inferred'}`);
         this.log(`Priority:    ${t.priority ?? '-'}`);
         this.log(`Parent:      ${t.parentId ?? '-'}`);
@@ -291,6 +305,34 @@ class TasksShow extends base_command_1.BaseCommand {
             }
         }
         const ref = String(t.id ?? t._id ?? taskIdentity.id);
+        /**
+         * Where this Task stands, on the surface people already open.
+         *
+         * `tasks expectations <id>` answers this well and is reachable only if you
+         * already know it exists — its one pointer lives in the `--expect` help of
+         * `tasks create`, which you read while AUTHORING and not while closing. So
+         * an agent that submitted a Result had no cheap way to learn the Task was
+         * still owed, and reasonably concluded from the CLI's own output that it was
+         * not. Say it here, where the question is actually asked.
+         *
+         * Read, not recomputed, and never fatal: a Task page must still render when
+         * the acceptance read fails, and it must not invent a state it could not
+         * fetch.
+         */
+        try {
+            const acceptance = await data_provider_1.dataService.getTaskAcceptance(ref);
+            const gating = acceptance.expectations.filter((e) => e.gating);
+            if (gating.length > 0) {
+                const settled = gating.filter((e) => e.met).length;
+                this.log('');
+                this.log(`Expectations: ${settled} of ${gating.length} settled  ·  overall: ${acceptance.state}` +
+                    (settled < gating.length ? `  —  skrr tasks expectations ${ref}` : ''));
+            }
+        }
+        catch {
+            // Silent: a Task this caller can VIEW but whose acceptance they cannot
+            // read is a permissions shape, not something to shout about mid-page.
+        }
         this.log('');
         this.log(`What the agent produced: skrr tasks output ${ref}`);
         if (t.conversationId) {

package/dist/commands/tasks/update.d.ts

@@ -10,6 +10,7 @@ export default class TasksUpdate extends BaseCommand {
         task: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'from-json': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         title: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        yes: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         expect: import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         description: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'description-format': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;

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,50 @@ 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.
+         */
+        if (expectationsPatch !== undefined || body.expectations !== undefined) {
+            let settledCount = 0;
+            try {
+                const acceptance = await data_provider_1.dataService.getTaskAcceptance(taskIdentity.id);
+                settledCount = acceptance.expectations.filter((e) => e.assessmentId).length;
+            }
+            catch {
+                // An unreadable acceptance is not a reason to refuse the edit. Warn
+                // without a number rather than inventing one or blocking the write.
+                settledCount = -1;
+            }
+            if (settledCount !== 0 && !flags.yes) {
+                const noun = settledCount === 1 ? 'assessment' : 'assessments';
+                const count = settledCount < 0 ? 'Any existing' : `${settledCount} existing`;
+                this.log(`Changing Expectations advances the Task specification, so ${count} ${noun} ` +
+                    'will stop counting and must be recorded again.');
+                const ok = await this.confirm('Continue? [y/N] ');
+                if (!ok) {
+                    this.log('No change made.');
+                    return;
+                }
+            }
+        }
         const payload = (0, prompt_1.mergeDefined)((0, task_resolver_1.stripTaskIdentityFields)(body), {
             title: flags.title,
             expectations: expectationsPatch === null ? [] : (expectationsPatch ?? undefined),

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

@@ -1,4 +1,4 @@
-import type { Agent, AgentAction, BuiltinActionConfig, BuiltinActionType, BuiltinAgentAction, EmbeddedActionRef, PromptAgentAction } from '@skrr-ai/data-provider';
+import type { Agent, AgentAction, AgentActionOutcome, AgentActionScope, 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"];
 export declare const ACTION_TARGET_TYPES: readonly ["group-chats", "spaces", "tasks", "goals", "slack-channels", "slack-users"];
 export type ActionTargetType = (typeof ACTION_TARGET_TYPES)[number];
@@ -7,28 +7,54 @@ 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;
 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.
+ */
+export declare function resolveAgentActionScopeFlags(flags: AgentActionScopeFlags): 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,6 +1,6 @@
 "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;
@@ -8,6 +8,8 @@ exports.findAgentAction = findAgentAction;
 exports.updateAgentActions = updateAgentActions;
 exports.makePromptAction = makePromptAction;
 exports.makeBuiltinAction = makeBuiltinAction;
+exports.resolveAgentActionScopeFlags = resolveAgentActionScopeFlags;
+exports.describeAgentActionScope = describeAgentActionScope;
 exports.nextActionOrder = nextActionOrder;
 exports.actionKind = actionKind;
 exports.renderActions = renderActions;
@@ -70,34 +72,77 @@ async function updateAgentActions(agentId, actions) {
         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.
+ */
+function resolveAgentActionScopeFlags(flags) {
+    const labelIds = (flags.label ?? []).map((value) => value.trim()).filter(Boolean);
+    const spaceId = flags.space?.trim();
+    const declared = flags.scope?.trim();
+    const kind = declared ?? (spaceId ? 'space' : labelIds.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 (!labelIds.length)
+            throw new Error('--scope label requires at least one --label <label-id>.');
+        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 +167,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 +189,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}`);

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

@@ -1,2 +1,13 @@
+export declare const COMMITMENT_RESPONSIBILITY_LEVELS: readonly ["reasoning_only", "full_ownership"];
+export declare const REASONING_TOOL_ESCAPES: readonly ["bash", "browser"];
+export declare const RELEASE_INSTALL_CHANNELS: readonly ["latest", "manual"];
+/**
+ * `09:00-18:00` or `09:00-18:00@America/Los_Angeles`, or a JSON object.
+ *
+ * The stored shape is `{start, end, timezone}` with `start`/`end` REQUIRED, so
+ * the shorthand always supplies both and never a half-open window the schema
+ * would reject at write time with a message about a subdocument.
+ */
+export declare function parseWorkingHoursFlag(value: string): Record<string, unknown>;
 /** Apply the structured agent fields exposed by the web config editor. */
 export declare function mergeAgentConfigFlags(body: Record<string, unknown>, flags: Record<string, unknown>): Record<string, unknown>;

package/dist/lib/agent-config.js

@@ -1,7 +1,35 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.RELEASE_INSTALL_CHANNELS = exports.REASONING_TOOL_ESCAPES = exports.COMMITMENT_RESPONSIBILITY_LEVELS = void 0;
+exports.parseWorkingHoursFlag = parseWorkingHoursFlag;
 exports.mergeAgentConfigFlags = mergeAgentConfigFlags;
 const prompt_1 = require("./prompt");
+const agent_visual_refs_1 = require("./agent-visual-refs");
+exports.COMMITMENT_RESPONSIBILITY_LEVELS = ['reasoning_only', 'full_ownership'];
+exports.REASONING_TOOL_ESCAPES = ['bash', 'browser'];
+exports.RELEASE_INSTALL_CHANNELS = ['latest', 'manual'];
+/**
+ * `09:00-18:00` or `09:00-18:00@America/Los_Angeles`, or a JSON object.
+ *
+ * The stored shape is `{start, end, timezone}` with `start`/`end` REQUIRED, so
+ * the shorthand always supplies both and never a half-open window the schema
+ * would reject at write time with a message about a subdocument.
+ */
+function parseWorkingHoursFlag(value) {
+    const trimmed = value.trim();
+    if (trimmed.startsWith('{'))
+        return JSON.parse(trimmed);
+    const [window, timezone] = trimmed.split('@');
+    const match = /^([0-2]\d:[0-5]\d)-([0-2]\d:[0-5]\d)$/.exec(window ?? '');
+    if (!match) {
+        throw new Error(`--todo-working-hours: cannot read "${value}". ` +
+            'Write HH:MM-HH:MM, optionally @<IANA timezone> — for example ' +
+            '09:00-18:00@America/Los_Angeles. A JSON object is also accepted.');
+    }
+    return timezone
+        ? { start: match[1], end: match[2], timezone }
+        : { start: match[1], end: match[2] };
+}
 /** Apply the structured agent fields exposed by the web config editor. */
 function mergeAgentConfigFlags(body, flags) {
     const json = {
@@ -22,10 +50,21 @@ function mergeAgentConfigFlags(body, flags) {
         if (value !== undefined)
             parsed[field] = JSON.parse(String(value));
     }
+    /**
+     * `avatar` and `sceneBackground` are DISCRIMINATED UNIONS server-side, not
+     * strings — see `agent-visual-refs.ts`. `--scene-background` used to sit in
+     * the pass-through map below, which made it a flag with no value that could
+     * pass validation. Both go through the shared parser.
+     */
+    if (flags['scene-background'] !== undefined) {
+        parsed.sceneBackground = (0, agent_visual_refs_1.parseSceneBackgroundFlag)(String(flags['scene-background']));
+    }
+    if (flags.avatar !== undefined) {
+        parsed.avatar = (0, agent_visual_refs_1.parseAvatarRefFlag)(String(flags.avatar));
+    }
     const direct = {
         'network-mode': 'network_mode',
         'character-3d-id': 'character3DId',
-        'scene-background': 'sceneBackground',
         'tone-mode': 'toneMode',
         'tone-id': 'toneId',
         'tone-notes': 'toneNotes',
@@ -46,8 +85,51 @@ function mergeAgentConfigFlags(body, flags) {
         if (flags[flag] !== undefined)
             parsed[field] = flags[flag];
     }
-    if (flags['recursion-limit'] !== undefined)
-        parsed.recursion_limit = flags['recursion-limit'];
+    const integers = {
+        'recursion-limit': 'recursion_limit',
+        'max-turns': 'maxTurns',
+    };
+    for (const [flag, field] of Object.entries(integers)) {
+        if (flags[flag] !== undefined)
+            parsed[field] = flags[flag];
+    }
+    /* Fields the web config editor has always written and no flag reached. */
+    if (flags['conversation-starter'] !== undefined) {
+        parsed.conversation_starters = flags['conversation-starter'];
+    }
+    if (flags['todo-working-hours'] !== undefined) {
+        parsed.todoWorkingHours = parseWorkingHoursFlag(String(flags['todo-working-hours']));
+    }
+    if (flags['reasoning-tool-escape'] !== undefined) {
+        parsed.reasoningToolEscapes = flags['reasoning-tool-escape'];
+    }
+    if (flags['commitment-responsibility'] !== undefined) {
+        parsed.commitmentResponsibilityDefault = flags['commitment-responsibility'];
+    }
+    if (flags['commitment-responsibility-ceiling'] !== undefined) {
+        parsed.commitmentResponsibilityCeiling = flags['commitment-responsibility-ceiling'];
+    }
+    if (flags['tool-resources'] !== undefined) {
+        parsed.tool_resources = JSON.parse(String(flags['tool-resources']));
+    }
+    if (flags['project-id'] !== undefined)
+        parsed.projectIds = flags['project-id'];
+    if (flags['remove-project-id'] !== undefined) {
+        parsed.removeProjectIds = flags['remove-project-id'];
+    }
+    // Two flags, one stored object. Sent whole so a caller who sets only the
+    // channel does not silently clear `allowAutoMinorUpdates` — the server
+    // replaces the subdocument rather than merging into it.
+    if (flags['install-channel'] !== undefined || flags['auto-minor-updates'] !== undefined) {
+        const releasePolicy = {};
+        if (flags['install-channel'] !== undefined) {
+            releasePolicy.defaultInstallChannel = flags['install-channel'];
+        }
+        if (flags['auto-minor-updates'] !== undefined) {
+            releasePolicy.allowAutoMinorUpdates = flags['auto-minor-updates'];
+        }
+        parsed.releasePolicy = releasePolicy;
+    }
     // Cross-Space Task execution ceiling. `0` means unlimited, matching the
     // Space limits' convention so a user learns one spelling of "no cap".
     if (flags['max-concurrent-task-executions'] !== undefined) {

package/dist/lib/agent-pin-mute.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `pin` / `unpin` / `mute` / `unmute` on top of a TOGGLE endpoint.
+ *
+ * `PATCH /api/user/agent-preferences/:agentId/pin` flips the bit; it does not
+ * take a desired state. A CLI that exposed the flip directly would make
+ * `skrr agents pin X` mean "pin it, unless it already was, in which case unpin
+ * it" — fine for a button a human clicks while looking at the result, wrong for
+ * a command in a script, where the outcome would depend on state the script
+ * never read.
+ *
+ * So the desired state is read first and the toggle is sent only when it
+ * differs. That makes each command idempotent and its name true. The read is not
+ * a lock: two concurrent invocations can still race, which is a real limit of a
+ * toggle endpoint and not something the CLI can fix from out here — the
+ * returned state is always what the server says, never what was asked for.
+ */
+export type AgentFlag = 'pin' | 'mute';
+export interface FlagChange {
+    /** The value the server reports AFTER this call. */
+    value: boolean;
+    /** False when the flag already held the desired value and nothing was sent. */
+    changed: boolean;
+}
+export declare function setAgentFlag(agentId: string, flag: AgentFlag, desired: boolean): Promise<FlagChange>;

package/dist/lib/agent-pin-mute.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setAgentFlag = setAgentFlag;
+const data_provider_1 = require("@skrr-ai/data-provider");
+async function setAgentFlag(agentId, flag, desired) {
+    const current = await data_provider_1.dataService.getAgentPreferences(agentId);
+    const held = flag === 'pin' ? current.preferences?.isPinned : current.preferences?.isMuted;
+    if (Boolean(held) === desired) {
+        return { value: desired, changed: false };
+    }
+    if (flag === 'pin') {
+        const result = await data_provider_1.dataService.toggleAgentPin(agentId);
+        return { value: result.isPinned, changed: true };
+    }
+    const result = await data_provider_1.dataService.toggleAgentMute(agentId);
+    return { value: result.isMuted, changed: true };
+}