@toren-run/core 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/apiKeys.d.ts

@@ -0,0 +1,28 @@
+import type pg from "pg";
+/**
+ * Deployment API keys. Secrets are shown once at
+ * creation and stored only as SHA-256 hashes; verification is a hash lookup,
+ * so the raw secret never touches a comparison the caller can time.
+ */
+export interface ApiKeyRecord {
+    id: string;
+    name: string;
+    /** First characters of the secret, for display ("trn_ab12cd34…"). */
+    prefix: string;
+    createdAt: Date;
+    revokedAt: Date | null;
+    lastUsedAt: Date | null;
+}
+export interface CreatedApiKey extends ApiKeyRecord {
+    /** The full secret — returned exactly once, never stored. */
+    secret: string;
+}
+export declare function createApiKey(pool: pg.Pool, name: string): Promise<CreatedApiKey>;
+/** Returns the key's identity if the secret matches an unrevoked key, else null. */
+export declare function verifyApiKey(pool: pg.Pool, secret: string): Promise<{
+    id: string;
+    name: string;
+} | null>;
+/** Revokes a key. Returns false if the key doesn't exist or was already revoked. */
+export declare function revokeApiKey(pool: pg.Pool, id: string): Promise<boolean>;
+export declare function listApiKeys(pool: pg.Pool): Promise<ApiKeyRecord[]>;

package/dist/apiKeys.js

@@ -0,0 +1,40 @@
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+const hash = (secret) => createHash("sha256").update(secret).digest("hex");
+const rowToRecord = (r) => ({
+    id: String(r.id),
+    name: String(r.name),
+    prefix: String(r.prefix),
+    createdAt: r.created_at,
+    revokedAt: r.revoked_at ?? null,
+    lastUsedAt: r.last_used_at ?? null,
+});
+export async function createApiKey(pool, name) {
+    if (!name.trim())
+        throw new Error("api key name must be non-empty");
+    const secret = `trn_${randomBytes(20).toString("hex")}`;
+    const prefix = secret.slice(0, 12);
+    const id = randomUUID();
+    const res = await pool.query(`INSERT INTO toren_control.api_keys (id, name, key_hash, prefix) VALUES ($1, $2, $3, $4)
+     RETURNING id, name, prefix, created_at, revoked_at, last_used_at`, [id, name.trim(), hash(secret), prefix]);
+    return { ...rowToRecord(res.rows[0]), secret };
+}
+/** Returns the key's identity if the secret matches an unrevoked key, else null. */
+export async function verifyApiKey(pool, secret) {
+    if (!secret)
+        return null;
+    const res = await pool.query(`UPDATE toren_control.api_keys SET last_used_at = now()
+     WHERE key_hash = $1 AND revoked_at IS NULL
+     RETURNING id, name`, [hash(secret)]);
+    const row = res.rows[0];
+    return row ? { id: String(row.id), name: String(row.name) } : null;
+}
+/** Revokes a key. Returns false if the key doesn't exist or was already revoked. */
+export async function revokeApiKey(pool, id) {
+    const res = await pool.query(`UPDATE toren_control.api_keys SET revoked_at = now() WHERE id = $1 AND revoked_at IS NULL`, [id]);
+    return (res.rowCount ?? 0) > 0;
+}
+export async function listApiKeys(pool) {
+    const res = await pool.query(`SELECT id, name, prefix, created_at, revoked_at, last_used_at
+     FROM toren_control.api_keys ORDER BY created_at DESC`);
+    return res.rows.map(rowToRecord);
+}

package/dist/approvals.d.ts

@@ -0,0 +1,30 @@
+import type { PgStateStore } from "./store.js";
+import type { QueueAdapter } from "./queue.js";
+import type { PgLeases } from "./leases.js";
+export interface PendingApproval {
+    runId: string;
+    taskId: string;
+    stepId: string;
+    tool: string;
+    args: unknown;
+}
+/** Unresolved ApprovalRequested events across non-terminal runs (or one run). */
+export declare function listPendingApprovals(store: PgStateStore, runId?: string): Promise<PendingApproval[]>;
+export interface ResolveApprovalDeps {
+    store: PgStateStore;
+    leases: PgLeases;
+    queue: QueueAdapter;
+}
+export interface ResolveApprovalReq {
+    runId: string;
+    taskId: string;
+    stepId: string;
+    granted: boolean;
+    by: string;
+    comment?: string;
+}
+/**
+ * Append ApprovalResolved to the parked task's stream (taking its lease
+ * briefly) and nudge the orchestrator so the run resumes.
+ */
+export declare function resolveApproval(deps: ResolveApprovalDeps, req: ResolveApprovalReq): Promise<void>;

package/dist/approvals.js

@@ -0,0 +1,54 @@
+import { effectiveEvents } from "./fold.js";
+/** Unresolved ApprovalRequested events across non-terminal runs (or one run). */
+export async function listPendingApprovals(store, runId) {
+    const runIds = runId ? [runId] : await store.listNonTerminalRuns();
+    const pending = [];
+    for (const rid of runIds) {
+        const runEff = effectiveEvents(await store.read(rid, "run"));
+        const taskIds = runEff
+            .filter((e) => e.type === "WavePlanned")
+            .flatMap((e) => e.payload.tasks.map((t) => t.taskId));
+        for (const taskId of taskIds) {
+            const eff = effectiveEvents(await store.read(rid, `task:${taskId}`));
+            const resolved = new Set(eff.filter((e) => e.type === "ApprovalResolved").map((e) => String(e.payload.stepId)));
+            for (const e of eff) {
+                if (e.type === "ApprovalRequested" && !resolved.has(String(e.payload.stepId))) {
+                    pending.push({
+                        runId: rid, taskId,
+                        stepId: String(e.payload.stepId),
+                        tool: String(e.payload.tool),
+                        args: e.payload.args,
+                    });
+                }
+            }
+        }
+    }
+    return pending;
+}
+/**
+ * Append ApprovalResolved to the parked task's stream (taking its lease
+ * briefly) and nudge the orchestrator so the run resumes.
+ */
+export async function resolveApproval(deps, req) {
+    const streamId = `task:${req.taskId}`;
+    const lease = await deps.leases.acquire(req.runId, streamId, `approvals-${req.by}`, 30);
+    if (!lease)
+        throw new Error(`task ${req.taskId} is currently leased — is a worker still running it?`);
+    try {
+        const raw = await deps.store.read(req.runId, streamId);
+        const head = raw.at(-1)?.seq ?? 0;
+        const r = await deps.store.append(req.runId, streamId, head, [
+            {
+                type: "ApprovalResolved",
+                payload: { v: 1, stepId: req.stepId, granted: req.granted, by: req.by, comment: req.comment },
+            },
+        ]);
+        if (!r.ok)
+            throw new Error("task stream advanced concurrently; retry the approval");
+    }
+    finally {
+        await deps.leases.release(lease);
+    }
+    // Wake the task, then the orchestrator will absorb the outcome.
+    await deps.queue.send("tasks-short", { kind: "task", runId: req.runId, taskId: req.taskId, dedupeKey: `approve-${req.taskId}-${req.stepId}` });
+}

package/dist/blobs.d.ts

@@ -0,0 +1,12 @@
+import type pg from "pg";
+export interface BlobRef {
+    runId: string;
+    key: string;
+}
+export declare class PgBlobs {
+    private pool;
+    private schema;
+    constructor(pool: pg.Pool, schema: string);
+    put(runId: string, key: string, data: Buffer): Promise<BlobRef>;
+    get(ref: BlobRef): Promise<Buffer | null>;
+}

package/dist/blobs.js

@@ -0,0 +1,17 @@
+export class PgBlobs {
+    pool;
+    schema;
+    constructor(pool, schema) {
+        this.pool = pool;
+        this.schema = schema;
+    }
+    async put(runId, key, data) {
+        await this.pool.query(`INSERT INTO ${this.schema}.blobs (run_id, key, data) VALUES ($1, $2, $3)
+       ON CONFLICT (run_id, key) DO UPDATE SET data = EXCLUDED.data`, [runId, key, data]);
+        return { runId, key };
+    }
+    async get(ref) {
+        const r = await this.pool.query(`SELECT data FROM ${this.schema}.blobs WHERE run_id = $1 AND key = $2`, [ref.runId, ref.key]);
+        return r.rows[0]?.data ?? null;
+    }
+}

package/dist/builtins.d.ts

@@ -0,0 +1,10 @@
+import { type ToolDefAny } from "./tools.js";
+export declare const BUILTIN_TOOLS: Record<string, ToolDefAny>;
+/** Env each builtin needs — folded into the agent's required env by the loader. */
+export declare const BUILTIN_TOOL_ENV: Record<string, string[]>;
+/**
+ * The toolkit `sandbox: true` grants: a computer for the agent. bash gates on
+ * approval by default; workspace file operations are free (their blast radius
+ * is the workspace itself).
+ */
+export declare const SANDBOX_TOOLKIT: ToolDefAny[];

package/dist/builtins.js

@@ -0,0 +1,244 @@
+import pg from "pg";
+import { z } from "zod";
+import { defineTool } from "./tools.js";
+/**
+ * Built-in tools: declared by name in agent.yaml (`builtin_tools: [web_search]`),
+ * no handler to write. Each carries the env it needs; the loader folds that into
+ * the agent's required env so a missing key fails fast at startup, not mid-run.
+ */
+const webSearch = defineTool({
+    name: "web_search",
+    description: "Search the live web. Returns JSON with a short answer (when available) and the top results as {title, url, snippet}.",
+    input: z.object({
+        query: z.string().describe("what to search for"),
+        max_results: z.number().int().min(1).max(10).default(5),
+    }),
+    effects: "none",
+    idempotency: "keyed",
+    approval: "never",
+    handler: async ({ query, max_results }, ctx) => {
+        const res = await fetch("https://api.tavily.com/search", {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${ctx.env.TAVILY_API_KEY}`,
+            },
+            body: JSON.stringify({ query, max_results, include_answer: "basic" }),
+        });
+        if (!res.ok) {
+            const detail = (await res.text().catch(() => "")).slice(0, 200);
+            throw new Error(`web_search: tavily returned HTTP ${res.status}${detail ? ` (${detail})` : ""}`);
+        }
+        const body = (await res.json());
+        return JSON.stringify({
+            answer: body.answer,
+            results: (body.results ?? []).map((r) => ({ title: r.title, url: r.url, snippet: r.content })),
+        });
+    },
+});
+const readAttachment = defineTool({
+    name: "read_attachment",
+    description: "Read one page of an attached file. Attachments are listed in the conversation with their file_id and page count; call again with the next page number to keep reading.",
+    input: z.object({
+        file_id: z.string().describe("from the attachment list"),
+        page: z.number().int().min(1).default(1),
+    }),
+    effects: "none",
+    idempotency: "keyed",
+    approval: "never",
+    handler: async ({ file_id, page }, ctx) => {
+        if (!ctx.files)
+            throw new Error("read_file: this deployment has no file store configured");
+        const f = await ctx.files.get(file_id);
+        if (!f)
+            return JSON.stringify({ error: `no file with id ${file_id}; check the attachment list` });
+        const text = f.pages[page - 1];
+        if (text === undefined) {
+            return JSON.stringify({ error: `page ${page} is out of range`, name: f.name, pages: f.pages.length });
+        }
+        return JSON.stringify({ name: f.name, page, of: f.pages.length, text });
+    },
+});
+const BASH_OUTPUT_CAP = 8_000; // chars kept from each of head and tail per stream
+function capOutput(s) {
+    if (s.length <= BASH_OUTPUT_CAP * 2)
+        return s;
+    return `${s.slice(0, BASH_OUTPUT_CAP)}\n[... ${s.length - BASH_OUTPUT_CAP * 2} chars elided ...]\n${s.slice(-BASH_OUTPUT_CAP)}`;
+}
+function needSandbox(ctx) {
+    if (!ctx.sandbox)
+        throw new Error("this deployment has no sandbox backend configured (is docker available?)");
+    return ctx.sandbox;
+}
+/** Workspace file tools, pi-style: models edit reliably with exact strings, not sed. */
+const wsReadFile = defineTool({
+    name: "read_file",
+    description: "Read a file from the workspace. Returns the content with 1-indexed line numbers.",
+    input: z.object({
+        path: z.string().describe("workspace-relative path"),
+        offset: z.number().int().min(1).default(1).describe("first line to read"),
+        limit: z.number().int().min(1).max(2000).default(500),
+    }),
+    effects: "sandbox",
+    idempotency: "keyed",
+    approval: "never",
+    handler: async ({ path, offset, limit }, ctx) => {
+        const content = await needSandbox(ctx).readFile(path);
+        const lines = content.split("\n");
+        const slice = lines.slice(offset - 1, offset - 1 + limit);
+        const numbered = slice.map((l, i) => `${offset + i}\t${l}`).join("\n");
+        return JSON.stringify({ path, lines: lines.length, from: offset, text: capOutput(numbered) });
+    },
+});
+const wsWriteFile = defineTool({
+    name: "write_file",
+    description: "Create or overwrite a file in the workspace.",
+    input: z.object({ path: z.string(), content: z.string() }),
+    effects: "sandbox",
+    idempotency: "keyed",
+    approval: "never",
+    handler: async ({ path, content }, ctx) => {
+        await needSandbox(ctx).writeFile(path, content);
+        return JSON.stringify({ path, bytes: Buffer.byteLength(content) });
+    },
+});
+const wsEditFile = defineTool({
+    name: "edit_file",
+    description: "Replace an exact string in a workspace file. old_string must appear exactly once unless replace_all is set; include enough surrounding context to make it unique.",
+    input: z.object({
+        path: z.string(),
+        old_string: z.string(),
+        new_string: z.string(),
+        replace_all: z.boolean().default(false),
+    }),
+    effects: "sandbox",
+    idempotency: "keyed",
+    approval: "never",
+    handler: async ({ path, old_string, new_string, replace_all }, ctx) => {
+        const sandbox = needSandbox(ctx);
+        const content = await sandbox.readFile(path);
+        const count = content.split(old_string).length - 1;
+        if (count === 0)
+            return JSON.stringify({ error: "old_string not found", path });
+        if (count > 1 && !replace_all)
+            return JSON.stringify({ error: `old_string appears ${count} times; add context or set replace_all`, path });
+        const next = replace_all ? content.split(old_string).join(new_string) : content.replace(old_string, new_string);
+        await sandbox.writeFile(path, next);
+        return JSON.stringify({ path, replacements: replace_all ? count : 1 });
+    },
+});
+const bash = defineTool({
+    name: "bash",
+    description: "Run a shell command in this run's persistent workspace. The workspace survives crashes and restarts; " +
+        "files you create stay for later commands. Commands run in a sandbox container with no credentials.",
+    input: z.object({
+        command: z.string().describe("the shell command"),
+        timeout_seconds: z.number().int().min(1).max(600).default(120),
+    }),
+    effects: "sandbox",
+    idempotency: "keyed",
+    approval: "always",
+    handler: async ({ command, timeout_seconds }, ctx) => {
+        if (!ctx.sandbox)
+            throw new Error("bash: this deployment has no sandbox backend configured (is docker available?)");
+        const r = await ctx.sandbox.exec(command, { timeoutMs: timeout_seconds * 1000 });
+        return JSON.stringify({ exit_code: r.exitCode, stdout: capOutput(r.stdout), stderr: capOutput(r.stderr) });
+    },
+});
+// ---- sql_query: read-only database access as a tool.
+// Defense in depth on top of the STRONGLY RECOMMENDED read-only DB role:
+// only a single SELECT/WITH runs, forbidden keywords are rejected, stacked
+// statements are blocked, the result is row-capped, and a statement timeout
+// bounds a heavy query. Pools are cached per connection string.
+const sqlPools = new Map();
+function sqlPool(url) {
+    let p = sqlPools.get(url);
+    if (!p) {
+        p = new pg.Pool({ connectionString: url, max: 2, statement_timeout: 10_000, query_timeout: 12_000 });
+        sqlPools.set(url, p);
+    }
+    return p;
+}
+const SELECT_ONLY = /^\s*(with[\s\S]+\bselect\b|select)\b/i;
+const FORBIDDEN = /\b(insert|update|delete|drop|alter|create|truncate|grant|revoke|copy|call|merge|vacuum|reindex|comment|do|set|begin|commit)\b/i;
+const sqlQuery = defineTool({
+    name: "sql_query",
+    description: "Run a READ-ONLY SQL query (a single SELECT) against the configured database and get the rows back as JSON. Use standard SQL; results are capped.",
+    input: z.object({
+        query: z.string().describe("a single read-only SELECT statement"),
+        limit: z.number().int().min(1).max(500).default(100),
+    }),
+    effects: "none",
+    idempotency: "keyed",
+    approval: "never",
+    handler: async ({ query, limit }, ctx) => {
+        const url = ctx.env.SQL_DATABASE_URL;
+        if (!url)
+            throw new Error("sql_query: SQL_DATABASE_URL is not configured for this agent");
+        const q = query.trim().replace(/;\s*$/, "");
+        if (q.includes(";"))
+            return JSON.stringify({ error: "only one statement is allowed (no ';')" });
+        if (!SELECT_ONLY.test(q))
+            return JSON.stringify({ error: "only a read-only SELECT (or WITH ... SELECT) is allowed" });
+        if (FORBIDDEN.test(q))
+            return JSON.stringify({ error: "the query contains a forbidden (write/DDL) keyword; this tool is read-only" });
+        try {
+            // Wrap so a missing LIMIT can never return an unbounded result set.
+            const res = await sqlPool(url).query(`SELECT * FROM (${q}) AS _toren_q LIMIT ${limit}`);
+            const out = JSON.stringify({ rowCount: res.rowCount, truncated: (res.rowCount ?? 0) >= limit, rows: res.rows });
+            return out.length > 24_000 ? JSON.stringify({ rowCount: res.rowCount, note: "result too large; add columns/filters or a smaller limit", rows: res.rows.slice(0, 10) }) : out;
+        }
+        catch (e) {
+            return JSON.stringify({ error: `query failed: ${e instanceof Error ? e.message : String(e)}` });
+        }
+    },
+});
+// ---- run_process / check_run: the spawn arc. A conversation triggers a named
+// process as a durable background run; a watcher wakes the session when it
+// settles, so the agent messages the user in-channel without polling. The
+// child runId derives from the tool-use id, so a crash-window re-run finds the
+// run already exists — spawning is effectively-once.
+const runProcess = defineTool({
+    name: "run_process",
+    description: "Start one of this agent's named processes as a background run. It executes durably on the workers while this conversation continues; a message lands in this conversation when it settles, and check_run polls it on demand.",
+    input: z.object({
+        process: z.string().describe("the process name to run"),
+        input: z.string().describe("the input handed to the process run"),
+    }),
+    effects: "none",
+    idempotency: "keyed",
+    approval: "never",
+    handler: async ({ process, input }, ctx) => {
+        if (!ctx.processes)
+            throw new Error("run_process: background processes are not wired in this deployment");
+        const r = await ctx.processes.start({ process, input, parentRunId: ctx.runId, parentTaskId: ctx.taskId, toolUseId: ctx.toolUseId });
+        return JSON.stringify({ run_id: r.runId, process, status: r.started ? "started" : "already_running" });
+    },
+});
+const checkRun = defineTool({
+    name: "check_run",
+    description: "Check a background run started with run_process: status, per-wave progress from its event log, and the output once it finishes.",
+    input: z.object({
+        run_id: z.string().describe("from run_process"),
+    }),
+    effects: "none",
+    idempotency: "keyed",
+    approval: "never",
+    handler: async ({ run_id }, ctx) => {
+        if (!ctx.processes)
+            throw new Error("check_run: background processes are not wired in this deployment");
+        const s = await ctx.processes.status(run_id);
+        if (!s)
+            return JSON.stringify({ error: `no run ${run_id}` });
+        return JSON.stringify({ run_id: s.runId, process: s.process, status: s.status, waves: s.waves, ...(s.output !== undefined ? { output: s.output } : {}), ...(s.error !== undefined ? { error: s.error } : {}) });
+    },
+});
+export const BUILTIN_TOOLS = { web_search: webSearch, read_attachment: readAttachment, sql_query: sqlQuery, bash, run_process: runProcess, check_run: checkRun };
+/** Env each builtin needs — folded into the agent's required env by the loader. */
+export const BUILTIN_TOOL_ENV = { web_search: ["TAVILY_API_KEY"], read_attachment: [], sql_query: ["SQL_DATABASE_URL"], bash: [], run_process: [], check_run: [] };
+/**
+ * The toolkit `sandbox: true` grants: a computer for the agent. bash gates on
+ * approval by default; workspace file operations are free (their blast radius
+ * is the workspace itself).
+ */
+export const SANDBOX_TOOLKIT = [bash, wsReadFile, wsWriteFile, wsEditFile];