vaan-ai 0.1.0

package/dist/src/providers/index.js

@@ -0,0 +1,122 @@
+// The registry, and the string that picks a model.
+//
+// `anthropic/claude-opus-4-8`, `openai/gpt-5`, `google/gemini-2.5-pro`,
+// `ollama/qwen3:8b`. The prefix picks an adapter; everything after the first
+// slash is the model name and is passed through untouched. There is no
+// allowlist of model names anywhere in this codebase, on purpose — a model
+// released tomorrow works today.
+import { customProvider, isShape, SHAPES } from "./custom.js";
+import { OLLAMA_BASE_URL } from "./ollama.js";
+const ENV_PREFIX = "VAAN_PROVIDER_";
+const BUILT_IN = [
+    {
+        name: "anthropic",
+        shape: "anthropic",
+        baseUrl: "https://api.anthropic.com",
+        envKey: "ANTHROPIC_API_KEY",
+    },
+    {
+        name: "openai",
+        shape: "openai",
+        baseUrl: "https://api.openai.com/v1",
+        envKey: "OPENAI_API_KEY",
+    },
+    {
+        name: "google",
+        shape: "google",
+        baseUrl: "https://generativelanguage.googleapis.com/v1beta",
+        envKey: "GOOGLE_API_KEY",
+        altEnvKeys: ["GEMINI_API_KEY"],
+    },
+    { name: "ollama", shape: "openai", baseUrl: OLLAMA_BASE_URL },
+    {
+        name: "groq",
+        shape: "openai",
+        baseUrl: "https://api.groq.com/openai/v1",
+        envKey: "GROQ_API_KEY",
+    },
+];
+/**
+ * Built-ins plus anything registered through the environment:
+ *
+ *     VAAN_PROVIDER_TOGETHER=openai:https://api.together.xyz/v1
+ *
+ * which reads its key from `TOGETHER_API_KEY`. A name that collides with a
+ * built-in overrides it, which is how you point `openai` at a proxy.
+ */
+export function registry(env = process.env) {
+    const specs = new Map(BUILT_IN.map((spec) => [spec.name, spec]));
+    for (const [key, value] of Object.entries(env)) {
+        if (!key.startsWith(ENV_PREFIX) || !value)
+            continue;
+        const name = key.slice(ENV_PREFIX.length).toLowerCase();
+        specs.set(name, parseSpec(key, name, value));
+    }
+    return [...specs.values()];
+}
+function parseSpec(envName, name, value) {
+    const separator = value.indexOf(":");
+    const shape = value.slice(0, separator);
+    const baseUrl = value.slice(separator + 1).replace(/\/+$/, "");
+    if (!isShape(shape) || !baseUrl) {
+        // Loudly, rather than silently ignoring a typo and failing much later
+        // with a confusing 404 from whatever the default endpoint was.
+        throw new Error(`${envName} is malformed. Expected "<shape>:<url>" where shape is ` +
+            `"anthropic", "openai" or "google", for example "openai:https://api.example.com/v1".`);
+    }
+    return { name, shape, baseUrl, envKey: `${name.toUpperCase()}_API_KEY` };
+}
+/** The first of a spec's key names that is actually set. */
+export function keyFor(spec, env) {
+    for (const name of [spec.envKey, ...(spec.altEnvKeys ?? [])]) {
+        if (name && env[name])
+            return env[name];
+    }
+    return undefined;
+}
+/** Split `provider/model` and build the adapter. Throws if the key is missing. */
+export function resolve(spec, env = process.env) {
+    const slash = spec.indexOf("/");
+    const known = registry(env);
+    if (slash === -1) {
+        const names = known.map((entry) => entry.name).join(", ");
+        throw new Error(`"${spec}" is missing a provider prefix. Try one of: ${names}. ` +
+            `For example "${known[0]?.name ?? "anthropic"}/${spec}".`);
+    }
+    const name = spec.slice(0, slash).toLowerCase();
+    // Everything after the first slash, verbatim: model names contain slashes
+    // (meta-llama/Llama-3-70b) and colons (qwen3:8b).
+    const model = spec.slice(slash + 1);
+    const found = known.find((entry) => entry.name === name);
+    if (!found) {
+        const names = known.map((entry) => entry.name).join(", ");
+        throw new Error(`Unknown provider "${name}". Registered: ${names}.`);
+    }
+    if (!model)
+        throw new Error(`"${spec}" has a provider but no model name.`);
+    return { provider: build(found, env), model };
+}
+export function build(spec, env = process.env) {
+    const apiKey = spec.envKey ? (keyFor(spec, env) ?? "") : "";
+    if (spec.envKey && !apiKey) {
+        const names = [spec.envKey, ...(spec.altEnvKeys ?? [])].join(" or ");
+        throw new Error(`${spec.name} needs ${names}. Set it in your environment or .env, ` +
+            `or run \`vaan init\` to write one.`);
+    }
+    return customProvider({
+        name: spec.name,
+        shape: spec.shape,
+        baseUrl: spec.baseUrl,
+        apiKey,
+        ...(spec.envKey ? { envKey: spec.envKey } : {}),
+    });
+}
+/** What bare `/model` prints: registered prefixes and which keys are set. */
+export function statuses(env = process.env) {
+    return registry(env).map((spec) => ({
+        ...spec,
+        ready: !spec.envKey || Boolean(keyFor(spec, env)),
+    }));
+}
+export { isShape, SHAPES };
+//# sourceMappingURL=index.js.map

package/dist/src/providers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/providers/index.ts"],"names":[],"mappings":"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"}

package/dist/src/providers/ollama.js

@@ -0,0 +1,44 @@
+// Ollama, and anything else serving an OpenAI-shaped API on this machine.
+//
+// It is the chat-completions adapter pointed at localhost, with one thing added
+// that matters more than it looks: when the daemon isn't running, `fetch` fails
+// with `ECONNREFUSED` and a URL, which reads like a bug in Vaan rather than a
+// program that isn't started. Local models are the path people try first, so
+// the first failure they see should say what to do.
+import { openaiProvider } from "./openai.js";
+export const OLLAMA_BASE_URL = "http://localhost:11434/v1";
+export function ollamaProvider(opts) {
+    // No key: the header goes out anyway and the daemon ignores it.
+    const inner = openaiProvider({ ...opts, apiKey: opts.apiKey || "local" });
+    return {
+        name: opts.name,
+        async generate(req) {
+            try {
+                return await inner.generate(req);
+            }
+            catch (err) {
+                throw explain(err, opts.baseUrl, req.model);
+            }
+        },
+        async *stream(req) {
+            try {
+                yield* inner.stream(req);
+            }
+            catch (err) {
+                throw explain(err, opts.baseUrl, req.model);
+            }
+        },
+    };
+}
+function explain(err, baseUrl, model) {
+    const detail = err instanceof Error ? err.message : String(err);
+    if (/ECONNREFUSED|fetch failed|ENOTFOUND/i.test(detail)) {
+        return new Error(`Nothing is answering at ${baseUrl}. Start the daemon with \`ollama serve\`, ` +
+            `then \`ollama pull ${model}\` if you haven't already.`);
+    }
+    if (/404/.test(detail) && /model/i.test(detail)) {
+        return new Error(`Ollama doesn't have "${model}". Pull it first: \`ollama pull ${model}\`.`);
+    }
+    return err instanceof Error ? err : new Error(detail);
+}
+//# sourceMappingURL=ollama.js.map

package/dist/src/providers/ollama.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ollama.js","sourceRoot":"","sources":["../../../src/providers/ollama.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,EAAE;AACF,gFAAgF;AAChF,gFAAgF;AAChF,8EAA8E;AAC9E,6EAA6E;AAC7E,oDAAoD;AAGpD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG7C,MAAM,CAAC,MAAM,eAAe,GAAG,2BAA2B,CAAC;AAI3D,MAAM,UAAU,cAAc,CAAC,IAAmB;IAChD,gEAAgE;IAChE,MAAM,KAAK,GAAG,cAAc,CAAC,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,OAAO,EAAE,CAAC,CAAC;IAE1E,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,KAAK,CAAC,QAAQ,CAAC,GAAoB;YACjC,IAAI,CAAC;gBACH,OAAO,MAAM,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YACnC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;YAC9C,CAAC;QACH,CAAC;QACD,KAAK,CAAC,CAAC,MAAM,CAAC,GAAG;YACf,IAAI,CAAC;gBACH,KAAK,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC3B,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;YAC9C,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,OAAO,CAAC,GAAY,EAAE,OAAe,EAAE,KAAa;IAC3D,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAEhE,IAAI,sCAAsC,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACxD,OAAO,IAAI,KAAK,CACd,2BAA2B,OAAO,4CAA4C;YAC5E,sBAAsB,KAAK,4BAA4B,CAC1D,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QAChD,OAAO,IAAI,KAAK,CAAC,wBAAwB,KAAK,mCAAmC,KAAK,KAAK,CAAC,CAAC;IAC/F,CAAC;IACD,OAAO,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC;AACxD,CAAC"}

package/dist/src/providers/openai.js

@@ -0,0 +1,193 @@
+// Chat-completions adapter. Speaks to OpenAI and to everything that copies its
+// shape — Groq, Together, Ollama, vLLM, LM Studio — by pointing at a different
+// base URL. Two things differ from the Messages API and both bite:
+//
+//   1. Tool results are their own `role: "tool"` messages, one per result, not
+//      blocks inside a user turn. One Vaan message fans out into several.
+//   2. `max_tokens` is deprecated upstream in favour of `max_completion_tokens`,
+//      but most compatible servers only accept the old name. We send the name
+//      that works everywhere.
+import { parseFrameData, postJson, postSse } from "../http.js";
+import { fallbackStream, isRecord, parseArguments } from "./shared.js";
+export function openaiProvider(opts) {
+    const generate = async (req) => {
+        const json = (await postJson(`${opts.baseUrl}/chat/completions`, {
+            // Ollama and friends ignore the header; sending it unconditionally is
+            // simpler than teaching the adapter which servers want auth.
+            headers: { authorization: `Bearer ${opts.apiKey}` },
+            body: wireBody(req, false),
+            ...(req.signal ? { signal: req.signal } : {}),
+        }));
+        return fromWire(json);
+    };
+    return {
+        name: opts.name,
+        ...(opts.envKey ? { envKey: opts.envKey } : {}),
+        generate,
+        stream(req) {
+            return streamCompletions(opts, req, generate);
+        },
+    };
+}
+function wireBody(req, stream) {
+    const messages = [];
+    if (req.system)
+        messages.push({ role: "system", content: req.system });
+    for (const message of req.messages)
+        messages.push(...toWireMessages(message));
+    return {
+        model: req.model,
+        max_tokens: req.maxTokens,
+        messages,
+        ...(req.tools.length ? { tools: req.tools.map(toWireTool) } : {}),
+        ...(stream ? { stream: true, stream_options: { include_usage: true } } : {}),
+    };
+}
+function toWireMessages(message) {
+    // GUARD 1. Echo the assistant turn exactly as it arrived. Reasoning models
+    // return fields we don't model (`reasoning_content` and friends) that have to
+    // come back unmodified, and the turn's `tool_calls` must match the `tool`
+    // messages that follow it.
+    if (message.role === "assistant" && isRecord(message.raw))
+        return [message.raw];
+    const results = message.parts.filter((part) => part.type === "tool_result");
+    if (results.length > 0) {
+        // Fan out: one `tool` message per result. Unlike the Messages API these
+        // are siblings, not blocks inside a single user turn.
+        return results.map((part) => ({
+            role: "tool",
+            tool_call_id: part.id,
+            content: part.isError ? `Error: ${part.output}` : part.output,
+        }));
+    }
+    const text = message.parts
+        .filter((part) => part.type === "text")
+        .map((part) => part.text)
+        .join("");
+    return [{ role: message.role, content: text }];
+}
+const toWireTool = (tool) => ({
+    type: "function",
+    function: {
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.parameters,
+    },
+});
+function fromWire(res) {
+    const choice = res.choices?.[0];
+    const wire = choice?.message ?? {};
+    const message = { role: "assistant", parts: partsOf(wire), raw: wire };
+    const usage = res.usage
+        ? { input: res.usage.prompt_tokens ?? 0, output: res.usage.completion_tokens ?? 0 }
+        : undefined;
+    return { message, stop: toStopReason(choice?.finish_reason), ...(usage ? { usage } : {}) };
+}
+function partsOf(wire) {
+    const parts = [];
+    if (wire.content)
+        parts.push({ type: "text", text: wire.content });
+    for (const call of wire.tool_calls ?? []) {
+        if (!call.id || !call.function?.name)
+            continue;
+        parts.push({
+            type: "tool_call",
+            id: call.id,
+            name: call.function.name,
+            input: parseArguments(call.function.arguments),
+        });
+    }
+    return parts;
+}
+function toStopReason(reason) {
+    switch (reason) {
+        case "tool_calls":
+        case "function_call":
+            return "tool_use";
+        case "length":
+            return "max_tokens";
+        default:
+            // There is no `pause_turn` equivalent in this shape.
+            return "done";
+    }
+}
+/**
+ * Reassemble a streamed completion into the same message `generate` returns.
+ *
+ * Tool calls arrive as fragments keyed by `index`, not by id — the id itself
+ * only appears in the first fragment — so they're accumulated positionally and
+ * only announced once the stream is done and the arguments are complete JSON.
+ */
+async function* streamCompletions(opts, req, generate) {
+    const calls = [];
+    let text = "";
+    let finish;
+    let usage;
+    let yielded = false;
+    try {
+        const frames = postSse(`${opts.baseUrl}/chat/completions`, {
+            headers: { authorization: `Bearer ${opts.apiKey}` },
+            body: wireBody(req, true),
+            ...(req.signal ? { signal: req.signal } : {}),
+        });
+        for await (const frame of frames) {
+            const chunk = parseFrameData(frame.data);
+            if (!chunk)
+                continue;
+            if (chunk.usage) {
+                usage = {
+                    input: chunk.usage.prompt_tokens ?? 0,
+                    output: chunk.usage.completion_tokens ?? 0,
+                };
+            }
+            const choice = chunk.choices?.[0];
+            if (!choice)
+                continue;
+            if (choice.finish_reason)
+                finish = choice.finish_reason;
+            const content = choice.delta?.content;
+            if (content) {
+                text += content;
+                yielded = true;
+                yield { type: "text", text: content };
+            }
+            for (const fragment of choice.delta?.tool_calls ?? []) {
+                const index = fragment.index ?? calls.length;
+                const existing = calls[index] ?? { function: { name: "", arguments: "" } };
+                calls[index] = {
+                    id: fragment.id ?? existing.id,
+                    index,
+                    function: {
+                        name: fragment.function?.name ?? existing.function?.name,
+                        arguments: (existing.function?.arguments ?? "") + (fragment.function?.arguments ?? ""),
+                    },
+                };
+            }
+        }
+    }
+    catch (err) {
+        if (!yielded) {
+            yield* fallbackStream(generate, req);
+            return;
+        }
+        throw err;
+    }
+    const assembled = {
+        ...(text ? { content: text } : {}),
+        ...(calls.length ? { tool_calls: calls.filter((call) => call !== undefined) } : {}),
+    };
+    for (const part of partsOf(assembled)) {
+        if (part.type === "tool_call") {
+            yield { type: "tool_call", id: part.id, name: part.name, input: part.input };
+        }
+    }
+    yield {
+        type: "done",
+        reply: {
+            message: { role: "assistant", parts: partsOf(assembled), raw: assembled },
+            stop: toStopReason(finish),
+            ...(usage ? { usage } : {}),
+        },
+    };
+}
+//# sourceMappingURL=openai.js.map

package/dist/src/providers/openai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../../src/providers/openai.ts"],"names":[],"mappings":"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"}

package/dist/src/providers/shared.js

@@ -0,0 +1,32 @@
+// Bits every adapter needs, so none of them grows its own copy.
+/**
+ * `stream` for an adapter that has no streaming endpoint, or whose stream just
+ * failed. It waits for the whole turn and then replays it as events: correct,
+ * and indistinguishable to a caller that only cares about the events — just not
+ * incremental. Better than an interface that is optional on half the providers.
+ */
+export async function* fallbackStream(generate, req) {
+    const reply = await generate(req);
+    for (const part of reply.message.parts) {
+        if (part.type === "text")
+            yield { type: "text", text: part.text };
+        else if (part.type === "tool_call") {
+            yield { type: "tool_call", id: part.id, name: part.name, input: part.input };
+        }
+    }
+    yield { type: "done", reply };
+}
+/** Tool-call arguments arrive as a JSON string, and a model can emit bad JSON. */
+export function parseArguments(raw) {
+    if (!raw)
+        return {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        // An empty input reaches the tool, which reports what it needed.
+        return {};
+    }
+}
+export const isRecord = (value) => value !== null && typeof value === "object";
+//# sourceMappingURL=shared.js.map

package/dist/src/providers/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../../src/providers/shared.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAWhE;;;;;GAKG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,cAAc,CACnC,QAA0D,EAC1D,GAAoB;IAEpB,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAC;IAClC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACvC,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM;YAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;aAC7D,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YACnC,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;QAC/E,CAAC;IACH,CAAC;IACD,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AAChC,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,cAAc,CAAC,GAAuB;IACpD,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,CAAC;IACpB,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,iEAAiE;QACjE,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,KAAc,EAAoC,EAAE,CAC3E,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC"}

package/dist/src/sandbox/filesystem.js

@@ -0,0 +1,193 @@
+// The filesystem boundary.
+//
+// Every path a tool is handed is resolved against the workspace and rejected if
+// it lands outside. This is the fence. GUARDRAILS.md is instruction; a confused
+// model can talk itself past instruction. It cannot talk itself past this.
+//
+// The permission policy sits above this and decides whether an in-bounds path
+// may be written at all. The two are separate on purpose: the jail answers
+// "where", the policy answers "may you".
+import { readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+export class JailError extends Error {
+    constructor(candidate) {
+        super(`"${candidate}" is outside the workspace, so Vaan won't touch it.`);
+        this.name = "JailError";
+    }
+}
+/**
+ * Resolve `candidate` inside `workspace`, or throw.
+ *
+ * Two checks, because either alone has a hole. Resolving normalises away `..`,
+ * which stops a traversal spelled out in the path. But a symlink inside the
+ * workspace can point anywhere, and resolving doesn't follow it — so we also
+ * resolve the real path and check that. For a file that doesn't exist yet we
+ * check the nearest ancestor that does: components that don't exist can't be
+ * symlinks, so if the deepest real ancestor is inside, the new file will be too.
+ */
+export function jail(workspace, candidate) {
+    const root = realpathSync(resolve(workspace));
+    const target = resolve(root, candidate);
+    if (!within(root, target))
+        throw new JailError(candidate);
+    if (!within(root, realpathOfNearest(target)))
+        throw new JailError(candidate);
+    return target;
+}
+/** The same question without the throw, for classification rather than access. */
+export function isInside(workspace, candidate) {
+    try {
+        jail(workspace, candidate);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const within = (root, path) => path === root || path.startsWith(root + sep);
+function realpathOfNearest(target) {
+    let current = target;
+    for (;;) {
+        try {
+            return realpathSync(current);
+        }
+        catch {
+            const parent = dirname(current);
+            // Hit the filesystem root without finding anything real. Nothing to
+            // resolve, and the plain resolve() check above already passed.
+            if (parent === current)
+                return current;
+            current = parent;
+        }
+    }
+}
+export const MAX_READ_BYTES = 100_000;
+export const MAX_ENTRIES = 300;
+export function readText(workspace, path) {
+    const target = jail(workspace, path);
+    const { size } = statSync(target);
+    const text = readFileSync(target, "utf8");
+    return size <= MAX_READ_BYTES
+        ? { text, bytes: size, truncated: false }
+        : { text: text.slice(0, MAX_READ_BYTES), bytes: size, truncated: true };
+}
+export function writeText(workspace, path, content) {
+    const target = jail(workspace, path);
+    writeFileSync(target, content, "utf8");
+    return target;
+}
+export function listEntries(workspace, path) {
+    const target = jail(workspace, path);
+    const all = readdirSync(target, { withFileTypes: true })
+        .map((entry) => (entry.isDirectory() ? `${entry.name}/` : entry.name))
+        .sort((a, b) => a.localeCompare(b));
+    return { entries: all.slice(0, MAX_ENTRIES), more: Math.max(0, all.length - MAX_ENTRIES) };
+}
+/** Directories that are never worth walking, and never what anyone meant. */
+export const IGNORED_DIRS = new Set([
+    ".git",
+    ".vaan",
+    "node_modules",
+    "dist",
+    "build",
+    "out",
+    "target",
+    "coverage",
+    ".next",
+    ".nuxt",
+    ".venv",
+    "venv",
+    "__pycache__",
+    ".pytest_cache",
+    ".mypy_cache",
+    ".gradle",
+    ".idea",
+    ".cache",
+    "vendor",
+]);
+/** Every file under `workspace`, skipping the directories nobody greps. */
+export function* walk(workspace, opts = {}) {
+    const limit = opts.limit ?? 20_000;
+    const maxDepth = opts.maxDepth ?? 12;
+    const root = realpathSync(resolve(workspace));
+    let seen = 0;
+    const queue = [{ dir: root, depth: 0 }];
+    while (queue.length > 0) {
+        const next = queue.shift();
+        if (!next || next.depth > maxDepth)
+            continue;
+        let entries;
+        try {
+            entries = readdirSync(next.dir, { withFileTypes: true });
+        }
+        catch {
+            continue; // Unreadable directory: not an error, just nothing to report.
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith(".") && entry.name !== ".github") {
+                if (IGNORED_DIRS.has(entry.name) || entry.isDirectory())
+                    continue;
+            }
+            const full = join(next.dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!IGNORED_DIRS.has(entry.name))
+                    queue.push({ dir: full, depth: next.depth + 1 });
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            if (++seen > limit)
+                return;
+            yield relative(root, full);
+        }
+    }
+}
+/** Bytes past which a file is assumed to be a build artefact rather than source. */
+const MAX_SEARCHABLE_BYTES = 400_000;
+/**
+ * Grep the workspace. Plain substring by default; a regex when asked, compiled
+ * with a length cap so a pathological pattern can't hang the turn.
+ */
+export function search(workspace, needle, opts = {}) {
+    const limit = opts.limit ?? 60;
+    const matcher = opts.regex ? safeRegex(needle) : undefined;
+    const lowered = needle.toLowerCase();
+    const out = [];
+    for (const path of walk(workspace)) {
+        if (out.length >= limit)
+            break;
+        if (opts.glob && !path.includes(opts.glob) && !path.endsWith(opts.glob))
+            continue;
+        let body;
+        try {
+            const full = join(realpathSync(resolve(workspace)), path);
+            if (statSync(full).size > MAX_SEARCHABLE_BYTES)
+                continue;
+            body = readFileSync(full, "utf8");
+        }
+        catch {
+            continue; // Binary, unreadable, or gone since the walk. Skip it.
+        }
+        if (body.includes("\u0000"))
+            continue;
+        const lines = body.split("\n");
+        for (let index = 0; index < lines.length && out.length < limit; index++) {
+            const line = lines[index] ?? "";
+            const hit = matcher ? matcher.test(line) : line.toLowerCase().includes(lowered);
+            if (hit)
+                out.push({ path, line: index + 1, text: line.trim().slice(0, 200) });
+        }
+    }
+    return out;
+}
+function safeRegex(pattern) {
+    if (pattern.length > 200)
+        throw new Error("Pattern is too long.");
+    try {
+        return new RegExp(pattern);
+    }
+    catch (err) {
+        throw new Error(`Not a valid regular expression: ${err instanceof Error ? err.message : err}`);
+    }
+}
+//# sourceMappingURL=filesystem.js.map

package/dist/src/sandbox/filesystem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem.js","sourceRoot":"","sources":["../../../src/sandbox/filesystem.ts"],"names":[],"mappings":"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"}