@cjhyy/code-shell-core 0.5.0-rc.2 → 0.6.0-rc.1

package/dist/tool-system/builtin/image-providers.js

@@ -0,0 +1,190 @@
+/**
+ * ImageProvider — adapter interface for text-to-image generation (TODO 7.1).
+ *
+ * Lifts the hardcoded OpenAI `gpt-image-2` call out of generate-image.ts so
+ * GenerateImage can target multiple providers (OpenAI now; Gemini next) and
+ * take an optional provider/model. Each adapter takes resolved credentials +
+ * the request and returns a base64 PNG (or an error string). The tool layer
+ * owns credential resolution from settings, file writing, and user-facing
+ * formatting — adapters are pure "creds + prompt → bytes".
+ *
+ * `fetch` is injected so adapters are unit-testable without network. Production
+ * call sites pass the global `fetch`.
+ */
+/**
+ * OpenAI Images API adapter (`/images/generations`, b64_json). Identical wire
+ * behavior to the pre-refactor generate-image.ts: POST model/prompt/size/
+ * quality/n, read data[0].b64_json.
+ */
+export class OpenAIImageProvider {
+    fetchImpl;
+    kind = "openai";
+    constructor(fetchImpl = fetch) {
+        this.fetchImpl = fetchImpl;
+    }
+    async generate(req) {
+        // Trim a trailing slash so `${baseUrl}/images/...` doesn't double up.
+        const baseUrl = req.creds.baseUrl.replace(/\/+$/, "");
+        const hasInputs = !!req.inputImages && req.inputImages.length > 0;
+        let resp;
+        try {
+            if (hasInputs) {
+                // Image-to-image → the EDITS endpoint, which takes multipart/form-data
+                // with one or more `image[]` parts (gpt-image accepts up to 16). Do NOT
+                // set Content-Type manually — fetch sets the multipart boundary.
+                const form = new FormData();
+                form.append("model", req.model);
+                form.append("prompt", req.prompt);
+                if (req.size && req.size !== "auto")
+                    form.append("size", req.size);
+                if (req.quality && req.quality !== "auto")
+                    form.append("quality", req.quality);
+                form.append("n", "1");
+                for (const img of req.inputImages) {
+                    // Copy into a fresh Uint8Array so the Blob gets a clean ArrayBuffer
+                    // (avoids SharedArrayBuffer / offset typing issues across runtimes).
+                    const buf = Uint8Array.from(img.bytes);
+                    form.append("image[]", new Blob([buf], { type: img.mimeType }), img.filename);
+                }
+                resp = await this.fetchImpl(`${baseUrl}/images/edits`, {
+                    method: "POST",
+                    headers: { Authorization: `Bearer ${req.creds.apiKey}` },
+                    body: form,
+                    signal: req.signal,
+                });
+            }
+            else {
+                resp = await this.fetchImpl(`${baseUrl}/images/generations`, {
+                    method: "POST",
+                    headers: {
+                        Authorization: `Bearer ${req.creds.apiKey}`,
+                        "Content-Type": "application/json",
+                    },
+                    body: JSON.stringify({
+                        model: req.model,
+                        prompt: req.prompt,
+                        size: req.size,
+                        quality: req.quality,
+                        n: 1,
+                    }),
+                    signal: req.signal,
+                });
+            }
+        }
+        catch (err) {
+            return { ok: false, error: `request failed: ${err.message}` };
+        }
+        if (!resp.ok) {
+            const body = (await resp.text().catch(() => "")).slice(0, 500);
+            return { ok: false, error: `image API returned ${resp.status}: ${body}` };
+        }
+        let json;
+        try {
+            json = await resp.json();
+        }
+        catch (err) {
+            return { ok: false, error: `could not parse image API response: ${err.message}` };
+        }
+        const b64 = json?.data?.[0]?.b64_json;
+        if (typeof b64 !== "string" || !b64) {
+            const preview = JSON.stringify(json).slice(0, 500);
+            return { ok: false, error: `no image in response: ${preview}` };
+        }
+        return { ok: true, b64 };
+    }
+}
+/**
+ * Gemini Images adapter — the `generateContent` endpoint
+ * (`/models/{model}:generateContent`), API key in the `x-goog-api-key`
+ * header, prompt as a text content-part, PNG returned base64 in
+ * `candidates[].content.parts[].inline_data.data` (REST may camelCase it to
+ * `inlineData`; we read both). Wire shape per ai.google.dev image-generation
+ * docs. The OpenAI-style `size`/`quality` args don't map 1:1 to Gemini's
+ * aspectRatio/imageSize, so we only forward the prompt + IMAGE modality and
+ * leave Gemini's own defaults for dimensions (a later pass can map size →
+ * aspectRatio if needed).
+ */
+export class GeminiImageProvider {
+    fetchImpl;
+    kind = "google";
+    constructor(fetchImpl = fetch) {
+        this.fetchImpl = fetchImpl;
+    }
+    async generate(req) {
+        // Image generation uses the NATIVE Gemini REST path
+        // (`{base}/models/{model}:generateContent`). A provider configured for
+        // Gemini's OpenAI-compatibility layer carries a `…/openai` baseUrl (fine
+        // for chat) — strip that suffix so images hit the native endpoint without
+        // the user needing a second provider entry. A native `…/v1beta` baseUrl is
+        // left untouched.
+        const baseUrl = req.creds.baseUrl.replace(/\/+$/, "").replace(/\/openai$/, "");
+        let resp;
+        try {
+            // Image-to-image: Gemini conditions on input images passed as additional
+            // inline_data parts alongside the text prompt (base64, no data: prefix).
+            const parts = [{ text: req.prompt }];
+            for (const img of req.inputImages ?? []) {
+                parts.push({
+                    inline_data: {
+                        mime_type: img.mimeType,
+                        data: Buffer.from(img.bytes).toString("base64"),
+                    },
+                });
+            }
+            resp = await this.fetchImpl(`${baseUrl}/models/${req.model}:generateContent`, {
+                method: "POST",
+                headers: {
+                    "x-goog-api-key": req.creds.apiKey,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    contents: [{ parts }],
+                    generationConfig: { responseModalities: ["TEXT", "IMAGE"] },
+                }),
+                signal: req.signal,
+            });
+        }
+        catch (err) {
+            return { ok: false, error: `request failed: ${err.message}` };
+        }
+        if (!resp.ok) {
+            const body = (await resp.text().catch(() => "")).slice(0, 500);
+            return { ok: false, error: `image API returned ${resp.status}: ${body}` };
+        }
+        let json;
+        try {
+            json = await resp.json();
+        }
+        catch (err) {
+            return { ok: false, error: `could not parse image API response: ${err.message}` };
+        }
+        const parts = json
+            ?.candidates?.[0]?.content?.parts ?? [];
+        for (const part of parts) {
+            // Accept both snake_case (inline_data) and camelCase (inlineData).
+            const inline = (part.inline_data ?? part.inlineData);
+            if (inline?.data)
+                return { ok: true, b64: inline.data };
+        }
+        const preview = JSON.stringify(json).slice(0, 500);
+        return { ok: false, error: `no image in response: ${preview}` };
+    }
+}
+/** Default model per provider kind when the caller doesn't specify one. */
+export const DEFAULT_IMAGE_MODEL = {
+    openai: "gpt-image-2",
+    // Nano Banana — the current recommended Gemini image model. Override per call
+    // via GenerateImage's `model` arg when a newer one (e.g. gemini-3.1-flash-image) is wanted.
+    google: "gemini-2.5-flash-image",
+};
+/** Registry of available image-provider adapters, keyed by `kind`. */
+export function getImageProvider(kind, fetchImpl = fetch) {
+    switch (kind) {
+        case "openai":
+            return new OpenAIImageProvider(fetchImpl);
+        case "google":
+            return new GeminiImageProvider(fetchImpl);
+        default:
+            return null;
+    }
+}

package/dist/tool-system/builtin/image-uploader.d.ts

@@ -0,0 +1,33 @@
+export interface UploaderCreds {
+    baseUrl: string;
+    apiKey: string;
+}
+export type UploadResult = {
+    ok: true;
+    url: string;
+} | {
+    ok: false;
+    error: string;
+};
+export interface ImageUploader {
+    readonly kind: string;
+    /** http/https → unchanged; local path → upload, return public URL. */
+    toUrl(pathOrUrl: string, creds: UploaderCreds, signal?: AbortSignal): Promise<UploadResult>;
+}
+export declare function isHttpUrl(s: string): boolean;
+export declare class FalStorageUploader implements ImageUploader {
+    private readonly fetchImpl;
+    readonly kind = "fal";
+    private static readonly UPLOAD_BASE;
+    constructor(fetchImpl?: typeof fetch);
+    toUrl(pathOrUrl: string, creds: UploaderCreds, signal?: AbortSignal): Promise<UploadResult>;
+    /**
+     * Upload raw bytes to fal storage, return the public URL. Two-step flow
+     * (verified against live API 2026-06-10):
+     *   1. POST {UPLOAD_BASE}/storage/upload/initiate → { file_url, upload_url }
+     *   2. PUT <upload_url> with the bytes (signed URL, no Authorization)
+     *   3. file_url is the final public URL.
+     */
+    private uploadBytes;
+}
+export declare function getImageUploader(kind: string, fetchImpl?: typeof fetch): ImageUploader | null;

package/dist/tool-system/builtin/image-uploader.js

@@ -0,0 +1,74 @@
+/**
+ * ImageUploader — pluggable "local path → public URL" so image-to-video /
+ * reference-to-video can accept local files, not just URLs. fal storage is the
+ * first impl; swapping in another image host = another impl, no provider change.
+ */
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+export function isHttpUrl(s) {
+    return /^https?:\/\//i.test(s);
+}
+function mimeFromName(name) {
+    const ext = name.toLowerCase().split(".").pop() ?? "";
+    const map = { png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", webp: "image/webp", gif: "image/gif" };
+    return map[ext] ?? "application/octet-stream";
+}
+export class FalStorageUploader {
+    fetchImpl;
+    kind = "fal";
+    // fal upload lives on a different host than queue.fal.run.
+    static UPLOAD_BASE = "https://rest.alpha.fal.ai";
+    constructor(fetchImpl = fetch) {
+        this.fetchImpl = fetchImpl;
+    }
+    async toUrl(pathOrUrl, creds, signal) {
+        if (isHttpUrl(pathOrUrl))
+            return { ok: true, url: pathOrUrl };
+        try {
+            const bytes = await readFile(pathOrUrl);
+            const url = await this.uploadBytes(bytes, basename(pathOrUrl), creds, signal);
+            return { ok: true, url };
+        }
+        catch (err) {
+            return { ok: false, error: `fal upload error for ${pathOrUrl}: ${err.message}` };
+        }
+    }
+    /**
+     * Upload raw bytes to fal storage, return the public URL. Two-step flow
+     * (verified against live API 2026-06-10):
+     *   1. POST {UPLOAD_BASE}/storage/upload/initiate → { file_url, upload_url }
+     *   2. PUT <upload_url> with the bytes (signed URL, no Authorization)
+     *   3. file_url is the final public URL.
+     */
+    async uploadBytes(bytes, name, creds, signal) {
+        const mime = mimeFromName(name);
+        const ini = await this.fetchImpl(`${FalStorageUploader.UPLOAD_BASE}/storage/upload/initiate`, {
+            method: "POST",
+            headers: { Authorization: `Key ${creds.apiKey}`, "Content-Type": "application/json" },
+            body: JSON.stringify({ content_type: mime, file_name: name }),
+            signal,
+        });
+        if (!ini.ok)
+            throw new Error(`initiate failed: HTTP ${ini.status}`);
+        const { file_url, upload_url } = (await ini.json());
+        if (!file_url || !upload_url)
+            throw new Error("initiate: missing file_url/upload_url");
+        const put = await this.fetchImpl(upload_url, {
+            method: "PUT",
+            headers: { "Content-Type": mime },
+            body: bytes,
+            signal,
+        });
+        if (!put.ok)
+            throw new Error(`upload PUT failed: HTTP ${put.status}`);
+        return file_url;
+    }
+}
+export function getImageUploader(kind, fetchImpl = fetch) {
+    switch (kind) {
+        case "fal":
+            return new FalStorageUploader(fetchImpl);
+        default:
+            return null;
+    }
+}

package/dist/tool-system/builtin/index.d.ts

@@ -16,11 +16,15 @@ import type { RegisteredTool } from "../../types.js";
  * 内置工具返回值:大多数返回纯文本字符串。需要回传图片(或其它结构化
  * 内容块)的工具(view_image)可改为返回 `{ contentBlocks }`;此时
  * registry 会把它放进 ToolResult.contentBlocks。可选的 `result` 字段是给
- * transcript / 摘要用的纯文本镜像。
+ * transcript / 摘要用的纯文本镜像。沙箱执行类工具(Bash 等)可返回
+ * `{ result, sandbox }`,registry 把 sandbox 透传到 ToolResult.sandbox 供 UI 显示。
  */
 export type BuiltinToolResult = string | {
     contentBlocks: import("../../types.js").ContentBlock[];
     result?: string;
+} | {
+    result: string;
+    sandbox: import("../../types.js").ToolResult["sandbox"];
 };
 export type BuiltinToolFn = (args: Record<string, unknown>, ctx?: import("../context.js").ToolContext) => Promise<BuiltinToolResult>;
 export interface BuiltinTool {
@@ -35,3 +39,5 @@ export declare const BUILTIN_TOOLS: BuiltinTool[];
  * Keyed by the tool's `name` (must match the toolDef name).
  */
 export declare const BUILTIN_TOOL_GUARDS: Map<string, (cwd: string) => boolean>;
+/** UseCredential is available when the cwd's CredentialStore has ≥1 credential. */
+export declare function isUseCredentialAvailable(cwd: string): boolean;