dsh-agy-cli 0.0.0-stage → 0.12.1

package/lib/provider/image-bridge.js

@@ -0,0 +1,290 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, mkdtemp, readdir, rm, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { dshHome } from '../dsh-home.js';
+import { serializeAgyPrompt, serializeAgyTurnPrompt } from './serialize.js';
+export const IMAGE_MEDIA_TYPES = ['image/png', 'image/jpeg', 'image/webp', 'image/gif'];
+/** Placeholder media type for a history image of an unsupported kind. */
+export const FALLBACK_IMAGE_MEDIA_TYPE = 'image/png';
+export const DEFAULT_IMAGE_MAX_BYTES = 8 * 1024 * 1024;
+export const DEFAULT_IMAGE_MAX_COUNT = 4;
+/**
+ * Images carried by the turn being answered are staged into a per-request temp
+ * directory and counted against `DEFAULT_IMAGE_MAX_COUNT`. Images from earlier
+ * turns are not: the request only accepts a handful of new ones, and rewriting
+ * every historical attachment on every turn is pure cost. They are materialized
+ * once into this stable cache instead, so their placeholder can still be opened
+ * on demand by the image-view Agent (or by the user in Explorer) long after the
+ * turn that uploaded them is over.
+ */
+export const IMAGE_HISTORY_CACHE_DIR = join(dshHome(), 'agy-cli', 'image-cache');
+const IMAGE_HISTORY_CACHE_MAX_AGE_MS = 14 * 24 * 60 * 60 * 1000;
+export class AgyImageBridgeError extends Error {
+    code;
+    constructor(message, code, options) {
+        super(message, options);
+        this.code = code;
+        this.name = 'AgyImageBridgeError';
+    }
+}
+const EXTENSIONS = {
+    'image/png': '.png',
+    'image/jpeg': '.jpg',
+    'image/webp': '.webp',
+    'image/gif': '.gif',
+};
+function imageRefsOf(content, output = []) {
+    for (const block of content) {
+        if (block.type === 'image')
+            output.push(block.attachment);
+    }
+    return output;
+}
+function imageKey(ref) {
+    return String(ref.attachmentId);
+}
+function mediaTypeOf(value) {
+    return IMAGE_MEDIA_TYPES.includes(value);
+}
+function placeholderFor(image) {
+    const meta = `media_type=${image.mediaType} width=${image.width} height=${image.height}`;
+    if (image.path === undefined) {
+        return `[IMAGE_ATTACHMENT ${meta} earlier_turn=unavailable]`;
+    }
+    return image.history
+        ? `[IMAGE_ATTACHMENT file=${image.path} ${meta} earlier_turn=cached]`
+        : `[IMAGE_ATTACHMENT file=${image.path} ${meta}]`;
+}
+function replaceImageBlocks(content, images) {
+    return content.map(block => {
+        if (block.type === 'image') {
+            const image = images.get(imageKey(block.attachment));
+            if (image === undefined) {
+                throw new AgyImageBridgeError('Image attachment was not staged', 'IMAGE_STAGING_FAILED');
+            }
+            return { type: 'text', text: placeholderFor(image) };
+        }
+        return block;
+    });
+}
+function replaceMessageImages(messages, images) {
+    return messages.map(message => ({
+        ...message,
+        content: replaceImageBlocks(message.content, images),
+    }));
+}
+function validateStoredImage(requested, stored, totalBytes, maxBytes) {
+    const ref = stored.ref;
+    if (String(ref.attachmentId) !== String(requested.attachmentId)) {
+        throw new AgyImageBridgeError('Attachment store returned a different image reference', 'IMAGE_READ_FAILED');
+    }
+    if (!mediaTypeOf(ref.mediaType)) {
+        throw new AgyImageBridgeError(`Unsupported image media type: ${ref.mediaType}`, 'IMAGE_UNSUPPORTED_MEDIA_TYPE');
+    }
+    if (stored.data.byteLength !== ref.bytes || ref.bytes !== requested.bytes) {
+        throw new AgyImageBridgeError('Image attachment byte length failed verification', 'IMAGE_READ_FAILED');
+    }
+    const nextTotalBytes = totalBytes + stored.data.byteLength;
+    if (nextTotalBytes > maxBytes) {
+        throw new AgyImageBridgeError(`Image attachments exceed the ${maxBytes}-byte staging limit`, 'IMAGE_SIZE_LIMIT');
+    }
+    return { mediaType: ref.mediaType, nextTotalBytes };
+}
+async function stageImages(refs, options) {
+    const store = options.attachmentStore;
+    if (store === undefined) {
+        throw new AgyImageBridgeError('Image input requires an available DSH AttachmentStore; configure text-only mode or install the attachment service', 'IMAGE_ATTACHMENT_UNAVAILABLE');
+    }
+    const maxBytes = options.maxBytes ?? DEFAULT_IMAGE_MAX_BYTES;
+    const maxCount = options.maxCount ?? DEFAULT_IMAGE_MAX_COUNT;
+    const uniqueRefs = [...new Map(refs.map(ref => [imageKey(ref), ref])).values()];
+    // Only the turn being answered is staged, so this budget is per message, not
+    // per conversation: earlier images are reference-only placeholders.
+    if (uniqueRefs.length > maxCount) {
+        throw new AgyImageBridgeError(`Agy image bridge accepts at most ${maxCount} images per request`, 'IMAGE_SIZE_LIMIT');
+    }
+    let directory;
+    try {
+        directory = await mkdtemp(join(tmpdir(), 'dsh-agy-image-'));
+        const images = new Map();
+        let totalBytes = 0;
+        for (const [index, ref] of uniqueRefs.entries()) {
+            let stored;
+            try {
+                stored = await store.readImage(ref, options.signal);
+            }
+            catch (error) {
+                if (error instanceof AgyImageBridgeError)
+                    throw error;
+                throw new AgyImageBridgeError('AttachmentStore could not read the image', 'IMAGE_READ_FAILED', { cause: error });
+            }
+            const validation = validateStoredImage(ref, stored, totalBytes, maxBytes);
+            totalBytes = validation.nextTotalBytes;
+            const path = join(directory, `image-${index}-${randomUUID()}${EXTENSIONS[validation.mediaType]}`);
+            await writeFile(path, stored.data, { flag: 'wx', mode: 0o600 });
+            images.set(imageKey(ref), {
+                path,
+                mediaType: validation.mediaType,
+                width: stored.ref.width,
+                height: stored.ref.height,
+                history: false,
+            });
+        }
+        let cleaned = false;
+        const cleanup = async () => {
+            if (cleaned || directory === undefined)
+                return;
+            cleaned = true;
+            await rm(directory, { recursive: true, force: true });
+        };
+        return { directory, images, cleanup };
+    }
+    catch (error) {
+        if (directory !== undefined)
+            await rm(directory, { recursive: true, force: true }).catch(() => undefined);
+        if (error instanceof AgyImageBridgeError)
+            throw error;
+        throw new AgyImageBridgeError(`Could not stage image attachments: ${error instanceof Error ? error.message : String(error)}`, 'IMAGE_STAGING_FAILED', { cause: error });
+    }
+}
+function cacheFileName(ref, mediaType) {
+    return `${String(ref.attachmentId).replace(/[^A-Za-z0-9._-]/g, '_')}${EXTENSIONS[mediaType]}`;
+}
+let cachePruned = false;
+/** Best-effort age-based pruning; a stale cache file costs disk, never correctness. */
+async function pruneImageHistoryCache() {
+    if (cachePruned)
+        return;
+    cachePruned = true;
+    try {
+        const entries = await readdir(IMAGE_HISTORY_CACHE_DIR);
+        const now = Date.now();
+        for (const entry of entries) {
+            const path = join(IMAGE_HISTORY_CACHE_DIR, entry);
+            const info = await stat(path).catch(() => undefined);
+            if (info !== undefined && info.isFile() && now - info.mtimeMs > IMAGE_HISTORY_CACHE_MAX_AGE_MS) {
+                await rm(path, { force: true }).catch(() => undefined);
+            }
+        }
+    }
+    catch {
+        // No cache directory yet, or it is unreadable: the bridge still works, it
+        // just has nothing to reuse.
+    }
+}
+/**
+ * Materialize earlier turns' images into the stable cache. A failure here is not
+ * fatal on purpose: one unreadable attachment must not resurrect the very
+ * problem this path exists to fix, so it degrades to a placeholder that says
+ * `earlier_turn=unavailable` instead of failing the whole request.
+ */
+async function cacheHistoryImages(refs, options) {
+    const images = new Map();
+    const store = options.attachmentStore;
+    await pruneImageHistoryCache();
+    for (const ref of refs) {
+        const key = imageKey(ref);
+        if (!mediaTypeOf(ref.mediaType)) {
+            // An unsupported media type degrades to the same unavailable placeholder
+            // as an unreadable attachment: omitting the entry would make
+            // replaceImageBlocks throw IMAGE_STAGING_FAILED for every later turn of
+            // this conversation ("one unreadable attachment must not be fatal").
+            images.set(key, { path: undefined, mediaType: FALLBACK_IMAGE_MEDIA_TYPE, width: ref.width ?? 0, height: ref.height ?? 0, history: true });
+            continue;
+        }
+        const mediaType = ref.mediaType;
+        const width = ref.width ?? 0;
+        const height = ref.height ?? 0;
+        if (store === undefined) {
+            images.set(key, { path: undefined, mediaType, width, height, history: true });
+            continue;
+        }
+        const path = join(IMAGE_HISTORY_CACHE_DIR, cacheFileName(ref, mediaType));
+        try {
+            await mkdir(IMAGE_HISTORY_CACHE_DIR, { recursive: true });
+            if ((await stat(path).catch(() => undefined)) === undefined) {
+                const stored = await store.readImage(ref, options.signal);
+                await writeFile(path, stored.data, { flag: 'w', mode: 0o600 });
+            }
+            images.set(key, { path, mediaType, width, height, history: true });
+        }
+        catch {
+            images.set(key, { path: undefined, mediaType, width, height, history: true });
+        }
+    }
+    return images;
+}
+function lastAssistantIndex(messages) {
+    let index = -1;
+    messages.forEach((message, at) => {
+        if (message.role === 'assistant')
+            index = at;
+    });
+    return index;
+}
+/**
+ * Prepare text prompts for the experimental file bridge.
+ *
+ * Only the turn being answered is staged: the place budget belongs to one
+ * message, and a conversation accumulates images forever, so counting the whole
+ * replayed history used to kill every later turn once a fifth image existed.
+ * Earlier turns keep a placeholder that still points at a real file under
+ * `IMAGE_HISTORY_CACHE_DIR`, so nothing is thrown away — the image-view Agent
+ * can open it the moment the model actually needs it, one turn or fifty turns
+ * later, and the user can open the same path in Explorer.
+ */
+export async function prepareAgyPrompts(options, bridgeOptions) {
+    const anyImage = imageRefsOf(options.messages.flatMap(message => message.content));
+    if (anyImage.length === 0 || !bridgeOptions.enabled) {
+        return {
+            fullPrompt: serializeAgyPrompt(options),
+            turnPrompt: undefined,
+            imageDirectory: undefined,
+            imageCacheDirectory: undefined,
+            imagePaths: [],
+            bridgeActive: false,
+            cleanup: async () => undefined,
+        };
+    }
+    if (!bridgeOptions.agentCanViewFile) {
+        throw new AgyImageBridgeError('Experimental image input requires the bundled image-view Agent with view_file', 'IMAGE_AGENT_UNSUPPORTED');
+    }
+    // Everything after the last assistant message is the turn being answered;
+    // `serializeAgyTurnPrompt` slices at exactly the same boundary.
+    const turnStart = lastAssistantIndex(options.messages) + 1;
+    const currentRefs = [];
+    const historyRefs = [];
+    options.messages.forEach((message, index) => {
+        const bucket = index >= turnStart ? currentRefs : historyRefs;
+        for (const ref of imageRefsOf(message.content))
+            bucket.push(ref);
+    });
+    const staged = currentRefs.length === 0
+        ? { directory: undefined, images: new Map(), cleanup: async () => undefined }
+        : await stageImages(currentRefs, bridgeOptions);
+    const history = historyRefs.length === 0
+        ? new Map()
+        : await cacheHistoryImages(historyRefs, bridgeOptions);
+    const images = new Map([...history, ...staged.images]);
+    try {
+        const messages = replaceMessageImages(options.messages, images);
+        return {
+            fullPrompt: serializeAgyPrompt({
+                ...(options.system === undefined ? {} : { system: options.system }),
+                messages,
+            }),
+            turnPrompt: serializeAgyTurnPrompt({ messages }),
+            imageDirectory: staged.directory,
+            imageCacheDirectory: historyRefs.length === 0 ? undefined : IMAGE_HISTORY_CACHE_DIR,
+            imagePaths: [...images.values()].flatMap(image => (image.path === undefined ? [] : [image.path])),
+            bridgeActive: true,
+            cleanup: staged.cleanup,
+        };
+    }
+    catch (error) {
+        await staged.cleanup();
+        throw error;
+    }
+}
+//# sourceMappingURL=image-bridge.js.map

package/lib/provider/mock.d.ts

@@ -0,0 +1,15 @@
+import { LlmAdapter } from '@deepseek-ai/dsh-llm';
+import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, StreamChunk } from '@deepseek-ai/dsh-llm';
+import { type Config } from './config.js';
+export declare class MockAdapter extends LlmAdapter {
+    private readonly model;
+    private readonly models;
+    private readonly response;
+    private readonly delayMs;
+    constructor(config?: Config);
+    providerInfo(provider: string): LlmProviderInfo;
+    listModels(provider: string): Promise<readonly LlmModelInfo[]>;
+    resolveModel(provider: string, model: string, _signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+}
+//# sourceMappingURL=mock.d.ts.map

package/lib/provider/mock.js

@@ -0,0 +1,78 @@
+import { LlmAdapter, LlmError } from '@deepseek-ai/dsh-llm';
+import { configuredModels, normalizeModelId } from './config.js';
+const DEFAULT_PROVIDER = 'agy-mock';
+const DEFAULT_MOCK_MODEL = 'agy-mock-model';
+const DEFAULT_RESPONSE = 'AGY mock provider is ready.';
+function abortError() {
+    return new LlmError('AGY mock request aborted by caller', 'ABORTED');
+}
+function wait(ms, signal) {
+    if (ms === 0)
+        return Promise.resolve();
+    if (signal?.aborted)
+        return Promise.reject(abortError());
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            reject(abortError());
+        };
+        // The happy path must release its listener too: without this, every timed
+        // mock stream leaves one 'abort' listener attached until the signal dies.
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+export class MockAdapter extends LlmAdapter {
+    model;
+    models;
+    response;
+    delayMs;
+    constructor(config = {}) {
+        super();
+        this.model = config.model !== undefined ? normalizeModelId(config.model) : DEFAULT_MOCK_MODEL;
+        this.models = configuredModels({ ...config, model: this.model }).map(m => ({ ...m, id: normalizeModelId(m.id) }));
+        this.response = config.response ?? DEFAULT_RESPONSE;
+        this.delayMs = config.delayMs ?? 0;
+    }
+    providerInfo(provider) {
+        return { id: provider, name: 'AGY (Mock)' };
+    }
+    listModels(provider) {
+        return Promise.resolve(this.models.map(model => ({
+            provider,
+            id: model.id,
+            name: model.name ?? 'AGY Mock Model',
+            description: model.description ?? 'DSH Provider contract probe; does not consume AGY quota.',
+            inputModalities: ['text'],
+        })));
+    }
+    resolveModel(provider, model, _signal) {
+        const configured = this.models.find(entry => entry.id === model);
+        return Promise.resolve({
+            provider,
+            id: model,
+            name: configured?.name ?? model,
+            ...(configured?.description === undefined ? {} : { description: configured.description }),
+            inputModalities: ['text'],
+            context: { contextWindow: configured?.contextWindow ?? 128_000 },
+        });
+    }
+    async *stream(options) {
+        if (options.signal?.aborted)
+            throw abortError();
+        const text = this.response;
+        yield { type: 'block-start', index: 0, blockType: 'text' };
+        await wait(this.delayMs, options.signal);
+        if (options.signal?.aborted)
+            throw abortError();
+        yield { type: 'text-delta', index: 0, text };
+        yield { type: 'block-end', index: 0, block: { type: 'text', text } };
+        yield { type: 'usage', usage: { inputTokens: 0, outputTokens: text.length } };
+        yield { type: 'finish', reason: { kind: 'stop' } };
+    }
+}
+//# sourceMappingURL=mock.js.map

package/lib/provider/prompt-budget.d.ts

@@ -0,0 +1,45 @@
+export declare const DEFAULT_INPUT_FRAME_LIMIT_BYTES: number;
+export declare const DEFAULT_AGY_PROMPT_CONTENT_LIMIT_BYTES: number;
+export declare const DEFAULT_DSH_TOOL_PROMPT_CONTENT_LIMIT_BYTES: number;
+export declare const DEFAULT_MAX_SINGLE_TOOL_RESULT_BYTES: number;
+export declare const DEFAULT_MAX_HISTORICAL_TOOL_RESULT_BYTES: number;
+export declare class AgyPromptBudgetError extends Error {
+    readonly actualBytes: number;
+    readonly limitBytes: number;
+    readonly code: "AGY_INPUT_TOO_LARGE";
+    constructor(actualBytes: number, limitBytes: number);
+}
+export interface AgyPromptBudgetOptions {
+    maxFrameBytes: number;
+    maxPromptBytes?: number;
+    maxSingleToolResultBytes?: number;
+    maxHistoricalToolResultBytes?: number;
+    /**
+     * What to do when a single serialized section alone exceeds the prompt
+     * budget. `'reject'` (default) throws AGY_INPUT_TOO_LARGE; `'clamp'` clips
+     * that section's head and keeps its tail. The main turn stays on `'reject'`:
+     * silently losing the beginning of the user's own message is worse than a
+     * clean error. Side-channel requests (a session-title or compaction summary
+     * over the whole conversation, which arrive as one oversized section) use
+     * `'clamp'` — they have no tool protocol to protect, the newest content is
+     * what a summary needs, and failing them outright only stalls the panel.
+     */
+    oversizedSectionPolicy?: 'reject' | 'clamp';
+}
+export interface AgyPromptBudgetResult {
+    readonly prompt: string;
+    readonly promptBytes: number;
+    readonly promptLimitBytes: number;
+    readonly frameBytes: number;
+    readonly frameLimitBytes: number;
+    readonly toolResultCount: number;
+    readonly largestToolResultBytes: number;
+    readonly truncatedToolResultCount: number;
+    readonly historyCompacted: boolean;
+    readonly omittedMessageCount: number;
+}
+/** Return the immutable prefix before the first dynamic DSH history section. */
+export declare function stableAgyPromptPrefix(prompt: string): string;
+/** Bound historical DSH tool output before the prompt is sent to AGY. */
+export declare function boundAgyPrompt(prompt: string, options: AgyPromptBudgetOptions): AgyPromptBudgetResult;
+//# sourceMappingURL=prompt-budget.d.ts.map