vaan-ai 0.1.0

package/dist/src/sandbox/network.js

@@ -0,0 +1,119 @@
+// The network boundary for tools.
+//
+// The provider adapters don't come through here — talking to the model is the
+// one network call the user configured on purpose. Everything the *model* asks
+// for does, and the interesting case isn't the public internet. It's the local
+// one: a page that says "fetch http://169.254.169.254/latest/meta-data/" is
+// asking the agent to read cloud credentials from inside the trust boundary,
+// and a page that says "fetch http://localhost:8080/admin" is asking it to
+// reach something the firewall thinks is safe because it's local.
+//
+// So loopback and private ranges are refused by default, and text from a page
+// is information rather than instruction wherever it ends up.
+export const DEFAULT_NETWORK_POLICY = { allow: [], deny: [], allowLocal: false };
+/** Link-local, loopback, and the ranges that are only reachable from inside. */
+const PRIVATE_HOSTS = [
+    /^localhost$/i,
+    /^127\./,
+    /^0\.0\.0\.0$/,
+    /^10\./,
+    /^192\.168\./,
+    /^172\.(1[6-9]|2\d|3[01])\./,
+    /^169\.254\./, // includes the cloud metadata address
+    /^::1$/,
+    /^\[::1\]$/,
+    /^f[cd][0-9a-f]{2}:/i,
+    /\.local$/i,
+    /\.internal$/i,
+];
+/** Decide whether a tool may fetch this URL, before any permission prompt. */
+export function checkUrl(raw, policy = DEFAULT_NETWORK_POLICY) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return { ok: false, reason: "not a valid URL", host: "" };
+    }
+    const host = url.hostname;
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        return { ok: false, reason: `${url.protocol} is not a scheme Vaan fetches`, host };
+    }
+    if (policy.deny.some((entry) => hostMatches(entry, host))) {
+        return { ok: false, reason: "host is on the deny list", host };
+    }
+    if (policy.allow.some((entry) => hostMatches(entry, host))) {
+        return { ok: true, reason: "host is on the allow list", host };
+    }
+    if (!policy.allowLocal && PRIVATE_HOSTS.some((pattern) => pattern.test(host))) {
+        return {
+            ok: false,
+            reason: "that address is on this machine or its private network, which the agent doesn't reach",
+            host,
+        };
+    }
+    return { ok: true, reason: "public host", host };
+}
+const hostMatches = (entry, host) => entry.toLowerCase() === host.toLowerCase() || host.toLowerCase().endsWith(`.${entry.toLowerCase()}`);
+export const MAX_FETCH_BYTES = 200_000;
+const FETCH_TIMEOUT_MS = 20_000;
+/**
+ * Fetch a page as text, with a size cap and a timeout.
+ *
+ * Redirects are followed by `fetch`, so the final URL is re-checked: a public
+ * URL that 302s to 169.254.169.254 would otherwise walk straight past the
+ * check above.
+ */
+export async function fetchText(raw, policy = DEFAULT_NETWORK_POLICY, signal) {
+    const verdict = checkUrl(raw, policy);
+    if (!verdict.ok)
+        throw new Error(`${raw}: ${verdict.reason}`);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    signal?.addEventListener("abort", () => controller.abort(), { once: true });
+    try {
+        const response = await fetch(raw, {
+            redirect: "follow",
+            signal: controller.signal,
+            headers: { accept: "text/html,text/plain,application/json;q=0.9,*/*;q=0.5" },
+        });
+        const landed = checkUrl(response.url || raw, policy);
+        if (!landed.ok)
+            throw new Error(`${raw} redirected to ${landed.host}: ${landed.reason}`);
+        const body = await response.text();
+        return {
+            url: response.url || raw,
+            status: response.status,
+            contentType: response.headers.get("content-type") ?? "",
+            text: body.slice(0, MAX_FETCH_BYTES),
+            truncated: body.length > MAX_FETCH_BYTES,
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+const BLOCK_TAGS = /<(script|style|noscript|template|svg)[^>]*>[\s\S]*?<\/\1>/gi;
+const ENTITIES = {
+    "&amp;": "&",
+    "&lt;": "<",
+    "&gt;": ">",
+    "&quot;": '"',
+    "&#x27;": "'",
+    "&#39;": "'",
+    "&nbsp;": " ",
+};
+/** HTML to something a model can read. Not a browser, and doesn't pretend to be. */
+export function toReadableText(html) {
+    return html
+        .replace(BLOCK_TAGS, " ")
+        .replace(/<!--[\s\S]*?-->/g, " ")
+        .replace(/<\/(p|div|section|article|li|tr|h[1-6])>/gi, "\n")
+        .replace(/<br\s*\/?>/gi, "\n")
+        .replace(/<[^>]*>/g, " ")
+        .replace(/&(?:amp|lt|gt|quot|#x27|#39|nbsp);/g, (entity) => ENTITIES[entity] ?? entity)
+        .replace(/[ \t]+/g, " ")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+//# sourceMappingURL=network.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"network.js","sourceRoot":"","sources":["../../../src/sandbox/network.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,EAAE;AACF,8EAA8E;AAC9E,+EAA+E;AAC/E,+EAA+E;AAC/E,4EAA4E;AAC5E,6EAA6E;AAC7E,2EAA2E;AAC3E,kEAAkE;AAClE,EAAE;AACF,8EAA8E;AAC9E,8DAA8D;AAW9D,MAAM,CAAC,MAAM,sBAAsB,GAAkB,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;AAEhG,gFAAgF;AAChF,MAAM,aAAa,GAAa;IAC9B,cAAc;IACd,QAAQ;IACR,cAAc;IACd,OAAO;IACP,aAAa;IACb,4BAA4B;IAC5B,aAAa,EAAE,sCAAsC;IACrD,OAAO;IACP,WAAW;IACX,qBAAqB;IACrB,WAAW;IACX,cAAc;CACf,CAAC;AAQF,8EAA8E;AAC9E,MAAM,UAAU,QAAQ,CAAC,GAAW,EAAE,SAAwB,sBAAsB;IAClF,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;IAC5D,CAAC;IACD,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC;IAE1B,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC1D,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,QAAQ,+BAA+B,EAAE,IAAI,EAAE,CAAC;IACrF,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC;QAC1D,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,0BAA0B,EAAE,IAAI,EAAE,CAAC;IACjE,CAAC;IACD,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC;QAC3D,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,2BAA2B,EAAE,IAAI,EAAE,CAAC;IACjE,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,UAAU,IAAI,aAAa,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;QAC9E,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EACJ,uFAAuF;YACzF,IAAI;SACL,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;AACnD,CAAC;AAED,MAAM,WAAW,GAAG,CAAC,KAAa,EAAE,IAAY,EAAW,EAAE,CAC3D,KAAK,CAAC,WAAW,EAAE,KAAK,IAAI,CAAC,WAAW,EAAE,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;AAEvG,MAAM,CAAC,MAAM,eAAe,GAAG,OAAO,CAAC;AACvC,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAUhC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,GAAW,EACX,SAAwB,sBAAsB,EAC9C,MAAoB;IAEpB,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACtC,IAAI,CAAC,OAAO,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,GAAG,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAE9D,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,gBAAgB,CAAC,CAAC;IACrE,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAE5E,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAChC,QAAQ,EAAE,QAAQ;YAClB,MAAM,EAAE,UAAU,CAAC,MAAM;YACzB,OAAO,EAAE,EAAE,MAAM,EAAE,uDAAuD,EAAE;SAC7E,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAAC,GAAG,IAAI,GAAG,EAAE,MAAM,CAAC,CAAC;QACrD,IAAI,CAAC,MAAM,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,GAAG,GAAG,kBAAkB,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QAEzF,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QACnC,OAAO;YACL,GAAG,EAAE,QAAQ,CAAC,GAAG,IAAI,GAAG;YACxB,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,WAAW,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,EAAE;YACvD,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,eAAe,CAAC;YACpC,SAAS,EAAE,IAAI,CAAC,MAAM,GAAG,eAAe;SACzC,CAAC;IACJ,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,GAAG,6DAA6D,CAAC;AAEjF,MAAM,QAAQ,GAA2B;IACvC,OAAO,EAAE,GAAG;IACZ,MAAM,EAAE,GAAG;IACX,MAAM,EAAE,GAAG;IACX,QAAQ,EAAE,GAAG;IACb,QAAQ,EAAE,GAAG;IACb,OAAO,EAAE,GAAG;IACZ,QAAQ,EAAE,GAAG;CACd,CAAC;AAEF,oFAAoF;AACpF,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,IAAI;SACR,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC;SACxB,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC;SAChC,OAAO,CAAC,4CAA4C,EAAE,IAAI,CAAC;SAC3D,OAAO,CAAC,cAAc,EAAE,IAAI,CAAC;SAC7B,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC;SACxB,OAAO,CAAC,qCAAqC,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC;SACtF,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;SACvB,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC;SAC1B,IAAI,EAAE,CAAC;AACZ,CAAC"}

package/dist/src/sandbox/process.js

@@ -0,0 +1,198 @@
+// Running a command, without handing the model a shell.
+//
+// The old objection to an exec tool was sound: a shell resolves its own paths,
+// so it can't be jailed, and approving `bash -c "…"` is approving an opaque
+// string, so it can't be meaningfully confirmed either. Both problems come from
+// the shell, not from execution.
+//
+// So there is no shell. The command is tokenised here, in-process, and spawned
+// with `shell: false`. Metacharacters outside quotes are rejected rather than
+// interpreted, which means the argv a human approves is exactly the argv that
+// runs: no pipes, no redirection, no command substitution, no `&&` tail that
+// nobody read. What's left is `npm test`, `git status`, `pytest -k auth` — the
+// things a coding agent actually needs.
+//
+// On top of that: cwd is pinned to the workspace, credentials are stripped from
+// the environment, output is capped, and the whole thing is killed on a timeout.
+import { spawn } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { resolve, sep } from "node:path";
+export class CommandError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CommandError";
+    }
+}
+/** Rejected outside quotes. Each one is a way to run something else entirely. */
+const METACHARACTERS = new Set([";", "&", "|", "<", ">", "`", "$", "(", ")", "{", "}", "\n", "\r"]);
+/**
+ * Split a command line into argv, or throw.
+ *
+ * Quoted segments may contain anything — `--grep "a|b"` is a legitimate
+ * argument, not a pipe. Unquoted metacharacters are refused with a message the
+ * model can act on, because "run these as two commands" is a fix it can make.
+ */
+export function tokenize(command) {
+    const argv = [];
+    let current = "";
+    let started = false;
+    let quote;
+    for (let index = 0; index < command.length; index++) {
+        const char = command[index];
+        if (quote) {
+            if (char === quote)
+                quote = undefined;
+            else if (char === "\\" && quote === '"' && index + 1 < command.length) {
+                current += command[++index];
+            }
+            else
+                current += char;
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            started = true;
+            continue;
+        }
+        if (char === " " || char === "\t") {
+            if (started)
+                argv.push(current);
+            current = "";
+            started = false;
+            continue;
+        }
+        if (METACHARACTERS.has(char)) {
+            throw new CommandError(`"${char}" is a shell metacharacter and Vaan does not run commands through a shell. ` +
+                `Run one command at a time, and quote arguments that need it.`);
+        }
+        current += char;
+        started = true;
+    }
+    if (quote)
+        throw new CommandError("Unbalanced quote in the command.");
+    if (started)
+        argv.push(current);
+    if (argv.length === 0)
+        throw new CommandError("No command given.");
+    return argv;
+}
+/** Environment names whose value never enters the sandbox. */
+const SECRET_ENV = /(?:^|_)(?:API[-_]?KEY|APIKEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIALS?|PRIVATE[-_]?KEY|SESSION|COOKIE|AUTH)(?:$|_)/i;
+/**
+ * The parent environment minus anything that looks like a credential.
+ *
+ * A test run genuinely needs PATH, HOME and the rest of the ambient
+ * environment, so this is a denylist rather than an allowlist — but the model's
+ * own provider keys are exactly the shape this matches, so they never reach a
+ * process the model asked for.
+ */
+export function scrubEnv(env) {
+    const out = {};
+    for (const [key, value] of Object.entries(env)) {
+        if (value === undefined)
+            continue;
+        if (SECRET_ENV.test(key))
+            continue;
+        out[key] = value;
+    }
+    out.VAAN_SANDBOX = "1";
+    return out;
+}
+export const DEFAULT_TIMEOUT_MS = 120_000;
+export const MAX_OUTPUT_BYTES = 60_000;
+/**
+ * Run `command` inside the workspace and come back with what it printed.
+ *
+ * `async` rather than a plain Promise-returning function so that a refused
+ * command — a metacharacter, a cwd outside the workspace — arrives as a
+ * rejection like every other failure, instead of throwing synchronously past a
+ * caller that was only expecting `.catch()`.
+ */
+export async function runCommand(opts) {
+    const argv = tokenize(opts.command);
+    const [program, ...args] = argv;
+    const cwd = jailCwd(opts.workspace, opts.cwd);
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const startedAt = Date.now();
+    return new Promise((settle) => {
+        const child = spawn(program, args, {
+            cwd,
+            env: scrubEnv(opts.env ?? process.env),
+            shell: false,
+            // Nothing to type at: a command that waits for input would hang forever,
+            // so it gets EOF immediately instead.
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        let truncated = false;
+        let timedOut = false;
+        const capture = (chunk, into) => {
+            const text = chunk.toString("utf8");
+            if (into === "out") {
+                if (stdout.length + text.length > MAX_OUTPUT_BYTES)
+                    truncated = true;
+                stdout = (stdout + text).slice(0, MAX_OUTPUT_BYTES);
+            }
+            else {
+                if (stderr.length + text.length > MAX_OUTPUT_BYTES)
+                    truncated = true;
+                stderr = (stderr + text).slice(0, MAX_OUTPUT_BYTES);
+            }
+        };
+        child.stdout?.on("data", (chunk) => capture(chunk, "out"));
+        child.stderr?.on("data", (chunk) => capture(chunk, "err"));
+        const stop = () => {
+            child.kill("SIGKILL");
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            stop();
+        }, timeoutMs);
+        opts.signal?.addEventListener("abort", stop, { once: true });
+        const done = (code) => {
+            clearTimeout(timer);
+            opts.signal?.removeEventListener("abort", stop);
+            settle({
+                argv,
+                code,
+                stdout,
+                stderr,
+                timedOut,
+                truncated,
+                ms: Date.now() - startedAt,
+            });
+        };
+        child.on("error", (err) => {
+            stderr = `${stderr}${err.message}`;
+            done(null);
+        });
+        child.on("close", done);
+    });
+}
+/** The working directory must be inside the workspace, like every other path. */
+function jailCwd(workspace, candidate) {
+    const root = realpathSync(resolve(workspace));
+    if (!candidate)
+        return root;
+    const target = resolve(root, candidate);
+    const real = (() => {
+        try {
+            return realpathSync(target);
+        }
+        catch {
+            return target;
+        }
+    })();
+    if (real !== root && !real.startsWith(root + sep)) {
+        throw new CommandError(`"${candidate}" is outside the workspace.`);
+    }
+    return real;
+}
+/** A one-line summary of a run, for the trace and for the tool result. */
+export function summarise(result) {
+    if (result.timedOut)
+        return `timed out after ${result.ms}ms`;
+    return `exit ${result.code ?? "signal"} in ${result.ms}ms`;
+}
+//# sourceMappingURL=process.js.map

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

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

package/dist/src/skills.js

@@ -0,0 +1,80 @@
+// Skills are markdown in .vaan/skills/, not code. There is no plugin API to
+// learn and nothing to keep in sync with a Vaan release.
+//
+//     .vaan/skills/
+//       code-review/SKILL.md
+//       deployment/SKILL.md
+//
+// Only each skill's first line goes in the system prompt. When one applies, the
+// model reads the whole file with read_file — the skills folder is inside the
+// workspace, so the tool it already has is the tool it uses. Twenty skills
+// therefore cost twenty lines per turn, not twenty skills' worth.
+//
+// A skill is instruction, not permission. Nothing a SKILL.md says can widen
+// what the agent may do: the gate doesn't read them and wouldn't care.
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { skillsDir, skillsRelative } from "./paths.js";
+/** Past this many, the descriptions themselves start costing real tokens. */
+const WARN_ABOVE = 20;
+const MAX_DESCRIPTION = 200;
+export function loadSkills(workspace) {
+    const root = skillsDir(workspace);
+    let entries;
+    try {
+        entries = readdirSync(root).sort();
+    }
+    catch {
+        return { skills: [], warnings: [] };
+    }
+    const skills = [];
+    for (const entry of entries) {
+        const found = locate(root, entry);
+        if (!found)
+            continue;
+        const description = firstLine(join(workspace, found.path));
+        if (!description)
+            continue;
+        skills.push({ name: found.name, path: found.path, description });
+    }
+    const warnings = skills.length > WARN_ABOVE
+        ? [
+            `${skills.length} skills in ${skillsRelative}. Their descriptions are sent on every ` +
+                `turn — consider merging or removing some.`,
+        ]
+        : [];
+    return { skills, warnings };
+}
+/**
+ * A skill is `<name>/SKILL.md`. A bare `<name>.md` is accepted too, because
+ * that is what people write first and refusing it teaches nothing.
+ */
+function locate(root, entry) {
+    const full = join(root, entry);
+    try {
+        if (statSync(full).isDirectory()) {
+            const inner = join(full, "SKILL.md");
+            statSync(inner);
+            return { name: entry, path: join(skillsRelative, entry, "SKILL.md") };
+        }
+    }
+    catch {
+        return undefined; // A directory without a SKILL.md isn't a skill.
+    }
+    if (!entry.endsWith(".md"))
+        return undefined;
+    return { name: entry.replace(/\.md$/, ""), path: join(skillsRelative, entry) };
+}
+function firstLine(path) {
+    try {
+        const line = readFileSync(path, "utf8")
+            .split("\n")
+            .map((candidate) => candidate.replace(/^#+\s*/, "").trim())
+            .find((candidate) => candidate.length > 0);
+        return line ? line.slice(0, MAX_DESCRIPTION) : "";
+    }
+    catch {
+        return "";
+    }
+}
+//# sourceMappingURL=skills.js.map

package/dist/src/skills.js.map

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

package/dist/src/tools/basics.js

@@ -0,0 +1,41 @@
+export const now = {
+    name: "now",
+    description: "The current date and time. Call this before answering anything that depends on today's " +
+        "date — you have no other way to know it.",
+    group: "files",
+    parameters: { type: "object", properties: {} },
+    run() {
+        const at = new Date();
+        const zone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+        const local = at.toLocaleString(undefined, { dateStyle: "full", timeStyle: "long" });
+        return `${at.toISOString()} (UTC)\n${local} (${zone})`;
+    },
+};
+export const remember = {
+    name: "remember",
+    description: "Store one short, durable fact about the user, so it is available in every future " +
+        "conversation. Good: a dietary restriction, where they live, what they're building, how " +
+        "they like answers written. Not for anything that stops being true next week, and not for " +
+        "restating what was just said. Every stored fact costs tokens on every turn, so keep each " +
+        "one to a sentence and only store what's worth carrying.",
+    group: "memory",
+    parameters: {
+        type: "object",
+        properties: {
+            fact: {
+                type: "string",
+                description: 'The fact, written as a standalone sentence: "Is allergic to prawns."',
+            },
+        },
+        required: ["fact"],
+    },
+    async run(input, ctx) {
+        const fact = String(input.fact ?? "").trim();
+        if (!fact)
+            return "Nothing to remember — the fact was empty.";
+        await ctx.remember(fact);
+        ctx.trace.record({ kind: "memory", op: "remember", detail: fact });
+        return `Remembered: ${fact}`;
+    },
+};
+//# sourceMappingURL=basics.js.map

package/dist/src/tools/basics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"basics.js","sourceRoot":"","sources":["../../../src/tools/basics.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,GAAG,GAAS;IACvB,IAAI,EAAE,KAAK;IACX,WAAW,EACT,yFAAyF;QACzF,0CAA0C;IAC5C,KAAK,EAAE,OAAO;IACd,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE;IAC9C,GAAG;QACD,MAAM,EAAE,GAAG,IAAI,IAAI,EAAE,CAAC;QACtB,MAAM,IAAI,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC,eAAe,EAAE,CAAC,QAAQ,CAAC;QAC9D,MAAM,KAAK,GAAG,EAAE,CAAC,cAAc,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;QACrF,OAAO,GAAG,EAAE,CAAC,WAAW,EAAE,WAAW,KAAK,KAAK,IAAI,GAAG,CAAC;IACzD,CAAC;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,QAAQ,GAAS;IAC5B,IAAI,EAAE,UAAU;IAChB,WAAW,EACT,mFAAmF;QACnF,yFAAyF;QACzF,2FAA2F;QAC3F,2FAA2F;QAC3F,yDAAyD;IAC3D,KAAK,EAAE,QAAQ;IACf,UAAU,EAAE;QACV,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,IAAI,EAAE;gBACJ,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,sEAAsE;aACpF;SACF;QACD,QAAQ,EAAE,CAAC,MAAM,CAAC;KACnB;IACD,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG;QAClB,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QAC7C,IAAI,CAAC,IAAI;YAAE,OAAO,2CAA2C,CAAC;QAC9D,MAAM,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACzB,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;QACnE,OAAO,eAAe,IAAI,EAAE,CAAC;IAC/B,CAAC;CACF,CAAC"}

package/dist/src/tools/code.js

@@ -0,0 +1,114 @@
+// run_command — the coding sandbox's one entry point.
+//
+// This is the tool the old design refused to ship, and the objection was right
+// as far as it went: a shell resolves its own paths so it can't be jailed, and
+// approving `bash -c "…"` is approving an opaque string so it can't be
+// meaningfully confirmed. Both of those are properties of the shell.
+//
+// So there is no shell. src/sandbox/process.ts tokenises the command in-process
+// and spawns it with `shell: false`; unquoted metacharacters are rejected rather
+// than interpreted. What the user approves is the argv that runs — no pipe, no
+// `&&` tail, no command substitution, nothing that resolves to something else
+// after they said yes. On top of that, cwd is pinned inside the workspace,
+// credentials are stripped from the environment, output is capped and the
+// process is killed on a timeout.
+//
+// Classification decides which permission is asked for: `npm test` is
+// `execute`, `rm -rf build` is `destructive`, `npm install` is `network`, and
+// `mkfs` is refused without a prompt because there is no good answer to it.
+import { classifyCommand } from "../permissions/rules.js";
+import { CommandError, DEFAULT_TIMEOUT_MS, runCommand, summarise } from "../sandbox/process.js";
+const MAX_TIMEOUT_MS = 600_000;
+export const runCommandTool = {
+    name: "run_command",
+    description: "Run one command inside the workspace and get back its output and exit code. Use it to " +
+        "run tests, build, or inspect the project with its own tooling. There is no shell: " +
+        "pipes, redirection, `&&` and command substitution are rejected, so run one command at " +
+        "a time. The user approves the exact command before it runs.",
+    group: "code",
+    parameters: {
+        type: "object",
+        properties: {
+            command: {
+                type: "string",
+                description: 'One command with its arguments, e.g. "npm test" or "pytest -k auth".',
+            },
+            cwd: {
+                type: "string",
+                description: "Directory to run in, relative to the workspace. Defaults to its root.",
+            },
+            timeout_seconds: {
+                type: "number",
+                description: "How long to wait before killing it. Default 120, maximum 600.",
+            },
+        },
+        required: ["command"],
+    },
+    async run(input, ctx) {
+        const command = String(input.command ?? "").trim();
+        if (!command)
+            return "No command given.";
+        const shape = classifyCommand(command);
+        if (shape.forbidden) {
+            ctx.trace.record({
+                kind: "sandbox",
+                op: "refused",
+                target: command,
+                ok: false,
+                detail: shape.reasons.join("; "),
+            });
+            return (`Refused: that command ${shape.reasons.join(", ")}. This one isn't approvable — ` +
+                `if it's genuinely what you want, the user should run it themselves.`);
+        }
+        await ctx.gate.require({
+            tool: "run_command",
+            capability: shape.capability,
+            target: command,
+            ...(shape.reasons.length ? { detail: shape.reasons.join(", ") } : {}),
+        });
+        const seconds = Number(input.timeout_seconds);
+        const timeoutMs = Number.isFinite(seconds)
+            ? Math.min(Math.max(seconds, 1) * 1000, MAX_TIMEOUT_MS)
+            : DEFAULT_TIMEOUT_MS;
+        try {
+            const result = await runCommand({
+                command,
+                workspace: ctx.workspace,
+                ...(input.cwd === undefined ? {} : { cwd: String(input.cwd) }),
+                timeoutMs,
+                env: ctx.env,
+                ...(ctx.signal ? { signal: ctx.signal } : {}),
+            });
+            ctx.trace.record({
+                kind: "sandbox",
+                op: "exec",
+                target: result.argv.join(" "),
+                ok: result.code === 0,
+                detail: summarise(result),
+            });
+            return format(result.argv.join(" "), result);
+        }
+        catch (err) {
+            if (err instanceof CommandError)
+                return err.message;
+            throw err;
+        }
+    },
+};
+function format(command, result) {
+    const lines = [`$ ${command}`];
+    if (result.timedOut)
+        lines.push(`[killed after ${result.ms}ms]`);
+    else
+        lines.push(`[exit ${result.code ?? "signal"} in ${result.ms}ms]`);
+    if (result.stdout.trim())
+        lines.push("", result.stdout.trimEnd());
+    if (result.stderr.trim())
+        lines.push("", "stderr:", result.stderr.trimEnd());
+    if (!result.stdout.trim() && !result.stderr.trim())
+        lines.push("", "(no output)");
+    if (result.truncated)
+        lines.push("", "[output truncated]");
+    return lines.join("\n");
+}
+//# sourceMappingURL=code.js.map

package/dist/src/tools/code.js.map

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