@skrr-ai/cli 0.1.13 → 0.1.15

package/dist/lib/{exec-oversky.js → exec-runtime-binary.js}

@@ -5,12 +5,15 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RUNTIME_BINARY_NAMES = void 0;
 exports.forwardedFlagsNote = forwardedFlagsNote;
-exports.findOverskyBinary = findOverskyBinary;
+exports.findRuntimeBinary = findRuntimeBinary;
+exports.isCurrentRuntimeBinary = isCurrentRuntimeBinary;
+exports.normalizeRuntimeGlobalArgs = normalizeRuntimeGlobalArgs;
 exports.notInstalledMessage = notInstalledMessage;
-exports.execOversky = execOversky;
-exports.overskySupportsSubcommand = overskySupportsSubcommand;
+exports.execRuntimeBinary = execRuntimeBinary;
+exports.execRuntimeBinaryCapture = execRuntimeBinaryCapture;
+exports.runtimeBinarySupportsSubcommand = runtimeBinarySupportsSubcommand;
 /**
- * exec-oversky.ts — locate and forward to the local runtime binary.
+ * exec-runtime-binary.ts — locate and forward to the local runtime binary.
  *
  * The `gh → git` pattern: `skrr daemon ...` is a thin proxy. `skrr` is a REST
  * client; `skrrd` is the long-running runtime. Keeping them as separate
@@ -60,9 +63,13 @@ exports.RUNTIME_BINARY_NAMES = ['skrrd', 'oversky'];
  * `description` alone.
  */
 function forwardedFlagsNote(verb, opts = {}) {
-    const base = `Flags are forwarded to \`skrrd ${verb}\` unchanged, so they are not listed here —` +
-        ` run \`skrrd ${verb} --help\` for this verb's own flags, or \`skrrd --help\` for` +
-        ' global ones such as `--profile`.';
+    const base = opts.bootstrapsRuntime
+        ? `If no local runtime exists, this command first fetches the signed release. After it is ` +
+            `installed, flags are forwarded to \`skrrd ${verb}\` unchanged; run \`skrrd ${verb} --help\` ` +
+            `for this verb's own flags, or \`skrrd --help\` for global ones such as \`--profile\`.`
+        : `Flags are forwarded to \`skrrd ${verb}\` unchanged, so they are not listed here —` +
+            ` run \`skrrd ${verb} --help\` for this verb's own flags, or \`skrrd --help\` for` +
+            ' global ones such as `--profile`.';
     // `install` and `login` are not pure pass-throughs: they fill in the server
     // and profile from the CLI's own session when the caller named neither, so a
     // daemon cannot silently end up on a different deployment than the CLI that
@@ -72,41 +79,91 @@ function forwardedFlagsNote(verb, opts = {}) {
         ? `${base} \`--server\` and \`--profile\` are filled in from your CLI session unless you pass them.`
         : base;
 }
-/** Extra well-known install locations to check when PATH lookup misses. */
-const FALLBACK_PATHS = exports.RUNTIME_BINARY_NAMES.flatMap((name) => [
-    `/opt/homebrew/bin/${name}`,
-    `/usr/local/bin/${name}`,
-    // Linux script-installer default; the daemon's install script drops here.
-    `/usr/local/bin/${name}-daemon`,
-    // EC2 / pm2 layout used in daemon/CLAUDE.md examples.
-    `${process.env.HOME ?? ''}/.skrr/bin/${name}`,
-]);
-/** Resolve the absolute path of `oversky` if it exists, else return null. */
-function findOverskyBinary() {
+/** Extra well-known install locations for one runtime name, checked after PATH. */
+function fallbackPathsForRuntime(name) {
+    return [
+        `/opt/homebrew/bin/${name}`,
+        `/usr/local/bin/${name}`,
+        // Linux script-installer default; the daemon's install script drops here.
+        `/usr/local/bin/${name}-daemon`,
+        // EC2 / pm2 layout used in daemon/CLAUDE.md examples.
+        `${process.env.HOME ?? ''}/.skrr/bin/${name}`,
+    ];
+}
+/** Resolve the local runtime binary — `skrrd`, or the legacy `oversky` still on older PATHs. */
+function findRuntimeBinary() {
     // PATH lookup — Node 20 doesn't ship `which()` but we can mimic it.
     // On Windows, npm globals install a `.cmd` wrapper (not `.exe`) so we
     // must check both; installers that ship a native build still win
     // because `.exe` is checked first.
     const PATH = process.env.PATH ?? '';
     const sep = process.platform === 'win32' ? ';' : ':';
-    const exeNames = process.platform === 'win32'
-        ? exports.RUNTIME_BINARY_NAMES.flatMap((n) => [`${n}.exe`, `${n}.cmd`])
-        : [...exports.RUNTIME_BINARY_NAMES];
-    for (const dir of PATH.split(sep)) {
-        if (!dir)
-            continue;
-        for (const exeName of exeNames) {
-            const candidate = node_path_1.default.join(dir, exeName);
-            if (isExecutable(candidate))
+    const executableNamesFor = (name) => process.platform === 'win32' ? [`${name}.exe`, `${name}.cmd`] : [name];
+    // Check EVERY location for the current name before falling back to the
+    // legacy name. The former loop was directory-first, so an `oversky` binary
+    // in an early PATH entry won over a current `skrrd` in a later managed
+    // location. That stranded onboarding on the old binary precisely when it
+    // needed the current runtime to bootstrap its service.
+    const dirs = PATH.split(sep).filter(Boolean);
+    for (const runtimeName of exports.RUNTIME_BINARY_NAMES) {
+        for (const exeName of executableNamesFor(runtimeName)) {
+            for (const dir of dirs) {
+                const candidate = node_path_1.default.join(dir, exeName);
+                if (isExecutable(candidate))
+                    return candidate;
+            }
+        }
+        for (const candidate of fallbackPathsForRuntime(runtimeName)) {
+            if (candidate && isExecutable(candidate))
                 return candidate;
         }
     }
-    for (const candidate of FALLBACK_PATHS) {
-        if (candidate && isExecutable(candidate))
-            return candidate;
-    }
     return null;
 }
+/** Whether a resolved path names the current runtime rather than legacy oversky. */
+function isCurrentRuntimeBinary(binary) {
+    if (!binary)
+        return false;
+    const basename = node_path_1.default.basename(binary).toLowerCase();
+    return process.platform === 'win32'
+        ? basename === 'skrrd.exe' || basename === 'skrrd.cmd'
+        : basename === 'skrrd';
+}
+/**
+ * Commander reads runtime global options before the subcommand. The CLI
+ * wrappers naturally receive pass-through flags after a verb (`install
+ * --profile work`), which otherwise silently resolves the runtime profile as
+ * default. Move a well-formed profile flag ahead of the verb without changing
+ * the order of any command-specific flags or `--` payload.
+ */
+function normalizeRuntimeGlobalArgs(args) {
+    const rest = [];
+    let profile = null;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--') {
+            rest.push(...args.slice(index));
+            break;
+        }
+        if (arg === '--profile') {
+            const value = args[index + 1];
+            if (value && !value.startsWith('-')) {
+                profile = value;
+                index += 1;
+                continue;
+            }
+        }
+        if (arg.startsWith('--profile=')) {
+            const value = arg.slice('--profile='.length);
+            if (value) {
+                profile = value;
+                continue;
+            }
+        }
+        rest.push(arg);
+    }
+    return profile ? ['--profile', profile, ...rest] : rest;
+}
 function isExecutable(p) {
     try {
         (0, node_fs_1.accessSync)(p, node_fs_1.constants.X_OK);
@@ -155,11 +212,11 @@ function notInstalledMessage() {
  * preserving "exit code = the daemon's exit code" semantics that scripts
  * may depend on.
  */
-function execOversky(args) {
+function execRuntimeBinary(args) {
     return new Promise((resolve, reject) => {
-        const bin = findOverskyBinary();
+        const bin = findRuntimeBinary();
         if (!bin) {
-            reject(new Error('oversky-not-installed'));
+            reject(new Error('runtime-binary-not-installed'));
             return;
         }
         // On Windows, `.cmd` / `.bat` wrappers cannot be executed directly by
@@ -169,7 +226,7 @@ function execOversky(args) {
         // by package.json engines `>=20.0.0` — pin at install time) quotes
         // args when shell:true on Windows per CVE-2024-27980's fix.
         const isWinShim = process.platform === 'win32' && /\.(cmd|bat)$/i.test(bin);
-        const child = (0, node_child_process_1.spawn)(bin, args, {
+        const child = (0, node_child_process_1.spawn)(bin, normalizeRuntimeGlobalArgs(args), {
             stdio: 'inherit',
             ...(isWinShim ? { shell: true } : {}),
         });
@@ -186,6 +243,50 @@ function execOversky(args) {
         });
     });
 }
+/**
+ * Invoke the installed runtime without inheriting its streams. The regular
+ * lifecycle command still owns the terminal; this is only for the wrapper's
+ * post-condition probes, where output is evidence rather than user-facing
+ * command output.
+ */
+function execRuntimeBinaryCapture(args) {
+    return new Promise((resolve, reject) => {
+        const bin = findRuntimeBinary();
+        if (!bin) {
+            reject(new Error('runtime-binary-not-installed'));
+            return;
+        }
+        const isWinShim = process.platform === 'win32' && /\.(cmd|bat)$/i.test(bin);
+        const child = (0, node_child_process_1.spawn)(bin, normalizeRuntimeGlobalArgs(args), {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            ...(isWinShim ? { shell: true } : {}),
+        });
+        let stdout = '';
+        let stderr = '';
+        // A status response is tiny. Keep a broken runtime from making its wrapper
+        // retain an unbounded stream merely to decide whether `start` worked.
+        const append = (current, chunk) => {
+            const limit = 256 * 1024;
+            if (current.length >= limit)
+                return current;
+            return (current + chunk.toString()).slice(0, limit);
+        };
+        child.stdout?.on('data', (chunk) => {
+            stdout = append(stdout, chunk);
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderr = append(stderr, chunk);
+        });
+        child.on('error', reject);
+        child.on('exit', (code, signal) => {
+            resolve({
+                code: signal ? 128 + signalNumber(signal) : (code ?? 0),
+                stdout,
+                stderr,
+            });
+        });
+    });
+}
 /**
  * Check an installed daemon's top-level help before forwarding a command that
  * was added after older daemon releases shipped. A false result is useful to
@@ -195,8 +296,8 @@ function execOversky(args) {
  * This invokes only `oversky --help`: it never starts, stops, configures, or
  * otherwise mutates the local daemon.
  */
-function overskySupportsSubcommand(subcommand) {
-    const bin = findOverskyBinary();
+function runtimeBinarySupportsSubcommand(subcommand) {
+    const bin = findRuntimeBinary();
     if (!bin)
         return Promise.resolve(null);
     return new Promise((resolve) => {

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

@@ -2,6 +2,42 @@ export type GitTaskBranch = {
     branch: string;
     taskRef: string;
 };
+export type TaskDeliveryReceipt = {
+    kind: 'commit';
+    state: 'branch_ready' | 'integrated';
+    commitShas: string[];
+    headSha: string;
+    branch?: string;
+    integrationBranch?: string;
+    mergeCommit?: string;
+} | {
+    kind: 'pull_request';
+    state: 'pr_open' | 'integrated';
+    prUrl: string;
+    branch?: string;
+    headSha?: string;
+    integrationBranch?: string;
+    mergeCommit?: string;
+};
+type CommandResult = {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+};
+type CommandRunner = (command: string, args: string[], cwd: string) => CommandResult;
+export declare function commitArtifacts(deliverables: string): string[];
+/**
+ * Build a receipt for commit/PR deliverables before `tasks complete` writes
+ * anything. Commit reachability is checked against a freshly fetched remote
+ * default branch. A locally dangling commit is first anchored under refs/heads
+ * so even a held completion cannot leave it exposed to `git gc`.
+ */
+export declare function inspectTaskDeliveryArtifacts(opts: {
+    deliverables: string;
+    taskRef: string;
+    cwd?: string;
+    runner?: CommandRunner;
+}): TaskDeliveryReceipt | null;
 export declare class GitTaskError extends Error {
     readonly code: 'GIT_REPOSITORY_REQUIRED' | 'TASK_BRANCH_CONTEXT_MISSING' | 'GIT_BRANCH_SWITCH_FAILED';
     constructor(message: string, code: 'GIT_REPOSITORY_REQUIRED' | 'TASK_BRANCH_CONTEXT_MISSING' | 'GIT_BRANCH_SWITCH_FAILED');
@@ -23,3 +59,4 @@ export declare function checkoutTaskBranch(taskRef: string, cwd?: string): {
     branch: string;
     created: boolean;
 };
+export {};

package/dist/lib/git-task.js

@@ -34,11 +34,162 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GitTaskError = void 0;
+exports.commitArtifacts = commitArtifacts;
+exports.inspectTaskDeliveryArtifacts = inspectTaskDeliveryArtifacts;
 exports.currentGitBranch = currentGitBranch;
 exports.currentGitTaskBranch = currentGitTaskBranch;
 exports.checkoutTaskBranch = checkoutTaskBranch;
 const node_child_process_1 = require("node:child_process");
 const taskReferences = __importStar(require("@skrr-ai/data-provider"));
+const COMMIT_ARTIFACT_RE = /(?:^|[\s,;:(/])(?:commit\s+)?([0-9a-f]{7,40})(?=$|[\s,;:)?#])/gi;
+const GITHUB_PR_ARTIFACT_RE = /https:\/\/github\.com\/[^/\s]+\/[^/\s]+\/pull\/\d+/i;
+function runCommand(command, args, cwd) {
+    const result = (0, node_child_process_1.spawnSync)(command, args, {
+        cwd,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 15_000,
+    });
+    return {
+        status: result.status,
+        stdout: typeof result.stdout === 'string' ? result.stdout.trim() : '',
+        stderr: typeof result.stderr === 'string' ? result.stderr.trim() : '',
+    };
+}
+function commitArtifacts(deliverables) {
+    const commits = [];
+    for (const match of deliverables.matchAll(COMMIT_ARTIFACT_RE)) {
+        const sha = match[1].toLowerCase();
+        if (!commits.includes(sha))
+            commits.push(sha);
+    }
+    return commits;
+}
+function safeTaskBranchRef(taskRef, sha) {
+    const match = taskRef.match(/[A-Za-z][A-Za-z0-9]{1,31}-\d{1,12}/);
+    const label = match?.[0].toUpperCase() || 'recovery';
+    return `oversky/task/${label}/recovery-${sha.slice(0, 12)}`;
+}
+function resolveRemoteDefault(cwd, remote, runner) {
+    const live = runner('git', ['ls-remote', '--symref', remote, 'HEAD'], cwd);
+    if (live.status === 0) {
+        const match = live.stdout.match(/^ref:\s+refs\/heads\/(\S+)\s+HEAD$/m);
+        if (match)
+            return match[1];
+    }
+    const symbolic = runner('git', ['symbolic-ref', '--quiet', '--short', `refs/remotes/${remote}/HEAD`], cwd);
+    if (symbolic.status === 0 && symbolic.stdout.startsWith(`${remote}/`)) {
+        return symbolic.stdout.slice(remote.length + 1);
+    }
+    for (const fallback of ['main', 'master']) {
+        if (runner('git', ['show-ref', '--verify', '--quiet', `refs/remotes/${remote}/${fallback}`], cwd)
+            .status === 0) {
+            return fallback;
+        }
+    }
+    return null;
+}
+/**
+ * Build a receipt for commit/PR deliverables before `tasks complete` writes
+ * anything. Commit reachability is checked against a freshly fetched remote
+ * default branch. A locally dangling commit is first anchored under refs/heads
+ * so even a held completion cannot leave it exposed to `git gc`.
+ */
+function inspectTaskDeliveryArtifacts(opts) {
+    const cwd = opts.cwd ?? process.cwd();
+    const runner = opts.runner ?? runCommand;
+    const commits = commitArtifacts(opts.deliverables);
+    const verifiedCommits = [];
+    let containingBranch;
+    for (const claimed of commits) {
+        const resolved = runner('git', ['rev-parse', '--verify', `${claimed}^{commit}`], cwd);
+        if (resolved.status !== 0 || !/^[0-9a-f]{40}$/i.test(resolved.stdout))
+            continue;
+        const sha = resolved.stdout.toLowerCase();
+        verifiedCommits.push(sha);
+        const branches = runner('git', ['for-each-ref', '--format=%(refname:short)', '--contains', sha, 'refs/heads'], cwd);
+        const firstBranch = branches.stdout.split('\n').find(Boolean);
+        if (firstBranch) {
+            containingBranch ||= firstBranch;
+            continue;
+        }
+        const recoveryBranch = safeTaskBranchRef(opts.taskRef, sha);
+        const existing = runner('git', ['show-ref', '--verify', '--quiet', `refs/heads/${recoveryBranch}`], cwd);
+        if (existing.status !== 0) {
+            const anchored = runner('git', ['update-ref', `refs/heads/${recoveryBranch}`, sha], cwd);
+            if (anchored.status !== 0) {
+                throw new Error(`Commit ${sha} is not reachable from a named local branch, and ${recoveryBranch} ` +
+                    'could not be created. Completion was refused so the commit is not reported as safe.');
+            }
+            containingBranch ||= recoveryBranch;
+        }
+        else {
+            containingBranch ||= recoveryBranch;
+        }
+    }
+    const prUrl = opts.deliverables.match(GITHUB_PR_ARTIFACT_RE)?.[0];
+    if (prUrl) {
+        const viewed = runner('gh', [
+            'pr',
+            'view',
+            prUrl,
+            '--json',
+            'mergedAt,headRefName,headRefOid,baseRefName,mergeCommit,url',
+        ], cwd);
+        if (viewed.status === 0) {
+            try {
+                const pr = JSON.parse(viewed.stdout);
+                const headSha = typeof pr.headRefOid === 'string' ? pr.headRefOid : undefined;
+                const mergeCommit = pr.mergeCommit && typeof pr.mergeCommit === 'object'
+                    ? pr.mergeCommit.oid
+                    : undefined;
+                return {
+                    kind: 'pull_request',
+                    state: pr.mergedAt ? 'integrated' : 'pr_open',
+                    prUrl,
+                    ...(typeof pr.headRefName === 'string' ? { branch: pr.headRefName } : {}),
+                    ...(headSha && /^[0-9a-f]{7,40}$/i.test(headSha) ? { headSha } : {}),
+                    ...(typeof pr.baseRefName === 'string' ? { integrationBranch: pr.baseRefName } : {}),
+                    ...(typeof mergeCommit === 'string' && /^[0-9a-f]{7,40}$/i.test(mergeCommit)
+                        ? { mergeCommit }
+                        : {}),
+                };
+            }
+            catch {
+                // Invalid/unavailable gh evidence is not proof of integration.
+            }
+        }
+        return { kind: 'pull_request', state: 'pr_open', prUrl };
+    }
+    if (!commits.length || verifiedCommits.length !== commits.length)
+        return null;
+    const remotes = runner('git', ['remote'], cwd).stdout.split('\n').filter(Boolean);
+    const remote = remotes.includes('origin') ? 'origin' : remotes[0];
+    const integrationBranch = remote ? resolveRemoteDefault(cwd, remote, runner) : null;
+    let integrated = false;
+    if (remote && integrationBranch) {
+        const fetched = runner('git', [
+            'fetch',
+            '--quiet',
+            '--no-tags',
+            remote,
+            `+refs/heads/${integrationBranch}:refs/remotes/${remote}/${integrationBranch}`,
+        ], cwd);
+        integrated =
+            fetched.status === 0 &&
+                verifiedCommits.every((sha) => runner('git', ['merge-base', '--is-ancestor', sha, `refs/remotes/${remote}/${integrationBranch}`], cwd).status === 0);
+    }
+    const headSha = verifiedCommits[verifiedCommits.length - 1];
+    return {
+        kind: 'commit',
+        state: integrated ? 'integrated' : 'branch_ready',
+        commitShas: verifiedCommits,
+        headSha,
+        ...(containingBranch ? { branch: containingBranch } : {}),
+        ...(integrationBranch ? { integrationBranch } : {}),
+        ...(integrated ? { mergeCommit: headSha } : {}),
+    };
+}
 class GitTaskError extends Error {
     code;
     constructor(message, code) {

package/dist/lib/instruction-blocks.d.ts

@@ -0,0 +1,29 @@
+import type { AgentPromptBlockEntry, AgentPromptComposition, InstructionBlock, InstructionBlockCatalogResponse } from '@skrr-ai/data-provider';
+/**
+ * Helpers shared by the reusable Block Library commands and the per-Agent
+ * composition commands.  Keep this deliberately about data shape, not HTTP:
+ * the server remains the authority that resolves versions, bindings and
+ * rendered text before an Agent is saved.
+ */
+export declare function parseJsonFlag<T>(value: string | undefined, flag: string): T | undefined;
+export declare function parseStringArrayFlag(value: string | undefined, flag: string): string[] | undefined;
+/** Parse repeated `--binding key=value` flags without ever guessing a key. */
+export declare function parseBindings(values: string[] | undefined): Record<string, string> | undefined;
+/**
+ * Read the structured source when it exists; otherwise preserve the legacy
+ * prompt byte-for-byte as one inline entry before changing anything.  This is
+ * the same compatibility move as the server-side resolver, so `add` never
+ * drops an Agent's existing instructions merely because it predates Blocks.
+ */
+export declare function compositionForAgent(agent: {
+    promptComposition?: unknown;
+    instructions?: unknown;
+}): AgentPromptComposition;
+export declare function nextInstanceId(kind?: 'inline' | 'library'): string;
+export declare function entryByInstance(composition: AgentPromptComposition, instanceId: string): AgentPromptBlockEntry;
+export declare function replaceEntry(composition: AgentPromptComposition, instanceId: string, replacement: AgentPromptBlockEntry): AgentPromptComposition;
+export declare function removeEntry(composition: AgentPromptComposition, instanceId: string): AgentPromptComposition;
+/** Move one instance immediately before or after a different existing instance. */
+export declare function moveEntry(composition: AgentPromptComposition, instanceId: string, anchorId: string, placement: 'before' | 'after'): AgentPromptComposition;
+export declare function findBlock(catalog: InstructionBlockCatalogResponse, reference: string): InstructionBlock | undefined;
+export declare function renderInstructionBlockDetail(block: InstructionBlock): string[];

package/dist/lib/instruction-blocks.js

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseJsonFlag = parseJsonFlag;
+exports.parseStringArrayFlag = parseStringArrayFlag;
+exports.parseBindings = parseBindings;
+exports.compositionForAgent = compositionForAgent;
+exports.nextInstanceId = nextInstanceId;
+exports.entryByInstance = entryByInstance;
+exports.replaceEntry = replaceEntry;
+exports.removeEntry = removeEntry;
+exports.moveEntry = moveEntry;
+exports.findBlock = findBlock;
+exports.renderInstructionBlockDetail = renderInstructionBlockDetail;
+const node_crypto_1 = require("node:crypto");
+/**
+ * Helpers shared by the reusable Block Library commands and the per-Agent
+ * composition commands.  Keep this deliberately about data shape, not HTTP:
+ * the server remains the authority that resolves versions, bindings and
+ * rendered text before an Agent is saved.
+ */
+function parseJsonFlag(value, flag) {
+    if (value === undefined)
+        return undefined;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        throw new Error(`${flag} must be valid JSON`);
+    }
+}
+function parseStringArrayFlag(value, flag) {
+    const parsed = parseJsonFlag(value, flag);
+    if (parsed === undefined)
+        return undefined;
+    if (!Array.isArray(parsed) || parsed.some((entry) => typeof entry !== 'string')) {
+        throw new Error(`${flag} must be a JSON array of strings`);
+    }
+    return parsed;
+}
+/** Parse repeated `--binding key=value` flags without ever guessing a key. */
+function parseBindings(values) {
+    if (!values?.length)
+        return undefined;
+    const bindings = {};
+    for (const value of values) {
+        const separator = value.indexOf('=');
+        if (separator < 1) {
+            throw new Error(`Invalid binding "${value}". Use --binding key=value.`);
+        }
+        const key = value.slice(0, separator).trim();
+        if (!/^[a-z][a-z0-9_]{0,63}$/.test(key)) {
+            throw new Error(`Invalid binding key "${key}".`);
+        }
+        if (Object.prototype.hasOwnProperty.call(bindings, key)) {
+            throw new Error(`Binding "${key}" was supplied more than once.`);
+        }
+        bindings[key] = value.slice(separator + 1).trim();
+    }
+    return bindings;
+}
+/**
+ * Read the structured source when it exists; otherwise preserve the legacy
+ * prompt byte-for-byte as one inline entry before changing anything.  This is
+ * the same compatibility move as the server-side resolver, so `add` never
+ * drops an Agent's existing instructions merely because it predates Blocks.
+ */
+function compositionForAgent(agent) {
+    const composition = agent.promptComposition;
+    if (composition &&
+        typeof composition === 'object' &&
+        !Array.isArray(composition) &&
+        composition.schemaVersion === 1 &&
+        Array.isArray(composition.entries)) {
+        return composition;
+    }
+    const instructions = agent.instructions;
+    if (typeof instructions === 'string' && instructions.length) {
+        return {
+            schemaVersion: 1,
+            entries: [
+                {
+                    instanceId: nextInstanceId('inline'),
+                    enabled: true,
+                    source: { kind: 'inline', title: 'Core instructions', body: instructions },
+                },
+            ],
+        };
+    }
+    return { schemaVersion: 1, entries: [] };
+}
+function nextInstanceId(kind = 'inline') {
+    return `${kind}_${(0, node_crypto_1.randomUUID)()}`;
+}
+function entryByInstance(composition, instanceId) {
+    const entry = composition.entries.find((candidate) => candidate.instanceId === instanceId);
+    if (!entry) {
+        throw new Error(`No instruction block instance "${instanceId}". Run \`skrr agents instructions show\` to list this Agent's instances.`);
+    }
+    return entry;
+}
+function replaceEntry(composition, instanceId, replacement) {
+    entryByInstance(composition, instanceId);
+    return {
+        schemaVersion: 1,
+        entries: composition.entries.map((entry) => entry.instanceId === instanceId ? replacement : entry),
+    };
+}
+function removeEntry(composition, instanceId) {
+    entryByInstance(composition, instanceId);
+    return {
+        schemaVersion: 1,
+        entries: composition.entries.filter((entry) => entry.instanceId !== instanceId),
+    };
+}
+/** Move one instance immediately before or after a different existing instance. */
+function moveEntry(composition, instanceId, anchorId, placement) {
+    if (instanceId === anchorId)
+        throw new Error('A block cannot be moved relative to itself.');
+    const entry = entryByInstance(composition, instanceId);
+    entryByInstance(composition, anchorId);
+    const remaining = composition.entries.filter((candidate) => candidate.instanceId !== instanceId);
+    const anchor = remaining.findIndex((candidate) => candidate.instanceId === anchorId);
+    const insertAt = placement === 'before' ? anchor : anchor + 1;
+    return {
+        schemaVersion: 1,
+        entries: [...remaining.slice(0, insertAt), entry, ...remaining.slice(insertAt)],
+    };
+}
+function findBlock(catalog, reference) {
+    return [...catalog.official, ...catalog.library].find((block) => block.id === reference);
+}
+function renderInstructionBlockDetail(block) {
+    const current = block.versions.find((version) => version.version === block.currentVersion);
+    const lines = [
+        `${block.name}  (${block.id})`,
+        `Source:     ${block.source}`,
+        `Visibility: ${block.visibility}`,
+        `Status:     ${block.status}`,
+        `Version:    v${block.currentVersion}`,
+    ];
+    if (block.summary)
+        lines.push(`Summary:    ${block.summary}`);
+    if (block.tags.length)
+        lines.push(`Tags:       ${block.tags.join(', ')}`);
+    if (current) {
+        if (current.requirements.length) {
+            lines.push(`Needs:      ${current.requirements
+                .map((requirement) => `${requirement.kind}:${requirement.key}${requirement.access ? ` (${requirement.access})` : ''}`)
+                .join(', ')} — declarative only; this does not grant access`);
+        }
+        if (current.parameterSchema.length) {
+            lines.push(`Parameters: ${current.parameterSchema
+                .map((parameter) => `${parameter.key}${parameter.required ? ' (required)' : ''}`)
+                .join(', ')}`);
+        }
+        lines.push('', 'Instructions:', ...current.bodyTemplate.split('\n').map((line) => `  ${line}`));
+    }
+    return lines;
+}

package/dist/lib/node-adapter.js

@@ -317,9 +317,15 @@ function createNodeAdapter(opts = {}) {
             // can contain internal stack traces we don't want to echo to
             // terminals by default.
             const text = await res.text().catch(() => '');
+            // `method` is attached because the 403 branch of `handleApiError` needs
+            // to know whether the failing request even HAD a body before it can
+            // advise the user to "try again with less of the request body"
+            // (OSK-6765): `agents show` is a GET and had no body, so the advice
+            // could not be followed.
             const err = new Error(`HTTP ${res.status} ${res.statusText} — ${method} ${url}`);
             err.status = res.status;
             err.body = text;
+            err.method = method;
             throw err;
         }
         if (options?.responseType === 'arraybuffer') {