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

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

@@ -0,0 +1,235 @@
+/**
+ * VideoProvider — adapter interface for text-to-video generation (TODO 7.1).
+ *
+ * Unlike images (one request → bytes), video generation is asynchronous and
+ * long: SUBMIT a job → POLL its status until it finishes → DOWNLOAD the bytes.
+ * The interface captures exactly those three steps so the GenerateVideo tool's
+ * background polling loop is provider-agnostic, and concrete adapters
+ * (Seedance/Kling — filled in once their private API docs are available) only
+ * implement submit/poll/download.
+ *
+ * Credentials are resolved by the tool layer from settings; adapters are pure
+ * "creds + request → job lifecycle". `fetch` is injected for testability.
+ */
+/**
+ * Deterministic in-memory adapter for tests and local dev — no network. Models
+ * the three-step lifecycle: submit mints a job; poll returns `running` for the
+ * first N calls then `succeeded` (or `failed` after M); download returns the
+ * configured bytes. Lets the GenerateVideo background loop be tested end-to-end
+ * before any real (Seedance/Kling) adapter exists.
+ */
+export class FakeVideoProvider {
+    opts;
+    kind = "fake";
+    polls = new Map();
+    counter = 0;
+    constructor(opts = {}) {
+        this.opts = opts;
+    }
+    async submit(_req) {
+        this.counter += 1;
+        const jobId = `fakejob-${this.counter}`;
+        this.polls.set(jobId, 0);
+        return { ok: true, jobId };
+    }
+    async poll(req) {
+        const n = this.polls.get(req.jobId) ?? 0;
+        this.polls.set(req.jobId, n + 1);
+        if (this.opts.failAfterPolls !== undefined && n >= this.opts.failAfterPolls) {
+            return { ok: true, status: "failed", error: this.opts.failMessage ?? "job failed" };
+        }
+        if (this.opts.succeedAfterPolls !== undefined && n >= this.opts.succeedAfterPolls) {
+            return { ok: true, status: "succeeded" };
+        }
+        return { ok: true, status: "running" };
+    }
+    async download(_req) {
+        return { ok: true, bytes: Buffer.from(this.opts.bytes ?? "FAKE_VIDEO"), ext: "mp4" };
+    }
+}
+/**
+ * fal.ai video adapter — submit/poll/download against the fal queue API
+ * (https://queue.fal.run). model id selects the underlying model
+ * (e.g. fal-ai/kling-video/v3/pro/text-to-video). When `image` is present we
+ * switch a `...text-to-video` model to `...image-to-video` and send image_url,
+ * so callers only need to pass an image to get i2v.
+ *
+ * IMPORTANT: fal's status/result URLs use a model-FAMILY prefix
+ * (`fal-ai/kling-video/requests/<id>`), NOT the full submit path
+ * (`.../v3/pro/text-to-video/requests/<id>` → HTTP 405). So we never
+ * reconstruct those URLs; we encode the `status_url` + `response_url` that
+ * submit returns into the jobId (`<status_url>|<response_url>`) and use them
+ * verbatim in poll/download. Verified against the live API 2026-06-10.
+ */
+export class FalVideoProvider {
+    fetchImpl;
+    kind = "fal";
+    constructor(fetchImpl = fetch) {
+        this.fetchImpl = fetchImpl;
+    }
+    /** Effective image list: images[] wins; else single image; else []. */
+    imageList(req) {
+        if (req.images && req.images.length)
+            return req.images;
+        if (req.image)
+            return [req.image];
+        return [];
+    }
+    /**
+     * Does this model family support reference-to-video (multi-image)? Verified
+     * 2026-06-10 against the live API: Seedance has it; Kling does NOT (routing a
+     * Kling model to `.../reference-to-video` 404s at result fetch). Keep this a
+     * conservative allowlist — only families confirmed to expose the endpoint.
+     */
+    supportsReference(model) {
+        return /seedance/i.test(model);
+    }
+    /** Route model suffix by image count: 0→text, 1→image, ≥2→reference. */
+    resolveModel(model, imageCount) {
+        const target = imageCount >= 2 ? "reference-to-video" : imageCount === 1 ? "image-to-video" : null;
+        if (target && /(text|image|reference)-to-video$/.test(model)) {
+            return model.replace(/(text|image|reference)-to-video$/, target);
+        }
+        return model;
+    }
+    /** jobId = `${statusUrl}|${responseUrl}` (fal returns both from submit). */
+    split(jobId) {
+        const idx = jobId.indexOf("|");
+        if (idx < 0)
+            return { statusUrl: jobId, responseUrl: jobId };
+        return { statusUrl: jobId.slice(0, idx), responseUrl: jobId.slice(idx + 1) };
+    }
+    async submit(req) {
+        const base = req.creds.baseUrl.replace(/\/+$/, "");
+        const imgs = this.imageList(req);
+        const vids = req.videos ?? [];
+        // Multi-image OR any reference video needs the reference-to-video endpoint,
+        // which only some families (Seedance) expose. Routing e.g. Kling there
+        // 404s at result fetch — fail fast with a clear message instead.
+        const needsReference = imgs.length >= 2 || vids.length > 0;
+        if (needsReference && !this.supportsReference(req.model)) {
+            return {
+                ok: false,
+                error: `model "${req.model}" does not support reference-to-video (multiple images or reference videos). Use a Seedance model, or pass a single image / no video.`,
+            };
+        }
+        // imageCount alone can't express "reference needed"; bump to 2 when a video
+        // forces the reference endpoint so resolveModel picks reference-to-video.
+        const refImageCount = needsReference ? Math.max(imgs.length, 2) : imgs.length;
+        const model = this.resolveModel(req.model, refImageCount);
+        const body = { prompt: req.prompt };
+        if (imgs.length >= 2)
+            body.image_urls = imgs;
+        else if (imgs.length === 1)
+            body.image_url = imgs[0];
+        if (vids.length > 0)
+            body.video_urls = vids;
+        try {
+            const r = await this.fetchImpl(`${base}/${model}`, {
+                method: "POST",
+                headers: { Authorization: `Key ${req.creds.apiKey}`, "Content-Type": "application/json" },
+                body: JSON.stringify(body),
+                signal: req.signal,
+            });
+            if (!r.ok) {
+                const t = await r.text().catch(() => "");
+                return { ok: false, error: `fal submit failed: HTTP ${r.status} ${t}`.trim() };
+            }
+            const j = (await r.json());
+            if (!j.request_id)
+                return { ok: false, error: "fal submit: no request_id in response" };
+            // Prefer the URLs fal hands back; fall back to family-prefix reconstruction
+            // only if they're absent (defensive — live API always returns them).
+            const statusUrl = j.status_url ?? "";
+            const responseUrl = j.response_url ?? "";
+            if (!statusUrl || !responseUrl) {
+                return { ok: false, error: "fal submit: missing status_url/response_url" };
+            }
+            return { ok: true, jobId: `${statusUrl}|${responseUrl}` };
+        }
+        catch (err) {
+            return { ok: false, error: `fal submit error: ${err.message}` };
+        }
+    }
+    async poll(req) {
+        const { statusUrl } = this.split(req.jobId);
+        try {
+            const r = await this.fetchImpl(statusUrl, {
+                method: "GET",
+                headers: { Authorization: `Key ${req.creds.apiKey}` },
+                signal: req.signal,
+            });
+            // fal returns 200/202 for valid in-progress/queued states; only treat a
+            // hard client/server error (4xx except 202, 5xx) as a transport failure.
+            if (!r.ok && r.status !== 202) {
+                const t = await r.text().catch(() => "");
+                return { ok: false, error: `fal status failed: HTTP ${r.status} ${t}`.trim() };
+            }
+            const j = (await r.json());
+            switch (j.status) {
+                case "IN_QUEUE":
+                case "IN_PROGRESS":
+                    return { ok: true, status: "running" };
+                case "COMPLETED":
+                    return { ok: true, status: "succeeded" };
+                default:
+                    return { ok: true, status: "failed", error: `fal status: ${j.status ?? "unknown"}` };
+            }
+        }
+        catch (err) {
+            return { ok: false, error: `fal poll error: ${err.message}` };
+        }
+    }
+    async download(req) {
+        const { responseUrl } = this.split(req.jobId);
+        try {
+            // hop 1: result JSON
+            const r = await this.fetchImpl(responseUrl, {
+                method: "GET",
+                headers: { Authorization: `Key ${req.creds.apiKey}` },
+                signal: req.signal,
+            });
+            if (!r.ok) {
+                const t = await r.text().catch(() => "");
+                return { ok: false, error: `fal result failed: HTTP ${r.status} ${t}`.trim() };
+            }
+            const j = (await r.json());
+            const videoUrl = j.video?.url;
+            if (!videoUrl)
+                return { ok: false, error: "fal result: no video.url" };
+            // hop 2: video bytes
+            const vr = await this.fetchImpl(videoUrl, { method: "GET", signal: req.signal });
+            if (!vr.ok) {
+                return { ok: false, error: `fal video download failed: HTTP ${vr.status}` };
+            }
+            const buf = new Uint8Array(await vr.arrayBuffer());
+            const m = /\.([a-z0-9]{2,4})(?:\?|$)/i.exec(videoUrl);
+            const ext = m ? m[1].toLowerCase() : "mp4";
+            // Surface the fal-hosted URL so the model can reuse it for video extension
+            // (videos[] → video_urls) without re-uploading. Note: signed/expiring.
+            return { ok: true, bytes: buf, ext, url: videoUrl };
+        }
+        catch (err) {
+            return { ok: false, error: `fal download error: ${err.message}` };
+        }
+    }
+}
+/** Default model per video provider kind (filled in with real adapters). */
+export const DEFAULT_VIDEO_MODEL = {
+    fal: "fal-ai/kling-video/v3/pro/text-to-video",
+};
+/**
+ * Registry of video-provider adapters, keyed by `kind`. Only `fake` exists
+ * today (test/dev). Real adapters (seedance, kling) are intentionally absent
+ * until their private API contracts are confirmed — see TODO 7.1 块3.
+ */
+export function getVideoProvider(kind, fetchImpl = fetch) {
+    switch (kind) {
+        case "fake":
+            return new FakeVideoProvider({ succeedAfterPolls: 0 });
+        case "fal":
+            return new FalVideoProvider(fetchImpl);
+        default:
+            return null;
+    }
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Built-in view_image tool — 把一个本地图片文件以 base64 image ContentBlock
+ * 回传进上下文,让 vision 模型「看」它(对照 codex 的 view_image)。
+ *
+ * 典型用法:模型先写 SVG/Mermaid 并用 shell 转成 PNG,再调 view_image(png)
+ * 检查图画对没有(标签是否重叠、文字是否溢出),不对就改源再重转。
+ *
+ * 三道闸门,避免污染上下文 / 浪费 token:
+ *   1. vision gate —— 当前模型不支持视觉时不读文件,只回文字占位。
+ *   2. 格式 gate —— 只支持 png/jpeg/gif/webp(provider image 块能吃的);
+ *      svg/pdf 等回文字提示「先转 PNG」。
+ *   3. 大小 gate —— 超过 MAX_BYTES 回文字提示,不读进 base64。
+ */
+import type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
+import type { BuiltinToolResult } from "./index.js";
+export declare const viewImageToolDef: ToolDefinition;
+export declare function viewImageTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<BuiltinToolResult>;

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

@@ -0,0 +1,96 @@
+/**
+ * Built-in view_image tool — 把一个本地图片文件以 base64 image ContentBlock
+ * 回传进上下文,让 vision 模型「看」它(对照 codex 的 view_image)。
+ *
+ * 典型用法:模型先写 SVG/Mermaid 并用 shell 转成 PNG,再调 view_image(png)
+ * 检查图画对没有(标签是否重叠、文字是否溢出),不对就改源再重转。
+ *
+ * 三道闸门,避免污染上下文 / 浪费 token:
+ *   1. vision gate —— 当前模型不支持视觉时不读文件,只回文字占位。
+ *   2. 格式 gate —— 只支持 png/jpeg/gif/webp(provider image 块能吃的);
+ *      svg/pdf 等回文字提示「先转 PNG」。
+ *   3. 大小 gate —— 超过 MAX_BYTES 回文字提示,不读进 base64。
+ */
+import { readFile, stat } from "node:fs/promises";
+import { extname, isAbsolute, resolve } from "node:path";
+import { capabilitiesFor } from "../../llm/capabilities/index.js";
+const MAX_BYTES = 5 * 1024 * 1024; // 5MB —— vision 模型按 tile 计 token,大图无益且撑大请求
+const MEDIA_TYPES = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+};
+export const viewImageToolDef = {
+    name: "view_image",
+    description: "Load a local image file into the conversation so you can SEE it (vision). " +
+        "Use after generating or rendering an image (e.g. SVG/Mermaid → PNG) to verify it " +
+        "looks right — check for overlapping labels, clipped text, wrong layout — then fix the " +
+        "source and re-render if needed. Supports PNG/JPEG/GIF/WebP only; convert SVG/PDF to PNG " +
+        "first. Requires a vision-capable model; otherwise the image is skipped.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            path: {
+                type: "string",
+                description: "Path to the image file (absolute, or relative to the working directory).",
+            },
+        },
+        required: ["path"],
+    },
+};
+export async function viewImageTool(args, ctx) {
+    const rawPath = args.path;
+    if (typeof rawPath !== "string" || !rawPath.trim()) {
+        return "Error: path is required";
+    }
+    const cwd = ctx?.cwd ?? process.cwd();
+    const abs = isAbsolute(rawPath) ? rawPath : resolve(cwd, rawPath);
+    // 闸门 1:vision gate —— 不支持视觉就不读文件。
+    // 缺 llmConfig 时按「非视觉」处理(fail closed),对齐 DEFAULT_CAPABILITY
+    // 的保守姿态:运行时 ToolContext.llmConfig 必有,缺失只发生在测试 / 异常
+    // 装配下,此时绝不把 base64 读进上下文。
+    const supportsVision = (() => {
+        if (!ctx?.llmConfig)
+            return false;
+        const kind = (ctx.llmConfig.providerKind ?? ctx.llmConfig.provider);
+        return capabilitiesFor(kind, ctx.llmConfig.model).supportsVision;
+    })();
+    if (!supportsVision) {
+        return `[图片未加载: ${abs} —— 当前模型不支持视觉输入,已跳过。切换到 vision 模型后再 view_image。]`;
+    }
+    // 闸门 2:格式 gate
+    const ext = extname(abs).toLowerCase();
+    const mediaType = MEDIA_TYPES[ext];
+    if (!mediaType) {
+        return `[图片未加载: ${abs} —— 格式 ${ext || "(无扩展名)"} 不支持视觉预览,请先转成 PNG/JPEG。]`;
+    }
+    // 闸门 3:大小 gate(读 stat,不读全文件)
+    let size;
+    try {
+        size = (await stat(abs)).size;
+    }
+    catch (err) {
+        return `Error: 无法读取 ${abs}: ${err.message}`;
+    }
+    if (size > MAX_BYTES) {
+        const mb = (size / 1024 / 1024).toFixed(1);
+        return `[图片未加载: ${abs} —— 文件过大 (${mb} MB > 5 MB),请先压缩或缩放再 view_image。]`;
+    }
+    let buf;
+    try {
+        buf = await readFile(abs);
+    }
+    catch (err) {
+        return `Error: 无法读取 ${abs}: ${err.message}`;
+    }
+    const data = buf.toString("base64");
+    const kb = Math.round(buf.length / 1024);
+    return {
+        contentBlocks: [
+            { type: "image", source: { type: "base64", media_type: mediaType, data } },
+        ],
+        result: `[已加载图片: ${abs} (${mediaType}, ${kb} KB)]`,
+    };
+}

package/dist/tool-system/builtin/web-fetch.js

@@ -176,7 +176,12 @@ export async function webFetchTool(args) {
     catch {
         return `Error: invalid URL "${url}"`;
     }
-    const maxLength = Math.min(args.max_length || DEFAULT_MAX, MAX_OUTPUT);
+    // A non-positive max_length must NOT reach `text.slice(0, maxLength)` below
+    // with a negative end — JS reads that as "all but the last N", silently
+    // returning the WRONG bytes (+ a misleading "truncated" suffix). `|| DEFAULT`
+    // only caught 0/NaN, not negatives. Floor to the default page size first.
+    const rawMaxLength = args.max_length;
+    const maxLength = Math.min(typeof rawMaxLength === "number" && rawMaxLength > 0 ? rawMaxLength : DEFAULT_MAX, MAX_OUTPUT);
     const rawHeaders = args.headers ?? {};
     const baseHeaders = {
         "User-Agent": "Mozilla/5.0 (compatible; code-shell/0.1; +https://github.com/nicepkg/code-shell)",
@@ -192,7 +197,12 @@ export async function webFetchTool(args) {
     // host, and DNS-resolved IPs against the block lists. fetch() runs
     // with redirect: "manual" so the runtime cannot silently follow a
     // redirect into private/loopback/metadata space.
+    // Combine the 30s fetch timeout with the run's abort signal (registry injects
+    // __signal) so a user Stop cancels an in-flight fetch promptly, not only on
+    // the 30s timeout. Timeout alone was the previous behavior.
     const timeoutSignal = AbortSignal.timeout(30_000);
+    const userSignal = args.__signal;
+    const fetchSignal = userSignal ? AbortSignal.any([userSignal, timeoutSignal]) : timeoutSignal;
     let currentUrl = parsed;
     let currentHeaders = { ...baseHeaders };
     const originalOrigin = parsed;
@@ -206,7 +216,7 @@ export async function webFetchTool(args) {
             const res = await fetch(currentUrl, {
                 headers: currentHeaders,
                 redirect: "manual",
-                signal: timeoutSignal,
+                signal: fetchSignal,
             });
             // Not a redirect: return body (or HTTP error).
             if (res.status < 300 || res.status >= 400 || !res.headers.get("location")) {

package/dist/tool-system/builtin/web-search.d.ts

@@ -21,5 +21,8 @@ export interface ResolvedSearchConfig {
  * the user where the value came from when debugging.
  */
 export declare function resolveSearchConfig(cwd?: string): ResolvedSearchConfig;
+export declare function isWebSearchAvailable(cwd?: string, nowMs?: number): boolean;
 export declare const webSearchToolDef: ToolDefinition;
-export declare function webSearchTool(args: Record<string, unknown>): Promise<string>;
+export declare function webSearchTool(args: Record<string, unknown>, ctx?: {
+    cwd?: string;
+}): Promise<string>;

package/dist/tool-system/builtin/web-search.js

@@ -18,7 +18,11 @@ export function resolveSearchConfig(cwd = process.cwd()) {
     let settingsKey;
     let settingsBaseUrl;
     try {
-        const merged = new SettingsManager(cwd).get();
+        // scope "full" so the USER-level ~/.code-shell/settings.json is read, not
+        // just ${cwd}/.code-shell — the search key is typically a personal/global
+        // credential. Default "project" scope would miss it (the "No search provider
+        // configured" bug, esp. for automation runs rooted at the app dir).
+        const merged = new SettingsManager(cwd, "full").get();
         const search = merged.search ?? {};
         const p = search.provider;
         if (p === "serper" || p === "tavily" || p === "searxng")
@@ -68,6 +72,33 @@ export function resolveSearchConfig(cwd = process.cwd()) {
         return { provider: "searxng", baseUrl: envSearxng, source: "env" };
     return { provider: "serper", source: "none" };
 }
+/**
+ * Tool-visibility guard: WebSearch is only useful when a search provider is
+ * configured. Mirrors the runtime check in the tool itself (source === "none"
+ * means no provider).
+ *
+ * Cached per-cwd with a short TTL: this runs on EVERY message's toolDefs
+ * assembly (engine.ts), and resolveSearchConfig reads + parses settings from
+ * disk each call. The 1s TTL collapses back-to-back reads while still picking
+ * up a newly-configured provider before the user's next message. The execution
+ * path (resolveSearchConfig) is intentionally NOT cached — only this boolean.
+ */
+const availCache = new Map();
+const AVAIL_TTL_MS = 1000;
+export function isWebSearchAvailable(cwd = process.cwd(), nowMs = Date.now()) {
+    const hit = availCache.get(cwd);
+    if (hit && nowMs - hit.at < AVAIL_TTL_MS)
+        return hit.value;
+    let value = false;
+    try {
+        value = resolveSearchConfig(cwd).source !== "none";
+    }
+    catch {
+        value = false; // unresolved config → treat as unavailable
+    }
+    availCache.set(cwd, { at: nowMs, value });
+    return value;
+}
 export const webSearchToolDef = {
     name: "WebSearch",
     description: "Search the web for information. Returns a list of search results with titles, URLs, and snippets. " +
@@ -84,25 +115,38 @@ export const webSearchToolDef = {
         required: ["query"],
     },
 };
-export async function webSearchTool(args) {
+export async function webSearchTool(args, ctx) {
     const query = args.query;
     if (!query)
         return "Error: query is required";
-    const numResults = Math.min(args.num_results || 10, 20);
-    const config = resolveSearchConfig();
+    // Floor to default on non-positive: a negative num_results would reach
+    // `results.slice(0, num)` with a negative end (= all but the last N), silently
+    // returning the wrong result set. `|| 10` only caught 0/NaN, not negatives.
+    const rawNum = args.num_results;
+    const numResults = Math.min(typeof rawNum === "number" && rawNum > 0 ? rawNum : 10, 20);
+    // Use the run's cwd (e.g. an automation job's project dir) so per-project
+    // settings resolve correctly; falls back to process.cwd() when absent.
+    const config = resolveSearchConfig(ctx?.cwd);
     if (config.source === "none") {
         return "Error: No search provider configured. Open desktop 设置 → 连接 to add credentials, or set SERPER_API_KEY / TAVILY_API_KEY / SEARXNG_URL.";
     }
+    // A search provider's fetch had NO timeout and NO abort wiring — a hung/slow
+    // provider blocked the tool indefinitely and a user Stop couldn't cancel it.
+    // Give every provider call a 20s timeout, combined with the run's abort
+    // signal (registry injects __signal) so Stop is prompt.
+    const userSignal = args.__signal;
+    const timeoutSignal = AbortSignal.timeout(20_000);
+    const signal = userSignal ? AbortSignal.any([userSignal, timeoutSignal]) : timeoutSignal;
     try {
         let results;
         if (config.provider === "serper" && config.apiKey) {
-            results = await searchSerper(query, numResults, config.apiKey);
+            results = await searchSerper(query, numResults, config.apiKey, signal);
         }
         else if (config.provider === "tavily" && config.apiKey) {
-            results = await searchTavily(query, numResults, config.apiKey);
+            results = await searchTavily(query, numResults, config.apiKey, signal);
         }
         else if (config.provider === "searxng" && config.baseUrl) {
-            results = await searchSearXNG(query, numResults, config.baseUrl);
+            results = await searchSearXNG(query, numResults, config.baseUrl, signal);
         }
         else {
             return `Error: provider "${config.provider}" missing ${config.provider === "searxng" ? "base URL" : "API key"}`;
@@ -117,7 +161,7 @@ export async function webSearchTool(args) {
         return `Search error: ${err.message}`;
     }
 }
-async function searchSerper(query, num, apiKey) {
+async function searchSerper(query, num, apiKey, signal) {
     const res = await fetch("https://google.serper.dev/search", {
         method: "POST",
         headers: {
@@ -125,6 +169,7 @@ async function searchSerper(query, num, apiKey) {
             "Content-Type": "application/json",
         },
         body: JSON.stringify({ q: query, num }),
+        signal,
     });
     if (!res.ok)
         throw new Error(`Serper API error: ${res.status} ${res.statusText}`);
@@ -135,7 +180,7 @@ async function searchSerper(query, num, apiKey) {
         snippet: item.snippet ?? "",
     }));
 }
-async function searchTavily(query, num, apiKey) {
+async function searchTavily(query, num, apiKey, signal) {
     const res = await fetch("https://api.tavily.com/search", {
         method: "POST",
         headers: { "Content-Type": "application/json" },
@@ -145,6 +190,7 @@ async function searchTavily(query, num, apiKey) {
             max_results: num,
             include_answer: false,
         }),
+        signal,
     });
     if (!res.ok)
         throw new Error(`Tavily API error: ${res.status} ${res.statusText}`);
@@ -155,13 +201,14 @@ async function searchTavily(query, num, apiKey) {
         snippet: item.content ?? "",
     }));
 }
-async function searchSearXNG(query, num, baseUrl) {
+async function searchSearXNG(query, num, baseUrl, signal) {
     const url = new URL("/search", baseUrl);
     url.searchParams.set("q", query);
     url.searchParams.set("format", "json");
     url.searchParams.set("pageno", "1");
     const res = await fetch(url.toString(), {
         headers: { Accept: "application/json" },
+        signal,
     });
     if (!res.ok)
         throw new Error(`SearXNG error: ${res.status} ${res.statusText}`);

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

@@ -2,9 +2,10 @@
  * EnterWorktree / ExitWorktree tools — create and manage isolated git worktrees.
  */
 import type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
 import { type WorktreeSession } from "../../git/worktree.js";
 export declare function getActiveWorktree(): WorktreeSession | undefined;
 export declare const enterWorktreeToolDef: ToolDefinition;
-export declare function enterWorktreeTool(args: Record<string, unknown>): Promise<string>;
+export declare function enterWorktreeTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
 export declare const exitWorktreeToolDef: ToolDefinition;
 export declare function exitWorktreeTool(args: Record<string, unknown>): Promise<string>;

package/dist/tool-system/builtin/worktree.js

@@ -1,7 +1,7 @@
 /**
  * EnterWorktree / ExitWorktree tools — create and manage isolated git worktrees.
  */
-import { createWorktree, removeWorktree, validateWorktreeSlug, } from "../../git/worktree.js";
+import { createWorktree, removeWorktree, validateWorktreeSlug, selectPlatformScript, runWorktreeSetup, } from "../../git/worktree.js";
 // Global worktree state
 let _activeWorktree;
 export function getActiveWorktree() {
@@ -25,7 +25,7 @@ export const enterWorktreeToolDef = {
         required: ["slug"],
     },
 };
-export async function enterWorktreeTool(args) {
+export async function enterWorktreeTool(args, ctx) {
     const slug = args.slug;
     if (!slug)
         return "Error: slug is required";
@@ -41,18 +41,45 @@ export async function enterWorktreeTool(args) {
     try {
         // Use a placeholder session ID (the agent should set this properly)
         const sessionId = args.__sessionId ?? `wt-${Date.now()}`;
-        const cwd = args.__cwd ?? process.cwd();
+        const cwd = args.__cwd ?? ctx?.cwd ?? process.cwd();
         _activeWorktree = createWorktree(cwd, slug, sessionId);
+        // Run the project's localEnvironment.setupScripts once in the new
+        // worktree root (Beta decision 2026-06-08: setup belongs to the worktree
+        // lifecycle, not the conversation). Failure warns-but-continues — a broken
+        // setup script must not strand the agent outside a worktree it just made.
+        let setupNote = "";
+        const setupScripts = ctx?.engine?.readWorktreeSetupScripts(cwd);
+        const script = selectPlatformScript(setupScripts);
+        if (script) {
+            const setup = await runWorktreeSetup(_activeWorktree.worktreePath, script, {
+                sandbox: ctx?.sandbox,
+                shellEnv: ctx?.shellEnv,
+                signal: ctx?.signal,
+            });
+            if (setup.ok) {
+                setupNote = `\n\nRan setup script (exit 0).${setup.output ? `\n${truncate(setup.output)}` : ""}`;
+            }
+            else {
+                setupNote =
+                    `\n\n⚠️ Setup script failed (exit ${setup.exitCode ?? "?"}) — continuing anyway. ` +
+                        `You may need to run setup manually.${setup.output ? `\n${truncate(setup.output)}` : ""}`;
+            }
+        }
         return (`Worktree created:\n` +
             `  Path:   ${_activeWorktree.worktreePath}\n` +
             `  Branch: ${_activeWorktree.worktreeBranch}\n` +
             `  From:   ${_activeWorktree.originalBranch ?? "HEAD"}\n\n` +
-            `You are now working in an isolated copy. Changes here won't affect the main repo.`);
+            `You are now working in an isolated copy. Changes here won't affect the main repo.` +
+            setupNote);
     }
     catch (err) {
         return `Error creating worktree: ${err.message}`;
     }
 }
+/** Keep setup output from bloating the tool result — head+tail-ish trim. */
+function truncate(s, max = 2000) {
+    return s.length <= max ? s : `${s.slice(0, max)}\n…(${s.length - max} more chars)`;
+}
 export const exitWorktreeToolDef = {
     name: "ExitWorktree",
     description: "Exit the current worktree and return to the main working directory. " +

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

@@ -2,5 +2,6 @@
  * Built-in Write file tool.
  */
 import type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
 export declare const writeToolDef: ToolDefinition;
-export declare function writeTool(args: Record<string, unknown>): Promise<string>;
+export declare function writeTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;

package/dist/tool-system/builtin/write.js

@@ -17,7 +17,7 @@ export const writeToolDef = {
         required: ["file_path", "content"],
     },
 };
-export async function writeTool(args) {
+export async function writeTool(args, ctx) {
     const filePath = args.file_path;
     const content = args.content;
     if (!filePath)