@deepseek-harness-tui/dsh-tui 0.13.0 → 0.14.0

package/lib/types/backends/claude/dialogs.js

@@ -0,0 +1,253 @@
+import { createElicitationForm, createElicitationUrlAsk, elicitationNotices } from '../../channel/elicitation.js';
+import { t } from '../../i18n.js';
+import { errorText, rec, str } from './narrow.js';
+/** The dialog kinds this client renders (`supportedDialogKinds`). */
+export const SUPPORTED_DIALOG_KINDS = ['refusal_fallback_prompt'];
+// The form schema rules are the shared, backend-neutral ones
+// (`src/channel/elicitation.ts`); re-exported for this backend's callers.
+export { formFields, parseFieldText } from '../../channel/elicitation.js';
+/** Create the bridge for one session. */
+export function createClaudeDialogBridge(deps) {
+    /** By the ask id currently shown. */
+    const byAsk = new Map();
+    /** By the SDK request id. */
+    const byFlow = new Map();
+    const changed = () => {
+        try {
+            deps.onPendingChange?.(byFlow.size);
+        }
+        catch (error) {
+            deps.debug(`claude: dialog pending-change listener failed (${errorText(error)})`);
+        }
+    };
+    /** Show (or re-show) a flow's ask. */
+    const show = (entry, askId, questions) => {
+        byAsk.delete(entry.askId);
+        entry.askId = askId;
+        byAsk.set(askId, entry);
+        deps.emit([{ type: 'question.request', request: { requestId: askId, questions } }]);
+    };
+    /** Close a flow's panel and forget it (once). */
+    const close = (entry) => {
+        if (byFlow.get(entry.flow) !== entry)
+            return false;
+        byFlow.delete(entry.flow);
+        byAsk.delete(entry.askId);
+        deps.emit([{ type: 'question.settled', requestId: entry.askId }]);
+        changed();
+        return true;
+    };
+    /** Park a flow: its first ask, its abort wiring, its settlement. */
+    const park = (flow, signal, resolve, build) => {
+        let settled = false;
+        let round = 0;
+        let entry;
+        const resolvers = [resolve];
+        const signals = [signal];
+        const onAbort = () => { entry?.withdraw(); };
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            for (const each of signals.splice(0))
+                each.removeEventListener('abort', onAbort);
+            if (entry !== undefined)
+                close(entry);
+            for (const each of resolvers.splice(0))
+                each(result);
+        };
+        const reask = (questions) => {
+            if (settled || entry === undefined)
+                return;
+            round += 1;
+            // The old ask closes; the new one carries its own id.
+            deps.emit([{ type: 'question.settled', requestId: entry.askId }]);
+            show(entry, `${flow}~${round}`, questions);
+        };
+        const built = build(finish, reask);
+        entry = {
+            flow,
+            askId: flow,
+            kind: built.kind,
+            answer: built.answer,
+            dismiss: built.dismiss,
+            withdraw: () => finish(built.cancelled),
+            join: (more, moreSignal) => {
+                resolvers.push(more);
+                if (moreSignal.aborted) {
+                    finish(built.cancelled);
+                    return;
+                }
+                signals.push(moreSignal);
+                moreSignal.addEventListener('abort', onAbort, { once: true });
+            },
+            ...(built.url === undefined ? {} : { url: built.url }),
+            ...(built.complete === undefined ? {} : { complete: built.complete }),
+        };
+        byFlow.set(flow, entry);
+        byAsk.set(flow, entry);
+        signal.addEventListener('abort', onAbort, { once: true });
+        deps.emit([{ type: 'question.request', request: { requestId: flow, questions: built.questions } }]);
+        changed();
+    };
+    /** A form elicitation: its fields, then send / decline (the shared
+     *  form flow decides every round; this bridge only parks and answers). */
+    const form = (request, flow, signal, resolve) => {
+        const ask = createElicitationForm(request);
+        park(flow, signal, resolve, (finish, reask) => ({
+            kind: 'form',
+            questions: ask.questions,
+            cancelled: { action: 'cancel' },
+            answer: answers => {
+                const step = ask.answer(answers);
+                if (step.kind === 'reask')
+                    reask(step.questions);
+                else if (step.kind === 'decline')
+                    finish({ action: 'decline' });
+                else
+                    finish({ action: 'accept', content: { ...step.content } });
+            },
+            dismiss: () => finish({ action: 'cancel' }),
+        }));
+    };
+    /** A URL elicitation: the notice, then accept / decline with the link. */
+    const url = (request, flow, signal, resolve) => {
+        const ask = createElicitationUrlAsk(request);
+        if (ask === undefined) {
+            deps.emit([{ type: 'notice', level: 'warning', key: `elicit:${flow}`, text: elicitationNotices.urlMissing(request.serverName) }]);
+            resolve({ action: 'decline' });
+            return;
+        }
+        deps.emit([{ type: 'notice', level: 'info', key: `elicit-url:${request.elicitationId ?? flow}`, text: elicitationNotices.urlOpen(request.serverName, request.url) }]);
+        park(flow, signal, resolve, finish => ({
+            kind: 'url',
+            url: { server: request.serverName, ...(request.elicitationId === undefined ? {} : { elicitationId: request.elicitationId }) },
+            questions: ask.questions,
+            cancelled: { action: 'cancel' },
+            answer: answers => finish({ action: ask.accepted(answers) ? 'accept' : 'decline' }),
+            dismiss: () => finish({ action: 'cancel' }),
+            complete: () => finish({ action: 'accept' }),
+        }));
+    };
+    const onElicitation = (request, options) => new Promise(resolve => {
+        try {
+            const flow = `elicit-${options.requestId}`;
+            if (deps.closing()) {
+                resolve({ action: 'cancel' });
+                return;
+            }
+            const previous = byFlow.get(flow);
+            if (previous !== undefined) {
+                // A redelivered request (a transport gap) waits for the same answer.
+                previous.join(resolve, options.signal);
+                return;
+            }
+            if (options.signal.aborted) {
+                resolve({ action: 'cancel' });
+                return;
+            }
+            const mode = request.mode ?? 'form';
+            if (mode === 'form')
+                form(request, flow, options.signal, resolve);
+            else if (mode === 'url')
+                url(request, flow, options.signal, resolve);
+            else {
+                deps.emit([{ type: 'notice', level: 'warning', key: `elicit:${flow}`, text: elicitationNotices.unsupported(request.serverName, String(mode)) }]);
+                resolve({ action: 'decline' });
+            }
+        }
+        catch (error) {
+            deps.debug(`claude: elicitation failed (${errorText(error)})`);
+            resolve({ action: 'decline' });
+        }
+    });
+    /** The refusal-fallback dialog: retry on the fallback model, or cancel. */
+    const refusalFallback = (request, flow, signal, resolve) => {
+        const payload = rec(request.payload);
+        const fallback = str(payload?.fallbackModel);
+        const original = str(payload?.originalModel);
+        if (fallback === undefined || fallback === '') {
+            resolve({ behavior: 'cancelled' });
+            return;
+        }
+        const retry = t('claude-refusal-retry', { model: fallback });
+        const cancel = t('claude-refusal-cancel');
+        const category = str(payload?.apiRefusalCategory);
+        const detail = [
+            str(payload?.guidanceText)?.trim(),
+            category === undefined || category === '' ? undefined : t('claude-refusal-category', { category }),
+        ].filter((line) => line !== undefined && line !== '').join('\n');
+        park(flow, signal, resolve, finish => ({
+            kind: 'dialog',
+            questions: [{
+                    question: t('claude-refusal-question', { model: original ?? t('claude-refusal-this-model') }),
+                    header: t('claude-refusal-header'),
+                    ...(detail === '' ? {} : { detail }),
+                    options: [{ label: retry, description: t('claude-refusal-retry-desc') }, { label: cancel, description: t('claude-refusal-cancel-desc') }],
+                    hideCustomInput: true,
+                }],
+            cancelled: { behavior: 'cancelled' },
+            answer: answers => finish(answers.answers[0]?.selected[0] === retry
+                ? { behavior: 'completed', result: 'retry_fallback' }
+                : { behavior: 'completed', result: 'cancelled' }),
+            dismiss: () => finish({ behavior: 'cancelled' }),
+        }));
+    };
+    const onUserDialog = (request, options) => new Promise(resolve => {
+        try {
+            const flow = `dialog-${options.requestId}`;
+            if (deps.closing()) {
+                resolve({ behavior: 'cancelled' });
+                return;
+            }
+            const previous = byFlow.get(flow);
+            if (previous !== undefined) {
+                previous.join(resolve, options.signal);
+                return;
+            }
+            if (options.signal.aborted) {
+                resolve({ behavior: 'cancelled' });
+                return;
+            }
+            if (request.dialogKind === 'refusal_fallback_prompt') {
+                refusalFallback(request, flow, options.signal, resolve);
+                return;
+            }
+            // An undeclared kind: the SDK's contract answer (the CLI then applies
+            // the dialog's default).
+            deps.debug(`claude: dialog kind ${request.dialogKind} not rendered; cancelled`);
+            resolve({ behavior: 'cancelled' });
+        }
+        catch (error) {
+            deps.debug(`claude: dialog failed (${errorText(error)})`);
+            resolve({ behavior: 'cancelled' });
+        }
+    });
+    return {
+        onElicitation,
+        onUserDialog,
+        /** Whether an ask id is one of this bridge's (else the permission bridge's). */
+        owns: (askId) => byAsk.has(askId),
+        respond(askId, answers) {
+            byAsk.get(askId)?.answer(answers);
+        },
+        cancel(askId) {
+            byAsk.get(askId)?.dismiss();
+        },
+        /** `system/elicitation_complete`: the URL flow it names is done. */
+        complete(server, elicitationId) {
+            for (const entry of [...byFlow.values()]) {
+                if (entry.kind !== 'url' || entry.url?.server !== server || entry.url.elicitationId !== elicitationId)
+                    continue;
+                deps.emit([{ type: 'notice', level: 'info', key: `elicit-url:${elicitationId}`, text: elicitationNotices.urlComplete(server) }]);
+                entry.complete?.();
+            }
+        },
+        get size() { return byFlow.size; },
+        /** Withdraw everything (dispose, reconnect, a forced turn close). */
+        settleAll() {
+            for (const entry of [...byFlow.values()])
+                entry.withdraw();
+        },
+    };
+}

package/lib/types/backends/claude/flag-settings.d.ts

@@ -0,0 +1,12 @@
+export interface FlagSettingsFile {
+    /** What to pass as the SDK `settings` option. */
+    readonly path: string;
+    /** Remove the file (idempotent). */
+    dispose(): void;
+}
+/** Write one run's flag settings; throws when the file cannot be written
+ *  (the caller must not fall back to the inline form). */
+export declare function writeFlagSettingsFile(settings: {
+    readonly env: Readonly<Record<string, string>>;
+}): FlagSettingsFile;
+//# sourceMappingURL=flag-settings.d.ts.map

package/lib/types/backends/claude/flag-settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flag-settings.d.ts","sourceRoot":"","sources":["../../../../src/backends/claude/flag-settings.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,gBAAgB;IAC/B,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,oCAAoC;IACpC,OAAO,IAAI,IAAI,CAAA;CAChB;AAeD;0DAC0D;AAC1D,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAAE,GAAG,gBAAgB,CAepH"}

package/lib/types/backends/claude/flag-settings.js

@@ -0,0 +1,49 @@
+/**
+ * The flag-settings layer (the SDK `settings` option) as a private file.
+ *
+ * The SDK turns an inline `settings` object into `--settings <json>` on the
+ * CLI's command line, where any local user can read it (`ps`,
+ * `/proc/<pid>/cmdline`), and a channel's token rides that layer. Passed as
+ * a path instead, it is the same layer (the CLI reads the file into its flag
+ * settings) and the token stays out of argv. The file is owner-only, inside
+ * a fresh directory under the system temp directory (0700 on POSIX; the
+ * per-user temp directory on Windows), and lives exactly as long as the CLI
+ * that reads it: the caller disposes it when the run stops, and whatever is
+ * still open when the process exits is removed then.
+ */
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+/** Directories not yet disposed, removed on process exit. */
+const live = new Set();
+let exitHooked = false;
+function remove(dir) {
+    live.delete(dir);
+    try {
+        rmSync(dir, { recursive: true, force: true });
+    }
+    catch {
+        // Already gone, or the platform holds it for a moment: nothing to do.
+    }
+}
+/** Write one run's flag settings; throws when the file cannot be written
+ *  (the caller must not fall back to the inline form). */
+export function writeFlagSettingsFile(settings) {
+    if (!exitHooked) {
+        exitHooked = true;
+        process.once('exit', () => { for (const dir of [...live])
+            remove(dir); });
+    }
+    const dir = mkdtempSync(join(tmpdir(), 'dsh-tui-claude-flags-'));
+    live.add(dir);
+    const path = join(dir, 'settings.json');
+    try {
+        writeFileSync(path, JSON.stringify({ env: settings.env }), { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+    }
+    catch (error) {
+        remove(dir);
+        throw error;
+    }
+    return { path, dispose: () => { if (live.has(dir))
+            remove(dir); } };
+}

package/lib/types/backends/claude/images.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Image input for Claude sessions: the limits the composer stages
+ * images under (the `images` capability), the base64 image blocks a user
+ * message carries after its text, and the lazy facades a transcript image
+ * block replays as.
+ *
+ * Limits (the Anthropic Messages API): PNG / JPEG / GIF / WebP, at most
+ * 5 MiB per image after the composer's downsample path; a message carries
+ * at most 20 images (the API's dimension cap tightens to 2000 px per side
+ * beyond 20) and 20 MiB of image bytes (≈ 27 MB of base64, under the 32 MB
+ * request cap); images are resampled into 2000 px per side / 4 MP — the API
+ * scales larger ones down anyway.
+ *
+ * Replay: `getSessionMessages` returns the base64 blocks as sent. A facade
+ * keeps the base64 string the transcript already holds and decodes nothing
+ * until asked: its size is probed from a short decoded prefix on first
+ * access, its bytes decoded on `read()` — no pixels in the projection.
+ */
+import type { TranscriptImage } from '../../adapter/ports/channel-view.js';
+import type { ImageLimitsView } from '../../agent/capabilities.js';
+import type { ImageRef } from '../../agent/events.js';
+/** What a Claude message may carry (see the module comment). */
+export declare const CLAUDE_IMAGE_LIMITS: ImageLimitsView;
+/** One base64 image block as the Messages API takes it. */
+export interface ClaudeImageBlock {
+    readonly type: 'image';
+    readonly source: {
+        readonly type: 'base64';
+        readonly media_type: 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp';
+        readonly data: string;
+    };
+}
+/**
+ * The image blocks of one message, in order: every staged image read back
+ * and checked against the limits once more (a limit change, a foreign
+ * facade). Throws a user-facing sentence when one cannot be sent — never a
+ * message silently missing an image.
+ */
+export declare function claudeImageBlocks(images: readonly TranscriptImage[], limits?: ImageLimitsView): Promise<ClaudeImageBlock[]>;
+/**
+ * A lazy facade over one base64 image the transcript holds: the size is
+ * probed on first access (a decoded prefix; the whole image only when the
+ * prefix does not reach the size header), the bytes decoded on `read()`.
+ */
+export declare function base64ImageFacade(id: string, mediaType: string, data: string): TranscriptImage;
+/** The base64 image blocks of a user message's content, as lazy facades
+ *  (`<idPrefix>#<n>`); other sources (URLs, files) are not shown. */
+export declare function transcriptImages(content: unknown, idPrefix: string): ImageRef[];
+//# sourceMappingURL=images.d.ts.map

package/lib/types/backends/claude/images.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"images.d.ts","sourceRoot":"","sources":["../../../../src/backends/claude/images.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAA;AAC1E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAA;AAClE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AAKrD,gEAAgE;AAChE,eAAO,MAAM,mBAAmB,EAAE,eAOhC,CAAA;AAEF,2DAA2D;AAC3D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;QAAC,QAAQ,CAAC,UAAU,EAAE,WAAW,GAAG,YAAY,GAAG,WAAW,GAAG,YAAY,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;CAClJ;AAKD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,EAAE,MAAM,GAAE,eAAqC,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAmBtJ;AAWD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,eAAe,CAiB9F;AAED;qEACqE;AACrE,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,QAAQ,EAAE,CAa/E"}

package/lib/types/backends/claude/images.js

@@ -0,0 +1,94 @@
+import { t } from '../../i18n.js';
+import { probeImageSize } from '../../utils/imageResize.js';
+import { rec } from './narrow.js';
+/** What a Claude message may carry (see the module comment). */
+export const CLAUDE_IMAGE_LIMITS = Object.freeze({
+    mediaTypes: Object.freeze(['image/png', 'image/jpeg', 'image/gif', 'image/webp']),
+    maxImageBytes: 5 * 1024 * 1024,
+    maxImagesPerMessage: 20,
+    maxMessageImageBytes: 20 * 1024 * 1024,
+    maxImageDimension: 2000,
+    maxImagePixels: 4_000_000,
+});
+const isAccepted = (mediaType) => mediaType !== undefined && CLAUDE_IMAGE_LIMITS.mediaTypes.includes(mediaType);
+/**
+ * The image blocks of one message, in order: every staged image read back
+ * and checked against the limits once more (a limit change, a foreign
+ * facade). Throws a user-facing sentence when one cannot be sent — never a
+ * message silently missing an image.
+ */
+export async function claudeImageBlocks(images, limits = CLAUDE_IMAGE_LIMITS) {
+    if (images.length > limits.maxImagesPerMessage)
+        throw new Error(t('claude-images-too-many', { n: limits.maxImagesPerMessage }));
+    const blocks = [];
+    let total = 0;
+    for (const image of images) {
+        const label = image.name ?? image.id;
+        if (!isAccepted(image.mediaType) || !limits.mediaTypes.includes(image.mediaType))
+            throw new Error(t('claude-image-type-refused', { name: label, type: image.mediaType ?? '?' }));
+        let data;
+        try {
+            data = await image.read();
+        }
+        catch (error) {
+            throw new Error(t('claude-image-unreadable', { name: label, err: error instanceof Error ? error.message : String(error) }));
+        }
+        if (data.byteLength > limits.maxImageBytes)
+            throw new Error(t('claude-image-too-large', { name: label, mb: Math.round(limits.maxImageBytes / (1024 * 1024)) }));
+        total += data.byteLength;
+        if (total > limits.maxMessageImageBytes)
+            throw new Error(t('claude-images-too-large', { mb: Math.round(limits.maxMessageImageBytes / (1024 * 1024)) }));
+        blocks.push({ type: 'image', source: { type: 'base64', media_type: image.mediaType, data: Buffer.from(data.buffer, data.byteOffset, data.byteLength).toString('base64') } });
+    }
+    return blocks;
+}
+/** Base64 characters decoded to probe an image's size (a multiple of 4: ≈ 64 KiB). */
+const PROBE_CHARS = 87_384;
+/** The decoded byte length of a base64 string (no decoding). */
+function decodedLength(data) {
+    const padding = data.endsWith('==') ? 2 : data.endsWith('=') ? 1 : 0;
+    return Math.max(0, Math.floor(data.length * 3 / 4) - padding);
+}
+/**
+ * A lazy facade over one base64 image the transcript holds: the size is
+ * probed on first access (a decoded prefix; the whole image only when the
+ * prefix does not reach the size header), the bytes decoded on `read()`.
+ */
+export function base64ImageFacade(id, mediaType, data) {
+    let size;
+    const measure = () => {
+        if (size !== undefined)
+            return size;
+        const head = Buffer.from(data.slice(0, PROBE_CHARS), 'base64');
+        size = probeImageSize(head) ?? (data.length > PROBE_CHARS ? probeImageSize(Buffer.from(data, 'base64')) : null);
+        return size;
+    };
+    return {
+        id,
+        mediaType,
+        bytes: decodedLength(data),
+        // A size the probe cannot read lays out square (the preview still loads).
+        get width() { return measure()?.width ?? 1; },
+        get height() { return measure()?.height ?? 1; },
+        read: () => Promise.resolve(new Uint8Array(Buffer.from(data, 'base64'))),
+    };
+}
+/** The base64 image blocks of a user message's content, as lazy facades
+ *  (`<idPrefix>#<n>`); other sources (URLs, files) are not shown. */
+export function transcriptImages(content, idPrefix) {
+    if (!Array.isArray(content))
+        return [];
+    const images = [];
+    content.forEach((raw, index) => {
+        const block = rec(raw);
+        const source = rec(block?.source);
+        if (block?.type !== 'image' || source?.type !== 'base64')
+            return;
+        const data = source.data;
+        const mediaType = source.media_type;
+        if (typeof data !== 'string' || data === '' || typeof mediaType !== 'string')
+            return;
+        images.push(base64ImageFacade(`${idPrefix}#${index}`, mediaType, data));
+    });
+    return images;
+}

package/lib/types/backends/claude/index.d.ts

@@ -0,0 +1,5 @@
+/** The Claude Agent backend (the only directory that may import `@anthropic-ai/*`). */
+export { claudeBackend } from './backend.js';
+export { CLAUDE_BACKEND_ID, CLAUDE_BACKEND_LABEL, VALIDATED_CLI_VERSIONS, VALIDATED_SDK_VERSION, claudeResumeCommand } from './contract.js';
+export { fileClaudePrefs } from './prefs.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/backends/claude/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/backends/claude/index.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC5C,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AAC3I,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA"}

package/lib/types/backends/claude/index.js

@@ -0,0 +1,4 @@
+/** The Claude Agent backend (the only directory that may import `@anthropic-ai/*`). */
+export { claudeBackend } from './backend.js';
+export { CLAUDE_BACKEND_ID, CLAUDE_BACKEND_LABEL, VALIDATED_CLI_VERSIONS, VALIDATED_SDK_VERSION, claudeResumeCommand } from './contract.js';
+export { fileClaudePrefs } from './prefs.js';

package/lib/types/backends/claude/install.d.ts

@@ -0,0 +1,15 @@
+import type { SdkInstallTarget, SdkInstaller } from '../../agent/backend.js';
+/** What `pnpm add` installs, at the validated pin (see contract.ts). */
+export declare const CLAUDE_SDK_SPECIFIER = "@anthropic-ai/claude-agent-sdk@0.3.287";
+export type { SdkInstallTarget, SdkInstallResult, SdkInstaller } from '../../agent/backend.js';
+/** Resolve the install target for the CURRENT launch (never throws). The
+ *  non-profile kinds carry the reason for the wizard's manual-instructions
+ *  panel: standalone builds swap a whole binary (update.ts owns that path),
+ *  and source checkouts / `--config` launches have no profile to add into. */
+export declare function resolveSdkInstallTarget(argv?: readonly string[]): SdkInstallTarget;
+/** Whether `pnpm` runs at all (the wizard's preflight). */
+export declare function checkPnpmAvailable(): Promise<boolean>;
+/** Install the pinned SDK into the profile root. Resolve target failures are
+ *  the caller's business (the wizard shows manual instructions for them). */
+export declare function startClaudeSdkInstall(dir: string): SdkInstaller;
+//# sourceMappingURL=install.d.ts.map

package/lib/types/backends/claude/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../../src/backends/claude/install.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAoB,gBAAgB,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAK9F,wEAAwE;AACxE,eAAO,MAAM,oBAAoB,2CAA4D,CAAA;AAE7F,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAE9F;;;8EAG8E;AAC9E,wBAAgB,uBAAuB,CAAC,IAAI,GAAE,SAAS,MAAM,EAAiB,GAAG,gBAAgB,CAIhG;AA2CD,2DAA2D;AAC3D,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,OAAO,CAAC,CAI3D;AAED;6EAC6E;AAC7E,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,CAU/D"}

package/lib/types/backends/claude/install.js

@@ -0,0 +1,91 @@
+/**
+ * One-shot installer for the optional `@anthropic-ai/claude-agent-sdk` peer.
+ *
+ * Runs `pnpm add <sdk>@<pin>` in the DSH profile root — the install dir whose
+ * `node_modules` the backend's dynamic import resolves through. Everything the
+ * child prints is piped and captured, never inherited: an inherit-stdio child
+ * may only run after the Ink frame is unmounted (the update.ts contract); a
+ * captured one may run under the live TUI, which is what the kernel-picker
+ * install wizard needs. Only the tail of the captured output is surfaced, on
+ * failure.
+ *
+ * The pinned SDK version is old enough that pnpm's minimumReleaseAge gate
+ * never blocks it; if the pin ever moves to a version published within the
+ * gate's window, the install needs a `minimumReleaseAgeExclude` entry
+ * (generalize `ensureProfileReleaseAgeExclude` in update.ts then).
+ */
+import { spawn } from 'node:child_process';
+import { homedir } from 'node:os';
+import { dirname } from 'node:path';
+import stripAnsi from 'strip-ansi';
+import { isStandaloneRuntime, profileWorkspaceYamlPath, resolveDshProfileName } from '../../update.js';
+import { shellQuote } from '../../utils/shellQuote.js';
+import { VALIDATED_SDK_VERSION } from './contract.js';
+/** What `pnpm add` installs, at the validated pin (see contract.ts). */
+export const CLAUDE_SDK_SPECIFIER = `@anthropic-ai/claude-agent-sdk@${VALIDATED_SDK_VERSION}`;
+/** Resolve the install target for the CURRENT launch (never throws). The
+ *  non-profile kinds carry the reason for the wizard's manual-instructions
+ *  panel: standalone builds swap a whole binary (update.ts owns that path),
+ *  and source checkouts / `--config` launches have no profile to add into. */
+export function resolveSdkInstallTarget(argv = process.argv) {
+    if (isStandaloneRuntime())
+        return { kind: 'standalone' };
+    const profile = resolveDshProfileName(argv);
+    return profile === undefined ? { kind: 'no-profile' } : { kind: 'profile', dir: dirname(profileWorkspaceYamlPath(profile)) };
+}
+/** Run pnpm with captured output. On Windows the arguments fold into the
+ *  command string and go through the shell — pnpm is a `.cmd` shim there and
+ *  Node ≥22 refuses to spawn `.cmd` directly (DEP0190) — the same escape
+ *  update.ts's runProcess uses. */
+function runPnpm(args, cwd) {
+    const windows = process.platform === 'win32';
+    const [command, spawnArgs] = windows
+        ? [`pnpm ${shellQuote(args).join(' ')}`, []]
+        : ['pnpm', [...args]];
+    const child = spawn(command, spawnArgs, {
+        cwd,
+        shell: windows,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true,
+    });
+    const chunks = [];
+    for (const stream of [child.stdout, child.stderr]) {
+        if (stream === null)
+            continue;
+        stream.setEncoding('utf8');
+        stream.on('data', (chunk) => { chunks.push(chunk); });
+    }
+    const promise = new Promise(resolve => {
+        const finish = (code, spawnError) => {
+            // pnpm progress frames redraw with \r — split on all line breaks, strip
+            // the ANSI layer, drop the empty frames the redraws leave behind.
+            const lines = chunks.join('').split(/\r\n|\r|\n/u).map(line => stripAnsi(line).trim()).filter(line => line !== '');
+            resolve({ code, spawnError, lines });
+        };
+        child.once('error', error => finish(undefined, error.code));
+        child.once('close', code => finish(code ?? undefined));
+    });
+    return { promise, cancel: () => { child.kill(); } };
+}
+/** Whether `pnpm` runs at all (the wizard's preflight). */
+export async function checkPnpmAvailable() {
+    const { promise } = runPnpm(['--version'], homedir());
+    const run = await promise;
+    return run.code === 0 && run.spawnError === undefined;
+}
+/** Install the pinned SDK into the profile root. Resolve target failures are
+ *  the caller's business (the wizard shows manual instructions for them). */
+export function startClaudeSdkInstall(dir) {
+    let cancelled = false;
+    const { promise, cancel } = runPnpm(['add', CLAUDE_SDK_SPECIFIER], dir);
+    const result = promise.then(run => {
+        if (cancelled)
+            return { kind: 'cancelled' };
+        if (run.code === 0)
+            return { kind: 'ok' };
+        if (run.spawnError === 'ENOENT')
+            return { kind: 'pnpm-missing' };
+        return { kind: 'failed', exitCode: run.code ?? 1, tail: run.lines.slice(-10) };
+    });
+    return { result, cancel: () => { cancelled = true; cancel(); } };
+}