@skrr-ai/cli 0.1.46 → 0.1.48

package/dist/lib/guest-service.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GUEST_SERVICE_CALL_TIMEOUT_MS = void 0;
+exports.callGuestServiceSocket = callGuestServiceSocket;
+exports.proposeGuestService = proposeGuestService;
+exports.callGuestServiceRead = callGuestServiceRead;
+exports.readGuestSpecFile = readGuestSpecFile;
+const node_fs_1 = require("node:fs");
+const node_net_1 = require("node:net");
+const dedicated_service_1 = require("./dedicated-service");
+exports.GUEST_SERVICE_CALL_TIMEOUT_MS = 15_000;
+/**
+ * Write one document to the propose socket and read the daemon's one reply.
+ * Half-closing after the write is the "request is complete" signal — a
+ * keep-alive protocol would need framing the design does not specify.
+ */
+function callGuestServiceSocket(document, options = {}) {
+    const socketPath = options.socketPath ?? dedicated_service_1.GUEST_SERVICE_SOCKET_PATH;
+    const connect = options.connect ?? node_net_1.connect;
+    const timeoutMs = options.timeoutMs ?? exports.GUEST_SERVICE_CALL_TIMEOUT_MS;
+    return new Promise((resolve, reject) => {
+        const socket = connect(socketPath);
+        const chunks = [];
+        let done = false;
+        const fail = (error) => {
+            if (done)
+                return;
+            done = true;
+            socket.destroy();
+            reject(error);
+        };
+        const timer = setTimeout(() => {
+            fail(new dedicated_service_1.DedicatedServiceError('The machine’s daemon did not answer the service socket in time.', 'GUEST_SERVICE_TIMEOUT'));
+        }, timeoutMs);
+        socket.on('connect', () => {
+            socket.write(`${JSON.stringify(document)}\n`, () => {
+                socket.end();
+            });
+        });
+        socket.on('data', (chunk) => chunks.push(chunk));
+        socket.on('error', (err) => {
+            clearTimeout(timer);
+            if (err.code === 'ENOENT' || err.code === 'ECONNREFUSED') {
+                fail(new dedicated_service_1.DedicatedServiceError(`The service socket (${socketPath}) is not there — this machine's daemon does not offer the service lane. ` +
+                    'An agent should ask the owner to run `skrr machines dedicated service …` instead.', 'GUEST_SERVICE_UNAVAILABLE'));
+                return;
+            }
+            fail(new dedicated_service_1.DedicatedServiceError(`The service socket refused the connection: ${err.message}`, 'GUEST_SERVICE_SOCKET'));
+        });
+        socket.on('close', () => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            const text = Buffer.concat(chunks).toString('utf8').trim();
+            if (!text) {
+                reject(new dedicated_service_1.DedicatedServiceError('The daemon closed the service socket without an answer.', 'GUEST_SERVICE_EMPTY'));
+                return;
+            }
+            let reply;
+            try {
+                reply = JSON.parse(text);
+            }
+            catch {
+                reject(new dedicated_service_1.DedicatedServiceError(`The daemon answered with something that is not JSON: ${text.slice(0, 200)}`, 'GUEST_SERVICE_REPLY'));
+                return;
+            }
+            if (!reply.ok) {
+                reject(new dedicated_service_1.DedicatedServiceError(reply.error || 'The daemon refused the service request.', reply.code || 'GUEST_SERVICE_REFUSED'));
+                return;
+            }
+            resolve(reply);
+        });
+    });
+}
+/** `skrr service propose` — hand the daemon a spec, get back a proposal id. */
+async function proposeGuestService(spec, options = {}) {
+    const reply = await callGuestServiceSocket({ verb: 'propose', spec: (0, dedicated_service_1.specPayload)(spec) }, options);
+    // The daemon's pending proposal is keyed by the service name — that IS
+    // the id the owner approves with.
+    const proposalId = typeof reply.proposalId === 'string'
+        ? reply.proposalId
+        : typeof reply.name === 'string'
+            ? reply.name
+            : typeof reply.result?.proposalId === 'string'
+                ? reply.result.proposalId
+                : '';
+    return { proposalId, reply };
+}
+/**
+ * `skrr service ls|status|logs` — the read verbs on the same socket. The
+ * daemon returns `result` in whatever shape the verb defines; the commands
+ * render it, they do not reinterpret it.
+ */
+async function callGuestServiceRead(op, args = {}, options = {}) {
+    return callGuestServiceSocket({
+        verb: op,
+        ...(args.name ? { name: args.name } : {}),
+        ...(args.tailBytes !== undefined ? { tailBytes: args.tailBytes } : {}),
+    }, options);
+}
+/** Parse and validate a spec document read from a file the guest hands the daemon. */
+function readGuestSpecFile(filePath) {
+    let raw;
+    try {
+        raw = (0, node_fs_1.readFileSync)(filePath, 'utf8');
+    }
+    catch (err) {
+        throw new dedicated_service_1.DedicatedServiceError(`Cannot read ${filePath}: ${err instanceof Error ? err.message : err}`, 'SPEC_FILE');
+    }
+    return (0, dedicated_service_1.parseServiceSpecDocument)(raw, filePath);
+}

package/dist/lib/prompt.d.ts

@@ -47,6 +47,7 @@ export declare function confirmDestructive(question: string, yesFlag: boolean, f
  */
 export declare function readJsonValue(source: string | undefined): Promise<unknown>;
 export declare function readJsonBody(source: string | undefined): Promise<Record<string, unknown>>;
+export declare function readStdin(): Promise<string>;
 /**
  * Copy every defined property from `overrides` onto `base` and return the
  * result. `undefined` values are skipped so unset oclif flags don't clobber

package/dist/lib/prompt.js

@@ -38,6 +38,7 @@ exports.confirm = confirm;
 exports.confirmDestructive = confirmDestructive;
 exports.readJsonValue = readJsonValue;
 exports.readJsonBody = readJsonBody;
+exports.readStdin = readStdin;
 exports.mergeDefined = mergeDefined;
 const fs = __importStar(require("node:fs"));
 const readline = __importStar(require("node:readline"));

package/dist/lib/task-asset-upload.d.ts

@@ -1,4 +1,23 @@
 export type TaskAssetRole = 'input' | 'evidence' | 'deliverable';
+/**
+ * What the bytes ARE in the work ledger, for an upload that is the archived
+ * copy of an artifact that already has a name (`docs/policies/payout.md`).
+ *
+ * Without it the server keys the Resource on the attachment id, which is right
+ * for a screenshot and wrong for a named document: the coordinate somebody
+ * cited and the copy nobody can match to it become two Resources.
+ *
+ * Both upload paths carry it. On the direct-to-storage path it is declared at
+ * INTENT time and persisted on the attachment row, because `complete` — which
+ * writes the receipt — runs in a later request that never sees the intent's
+ * body. Without that, a Deliverable's ledger identity would depend on its
+ * SIZE, which is an implementation detail deciding a durable record.
+ */
+export interface TaskAssetLedgerResource {
+    identity: string;
+    title?: string;
+    expectationIds?: string[];
+}
 export interface UploadedTaskAsset {
     id: string;
     /**
@@ -35,6 +54,7 @@ export declare function uploadTaskAssetFile(opts: {
     taskId: string;
     filePath: string;
     role?: TaskAssetRole;
+    ledger?: TaskAssetLedgerResource;
 }): Promise<UploadedTaskAsset>;
 /**
  * Upload every `--attach` file and return the reference objects an Update or

package/dist/lib/task-asset-upload.js

@@ -105,7 +105,7 @@ async function readTaskForUpload(taskId) {
  * Throws a plain Error; callers decide how to surface it.
  */
 async function uploadTaskAssetFile(opts) {
-    const { taskId, filePath, role } = opts;
+    const { taskId, filePath, role, ledger } = opts;
     if (!fs.existsSync(filePath)) {
         throw new Error(`File not found: ${filePath}`);
     }
@@ -130,13 +130,13 @@ async function uploadTaskAssetFile(opts) {
         if (sessionPath) {
             await readTaskForUpload(taskId);
             result = direct
-                ? await sessionDirectUpload({ filePath, size, filename, mimeType, role })
-                : await sessionBufferedUpload({ filePath, filename, mimeType, role });
+                ? await sessionDirectUpload({ filePath, size, filename, mimeType, role, ledger })
+                : await sessionBufferedUpload({ filePath, filename, mimeType, role, ledger });
         }
         else {
             result = direct
-                ? await genericDirectUpload({ taskId, filePath, size, filename, mimeType, role })
-                : await genericBufferedUpload({ taskId, filePath, filename, mimeType, role });
+                ? await genericDirectUpload({ taskId, filePath, size, filename, mimeType, role, ledger })
+                : await genericBufferedUpload({ taskId, filePath, filename, mimeType, role, ledger });
         }
     }
     catch (err) {
@@ -205,23 +205,31 @@ function taskAssetMarkdownRef(asset) {
  * The buffered path holds the file in memory by design: it is capped at the
  * buffered limit, and the server needs the whole body to canonicalize it.
  */
-function fileFormData(filePath, filename, mimeType, role) {
+function fileFormData(filePath, filename, mimeType, role, ledger) {
     const fd = new FormData();
     fd.append('file', new node_buffer_1.Blob([fs.readFileSync(filePath)], { type: mimeType }), filename);
     if (role)
         fd.append('role', role);
+    if (ledger?.identity) {
+        fd.append('identity', ledger.identity);
+        if (ledger.title)
+            fd.append('title', ledger.title);
+        if (ledger.expectationIds?.length) {
+            fd.append('expectationIds', JSON.stringify(ledger.expectationIds));
+        }
+    }
     return fd;
 }
 async function genericBufferedUpload(p) {
     return data_provider_1.dataService.uploadTaskAttachment({
         taskId: p.taskId,
-        formData: fileFormData(p.filePath, p.filename, p.mimeType, p.role),
+        formData: fileFormData(p.filePath, p.filename, p.mimeType, p.role, p.ledger),
     });
 }
 async function sessionBufferedUpload(p) {
     return (0, api_fetch_1.apiFetch)((await (0, session_task_endpoints_1.sessionScopedTaskPath)('attachment')), {
         method: 'POST',
-        body: fileFormData(p.filePath, p.filename, p.mimeType, p.role),
+        body: fileFormData(p.filePath, p.filename, p.mimeType, p.role, p.ledger),
     });
 }
 async function genericDirectUpload(p) {
@@ -232,6 +240,13 @@ async function genericDirectUpload(p) {
         sizeBytes: p.size,
         sha256: await sha256OfFile(p.filePath),
         role: p.role,
+        ...(p.ledger?.identity
+            ? {
+                identity: p.ledger.identity,
+                title: p.ledger.title,
+                expectationIds: p.ledger.expectationIds,
+            }
+            : {}),
     });
     if (!intent.uploadUrl)
         return intent.attachment;
@@ -257,6 +272,13 @@ async function sessionDirectUpload(p) {
             sizeBytes: p.size,
             sha256: await sha256OfFile(p.filePath),
             ...(p.role ? { role: p.role } : {}),
+            ...(p.ledger?.identity
+                ? {
+                    identity: p.ledger.identity,
+                    title: p.ledger.title,
+                    expectationIds: p.ledger.expectationIds,
+                }
+                : {}),
         },
     });
     if (!intent.uploadUrl)

package/dist/lib/task-extras.d.ts

@@ -133,4 +133,27 @@ export declare const taskChatApi: {
      */
     taskHistory: (id: string, query?: Query) => Promise<Json>;
 };
+/**
+ * `POST /api/tasks/:taskId/labels/suggest` — the on-demand half of the
+ * create-time `_labelGuidance` hint. The server keeps the model call off the
+ * task-create path (the hottest write in the product); this is how a caller
+ * pays for ONE suggestion when it actually wants it. Advisory only: the model
+ * chooses from the declared vocabulary and nothing is written.
+ *
+ * `apiFetch` rather than `request.post` for consistency with the lib's other
+ * standalone verbs; either would do — nothing here needs the idempotency
+ * stamp, because a suggestion is a read in POST clothing.
+ */
+export interface TaskLabelSuggestion {
+    id?: string;
+    name?: string;
+}
+export interface TaskLabelSuggestionResponse {
+    taskId?: string;
+    identifier?: string;
+    /** Size of the applicable vocabulary AFTER the task's own labels are excluded. */
+    vocabularySize?: number;
+    suggestions?: TaskLabelSuggestion[];
+}
+export declare function taskLabelSuggestion(taskId: string): Promise<TaskLabelSuggestionResponse>;
 export {};

package/dist/lib/task-extras.js

@@ -6,6 +6,7 @@ exports.taskRunHandover = taskRunHandover;
 exports.taskRunFork = taskRunFork;
 exports.taskRunPromote = taskRunPromote;
 exports.parseExecutionTargetRef = parseExecutionTargetRef;
+exports.taskLabelSuggestion = taskLabelSuggestion;
 /**
  * task-extras.ts — the `/api/tasks` endpoints that have no `dataService.*`
  * wrapper, gathered so every one of them is reachable from `skrr`.
@@ -185,3 +186,8 @@ exports.taskChatApi = {
      */
     taskHistory: (id, query = {}) => data_provider_1.request.get((0, triggers_1.withQuery)(`${base(id)}/transcript`, query)),
 };
+function taskLabelSuggestion(taskId) {
+    return (0, api_fetch_1.apiFetch)(`${base(taskId)}/labels/suggest`, {
+        method: 'POST',
+    });
+}

package/dist/lib/update-check.d.ts

@@ -1,11 +1,37 @@
+export type CliInstallKind = 'npm-global' | 'npm-local' | 'dev' | 'bundled' | 'other';
+interface CheckCache {
+    /** Epoch ms of the last successful refresh. */
+    lastCheckAt: number;
+    /** Latest advertised CLI version, or null if the API had none. */
+    latest: string | null;
+    /** npm package to update (advisory copy), or null. */
+    npmPackage: string | null;
+    /** baseURL the cache was fetched against — invalidates on server switch. */
+    baseURL: string;
+    /** Resolved install shape, classified during the last refresh. */
+    install?: {
+        kind: CliInstallKind;
+        writable?: boolean;
+    };
+    /** Recorded BEFORE a background self-update is scheduled. */
+    autoUpdate?: {
+        attemptedAt: number;
+        version: string;
+    };
+}
 /** Trailing-slash- and case-insensitive normalization for baseURL compares. */
 export declare function normalizeBaseUrl(url: string): string;
 /**
  * True when the advisory must stay silent regardless of version state:
- * explicit suppression, or a desktop-app-bundled CLI (which auto-updates
- * with the app and must not be told to `npm update -g`).
+ * explicit suppression, a desktop-app-bundled CLI (which auto-updates with
+ * the app and must not be told to `npm update -g`), or an image-baked install
+ * the control plane owns.
  */
 export declare function isNudgeSuppressed(env?: NodeJS.ProcessEnv): boolean;
+/** True when the background self-update is allowed to run at all. Suppression
+ *  implies no auto-update — a user who asked for silence did not ask for a
+ *  silent mutation of their global npm. */
+export declare function isAutoUpdateSuppressed(env?: NodeJS.ProcessEnv): boolean;
 /**
  * True iff `current` is strictly older than `latest` by numeric release
  * core. Conservative: any unparseable input returns false (no nudge).
@@ -13,19 +39,66 @@ export declare function isNudgeSuppressed(env?: NodeJS.ProcessEnv): boolean;
  * we never nag someone testing a prerelease of the latest line.
  */
 export declare function isOlderVersion(current: string, latest: string): boolean;
+/**
+ * Resolve the package directory this process was launched from when it lives
+ * under `node_modules/@skrr-ai/cli` (any npm install — global or project-local),
+ * or null. Probes both the raw entry path and its realpath because the bin is
+ * usually a symlink into the package.
+ */
+export declare function resolveCliPackageDir(argv?: readonly string[]): string | null;
+/**
+ * Classify how this CLI was installed. `npmGlobalRoot` (from `npm root -g`)
+ * distinguishes a global install — which we may auto-update — from a
+ * project-local dependency, whose bytes belong to that project's package.json.
+ * `dev` is a checkout launched via its own `bin/run.js`: a `src/commands`
+ * dir beside `dist` exists only in a checkout — published packages ship
+ * `dist` and no `src`.
+ */
+export declare function classifyCliInstall(env: NodeJS.ProcessEnv, argv: readonly string[], npmGlobalRoot: string | null): {
+    kind: CliInstallKind;
+    writable?: boolean;
+};
 /**
  * Build the one-line stderr advisory, or null when no nudge is warranted.
- * Exported for direct unit testing without touching disk or the network.
+ * `installKind` tailors the command to the bytes' owner: a project-local dep
+ * is updated inside its project, a dev checkout is rebuilt — telling either
+ * to `npm update -g` would fix the wrong install.
  */
-export declare function buildNudgeLine(currentVersion: string, latest: string | null, npmPackage: string | null): string | null;
+export declare function buildNudgeLine(currentVersion: string, latest: string | null, npmPackage: string | null, installKind?: CliInstallKind): string | null;
+export type CliUpdateAction = {
+    type: 'nudge';
+    line: string;
+} | {
+    type: 'auto-update';
+    version: string;
+    pkg: string;
+    line: string;
+} | null;
+/**
+ * Decide, synchronously and from cache alone, what this command should do
+ * about its version state. Pure — exported for direct unit testing.
+ *
+ * AUTO-UPDATE fires at most once per TTL window per target version, and only
+ * for a provably writable npm-global install on an interactive TTY. An attempt
+ * that didn't take (still outdated next run) falls back to the manual nudge
+ * rather than retrying immediately.
+ */
+export declare function decideCliUpdateAction(args: {
+    currentVersion: string;
+    cache: CheckCache | null;
+    env: NodeJS.ProcessEnv;
+    isTTY: boolean;
+    now?: number;
+}): CliUpdateAction;
 /**
  * Entry point, called once per command from `BaseCommand.init()`.
  *
- * Synchronous by design: it decides the nudge from the cache (no network
- * on the hot path) and only kicks off a background refresh when the cache
- * is stale, missing, or from a different server. Returns immediately.
+ * Synchronous by design: it decides from the cache (no network on the hot
+ * path) and only kicks off a background refresh when the cache is stale,
+ * missing, or from a different server. Returns immediately.
  */
 export declare function maybeWarnOutdatedCli(opts: {
     currentVersion: string;
     baseURL: string;
 }): void;
+export {};