@skrr-ai/cli 0.1.92 → 0.1.94

package/dist/commands/tasks/snooze.js

@@ -62,25 +62,26 @@ class TasksSnooze extends base_command_1.BaseCommand {
             this.failWithCliError({ ...failure, exit: 2, retryable: false });
             return;
         }
+        const taskRef = await this.resolveEntityRef('task', identity.id);
         try {
             if (flags.status) {
-                const response = await data_provider_1.dataService.getTaskSnooze(identity.id);
+                const response = await data_provider_1.dataService.getTaskSnooze(taskRef);
                 if (flags.json)
                     this.log(JSON.stringify(response, null, 2));
                 else
-                    this.log(response.snoozed ? `Snoozed ${identity.id}.` : `Not snoozed: ${identity.id}.`);
+                    this.log(response.snoozed ? `Snoozed ${taskRef}.` : `Not snoozed: ${taskRef}.`);
                 return;
             }
-            const response = await data_provider_1.dataService.snoozeTask(identity.id, {
+            const response = await data_provider_1.dataService.snoozeTask(taskRef, {
                 ...(flags.until ? { until: new Date(flags.until).toISOString() } : {}),
                 ...(flags['until-activity'] ? { untilActivity: true } : {}),
             });
             if (flags.json)
                 this.log(JSON.stringify(response, null, 2));
             else if (flags['until-activity'])
-                this.log(`Snoozed ${identity.id} until new activity.`);
+                this.log(`Snoozed ${taskRef} until new activity.`);
             else
-                this.log(`Snoozed ${identity.id} until ${new Date(flags.until).toLocaleString()}.`);
+                this.log(`Snoozed ${taskRef} until ${new Date(flags.until).toLocaleString()}.`);
         }
         catch (error) {
             this.handleApiError(error);

package/dist/commands/tasks/start-all.js

@@ -24,17 +24,18 @@ class TasksStartAll extends base_command_1.BaseCommand {
     async run() {
         this.requireAuth();
         const { args, flags } = await this.parse(TasksStartAll);
+        const taskRef = await this.resolveEntityRef('task', args.id);
         const mode = flags.mode;
         let result;
         try {
             if (mode === 'dri') {
-                result = await data_provider_1.dataService.startDRIAgent(args.id);
+                result = await data_provider_1.dataService.startDRIAgent(taskRef);
             }
             else if (mode === 'dri-plan') {
-                result = await data_provider_1.dataService.startDRIPlan(args.id);
+                result = await data_provider_1.dataService.startDRIPlan(taskRef);
             }
             else {
-                result = await data_provider_1.dataService.startAllTasks(args.id);
+                result = await data_provider_1.dataService.startAllTasks(taskRef);
             }
         }
         catch (err) {
@@ -44,7 +45,7 @@ class TasksStartAll extends base_command_1.BaseCommand {
             this.log(JSON.stringify(result, null, 2));
             return;
         }
-        this.log(`Started ${mode} pipeline for task ${args.id}`);
+        this.log(`Started ${mode} pipeline for task ${taskRef}`);
         const r = result;
         if (r.runId)
             this.log(`Run ID:          ${r.runId}`);

package/dist/commands/tasks/subscribe.js

@@ -36,6 +36,7 @@ class TasksSubscribe extends base_command_1.BaseCommand {
                 details: failure.details,
             });
         }
+        const taskRef = await this.resolveEntityRef('task', identity.id);
         let task;
         let response;
         try {

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

@@ -31,6 +31,7 @@ class TasksTagsAdd extends base_command_1.BaseCommand {
     async run() {
         this.requireAuth();
         const { args, flags } = await this.parse(TasksTagsAdd);
+        const taskRef = await this.resolveEntityRef('task', args.id);
         const incoming = (flags.tag ?? [])
             .map((t) => t.trim().toLowerCase())
             .filter((t) => t.length > 0);
@@ -39,7 +40,7 @@ class TasksTagsAdd extends base_command_1.BaseCommand {
         }
         let current;
         try {
-            current = await data_provider_1.dataService.getTask(args.id, { enrich: false });
+            current = await data_provider_1.dataService.getTask(taskRef, { enrich: false });
         }
         catch (err) {
             this.handleApiError(err);
@@ -55,7 +56,7 @@ class TasksTagsAdd extends base_command_1.BaseCommand {
         let updated;
         try {
             updated = await data_provider_1.dataService.updateTask({
-                taskId: args.id,
+                taskId: taskRef,
                 data: { tags: merged },
             });
         }
@@ -68,7 +69,7 @@ class TasksTagsAdd extends base_command_1.BaseCommand {
         }
         const t = updated;
         const ref = t.identifier ?? (t.taskNumber ? `#${t.taskNumber}` : '');
-        this.log(`Added ${incoming.length} tag(s) to task ${t.id ?? args.id}${ref ? ` (${ref})` : ''} — now: ${merged.join(', ')}`);
+        this.log(`Added ${incoming.length} tag(s) to task ${t.id ?? taskRef}${ref ? ` (${ref})` : ''} — now: ${merged.join(', ')}`);
     }
 }
 exports.default = TasksTagsAdd;

package/dist/commands/tasks/tags/remove.js

@@ -27,13 +27,14 @@ class TasksTagsRemove extends base_command_1.BaseCommand {
     async run() {
         this.requireAuth();
         const { args, flags } = await this.parse(TasksTagsRemove);
+        const taskRef = await this.resolveEntityRef('task', args.id);
         const targets = new Set((flags.tag ?? []).map((t) => t.trim().toLowerCase()).filter((t) => t.length > 0));
         if (targets.size === 0) {
             this.error('At least one --tag is required.', { exit: 1 });
         }
         let current;
         try {
-            current = await data_provider_1.dataService.getTask(args.id, { enrich: false });
+            current = await data_provider_1.dataService.getTask(taskRef, { enrich: false });
         }
         catch (err) {
             this.handleApiError(err);
@@ -49,7 +50,7 @@ class TasksTagsRemove extends base_command_1.BaseCommand {
         let updated;
         try {
             updated = await data_provider_1.dataService.updateTask({
-                taskId: args.id,
+                taskId: taskRef,
                 data: { tags: next },
             });
         }
@@ -62,7 +63,7 @@ class TasksTagsRemove extends base_command_1.BaseCommand {
         }
         const t = updated;
         const ref = t.identifier ?? (t.taskNumber ? `#${t.taskNumber}` : '');
-        this.log(`Removed ${existing.length - next.length} tag(s) from task ${t.id ?? args.id}${ref ? ` (${ref})` : ''} — now: ${next.join(', ') || '(none)'}`);
+        this.log(`Removed ${existing.length - next.length} tag(s) from task ${t.id ?? taskRef}${ref ? ` (${ref})` : ''} — now: ${next.join(', ') || '(none)'}`);
     }
 }
 exports.default = TasksTagsRemove;

package/dist/commands/tasks/timeline.js

@@ -33,9 +33,10 @@ class TasksTimeline extends base_command_1.BaseCommand {
     async run() {
         this.requireAuth();
         const { args, flags } = await this.parse(TasksTimeline);
+        const taskRef = await this.resolveEntityRef('task', args.id);
         let result;
         try {
-            result = await data_provider_1.dataService.getTaskTimeline(args.id, {
+            result = await data_provider_1.dataService.getTaskTimeline(taskRef, {
                 limit: flags.limit,
                 cursor: flags.cursor,
                 type: flags.type,
@@ -54,7 +55,7 @@ class TasksTimeline extends base_command_1.BaseCommand {
         if (rows.length === 0) {
             // `renderTable([])` prints NOTHING — no header, no empty state, exit 0 —
             // which is indistinguishable from a broken command. Say what happened.
-            this.log(await (0, task_legacy_1.emptyCanonicalView)(args.id, 'timeline entries'));
+            this.log(await (0, task_legacy_1.emptyCanonicalView)(taskRef, 'timeline entries'));
             return;
         }
         (0, format_1.renderTable)(rows.map((item) => ({

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

@@ -3,10 +3,13 @@ export default class TasksToday extends BaseCommand {
     static description: string;
     static examples: string[];
     static flags: {
+        'include-snoozed': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        fields: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        compact: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        ndjson: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         limit: import("@oclif/core/lib/interfaces").OptionFlag<number, import("@oclif/core/lib/interfaces").CustomOptions>;
         cursor: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
-        'include-snoozed': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
 }

package/dist/commands/tasks/today.js

@@ -5,6 +5,7 @@ const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../base-command");
 const web_url_1 = require("../../lib/web-url");
 const format_1 = require("../../lib/format");
+const list_output_1 = require("../../lib/list-output");
 class TasksToday extends base_command_1.BaseCommand {
     static description = "List today's tasks";
     static examples = [
@@ -12,11 +13,13 @@ class TasksToday extends base_command_1.BaseCommand {
         '<%= config.bin %> tasks today --limit 25',
         '<%= config.bin %> tasks today --json',
         '<%= config.bin %> tasks today --include-snoozed',
+        '<%= config.bin %> tasks today --compact --json',
     ];
     static flags = {
         json: core_1.Flags.boolean({ description: 'Output as JSON' }),
         limit: core_1.Flags.integer({ description: 'Max results', default: 50 }),
         cursor: core_1.Flags.string({ description: 'Pagination cursor from a previous page' }),
+        ...list_output_1.listOutputFlags,
         'include-snoozed': core_1.Flags.boolean({
             description: 'Include tasks you have personally snoozed (hidden by default)',
         }),
@@ -35,8 +38,15 @@ class TasksToday extends base_command_1.BaseCommand {
         catch (err) {
             this.handleApiError(err);
         }
-        if (flags.json) {
-            this.log(JSON.stringify((0, web_url_1.withDataUrls)(this.cliConfig.baseURL, response, web_url_1.taskUrlFrom), null, 2));
+        if (flags.json || flags.ndjson) {
+            // `/tasks/today` has no server-side `view=summary`, so --compact is a
+            // client-side trim here: the rows still cross the wire.
+            this.printList((0, list_output_1.shapeListResponse)((0, web_url_1.withDataUrls)(this.cliConfig.baseURL, response, web_url_1.taskUrlFrom), {
+                resource: 'task',
+                fields: flags.fields,
+                compact: flags.compact,
+                requestedLimit: flags.limit,
+            }), Boolean(flags.ndjson));
             return;
         }
         const r = response;

package/dist/commands/tasks/transcript.js

@@ -55,9 +55,10 @@ class TasksTranscript extends base_command_1.BaseCommand {
                 details: { suggestion: failure.suggestion, context: failure.details },
             });
         }
+        const taskRef = await this.resolveEntityRef('task', taskIdentity.id);
         let task;
         try {
-            task = (await data_provider_1.dataService.getTask(taskIdentity.id, { enrich: false }));
+            task = (await data_provider_1.dataService.getTask(taskRef, { enrich: false }));
         }
         catch (err) {
             this.handleApiError(err);
@@ -67,13 +68,13 @@ class TasksTranscript extends base_command_1.BaseCommand {
             // A task with no execution conversation has simply never been run by an
             // agent — a real state, not a lookup failure. Say which one it is.
             this.failWithCliError({
-                message: `Task ${task.identifier ?? taskIdentity.id} has no execution conversation yet (status: ${task.status ?? 'unknown'}).`,
+                message: `Task ${task.identifier ?? taskRef} has no execution conversation yet (status: ${task.status ?? 'unknown'}).`,
                 code: 'TASK_CONVERSATION_MISSING',
                 exit: 4,
                 retryable: false,
                 details: {
                     suggestion: 'Start the task (`skrr tasks start <task-id>`) or check `skrr tasks runs <task-id>` for a failed run.',
-                    taskId: taskIdentity.id,
+                    taskId: taskRef,
                     status: task.status ?? null,
                 },
             });
@@ -93,7 +94,7 @@ class TasksTranscript extends base_command_1.BaseCommand {
         if (flags.json) {
             this.log(JSON.stringify({
                 object: 'sky.task_transcript',
-                taskId: String(task.id ?? taskIdentity.id),
+                taskId: String(task.id ?? taskRef),
                 identifier: task.identifier ?? null,
                 status: task.status ?? null,
                 conversationId,
@@ -104,7 +105,7 @@ class TasksTranscript extends base_command_1.BaseCommand {
             }, null, 2));
             return;
         }
-        this.log(`Task:         ${task.identifier ?? task.id ?? taskIdentity.id} — ${task.title ?? '-'}`);
+        this.log(`Task:         ${task.identifier ?? task.id ?? taskRef} — ${task.title ?? '-'}`);
         this.log(`Status:       ${task.status ?? '-'}`);
         this.log(`Conversation: ${conversationId}`);
         this.log('');

package/dist/commands/tasks/unschedule.js

@@ -19,9 +19,10 @@ class TasksUnschedule extends base_command_1.BaseCommand {
     async run() {
         this.requireAuth();
         const { args, flags } = await this.parse(TasksUnschedule);
+        const taskRef = await this.resolveEntityRef('task', args.id);
         let result;
         try {
-            result = await data_provider_1.dataService.unscheduleTask(args.id);
+            result = await data_provider_1.dataService.unscheduleTask(taskRef);
         }
         catch (err) {
             this.handleApiError(err);
@@ -32,7 +33,7 @@ class TasksUnschedule extends base_command_1.BaseCommand {
         }
         const t = result;
         const ref = t.identifier ?? (t.taskNumber ? `#${t.taskNumber}` : '');
-        this.log(`Unscheduled task ${t.id ?? t._id ?? args.id}${ref ? ` (${ref})` : ''}`);
+        this.log(`Unscheduled task ${t.id ?? t._id ?? taskRef}${ref ? ` (${ref})` : ''}`);
     }
 }
 exports.default = TasksUnschedule;

package/dist/commands/tasks/unsnooze.js

@@ -30,12 +30,13 @@ class TasksUnsnooze extends base_command_1.BaseCommand {
             this.failWithCliError({ ...failure, exit: 2, retryable: false });
             return;
         }
+        const taskRef = await this.resolveEntityRef('task', identity.id);
         try {
-            const response = await data_provider_1.dataService.unsnoozeTask(identity.id);
+            const response = await data_provider_1.dataService.unsnoozeTask(taskRef);
             if (flags.json)
                 this.log(JSON.stringify(response, null, 2));
             else
-                this.log(`Unsnoozed ${identity.id}.`);
+                this.log(`Unsnoozed ${taskRef}.`);
         }
         catch (error) {
             this.handleApiError(error);

package/dist/commands/tasks/unsubscribe.js

@@ -36,10 +36,11 @@ class TasksUnsubscribe extends base_command_1.BaseCommand {
             });
             return;
         }
+        const taskRef = await this.resolveEntityRef('task', identity.id);
         let task;
         let response = { unsubscribed: false };
         try {
-            task = await data_provider_1.dataService.getTask(identity.id);
+            task = await data_provider_1.dataService.getTask(taskRef);
             const subscriptions = await data_provider_1.dataService.listEntitySubscriptions({ entityType: 'task' });
             const subscription = subscriptions.items.find((candidate) => candidate.entityId === task.id && candidate.subscriberType === 'user');
             if (subscription?.id)

package/dist/commands/tasks/update.js

@@ -220,6 +220,7 @@ class TasksUpdate extends base_command_1.BaseCommand {
                 details: { suggestion: failure.suggestion, context: failure.details },
             });
         }
+        const taskRef = await this.resolveEntityRef('task', taskIdentity.id);
         // `--expect clear` is an explicit empty list, which the API turns into $unset —
         // distinct from omitting the flag, which leaves the declaration untouched.
         // Without the sentinel there is no way to say "stop requiring an output"
@@ -284,7 +285,7 @@ class TasksUpdate extends base_command_1.BaseCommand {
         if (changesSpec) {
             let settled = [];
             try {
-                const acceptance = await data_provider_1.dataService.getTaskAcceptance(taskIdentity.id);
+                const acceptance = await data_provider_1.dataService.getTaskAcceptance(taskRef);
                 settled = acceptance.expectations.filter((e) => e.assessmentId);
             }
             catch {
@@ -435,7 +436,7 @@ class TasksUpdate extends base_command_1.BaseCommand {
         await this.resolveAssigneesInPayload(payload, {
             resolveSpaceId: async () => {
                 try {
-                    const task = (await data_provider_1.dataService.getTask(taskIdentity.id, { enrich: false }));
+                    const task = (await data_provider_1.dataService.getTask(taskRef, { enrich: false }));
                     return typeof task.spaceId === 'string' ? task.spaceId : undefined;
                 }
                 catch {
@@ -448,7 +449,7 @@ class TasksUpdate extends base_command_1.BaseCommand {
         let updated;
         try {
             updated = await data_provider_1.dataService.updateTask({
-                taskId: taskIdentity.id,
+                taskId: taskRef,
                 data: payload,
             });
         }
@@ -481,7 +482,7 @@ class TasksUpdate extends base_command_1.BaseCommand {
         }
         const t = updated;
         const ref = t.identifier ?? (t.taskNumber ? `#${t.taskNumber}` : '');
-        this.log(`Updated task ${t.id ?? t._id ?? taskIdentity.id}${ref ? ` (${ref})` : ''} — ${t.title ?? '(no title)'}`);
+        this.log(`Updated task ${t.id ?? t._id ?? taskRef}${ref ? ` (${ref})` : ''} — ${t.title ?? '(no title)'}`);
         // `--yes` asserts the revocation; it does not erase that it happened.
         // Report the cost after the write too, or the evidence is silently gone.
         if (changesSpec && flags.yes && (settledSpecAssessments > 0 || acceptanceUnreadable)) {

package/dist/commands/tasks/wait.js

@@ -54,6 +54,7 @@ class TasksWait extends base_command_1.BaseCommand {
                 details: { suggestion: failure.suggestion, context: failure.details },
             });
         }
+        const taskRef = await this.resolveEntityRef('task', taskIdentity.id);
         const failOn = (0, task_execution_1.parseStatusSet)(flags['fail-on'], task_execution_1.DEFAULT_FAIL_STATUSES);
         let timeoutMs = null;
         try {
@@ -75,16 +76,16 @@ class TasksWait extends base_command_1.BaseCommand {
             try {
                 tasks = flags.descendants
                     ? await (0, task_execution_1.fetchTaskSet)({
-                        rootId: taskIdentity.id,
+                        rootId: taskRef,
                         descendants: true,
                         childrenOnly: flags['children-only'],
                     })
-                    : await (0, task_execution_1.fetchTaskSet)({ ids: [taskIdentity.id, ...(flags.task ?? [])] });
+                    : await (0, task_execution_1.fetchTaskSet)({ ids: [taskRef, ...(flags.task ?? [])] });
             }
             catch (err) {
                 this.handleApiError(err);
             }
-            const snapshot = (0, task_execution_1.buildSnapshot)(tasks, failOn, taskIdentity.id);
+            const snapshot = (0, task_execution_1.buildSnapshot)(tasks, failOn, taskRef);
             const failed = snapshot.failureTasks.length > 0;
             const satisfied = snapshot.tasks.length > 0 &&
                 snapshot.tasks.every((task) => (0, task_execution_1.satisfiesWaitTarget)(task, flags.until));
@@ -101,7 +102,7 @@ class TasksWait extends base_command_1.BaseCommand {
             }
             if (timeoutMs != null && Date.now() - startedAt >= timeoutMs) {
                 this.failWithCliError({
-                    message: `Timed out waiting for ${taskIdentity.id} after ${flags.timeout}.`,
+                    message: `Timed out waiting for ${taskRef} after ${flags.timeout}.`,
                     code: 'TASK_WAIT_TIMEOUT',
                     exit: 124,
                     retryable: true,

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

@@ -0,0 +1,37 @@
+import { type DistributionChannel, type StoreBadgeStyle } from '@skrr-ai/data-provider';
+/**
+ * The CLI's half of agent distribution (docs/architecture/agent-distribution-2026-10-08.md):
+ * minting the sharer's attribution code for a public agent and building the
+ * addresses `skrr agents share` and `skrr agents badge` print.
+ *
+ * Every URL comes from data-provider's one builder over this deployment's web
+ * origin — never a hand-spelled `/a/…` — so a link printed here is the link the
+ * web and mobile share sheets print for the same (sharer, agent, channel).
+ */
+export type AgentShareLink = {
+    agentId: string;
+    channel: DistributionChannel;
+    code: string;
+    url: string;
+};
+/**
+ * The server answers every kind of not-public (private, unpublished, missing,
+ * moderated) with the same 404, so the CLI cannot — and must not try to — tell
+ * them apart. What it CAN say is what to do instead.
+ */
+export declare class AgentNotShareableError extends Error {
+    readonly agentId: string;
+    readonly code = "AGENT_NOT_SHAREABLE";
+    constructor(agentId: string);
+}
+/**
+ * Mint (idempotently — the same sharer, agent and channel always get the same
+ * code) and return the canonical attributed listing URL.
+ */
+export declare function mintAgentShareLink({ baseURL, agentId, channel, }: {
+    baseURL: string;
+    agentId: string;
+    channel: DistributionChannel;
+}): Promise<AgentShareLink>;
+/** The anonymous badge image of a public listing, on the API this CLI talks to. */
+export declare function agentBadgeImageUrl(agentId: string, style?: StoreBadgeStyle): string;

package/dist/lib/agent-distribution.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentNotShareableError = void 0;
+exports.mintAgentShareLink = mintAgentShareLink;
+exports.agentBadgeImageUrl = agentBadgeImageUrl;
+const data_provider_1 = require("@skrr-ai/data-provider");
+const http_error_1 = require("./http-error");
+const web_url_1 = require("./web-url");
+/**
+ * The server answers every kind of not-public (private, unpublished, missing,
+ * moderated) with the same 404, so the CLI cannot — and must not try to — tell
+ * them apart. What it CAN say is what to do instead.
+ */
+class AgentNotShareableError extends Error {
+    agentId;
+    code = 'AGENT_NOT_SHAREABLE';
+    constructor(agentId) {
+        super(`${agentId} has no public Store listing, so it has no public link: it is private, ` +
+            'unpublished, or does not exist. To give one person access to a private agent, use ' +
+            `\`skrr agent-shares create ${agentId} --recipient <user-id>\`; to publish it, ` +
+            `\`skrr agents visibility ${agentId} --public\`.`);
+        this.agentId = agentId;
+        this.name = 'AgentNotShareableError';
+    }
+}
+exports.AgentNotShareableError = AgentNotShareableError;
+function isNotDistributable(err) {
+    if ((0, http_error_1.httpStatusOf)(err) === 404)
+        return true;
+    const body = (0, http_error_1.httpBodyOf)(err);
+    return body?.code === 'ENTITY_NOT_FOUND';
+}
+/**
+ * Mint (idempotently — the same sharer, agent and channel always get the same
+ * code) and return the canonical attributed listing URL.
+ */
+async function mintAgentShareLink({ baseURL, agentId, channel, }) {
+    let minted;
+    try {
+        minted = await data_provider_1.dataService.mintDistributionCode({
+            entity: { kind: 'agent', id: agentId },
+            channel,
+        });
+    }
+    catch (err) {
+        if (isNotDistributable(err))
+            throw new AgentNotShareableError(agentId);
+        throw err;
+    }
+    return {
+        agentId,
+        channel,
+        code: minted.code,
+        url: (0, data_provider_1.buildShareUrl)((0, web_url_1.webOrigin)(baseURL), { kind: 'agent', id: agentId }, {
+            code: minted.code,
+            channel,
+        }),
+    };
+}
+/** The anonymous badge image of a public listing, on the API this CLI talks to. */
+function agentBadgeImageUrl(agentId, style) {
+    return (0, data_provider_1.publicStoreAgentBadge)(agentId, style && style !== 'flat' ? { style } : {});
+}

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

@@ -0,0 +1,69 @@
+import { type Attribution, type DistributionChannel, type ResolveAgentVanityResponse, type ResolveDistributionCodeResponse } from '@skrr-ai/data-provider';
+/**
+ * THE ONE PLACE A STORE AGENT REFERENCE IS RESOLVED.
+ *
+ * `skrr store install|show|stats`, `skrr agents share|badge` and `skrr open`
+ * read the positional through `resolveAgentRef`, never by using the raw string
+ * as an id. Accepted, in this order:
+ *
+ *   - an agent id, typed as-is (`agent_abc`) — no attribution: nobody shared it;
+ *   - any first-party link `parseSkrrLink` recognises as an agent
+ *     (`https://skrr.ai/a/<id>[/slug]`, `/store/agents/<id>`, `/agent/<id>`,
+ *     `skrr://agent/<id>`), keeping the link's own `?s=` / `?ch=`;
+ *   - a first-party link that carries only a share code (`/?s=<code>`), or
+ *     names something the CLI cannot look up locally but carries a code — the
+ *     code is resolved through the server (`resolveDistributionCode`);
+ *   - a vanity address, `@handle/agent-slug` or `…/@handle/agent-slug` — the
+ *     alias is resolved through the server's public vanity endpoint (a retired
+ *     handle or slug still resolves; agent-distribution-2026-10-08, "Vanity
+ *     URLs"). A vanity link that also carries a code is resolved by its code,
+ *     which names the agent exactly.
+ *
+ * Link recognition is data-provider's (`inspectSkrrLink`, principle 5): no
+ * regex here decides what a URL names.
+ *
+ * Attribution belongs to the SHARER's channel. A pasted link keeps the `ch` it
+ * was minted with; a bare id carries none, and this never invents one (no
+ * `ch=cli` for an id someone typed — that would credit a share nobody made).
+ */
+export type ResolvedAgentRef = {
+    agentId: string;
+    /**
+     * How it was given: an id, a link naming the agent, a share code the server
+     * resolved, or a vanity alias the server resolved.
+     */
+    source: 'id' | 'link' | 'code' | 'vanity';
+    attribution: Attribution;
+};
+export type AgentRefErrorCode = 'AGENT_REF_EMPTY' | 'AGENT_REF_UNSUPPORTED' | 'AGENT_REF_FOREIGN' | 'AGENT_REF_NOT_AN_AGENT' | 'AGENT_REF_VANITY_UNRESOLVED' | 'AGENT_REF_CODE_UNRESOLVED';
+export declare class AgentRefError extends Error {
+    readonly code: AgentRefErrorCode;
+    constructor(message: string, code: AgentRefErrorCode);
+}
+export type AgentRefOptions = {
+    /** The configured deployment; its hosts count as first-party besides the built-in list. */
+    baseURL?: string;
+    /** How a share code is resolved. Defaults to the anonymous public resolve endpoint. */
+    resolveCode?: (code: string) => Promise<ResolveDistributionCodeResponse | null>;
+    /** How a vanity alias is resolved. Defaults to the anonymous public vanity endpoint. */
+    resolveVanity?: (handle: string, slug: string) => Promise<ResolveAgentVanityResponse | null>;
+};
+/**
+ * The built-in first-party hosts plus every origin the configured deployment
+ * serves (a dev or self-hosted `baseURL` is first-party for its own user).
+ */
+export declare function cliFirstPartyHosts(baseURL?: string): string[];
+export declare function resolveAgentRef(input: string, options?: AgentRefOptions): Promise<ResolvedAgentRef>;
+/**
+ * The canonical public address of a resolved agent, keeping the attribution it
+ * arrived with — what a command prints when it echoes a link back (an install
+ * command, an `open`), so following the echo credits the same share.
+ */
+export declare function attributedListingUrl(baseURL: string, ref: Pick<ResolvedAgentRef, 'agentId' | 'attribution'>): string;
+/** The install body fields an attribution maps to; empty for an unattributed ref. */
+export declare function installAttribution(attribution: Attribution): {
+    distributionCode?: string;
+    channel?: DistributionChannel;
+};
+/** Quote a URL for a POSIX shell: `?` and `&` in an attributed link are metacharacters. */
+export declare function shellQuote(value: string): string;