@skrr-ai/cli 0.1.36 → 0.1.37

package/dist/lib/agent-visual-refs.d.ts

@@ -0,0 +1,6 @@
+import type { AgentAvatarRef, AgentSceneBackground } from '@skrr-ai/data-provider';
+/** Preset ids this build ships, for an error message that can be acted on. */
+export declare function avatarPresetIds(): string[];
+export declare function sceneBackgroundPresetIds(): string[];
+export declare function parseAvatarRefFlag(value: string): AgentAvatarRef;
+export declare function parseSceneBackgroundFlag(value: string): AgentSceneBackground;

package/dist/lib/agent-visual-refs.js

@@ -0,0 +1,142 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.avatarPresetIds = avatarPresetIds;
+exports.sceneBackgroundPresetIds = sceneBackgroundPresetIds;
+exports.parseAvatarRefFlag = parseAvatarRefFlag;
+exports.parseSceneBackgroundFlag = parseSceneBackgroundFlag;
+/**
+ * The two "how does this agent look" fields, parsed from a flag.
+ *
+ * WHY A PARSER AND NOT A PLAIN STRING
+ * ───────────────────────────────────
+ * `agent.avatar` and `agent.sceneBackground` are DISCRIMINATED UNIONS on the
+ * wire (`packages/api/src/agents/validation.ts`), because a face and a backdrop
+ * each have several possible origins — a built-in preset, the caller's own
+ * uploaded asset, an explicit "the platform default", a raw storage path — and
+ * a bare string cannot say which. `agentUpdateSchema.parse(req.body)` runs with
+ * no coercion, so a string reaches the server and is rejected.
+ *
+ * `--scene-background` shipped as a pass-through string for exactly that
+ * reason, which made it a flag with NO value that could ever succeed: every
+ * invocation was a 400 naming a zod path rather than the flag. The fix is to
+ * own the shorthand here, once, so both fields read the same way and neither
+ * can regress into a raw string again.
+ *
+ * THE SHORTHAND
+ * ─────────────
+ *   default                       → { type: 'default' }
+ *   preset:<id>                   → { type: 'preset', id }
+ *   asset:<id>                    → { type: 'asset', id }        (avatar only)
+ *   image:<filepath>@<source>     → { type: 'image', filepath, source }
+ *   {"type":"preset","id":"..."}  → parsed verbatim, the escape hatch
+ *
+ * A bare id is deliberately NOT accepted. `preset:studio` and an asset id are
+ * different namespaces, and guessing between them would make the failure mode
+ * "your avatar silently became someone else's" rather than a parse error.
+ */
+const data_provider_1 = require("@skrr-ai/data-provider");
+/** `image:path/to.png@s3` — the `@` is the LAST one, so a path may contain `@`. */
+function parseImage(rest, flag) {
+    const at = rest.lastIndexOf('@');
+    if (at <= 0 || at === rest.length - 1) {
+        throw new Error(`${flag}: "image:" needs a storage source — write image:<filepath>@<source>, ` +
+            'for example image:images/123/face.png@s3.');
+    }
+    return { filepath: rest.slice(0, at), source: rest.slice(at + 1) };
+}
+/**
+ * A JSON object escape hatch, so a shape this grammar has not learned yet is
+ * still expressible without falling back to `--from-json` for the whole agent.
+ * Returns `undefined` when the value is not JSON at all, so the caller can go on
+ * to the shorthand rather than reporting a JSON syntax error for `preset:foo`.
+ */
+function parseJsonObject(value) {
+    const trimmed = value.trim();
+    if (!trimmed.startsWith('{'))
+        return undefined;
+    try {
+        const parsed = JSON.parse(trimmed);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Preset ids this build ships, for an error message that can be acted on. */
+function avatarPresetIds() {
+    return data_provider_1.AGENT_AVATAR_PRESETS.map((preset) => preset.id);
+}
+function sceneBackgroundPresetIds() {
+    return data_provider_1.AGENT_SCENE_BACKGROUND_PRESETS.map((preset) => preset.id);
+}
+/**
+ * Name a handful of valid ids rather than all of them.
+ *
+ * There are ~60 avatar presets. An error that prints every one buries the
+ * sentence that says what went wrong, so show a few and point at the command
+ * that lists the rest.
+ */
+function someOf(ids, limit = 6) {
+    const head = ids.slice(0, limit).join(', ');
+    return ids.length > limit ? `${head}, … (${ids.length} total)` : head;
+}
+function parseAvatarRefFlag(value) {
+    const json = parseJsonObject(value);
+    if (json)
+        return json;
+    const raw = value.trim();
+    if (raw === 'default')
+        return { type: 'default' };
+    const colon = raw.indexOf(':');
+    const kind = colon === -1 ? raw : raw.slice(0, colon);
+    const rest = colon === -1 ? '' : raw.slice(colon + 1);
+    if (kind === 'preset') {
+        if (!(0, data_provider_1.isAgentAvatarPresetId)(rest)) {
+            throw new Error(`--avatar: "${rest}" is not an avatar preset in this build. ` +
+                `Try one of: ${someOf(avatarPresetIds())}. ` +
+                'Run `skrr agents avatar presets` for the full catalog.');
+        }
+        return { type: 'preset', id: rest };
+    }
+    if (kind === 'asset') {
+        if (!rest) {
+            throw new Error('--avatar: "asset:" needs an id from your library — ' +
+                'run `skrr agents avatar library` to list them.');
+        }
+        return { type: 'asset', id: rest };
+    }
+    if (kind === 'image')
+        return { type: 'image', ...parseImage(rest, '--avatar') };
+    throw new Error(`--avatar: cannot read "${value}". Accepted: default, preset:<id>, asset:<id>, ` +
+        'image:<filepath>@<source>, or a JSON object. ' +
+        'To upload a new image file instead, use `skrr agents avatar upload --file <path>`.');
+}
+function parseSceneBackgroundFlag(value) {
+    const json = parseJsonObject(value);
+    if (json)
+        return json;
+    const raw = value.trim();
+    if (raw === 'default')
+        return { type: 'default' };
+    const colon = raw.indexOf(':');
+    const kind = colon === -1 ? raw : raw.slice(0, colon);
+    const rest = colon === -1 ? '' : raw.slice(colon + 1);
+    if (kind === 'preset') {
+        if (!(0, data_provider_1.isAgentSceneBackgroundPresetId)(rest)) {
+            throw new Error(`--scene-background: "${rest}" is not a backdrop preset in this build. ` +
+                `Valid ids: ${sceneBackgroundPresetIds().join(', ')}.`);
+        }
+        return { type: 'preset', id: rest };
+    }
+    if (kind === 'image')
+        return { type: 'image', ...parseImage(rest, '--scene-background') };
+    // A bare preset id is the single most likely mistake here, because the
+    // backdrop catalog is short enough to remember. Say so instead of listing the
+    // grammar twice.
+    if ((0, data_provider_1.isAgentSceneBackgroundPresetId)(raw)) {
+        throw new Error(`--scene-background: "${raw}" is a preset id — write preset:${raw}. ` +
+            'A bare id is refused because preset and image live in different namespaces.');
+    }
+    throw new Error(`--scene-background: cannot read "${value}". Accepted: default, preset:<id>, ` +
+        `image:<filepath>@<source>, or a JSON object. Presets: ${sceneBackgroundPresetIds().join(', ')}.`);
+}

package/dist/lib/first-party-harness-agent.js

@@ -419,6 +419,13 @@ async function currentUserId(signal) {
  * function only after the flag, the config key, and the sole-owned-agent branch
  * have all declined, which is why the extra round trip is acceptable.
  */
+/**
+ * Deliberately NOT `dataService.ensureDefaultAgent`, which `agents
+ * ensure-default` uses for the same endpoint. This path takes an `AbortSignal`
+ * and the caller below distinguishes an abort from a refusal — reporting "no
+ * default agent" for a caller whose deadline expired sends someone to fix the
+ * wrong thing. The shared helper cannot carry a signal, so this one stays.
+ */
 async function ensureDefaultAgent(harness, signal) {
     const response = await (0, api_fetch_1.apiFetch)('/api/agents/default', {
         method: 'POST',

package/dist/lib/followups.d.ts

@@ -0,0 +1,107 @@
+import { withQuery } from './triggers';
+type Query = Parameters<typeof withQuery>[1];
+type Json = Record<string, unknown>;
+export declare const FOLLOWUP_KINDS: readonly ["reminder", "watch", "checkin", "act"];
+export type FollowUpKind = (typeof FOLLOWUP_KINDS)[number];
+export declare const FOLLOWUP_STATES: readonly ["armed", "proposed", "settled", "paused"];
+/** Terminals a caller may name on `resolve` — the rest are the runtime's. */
+export declare const FOLLOWUP_RESOLVE_OUTCOMES: readonly ["resolved", "abandoned"];
+export declare const WATCH_WAIT_KINDS: readonly ["clock", "event", "poll_until"];
+export interface FollowUpRow {
+    id: string;
+    kind?: string;
+    form?: string | null;
+    producer?: string;
+    why?: string;
+    intentKey?: string;
+    subject?: {
+        type?: string;
+        externalKey?: string;
+        label?: string;
+        url?: string;
+    } | null;
+    agentId?: string | null;
+    state?: string;
+    terminal?: string | null;
+    terminalAt?: string | null;
+    terminalReason?: string | null;
+    escalatedInitiativeId?: string | null;
+    capsule?: unknown;
+    nextRunAt?: string | null;
+    deadlineAt?: string | null;
+    createdAt?: string;
+    label?: string;
+}
+export interface FollowUpCreateResponse {
+    followup: FollowUpRow | null;
+    reused?: boolean;
+    dropped?: false | 'budget';
+    proposal?: boolean;
+    budget?: Json;
+    fallbackTriggerId?: string | null;
+}
+export interface FollowUpObservability {
+    generatedAt?: string;
+    agents?: Array<{
+        agentId: string;
+        kinds: Array<{
+            kind: string;
+            created: number;
+            armed: number;
+            proposed: number;
+            settled: number;
+            terminal: Record<string, number>;
+            escalationRate: number | null;
+            fires: number;
+            budget: {
+                pool: string | null;
+                used: number;
+                limit: number | null;
+            } | null;
+            silenceRate: number | null;
+            silentFires: number | null;
+        }>;
+    }>;
+}
+export type ResolvedFollowUpAgent = {
+    id: string;
+    /**
+     * True when the identity came from the session binding rather than a flag —
+     * a follow-up declared inside an agent's own turn is `agent_in_turn`; one
+     * declared by a human at a shell is `user_explicit`. The producer field is
+     * provenance, not authority, and this is the only honest signal a CLI has.
+     */
+    boundToSession: boolean;
+};
+/**
+ * Which agent a follow-up belongs to.
+ *
+ * Deliberately NOT `resolveAgentIdentity`: that resolver's last step picks
+ * "the only visible agent", and a follow-up bound to the wrong agent wakes
+ * the wrong agent in the wrong main chat. The only honest sources are an
+ * explicit `--agent` and the session binding the runtime already proves
+ * (`OVERSKY_SESSION_AGENT_ID`, or the legacy `OVERSKY_AGENT_ID` a manual
+ * local runtime sets). Anything else throws AGENT_CONTEXT_AMBIGUOUS and
+ * names the fix rather than guessing.
+ */
+export declare function resolveFollowUpAgent(explicitAgentId?: string, env?: Record<string, string | undefined>): ResolvedFollowUpAgent;
+/** A `type:externalKey` subject ref → the subject block the API wants. */
+export declare function parseSubjectRef(ref: string): {
+    type: string;
+    externalKey: string;
+};
+export declare const followupsApi: {
+    create: (body: Json) => Promise<FollowUpCreateResponse>;
+    list: (query?: Query) => Promise<{
+        followups: FollowUpRow[];
+    }>;
+    observability: (query?: Query) => Promise<FollowUpObservability>;
+    show: (id: string) => Promise<{
+        followup: FollowUpRow;
+    }>;
+    resolve: (id: string, body: Json) => Promise<Json>;
+    cancel: (id: string, body?: Json) => Promise<Json>;
+    reschedule: (id: string, body: Json) => Promise<Json>;
+};
+export declare function followupSummaryLine(row: FollowUpRow): string;
+export {};

package/dist/lib/followups.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.followupsApi = exports.WATCH_WAIT_KINDS = exports.FOLLOWUP_RESOLVE_OUTCOMES = exports.FOLLOWUP_STATES = exports.FOLLOWUP_KINDS = void 0;
+exports.resolveFollowUpAgent = resolveFollowUpAgent;
+exports.parseSubjectRef = parseSubjectRef;
+exports.followupSummaryLine = followupSummaryLine;
+/**
+ * followups.ts — the `skrr followups` domain lib.
+ *
+ * A follow-up is ONE resource with four kinds (`reminder`, `watch`, `checkin`,
+ * `act`), declared by intent and derived into mechanism entirely server-side
+ * (`FollowUps/` + `docs/architecture/followup-service-2026-09-15.md`). The CLI
+ * is the universal substrate — a daemon-run local harness reaches the platform
+ * only through `skrr` — so every verb the API exposes lives here, and commands
+ * own flags only. The `followup_*` MCP tools wrap the same surface.
+ *
+ * What this file deliberately does NOT contain: executor modes, trigger kinds,
+ * destination logic, or budget policy. A caller names `kind` + `subject` +
+ * `why` and the server derives the rest; a second derivation here would be
+ * exactly the drift the service exists to kill.
+ */
+const data_provider_1 = require("@skrr-ai/data-provider");
+const runtime_context_1 = require("./runtime-context");
+const triggers_1 = require("./triggers");
+const agent_resolver_1 = require("./agent-resolver");
+const MOUNT = '/api/followups';
+const base = (id) => `${MOUNT}/${encodeURIComponent(id)}`;
+/* ------------------------------------------------------------------ *
+ * Vocabulary (client-side validation only — the server is the authority) *
+ * ------------------------------------------------------------------ */
+exports.FOLLOWUP_KINDS = ['reminder', 'watch', 'checkin', 'act'];
+exports.FOLLOWUP_STATES = ['armed', 'proposed', 'settled', 'paused'];
+/** Terminals a caller may name on `resolve` — the rest are the runtime's. */
+exports.FOLLOWUP_RESOLVE_OUTCOMES = ['resolved', 'abandoned'];
+exports.WATCH_WAIT_KINDS = ['clock', 'event', 'poll_until'];
+/**
+ * Which agent a follow-up belongs to.
+ *
+ * Deliberately NOT `resolveAgentIdentity`: that resolver's last step picks
+ * "the only visible agent", and a follow-up bound to the wrong agent wakes
+ * the wrong agent in the wrong main chat. The only honest sources are an
+ * explicit `--agent` and the session binding the runtime already proves
+ * (`OVERSKY_SESSION_AGENT_ID`, or the legacy `OVERSKY_AGENT_ID` a manual
+ * local runtime sets). Anything else throws AGENT_CONTEXT_AMBIGUOUS and
+ * names the fix rather than guessing.
+ */
+function resolveFollowUpAgent(explicitAgentId, env = process.env) {
+    const runtime = (0, runtime_context_1.readRuntimeContext)(env);
+    const sessionAgent = runtime.agent?.source === 'OVERSKY_SESSION_AGENT_ID' ||
+        runtime.agent?.source === 'OVERSKY_AGENT_ID'
+        ? runtime.agent
+        : undefined;
+    if (sessionAgent) {
+        if (explicitAgentId && explicitAgentId !== sessionAgent.id) {
+            throw new agent_resolver_1.AgentResolutionError({
+                code: 'AGENT_CONTEXT_CONFLICT',
+                message: 'This local runtime is bound to a session agent. Do not override it with another agent ID.',
+                suggestion: 'Use the bound session agent, or start a new daemon session for a different agent.',
+                details: { explicitAgentId, sessionAgentId: sessionAgent.id, source: sessionAgent.source },
+            });
+        }
+        return { id: sessionAgent.id, boundToSession: true };
+    }
+    if (explicitAgentId)
+        return { id: explicitAgentId, boundToSession: false };
+    throw new agent_resolver_1.AgentResolutionError({
+        code: 'AGENT_CONTEXT_AMBIGUOUS',
+        message: 'No agent context: a follow-up needs an explicit agent and this session supplies none.',
+        suggestion: 'Pass `--agent <agent-id>`, run inside a daemon session that sets OVERSKY_SESSION_AGENT_ID, or use `--all-agents` where listing is the intent.',
+        details: { runtimeKind: runtime.kind },
+    });
+}
+/** A `type:externalKey` subject ref → the subject block the API wants. */
+function parseSubjectRef(ref) {
+    const idx = ref.indexOf(':');
+    if (idx <= 0 || idx === ref.length - 1) {
+        throw new Error(`--subject must be "type:externalKey" (e.g. task:OSK-42, conversation:conv_123), got "${ref}"`);
+    }
+    return { type: ref.slice(0, idx), externalKey: ref.slice(idx + 1) };
+}
+/* ------------------------------------------------------------------ *
+ * API                                                                  *
+ * ------------------------------------------------------------------ */
+exports.followupsApi = {
+    create: (body) => data_provider_1.request.post(MOUNT, body),
+    list: (query = {}) => data_provider_1.request.get((0, triggers_1.withQuery)(MOUNT, query)),
+    observability: (query = {}) => data_provider_1.request.get((0, triggers_1.withQuery)(`${MOUNT}/observability`, query)),
+    show: (id) => data_provider_1.request.get(base(id)),
+    resolve: (id, body) => data_provider_1.request.post(`${base(id)}/resolve`, body),
+    cancel: (id, body = {}) => data_provider_1.request.post(`${base(id)}/cancel`, body),
+    reschedule: (id, body) => data_provider_1.request.post(`${base(id)}/reschedule`, body),
+};
+/* ------------------------------------------------------------------ *
+ * Rendering                                                            *
+ * ------------------------------------------------------------------ */
+const fmtWhen = (iso) => (iso ? iso.slice(0, 16).replace('T', ' ') + 'Z' : '—');
+function followupSummaryLine(row) {
+    const subject = row.subject ? `${row.subject.type}:${row.subject.externalKey}` : '—';
+    const kindForm = row.form ? `${row.kind}/${row.form}` : (row.kind ?? '—');
+    const when = row.state === 'settled' ? `settled:${row.terminal ?? '?'}` : `next:${fmtWhen(row.nextRunAt)}`;
+    return `${row.id}  [${row.state ?? '?'}] ${kindForm}  ${subject}  ${when}`;
+}

package/dist/lib/label-ref.d.ts

@@ -0,0 +1,95 @@
+/**
+ * label-ref.ts — let a human type `--label dogfood` instead of a uuid.
+ *
+ * WHY
+ * ---
+ * Labels are addressed by id everywhere: `spaces labels add <space> --label
+ * <uuid>`. That is correct for the wire and hostile at a keyboard, and the cost
+ * was measurable — the fleet reached nine labels, every one of them
+ * `applicableTo: ['task']`, and not one space-applicable label had ever been
+ * created. Applying one meant `labels list`, eyeball the uuid, paste it. Three
+ * steps to do the thing the flag already existed for.
+ *
+ * THE RULE, AND WHY IT IS NOT "CREATE IT IF MISSING"
+ * -------------------------------------------------
+ * An unknown name is REFUSED, with the closest matches named. It is never
+ * created.
+ *
+ * Auto-create is the obvious convenience and it is the one thing that destroys
+ * the vocabulary: `--label dogfod` would mint a second label nobody meant, and
+ * a label is worth exactly as much as the completeness of a filter on it. The
+ * server draws the same line for every agent-supplied key — the operator
+ * declares the vocabulary, the caller chooses from it (`WakeIntentResolver`,
+ * the `agent_run` watched source, and `Labels/labelGuidance.js`). This is that
+ * rule at the keyboard instead of at the model.
+ *
+ * Refusing is also what makes the typo cheap: the caller sees
+ * `did you mean: dogfood?` and retries, instead of discovering six weeks later
+ * that half the program is under a name nobody can spell twice.
+ *
+ * An id passes through UNTOUCHED and costs no round trip — scripts and agents
+ * that already hold ids keep working exactly as before, and nothing here is on
+ * their path.
+ */
+import { dataService } from '@skrr-ai/data-provider';
+import type { LabelApplicable } from './label-scope';
+export declare function looksLikeLabelId(ref: string): boolean;
+/**
+ * A label row as the API returns it. Narrow on purpose at the fields this
+ * module reasons about; everything else rides along untouched so callers that
+ * RENDER labels (`labels list`) can use the same merge.
+ */
+export interface LabelRow {
+    id: string;
+    name: string;
+    scope?: string;
+    scopeId?: string;
+    color?: string;
+    applicableTo?: string[];
+    usageCount?: number;
+    archivedAt?: string | null;
+    [key: string]: unknown;
+}
+/**
+ * Names close enough to be worth printing. A suggestion list that includes
+ * everything is the same as no suggestion list — the caller still has to read
+ * all of it — so the threshold scales with the typed length and caps at three.
+ */
+export declare function closestNames(typed: string, names: string[], limit?: number): string[];
+export interface LabelVocabularyContext {
+    /** Narrow to labels attachable to this entity type. Omit for all of them. */
+    applicableTo?: LabelApplicable;
+    /** Narrows to the workspace scope; `--workspace` / OVERSKY_WORKSPACE_ID. */
+    workspaceId?: string;
+    /** Archived labels are excluded unless asked for. */
+    includeArchived?: boolean;
+    /** Injected in tests. */
+    getLabels?: typeof dataService.getLabels;
+}
+export interface LabelRefContext extends LabelVocabularyContext {
+    /** Which entity the resolved labels will be attached to. */
+    applicableTo: LabelApplicable;
+}
+/**
+ * Every scope this caller could legitimately attach from, merged.
+ *
+ * `GET /api/labels` takes ONE scope, and a label the caller may attach can live
+ * in either of two. Asking for one and calling it "the vocabulary" would refuse
+ * a name that exists — which is the failure mode that makes people stop using
+ * names at all. A scope that cannot be read contributes nothing and throws
+ * nothing: this runs to produce a better error message, and must never become
+ * the error.
+ */
+export declare function collectLabelVocabulary(context: LabelVocabularyContext): Promise<LabelRow[]>;
+export declare class LabelRefError extends Error {
+}
+/**
+ * Resolve `--label` / `--label-id` values, each either an id or a name.
+ *
+ * Throws `LabelRefError` with an actionable message when a name does not
+ * resolve, or resolves to more than one label. Ambiguity is a refusal rather
+ * than a pick: the same name may legitimately exist in a user scope and a
+ * workspace scope, and guessing which one the caller meant is how the wrong
+ * label ends up attached to a year of work.
+ */
+export declare function resolveLabelRefs(refs: string[] | undefined, context: LabelRefContext): Promise<string[]>;

package/dist/lib/label-ref.js

@@ -0,0 +1,163 @@
+"use strict";
+/**
+ * label-ref.ts — let a human type `--label dogfood` instead of a uuid.
+ *
+ * WHY
+ * ---
+ * Labels are addressed by id everywhere: `spaces labels add <space> --label
+ * <uuid>`. That is correct for the wire and hostile at a keyboard, and the cost
+ * was measurable — the fleet reached nine labels, every one of them
+ * `applicableTo: ['task']`, and not one space-applicable label had ever been
+ * created. Applying one meant `labels list`, eyeball the uuid, paste it. Three
+ * steps to do the thing the flag already existed for.
+ *
+ * THE RULE, AND WHY IT IS NOT "CREATE IT IF MISSING"
+ * -------------------------------------------------
+ * An unknown name is REFUSED, with the closest matches named. It is never
+ * created.
+ *
+ * Auto-create is the obvious convenience and it is the one thing that destroys
+ * the vocabulary: `--label dogfod` would mint a second label nobody meant, and
+ * a label is worth exactly as much as the completeness of a filter on it. The
+ * server draws the same line for every agent-supplied key — the operator
+ * declares the vocabulary, the caller chooses from it (`WakeIntentResolver`,
+ * the `agent_run` watched source, and `Labels/labelGuidance.js`). This is that
+ * rule at the keyboard instead of at the model.
+ *
+ * Refusing is also what makes the typo cheap: the caller sees
+ * `did you mean: dogfood?` and retries, instead of discovering six weeks later
+ * that half the program is under a name nobody can spell twice.
+ *
+ * An id passes through UNTOUCHED and costs no round trip — scripts and agents
+ * that already hold ids keep working exactly as before, and nothing here is on
+ * their path.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LabelRefError = void 0;
+exports.looksLikeLabelId = looksLikeLabelId;
+exports.closestNames = closestNames;
+exports.collectLabelVocabulary = collectLabelVocabulary;
+exports.resolveLabelRefs = resolveLabelRefs;
+const data_provider_1 = require("@skrr-ai/data-provider");
+/** A canonical v4 uuid, which is what every label id is. */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function looksLikeLabelId(ref) {
+    return UUID_RE.test(ref.trim());
+}
+/** Levenshtein, iterative, two rows. Only ever runs on a refusal path. */
+function distance(a, b) {
+    if (a === b)
+        return 0;
+    if (!a.length)
+        return b.length;
+    if (!b.length)
+        return a.length;
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i += 1) {
+        const row = [i];
+        for (let j = 1; j <= b.length; j += 1) {
+            row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev = row;
+    }
+    return prev[b.length];
+}
+/**
+ * Names close enough to be worth printing. A suggestion list that includes
+ * everything is the same as no suggestion list — the caller still has to read
+ * all of it — so the threshold scales with the typed length and caps at three.
+ */
+function closestNames(typed, names, limit = 3) {
+    const needle = typed.trim().toLowerCase();
+    const budget = Math.max(2, Math.ceil(needle.length / 3));
+    return names
+        .map((name) => ({ name, d: distance(needle, name.toLowerCase()) }))
+        .filter((row) => row.d <= budget || row.name.toLowerCase().includes(needle))
+        .sort((a, b) => a.d - b.d)
+        .slice(0, limit)
+        .map((row) => row.name);
+}
+/**
+ * Every scope this caller could legitimately attach from, merged.
+ *
+ * `GET /api/labels` takes ONE scope, and a label the caller may attach can live
+ * in either of two. Asking for one and calling it "the vocabulary" would refuse
+ * a name that exists — which is the failure mode that makes people stop using
+ * names at all. A scope that cannot be read contributes nothing and throws
+ * nothing: this runs to produce a better error message, and must never become
+ * the error.
+ */
+async function collectLabelVocabulary(context) {
+    const getLabels = context.getLabels ?? data_provider_1.dataService.getLabels;
+    const requests = [{ scope: 'user' }];
+    if (context.workspaceId)
+        requests.push({ scope: 'workspace', scopeId: context.workspaceId });
+    const settled = await Promise.allSettled(requests.map((request) => getLabels({
+        ...request,
+        ...(context.applicableTo ? { applicableTo: context.applicableTo } : {}),
+        ...(context.includeArchived ? { includeArchived: true } : {}),
+    })));
+    const byId = new Map();
+    for (const outcome of settled) {
+        if (outcome.status !== 'fulfilled')
+            continue;
+        for (const row of outcome.value?.data ?? []) {
+            if (row?.id && !byId.has(row.id))
+                byId.set(row.id, row);
+        }
+    }
+    return [...byId.values()];
+}
+class LabelRefError extends Error {
+}
+exports.LabelRefError = LabelRefError;
+/**
+ * Resolve `--label` / `--label-id` values, each either an id or a name.
+ *
+ * Throws `LabelRefError` with an actionable message when a name does not
+ * resolve, or resolves to more than one label. Ambiguity is a refusal rather
+ * than a pick: the same name may legitimately exist in a user scope and a
+ * workspace scope, and guessing which one the caller meant is how the wrong
+ * label ends up attached to a year of work.
+ */
+async function resolveLabelRefs(refs, context) {
+    const input = (refs ?? []).map((ref) => ref.trim()).filter(Boolean);
+    if (input.length === 0)
+        return [];
+    // Ids are the wire form and the common case for scripts. Resolve nothing,
+    // fetch nothing, and let the server be the authority on whether they exist.
+    if (input.every(looksLikeLabelId))
+        return input;
+    const vocabulary = await collectLabelVocabulary(context);
+    const resolved = [];
+    for (const ref of input) {
+        if (looksLikeLabelId(ref)) {
+            resolved.push(ref);
+            continue;
+        }
+        const needle = ref.toLowerCase();
+        const matches = vocabulary.filter((row) => (row.name ?? '').toLowerCase() === needle);
+        if (matches.length === 1) {
+            resolved.push(matches[0].id);
+            continue;
+        }
+        if (matches.length > 1) {
+            const listed = matches
+                .map((row) => `  ${row.id}  ${row.name}${row.scope ? ` (${row.scope})` : ''}`)
+                .join('\n');
+            throw new LabelRefError(`"${ref}" names ${matches.length} labels. Pass the id you mean:\n${listed}`);
+        }
+        if (vocabulary.length === 0) {
+            throw new LabelRefError(`No label named "${ref}" — and no label applies to ${context.applicableTo}s yet. ` +
+                `Create one with \`labels create --name ${ref} --applicable-to ${context.applicableTo}\`.`);
+        }
+        const near = closestNames(ref, vocabulary.map((row) => row.name));
+        throw new LabelRefError(`No label named "${ref}" applies to ${context.applicableTo}s.` +
+            (near.length ? ` Did you mean: ${near.join(', ')}?` : '') +
+            ` Run \`labels list\` for the vocabulary, or create it deliberately with ` +
+            `\`labels create --name ${ref} --applicable-to ${context.applicableTo}\` — ` +
+            'a name is never created implicitly, because a second spelling of a label ' +
+            'is worse than no label.');
+    }
+    return resolved;
+}

package/dist/lib/label-scope.d.ts

@@ -1,7 +1,7 @@
 /**
  * Shared plumbing for the unified label commands (`skrr labels …`).
  *
- * Labels are anchored to exactly one scope — a user, a space, or a workspace —
+ * Labels are anchored to exactly one scope — a user or a workspace —
  * via the `(scope, scopeId)` pair. That pair is simultaneously the uniqueness
  * key and the permission boundary server-side (see
  * `api/server/services/Labels/LabelService.js`), so every label command has to
@@ -9,7 +9,7 @@
  * always explicit; `user` is the default because that is the only scope whose
  * id the server can infer (it falls back to the caller).
  */
-export declare const LABEL_SCOPES: readonly ["user", "space", "workspace"];
+export declare const LABEL_SCOPES: readonly ["user", "workspace"];
 export type LabelScope = (typeof LABEL_SCOPES)[number];
 export declare const LABEL_APPLICABLE: readonly ["task", "space", "goal", "routine"];
 export type LabelApplicable = (typeof LABEL_APPLICABLE)[number];