@kosuke-ai/cli 1.0.1-next.4 → 1.0.1-next.6

package/dist/runtime/mcp-attachments.js

@@ -0,0 +1,110 @@
+import { closeSync, constants, fstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { RefusedArgument } from './mcp-guard.js';
+/**
+ * Where an attachment may come from. On the CLI a person types the path; here
+ * the model chooses it, so a prompt that says "attach ~/.config/kosuke/credentials.json"
+ * would otherwise upload a token to the platform and into the transcript. Every
+ * path is resolved through its symlinks first, then held to one root, and a
+ * hidden segment (`.ssh`, `.aws`, `.config`, `.env`) is refused even inside it:
+ * those hold credentials far more often than screenshots.
+ *
+ * The bytes that leave are then read once, through a handle opened on the
+ * path that passed and checked to be a regular file, and staged as a private
+ * copy for the shared multipart code to pick up. Reading the original path
+ * again later would trust a name a concurrent writer could have re-pointed,
+ * and a FIFO or a device under the root would hang the server for good.
+ */
+/** Mirrors the server's cap, which the shared attachment code enforces again. */
+const MAX_ATTACHMENT_BYTES = 10 * 1024 * 1024;
+export function defaultAttachmentPolicy(env = process.env) {
+    return { root: resolve(env.KOSUKE_MCP_ATTACHMENT_ROOT ?? process.cwd()) };
+}
+/** The real path of a file that may be attached, or a refusal that says why. */
+export function confineAttachment(path, policy) {
+    const given = isAbsolute(path) ? path : resolve(policy.root, path);
+    let root;
+    let real;
+    try {
+        root = realpathSync(policy.root);
+    }
+    catch {
+        throw new RefusedArgument(`The attachment root ${policy.root} does not exist.`);
+    }
+    try {
+        real = realpathSync(given);
+    }
+    catch {
+        throw new RefusedArgument(`Attachment ${path} does not exist or cannot be read.`);
+    }
+    const inside = relative(root, real);
+    if (inside === '' || inside.startsWith('..') || isAbsolute(inside)) {
+        throw new RefusedArgument(`Attachment ${path} resolves to ${real}, outside the attachment root ${root}. ` +
+            `Only files under the root can be attached; start the server with ` +
+            `--attachment-root or KOSUKE_MCP_ATTACHMENT_ROOT to change it.`);
+    }
+    const hidden = inside.split(sep).find((segment) => segment.startsWith('.'));
+    if (hidden) {
+        throw new RefusedArgument(`Attachment ${path} is under a hidden path (${hidden}), which this server does not ` +
+            `attach: such paths hold credentials more often than screenshots.`);
+    }
+    // Checked before any open: opening a FIFO for reading blocks until a writer
+    // arrives, and a directory or a device is not something to upload either.
+    if (!statSync(real).isFile()) {
+        throw new RefusedArgument(`Attachment ${path} is not a regular file.`);
+    }
+    return real;
+}
+/**
+ * Read each confined file once through its own handle and stage a private
+ * copy under a fresh 0700 directory. The handle is what is checked (a regular
+ * file, within the size cap) and what is read, so a path swapped after the
+ * check changes nothing; the copy keeps the file's name, which is what the
+ * platform sees, and lives only for this one request.
+ */
+export function stageAttachments(realPaths) {
+    if (!realPaths.length)
+        return { paths: [], cleanup: () => { } };
+    const directory = mkdtempSync(join(tmpdir(), 'kosuke-mcp-attachment-'));
+    const cleanup = () => rmSync(directory, { recursive: true, force: true });
+    try {
+        const paths = realPaths.map((real, index) => {
+            const bytes = readOnce(real);
+            const slot = join(directory, String(index));
+            mkdirSync(slot, { mode: 0o700 });
+            const copy = join(slot, basename(real));
+            writeFileSync(copy, bytes, { mode: 0o600 });
+            return copy;
+        });
+        return { paths, cleanup };
+    }
+    catch (error) {
+        cleanup();
+        throw error;
+    }
+}
+function readOnce(real) {
+    // O_NOFOLLOW: the leaf must still be the file realpath saw, not a symlink
+    // planted since. O_NONBLOCK: should it have become a FIFO, open returns
+    // instead of waiting, and fstat refuses it below.
+    let fd;
+    try {
+        fd = openSync(real, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    }
+    catch {
+        throw new RefusedArgument(`Attachment ${real} cannot be opened.`);
+    }
+    try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile())
+            throw new RefusedArgument(`Attachment ${real} is not a regular file.`);
+        if (stat.size > MAX_ATTACHMENT_BYTES) {
+            throw new RefusedArgument(`Attachment ${real} is larger than the 10 MiB attachment limit.`);
+        }
+        return readFileSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}

package/dist/runtime/mcp-composite-support.js

@@ -0,0 +1,49 @@
+/**
+ * What a composite tool is made of: the contract the server gives it, and the
+ * small readings of an invocation the three tools share. Kept apart from the
+ * tools themselves so the open-pr helpers can use them without a cycle.
+ */
+export const COMPOSITE_TOOLSET = 'composite';
+export function pick(args, keys) {
+    return Object.fromEntries(keys.filter((key) => args[key] !== undefined).map((k) => [k, args[k]]));
+}
+export function data(invocation) {
+    const body = invocation.body;
+    const value = body?.data;
+    return typeof value === 'object' && value !== null ? value : {};
+}
+export function tail(messages, count = 3) {
+    if (!Array.isArray(messages))
+        return [];
+    return messages.slice(-count).map((m) => ({ role: m.role, content: messageText(m) }));
+}
+/** Blocks whose `content` is prose addressed to the reader; tool and plan blocks are not. */
+const PROSE_BLOCKS = new Set(['text', 'clarification']);
+/**
+ * The text of a message. A user message carries it in `content`; an
+ * assistant message carries `content: null` and its text in `blocks`, beside
+ * tool blocks. Prose blocks joined in order, so a clarification question is
+ * what comes back for a job that is awaiting one; `content` as the fallback;
+ * null when there is no text at all.
+ */
+export function messageText(message) {
+    const blocks = Array.isArray(message.blocks) ? message.blocks : [];
+    const text = blocks
+        .filter((block) => PROSE_BLOCKS.has(String(block.type)) && typeof block.content === 'string')
+        .map((block) => block.content)
+        .join('\n\n')
+        .trim();
+    if (text)
+        return text;
+    return typeof message.content === 'string' && message.content.trim() ? message.content : null;
+}
+export function done(last, payload, warnings = last.warnings) {
+    return { ok: true, status: last.status, body: { data: payload }, warnings };
+}
+/** A step that failed: its error, named, so the model knows how far it got. */
+export function failed(step, name) {
+    const body = typeof step.body === 'object' && step.body !== null
+        ? { step: name, ...step.body }
+        : { step: name, error: step.body ?? `HTTP ${step.status}` };
+    return { ...step, body };
+}

package/dist/runtime/mcp-composite.js

@@ -0,0 +1,309 @@
+import { UsageError } from './invoke.js';
+import { COMPOSITE_TOOLSET, data, done, failed, messageText, pick, tail, } from './mcp-composite-support.js';
+import { openPrCommand, resolveProvider } from './mcp-open-pr.js';
+/**
+ * The hand-written tools: `ship`, `watch` and `submit`, the three arcs where a
+ * flat mirror of the API makes the model plumb ids by hand. Each one calls
+ * generated tools by name and nothing else, so it can reach no route the
+ * document does not describe, and it is the only part of the tool list that
+ * can drift from the spec.
+ */
+/** A chat job the platform will not move on its own. */
+const CHAT_SETTLED = new Set(['completed', 'failed', 'cancelled', 'awaiting_response']);
+/** Likewise for a deploy; `idle` is a project that has never deployed. */
+const DEPLOY_SETTLED = new Set(['deployed', 'failed', 'cancelled', 'awaiting_user', 'idle']);
+/**
+ * Under the 60 s an MCP client waits for a call by default: a longer default
+ * would time out on the client side while the server kept polling, and the
+ * documented `done: false` would never be seen.
+ */
+const WATCH_DEFAULT_SECONDS = 50;
+const WATCH_MAX_SECONDS = 1800;
+const POLL_DEFAULT_SECONDS = 5;
+const id = { type: 'string' };
+const ship = {
+    name: 'ship',
+    toolset: COMPOSITE_TOOLSET,
+    description: 'Start work: create a chat session from a prompt and start its first turn, or start an ' +
+        'existing backlog session. Returns the session and the job to pass to `watch`.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            projectId: { ...id, description: 'The project.' },
+            content: { type: 'string', description: 'The prompt. Required unless sessionId is given.' },
+            sessionId: {
+                ...id,
+                description: 'An existing backlog session to start instead of creating one.',
+            },
+            title: {
+                type: 'string',
+                description: 'Session title; derived from the prompt when omitted.',
+            },
+            model: { type: 'string', description: 'Model id such as anthropic:sonnet__medium.' },
+            priority: { type: 'string', enum: ['urgent', 'high', 'medium', 'low', 'none'] },
+            startBranch: {
+                type: 'string',
+                description: 'Branch to fork from; the project default otherwise.',
+            },
+            attachments: {
+                type: 'array',
+                maxItems: 10,
+                description: 'Files to attach to the prompt, as paths on this machine.',
+                items: {
+                    type: 'object',
+                    properties: { path: { type: 'string' } },
+                    required: ['path'],
+                    additionalProperties: false,
+                },
+            },
+        },
+        required: ['projectId'],
+        additionalProperties: false,
+    },
+    readOnly: false,
+    async run(args, context) {
+        const { projectId, sessionId, content } = args;
+        const warnings = [];
+        let result;
+        if (typeof sessionId === 'string' && sessionId) {
+            result = await context.call('sessions_activate', { projectId, sessionId });
+            if (!result.ok)
+                return failed(result, 'sessions_activate');
+            warnings.push(...result.warnings);
+        }
+        else {
+            if (typeof content !== 'string' || !content.trim()) {
+                throw new UsageError('content is required unless sessionId names a backlog session.');
+            }
+            result = await context.call('sessions_create', pick(args, [
+                'projectId',
+                'content',
+                'title',
+                'model',
+                'priority',
+                'startBranch',
+                'attachments',
+            ]));
+            if (!result.ok)
+                return failed(result, 'sessions_create');
+            warnings.push(...result.warnings);
+            // Created with a prompt, the session is active and its first job is queued
+            // already; if the platform left it for us to start, start it.
+            if (!data(result).chatJobId) {
+                const session = data(result).session;
+                result = await context.call('sessions_activate', { projectId, sessionId: session?.id });
+                if (!result.ok)
+                    return failed(result, 'sessions_activate');
+                warnings.push(...result.warnings);
+            }
+        }
+        const payload = data(result);
+        const session = (payload.session ?? {});
+        return done(result, {
+            sessionId: session.id,
+            branchName: session.branchName,
+            status: session.status,
+            chatJobId: payload.chatJobId,
+            jobNumber: payload.jobNumber,
+            watch: { projectId, sessionId: session.id, jobId: payload.chatJobId },
+        }, warnings);
+    },
+};
+const watch = {
+    name: 'watch',
+    toolset: COMPOSITE_TOOLSET,
+    description: 'Follow a chat job, or the deploy, until it settles, reporting progress on the way. ' +
+        'Returns the final status and the last assistant message. Stops after timeoutSeconds ' +
+        '(default under the usual 60 s client limit; a longer wait needs a client that resets ' +
+        'its timeout on progress) ' +
+        'with done=false; call again to keep waiting.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            projectId: { ...id, description: 'The project.' },
+            sessionId: { ...id, description: 'The chat session; required unless deploy is true.' },
+            jobId: { ...id, description: 'The chat job; the latest one of the session when omitted.' },
+            deploy: { type: 'boolean', description: 'Watch the project deploy instead of a chat job.' },
+            timeoutSeconds: {
+                type: 'integer',
+                minimum: 5,
+                maximum: WATCH_MAX_SECONDS,
+                description: `How long to wait before returning done=false. Default ${WATCH_DEFAULT_SECONDS}.`,
+            },
+            pollSeconds: {
+                type: 'integer',
+                minimum: 1,
+                maximum: 60,
+                description: 'Seconds between polls.',
+            },
+        },
+        required: ['projectId'],
+        additionalProperties: false,
+    },
+    readOnly: true,
+    async run(args, context) {
+        const projectId = args.projectId;
+        const timeout = Number(args.timeoutSeconds ?? WATCH_DEFAULT_SECONDS) * 1000;
+        const interval = Number(args.pollSeconds ?? POLL_DEFAULT_SECONDS) * 1000;
+        const started = context.now();
+        const elapsed = () => Math.round((context.now() - started) / 1000);
+        const remaining = () => Math.max(0, timeout - (context.now() - started));
+        const aborted = () => context.signal?.aborted === true;
+        const timedOut = () => remaining() === 0 || aborted();
+        // Never past the deadline, and nothing more once the caller has gone.
+        // After the wait the deadline is tested again, so a budget shorter than
+        // the poll interval ends with the last observation, not one more request.
+        const pause = async () => {
+            if (aborted())
+                return;
+            await context.sleep(Math.min(interval, remaining()));
+        };
+        if (args.deploy === true) {
+            for (;;) {
+                const current = await context.call('deploy_messages', { projectId });
+                if (!current.ok)
+                    return failed(current, 'deploy_messages');
+                const payload = data(current);
+                const status = String(payload.status);
+                const summary = {
+                    kind: 'deploy',
+                    status,
+                    deployJobId: payload.deployJobId,
+                    error: payload.error,
+                    lastMessages: tail(payload.messages),
+                };
+                if (DEPLOY_SETTLED.has(status))
+                    return done(current, { done: true, ...summary });
+                if (timedOut())
+                    return done(current, { done: false, ...summary });
+                await context.progress(`deploy ${status}`, elapsed(), timeout / 1000);
+                await pause();
+                if (timedOut())
+                    return done(current, { done: false, ...summary });
+            }
+        }
+        const sessionId = args.sessionId;
+        if (typeof sessionId !== 'string' || !sessionId) {
+            throw new UsageError('sessionId is required unless deploy is true.');
+        }
+        let jobId = args.jobId;
+        if (!jobId) {
+            const session = await context.call('sessions_get', { projectId, sessionId });
+            if (!session.ok)
+                return failed(session, 'sessions_get');
+            const latest = data(session).latestChatJob;
+            if (!latest?.id)
+                throw new UsageError('This session has no chat job to watch.');
+            jobId = String(latest.id);
+        }
+        for (;;) {
+            const current = await context.call('sessions_jobs_get', { projectId, sessionId, jobId });
+            if (!current.ok)
+                return failed(current, 'sessions_jobs_get');
+            const job = (data(current).job ?? {});
+            const status = String(job.status);
+            if (CHAT_SETTLED.has(status)) {
+                const [messages, session] = await Promise.all([
+                    context.call('sessions_messages', { projectId, sessionId }),
+                    context.call('sessions_get', { projectId, sessionId }),
+                ]);
+                const list = messages.ok ? data(messages).messages : undefined;
+                const assistant = [...(list ?? [])].reverse().find((m) => m.role === 'assistant');
+                const info = session.ok ? data(session) : {};
+                const row = (info.session ?? {});
+                return done(current, {
+                    done: true,
+                    kind: 'chat',
+                    job,
+                    session: {
+                        status: row.status,
+                        branchName: row.branchName,
+                        pullRequestNumber: row.pullRequestNumber,
+                        prUrl: info.prUrl,
+                    },
+                    lastAssistantMessage: assistant ? messageText(assistant) : null,
+                });
+            }
+            if (timedOut())
+                return done(current, { done: false, kind: 'chat', job });
+            await context.progress(`chat job ${status}`, elapsed(), timeout / 1000);
+            await pause();
+            if (timedOut())
+                return done(current, { done: false, kind: 'chat', job });
+        }
+    },
+};
+const submit = {
+    name: 'submit',
+    toolset: COMPOSITE_TOOLSET,
+    description: 'Ask the session to open its pull request, or bring the open one up to date, by sending ' +
+        'the open-pr skill. Returns the job to pass to `watch`; the PR link is on the session ' +
+        'once the job settles.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            projectId: { ...id, description: 'The project.' },
+            sessionId: { ...id, description: 'The chat session whose branch becomes the pull request.' },
+            draft: { type: 'boolean', description: 'Open as a draft. Ignored once a PR exists.' },
+            reviewers: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Reviewers to request, matched loosely against GitHub logins.',
+            },
+            evidence: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Links to add under an evidence section.',
+            },
+            notes: { type: 'string', description: 'Freeform notes for the pull request body.' },
+        },
+        required: ['projectId', 'sessionId'],
+        additionalProperties: false,
+    },
+    readOnly: false,
+    async run(args, context) {
+        const { projectId, sessionId } = args;
+        const got = await context.call('sessions_get', { projectId, sessionId });
+        if (!got.ok)
+            return failed(got, 'sessions_get');
+        const session = (data(got).session ?? {});
+        if (session.status === 'backlog') {
+            throw new UsageError('This session is in the backlog; start it with `ship` first.');
+        }
+        // Codex reads `$open-pr`, Claude `/open-pr`, so the provider decides whether
+        // the message is a skill or prose, and a guess is a silent failure.
+        const resolved = await resolveProvider(session, projectId, context);
+        if ('failed' in resolved)
+            return resolved.failed;
+        const { provider, model } = resolved;
+        const skills = await context.call('projects_skills', { projectId, provider, sessionId });
+        if (!skills.ok)
+            return failed(skills, 'projects_skills');
+        const list = (data(skills).skills ?? []);
+        if (!list.some((skill) => skill.factoryId === 'open-pr' || skill.slug === 'open-pr')) {
+            throw new UsageError('The open-pr skill is not available to this session; enable it in Workspace settings.');
+        }
+        const content = openPrCommand(provider === 'openai' ? '$' : '/', args);
+        // When the session had no model, the one the provider was read from is
+        // sent along, so the turn runs on the provider the trigger was written for.
+        const sent = await context.call('sessions_send', {
+            projectId,
+            sessionId,
+            content,
+            ...(model ? { model } : {}),
+        });
+        if (!sent.ok)
+            return failed(sent, 'sessions_send');
+        const payload = data(sent);
+        return done(sent, {
+            sent: content,
+            delivery: payload.delivery,
+            chatJobId: payload.chatJobId,
+            steerId: payload.steerId,
+            pullRequestNumber: session.pullRequestNumber ?? null,
+            prUrl: data(got).prUrl ?? null,
+            watch: { projectId, sessionId, jobId: payload.chatJobId },
+        }, [...got.warnings, ...skills.warnings, ...sent.warnings]);
+    },
+};
+export const compositeTools = [ship, watch, submit];

package/dist/runtime/mcp-guard.js

@@ -0,0 +1,74 @@
+/**
+ * What a tool call may not carry. Tool arguments end up in the agent's
+ * transcript, so a credential given as one is a credential written down.
+ *
+ * Two levels, on purpose. A field whose meaning is "this is a secret" is
+ * refused outright: a provider key on `workspaces ai-provider set`, or an
+ * environment variable marked `isSecret`. Free text is only scanned, and
+ * what it looks like is reported back as a warning: prose quotes credential
+ * shapes all the time (this feature's own ticket contains `kosuke_...`), and
+ * a regex must not veto a legitimate message.
+ */
+export class RefusedArgument extends Error {
+}
+/** Body keys that carry a provider key on `workspaces ai-provider set`. */
+const PROVIDER_KEY_FIELDS = new Set(['anthropicApiKey', 'bedrockApiKey', 'openaiApiKey']);
+const SETTINGS_HINT = 'Tool arguments are visible in the agent history, so set it in Settings on the platform ' +
+    'or with the CLI instead.';
+export function refuseSecrets(args) {
+    walk(args, '', (value, path) => {
+        if (!isRecord(value))
+            return;
+        for (const field of Object.keys(value)) {
+            if (PROVIDER_KEY_FIELDS.has(field) && value[field] !== undefined && value[field] !== null) {
+                throw new RefusedArgument(`${join(path, field)} carries a provider key, which this tool refuses. ${SETTINGS_HINT}`);
+            }
+        }
+        if (value.isSecret === true && 'value' in value) {
+            throw new RefusedArgument(`${join(path, 'value')} is marked isSecret, which this tool refuses. ${SETTINGS_HINT}`);
+        }
+    });
+}
+/** Loose by design: a false positive costs a warning, a miss costs nothing more than today. */
+const CREDENTIAL_SHAPES = [
+    { label: 'a Kosuke auth token', pattern: /\bkosuke_[A-Za-z0-9_-]{4,}/ },
+    { label: 'an Anthropic API key', pattern: /\bsk-ant-[A-Za-z0-9_-]{8,}/ },
+    { label: 'an OpenAI API key', pattern: /\bsk-(?!ant-)[A-Za-z0-9_-]{16,}/ },
+    { label: 'an AWS access key id', pattern: /\bAKIA[0-9A-Z]{16}\b/ },
+    {
+        label: 'a GitHub token',
+        pattern: /\b(?:gh[pousr]_[A-Za-z0-9]{16,}|github_pat_[A-Za-z0-9_]{16,})/,
+    },
+    { label: 'a private key block', pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----/ },
+];
+/** One line per argument that looks like it quotes a credential; empty when none does. */
+export function credentialWarnings(args) {
+    const warnings = [];
+    walk(args, '', (value, path) => {
+        if (typeof value !== 'string')
+            return;
+        for (const shape of CREDENTIAL_SHAPES) {
+            if (shape.pattern.test(value)) {
+                warnings.push(`${path || 'an argument'} looks like it contains ${shape.label}. It was sent as given; ` +
+                    `if it is a real credential, it is now in the agent history and should be revoked.`);
+            }
+        }
+    });
+    return warnings;
+}
+function walk(value, path, visit) {
+    visit(value, path);
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => walk(item, `${path}[${index}]`, visit));
+    }
+    else if (isRecord(value)) {
+        for (const [key, item] of Object.entries(value))
+            walk(item, join(path, key), visit);
+    }
+}
+function join(path, key) {
+    return path ? `${path}.${key}` : key;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/runtime/mcp-invoke.js

@@ -0,0 +1,123 @@
+import { buildRequest, execute, UsageError } from './invoke.js';
+import { confineAttachment, stageAttachments } from './mcp-attachments.js';
+import { credentialWarnings, refuseSecrets, RefusedArgument } from './mcp-guard.js';
+import { redact } from './mcp-redact.js';
+import { ATTACHMENTS_ARGUMENT, BODY_ARGUMENT } from './mcp-tool.js';
+/** A tool name the server does not expose; distinct from bad arguments, since the cure differs. */
+export class UnknownTool extends Error {
+    constructor(name) {
+        super(`Unknown tool "${name}". List the tools to see what this server exposes.`);
+    }
+}
+function inputFor(operation, args, policy) {
+    const names = new Set([...operation.query, ...(operation.body?.fields ?? []), ...(operation.multipart ?? [])].map((field) => field.name));
+    const fields = {};
+    for (const name of names)
+        if (args[name] !== undefined)
+            fields[name] = args[name];
+    const wholeBody = operation.body?.fields === null && args[BODY_ARGUMENT] !== undefined
+        ? args[BODY_ARGUMENT]
+        : undefined;
+    // Each attachment is an object so a second shape (inline bytes, for a server
+    // that does not share the caller's disk) can sit beside `path` later.
+    // Each path is confined before anything reads it.
+    const attachments = Array.isArray(args[ATTACHMENTS_ARGUMENT])
+        ? args[ATTACHMENTS_ARGUMENT].map((item) => confineAttachment(item.path, policy))
+        : [];
+    // A missing id would become an empty path segment and a 404 that blames the
+    // wrong thing; a composite tool handing one on is the likely source.
+    const pathParams = {};
+    for (const name of operation.pathParams) {
+        const value = args[name];
+        if (typeof value !== 'string' || !value.trim()) {
+            throw new UsageError(`${name} is required and cannot be empty.`);
+        }
+        pathParams[name] = value;
+    }
+    return {
+        pathParams,
+        fields,
+        ...(wholeBody !== undefined ? { wholeBody } : {}),
+        attachments,
+    };
+}
+/** Throws RefusedArgument or UsageError before any request leaves. */
+export async function invokeTool(tool, args, context) {
+    refuseSecrets(args);
+    const warnings = credentialWarnings(args);
+    const input = inputFor(tool.operation, args, context.attachments);
+    // The shared request builder reads attachments by path; it gets private
+    // copies made from handles checked here, never the caller's paths again.
+    const staged = stageAttachments(input.attachments);
+    try {
+        let request;
+        try {
+            request = buildRequest(tool.operation, { ...input, attachments: staged.paths });
+        }
+        catch (error) {
+            if (error instanceof UsageError)
+                throw new UsageError(asToolUsage(tool, error.message));
+            throw error;
+        }
+        const outcome = await execute(context.clientFor(tool.operation.anonymous), request);
+        return { ok: outcome.ok, status: outcome.status, body: redact(outcome.body), warnings };
+    }
+    finally {
+        staged.cleanup();
+    }
+}
+/**
+ * The request builder speaks in flags, because the commands are its first
+ * caller. A model told to pass `--content` would try exactly that and be
+ * refused by the schema, so its messages are re-said in argument names.
+ */
+function asToolUsage(tool, message) {
+    const { operation } = tool;
+    let text = message
+        .replace(`kosuke ${operation.command.join(' ')}`, tool.name)
+        .replace('pass it whole with --body, --body-file or on stdin', 'pass it whole as body')
+        .replace('pass --body, or --body-file with a path or - for stdin', 'pass body')
+        .replaceAll('--body', BODY_ARGUMENT);
+    const fields = [
+        ...operation.query,
+        ...(operation.body?.fields ?? []),
+        ...(operation.multipart ?? []),
+    ];
+    for (const field of fields)
+        text = text.replaceAll(`--${field.flag}`, field.name);
+    return text;
+}
+/**
+ * A success is the platform's own envelope, `{ data, meta? }`, with the
+ * warnings beside it when there are any; a failure is the error envelope
+ * plus the status, flagged so the model reads it as one.
+ */
+export function toResult(invocation) {
+    const { ok, status, body, warnings } = invocation;
+    const extra = warnings.length ? { warnings } : {};
+    if (ok) {
+        const payload = body === undefined
+            ? { status, ...extra }
+            : typeof body === 'object' && body !== null && !Array.isArray(body)
+                ? { ...body, ...extra }
+                : { data: body, ...extra };
+        return { content: [text(payload)] };
+    }
+    const error = typeof body === 'object' && body !== null
+        ? body
+        : { error: body ?? `HTTP ${status}` };
+    return { content: [text({ status, ...error, ...extra })], isError: true };
+}
+export function errorResult(error) {
+    const message = error instanceof RefusedArgument
+        ? `Refused: ${error.message}`
+        : error instanceof UsageError
+            ? `Invalid arguments: ${error.message}`
+            : error instanceof Error
+                ? error.message
+                : String(error);
+    return { content: [{ type: 'text', text: message }], isError: true };
+}
+function text(value) {
+    return { type: 'text', text: JSON.stringify(value, null, 2) };
+}