@tianshu-ai/tianshu 0.3.0

package/packages/server/dist/tools/read-file.js

@@ -0,0 +1,94 @@
+// read_file — agent tool that returns the contents of a small text file.
+//
+// Hard cap of 500 KB per call. For larger files the agent must page
+// through with `offset` and `limit` (the response includes the next
+// args you should pass).
+//
+// Binary files are detected heuristically (NUL byte in first 4 KB)
+// and returned as a stub message rather than raw bytes — preserving
+// the LLM's context window.
+import fs from "node:fs";
+import { Type } from "typebox";
+import { resolveInUserHome, PathOutsideRootError } from "./path-helper.js";
+export const MAX_TEXT_BYTES = 500_000;
+export function readFileSchema() {
+    return {
+        name: "read_file",
+        description: `Read a text file from the workspace. Returns up to ${MAX_TEXT_BYTES / 1000} KB per call. \
+For larger files, pass \`offset\` (byte offset to start at) and \`limit\` (max bytes); the \
+response will tell you the file's full size and the next offset to use.
+
+Binary files (image, archive, etc.) return a short stub instead of bytes — extract them \
+to text first via another tool if you need their contents.`,
+        parameters: Type.Object({
+            path: Type.String({
+                description: 'Path relative to the workspace root, e.g. "/notes/today.md".',
+            }),
+            offset: Type.Optional(Type.Integer({
+                minimum: 0,
+                description: "Byte offset to start reading from. Default 0.",
+            })),
+            limit: Type.Optional(Type.Integer({
+                minimum: 1,
+                description: `Max bytes to return. Capped at ${MAX_TEXT_BYTES}.`,
+            })),
+        }),
+    };
+}
+export function executeReadFile(userHome, args) {
+    let resolved;
+    try {
+        resolved = resolveInUserHome(userHome, args.path);
+    }
+    catch (err) {
+        if (err instanceof PathOutsideRootError) {
+            return { ok: false, text: `path is outside the workspace: ${args.path}` };
+        }
+        throw err;
+    }
+    if (!fs.existsSync(resolved)) {
+        return { ok: false, text: `not found: ${args.path}` };
+    }
+    const stat = fs.statSync(resolved);
+    if (stat.isDirectory()) {
+        return { ok: false, text: `is a directory, not a file: ${args.path}` };
+    }
+    const offset = Math.max(0, Math.floor(args.offset ?? 0));
+    const limit = Math.max(1, Math.min(args.limit ?? MAX_TEXT_BYTES, MAX_TEXT_BYTES));
+    const fd = fs.openSync(resolved, "r");
+    try {
+        const buf = Buffer.alloc(limit);
+        const bytesRead = fs.readSync(fd, buf, 0, limit, offset);
+        const slice = buf.subarray(0, bytesRead);
+        // Binary check — first 4 KB of the slice.
+        const probe = slice.subarray(0, Math.min(slice.length, 4096));
+        if (probe.includes(0)) {
+            return {
+                ok: true,
+                text: `(binary file: ${stat.size} bytes; not shown)`,
+                binary: true,
+                size: stat.size,
+            };
+        }
+        const content = slice.toString("utf8");
+        const nextOffset = offset + bytesRead;
+        const more = nextOffset < stat.size;
+        const header = stat.size <= MAX_TEXT_BYTES
+            ? `// ${args.path} (${stat.size} bytes)`
+            : `// ${args.path} bytes ${offset}–${nextOffset} of ${stat.size}` +
+                (more
+                    ? ` — call read_file again with offset=${nextOffset} for the next chunk`
+                    : " (final chunk)");
+        return {
+            ok: true,
+            text: `${header}\n${content}`,
+            size: stat.size,
+            bytesReturned: bytesRead,
+            nextOffset: more ? nextOffset : undefined,
+        };
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+//# sourceMappingURL=read-file.js.map

package/packages/server/dist/tools/read-file.js.map

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

package/packages/server/dist/tools/sandbox.d.ts

@@ -0,0 +1,57 @@
+import type { Tool } from "@earendil-works/pi-ai";
+import type { SandboxRunner, SandboxStatus } from "@tianshu/plugin-sdk";
+export interface ExecToolResult {
+    ok: boolean;
+    exit_code: number;
+    stdout: string;
+    stderr: string;
+    /** True iff stdout/stderr was truncated to fit the caller's budget. */
+    truncated: boolean;
+    duration_ms: number;
+    /** True iff the command was killed by the timeout. */
+    timed_out: boolean;
+}
+export declare function execSchema(): Tool;
+export declare function executeExec(runner: SandboxRunner, args: {
+    command: string;
+    workdir?: string;
+    timeout_ms?: number;
+}): Promise<ExecToolResult>;
+export interface ResetSandboxToolResult {
+    ok: boolean;
+    message: string;
+    status: SandboxStatus;
+}
+export declare function resetSandboxSchema(): Tool;
+export declare function executeResetSandbox(runner: SandboxRunner): Promise<ResetSandboxToolResult>;
+export interface GetSandboxStatusToolResult {
+    state: SandboxStatus["state"];
+    uptime_ms: number;
+    last_error: string | null;
+    meta: Record<string, unknown>;
+}
+export declare function getSandboxStatusSchema(): Tool;
+export declare function executeGetSandboxStatus(runner: SandboxRunner): Promise<GetSandboxStatusToolResult>;
+export interface UpdateSandboxConfigToolResult {
+    ok: boolean;
+    changed: Record<string, unknown>;
+    /** True iff a `reset_sandbox` is needed for the change to take effect. */
+    reset_required: boolean;
+    message: string;
+}
+export declare function updateSandboxConfigSchema(): Tool;
+export interface UpdateSandboxConfigCtx {
+    tenantId: string;
+    homeDir: string;
+}
+export declare function executeUpdateSandboxConfig(ctx: UpdateSandboxConfigCtx, args: Record<string, unknown>): UpdateSandboxConfigToolResult;
+/** True iff the runner's current status permits agent `exec`. We
+ *  expose `exec` for any state except `error` — `starting` /
+ *  `stopped` will block briefly inside the runner before turning
+ *  `running`, which is the right behaviour. */
+export declare function execGated(status: SandboxStatus): boolean;
+/** Conservative side-channel for tests / debugging that don't have
+ *  a runner and just want to know if the file system looks like a
+ *  valid tenant home. */
+export declare function tenantHomeLooksReal(homeDir: string, tenantId: string): boolean;
+//# sourceMappingURL=sandbox.d.ts.map

package/packages/server/dist/tools/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/tools/sandbox.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAgBxE,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,OAAO,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,wBAAgB,UAAU,IAAI,IAAI,CAiCjC;AAED,wBAAsB,WAAW,CAC/B,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/D,OAAO,CAAC,cAAc,CAAC,CA+BzB;AAyCD,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,aAAa,CAAC;CACvB;AAED,wBAAgB,kBAAkB,IAAI,IAAI,CAWzC;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,sBAAsB,CAAC,CAiBjC;AAID,MAAM,WAAW,0BAA0B;IACzC,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,wBAAgB,sBAAsB,IAAI,IAAI,CAS7C;AAED,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,0BAA0B,CAAC,CAQrC;AAcD,MAAM,WAAW,6BAA6B;IAC5C,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,0EAA0E;IAC1E,cAAc,EAAE,OAAO,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,yBAAyB,IAAI,IAAI,CA0BhD;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,sBAAsB,EAC3B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,6BAA6B,CAyD/B;AAaD;;;+CAG+C;AAC/C,wBAAgB,SAAS,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAExD;AAED;;yBAEyB;AACzB,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAM9E"}

package/packages/server/dist/tools/sandbox.js

@@ -0,0 +1,291 @@
+// Agent sandbox tools (ADR-0004 N+3).
+//
+// Four tools registered when the tenant has a `sandbox.shell`
+// provider in its capability registry. They route through the
+// runner the provider registered (typically the `microsandbox`
+// plugin's MicrosandboxRunner; see plugins/microsandbox/).
+//
+// - exec                   : run a shell command in the sandbox
+// - reset_sandbox          : tear down + re-create the sandbox VM
+// - get_sandbox_status     : structured liveness snapshot
+// - update_sandbox_config  : tenant-level sandbox config edit
+//
+// Tool registration is dynamic: the chat handler asks
+// `buildToolset({ capabilities, ... })` once per request, and the
+// builder picks up whichever capability values are currently
+// registered. Status gating (§10) is also done here — if
+// `sandbox.shell` reports `state: "error"`, we drop `exec` from the
+// schema list so the model never picks a doomed-to-fail tool.
+import fs from "node:fs";
+import path from "node:path";
+import { Type } from "typebox";
+import { loadTenantConfig, TenantConfigForbiddenFieldError, writeTenantConfig, } from "../core/config.js";
+// Defaults / caps mirror the closed-source repo so behaviour is
+// predictable across environments.
+const DEFAULT_EXEC_TIMEOUT_MS = 5 * 60_000; // 5 min
+const MAX_EXEC_TIMEOUT_MS = 30 * 60_000; // 30 min
+const STDOUT_LINE_CAP = 200;
+const STDOUT_BYTE_CAP = 8_000;
+export function execSchema() {
+    return {
+        name: "exec",
+        description: `Run a shell command inside the per-tenant sandbox. The sandbox boots \
+on first call (cold start ~10s), so subsequent calls in the same conversation are fast.
+
+Default timeout: ${DEFAULT_EXEC_TIMEOUT_MS / 1000}s. Raise \`timeout_ms\` for long-running tasks; cap is ${MAX_EXEC_TIMEOUT_MS / 1000}s.
+
+Outputs are truncated at ${STDOUT_LINE_CAP} lines / ${STDOUT_BYTE_CAP} bytes per stream. \
+Pipe to a file (\`> /workspace/out.log\`) if you need the full output, then read it with \
+\`read_file\`.
+
+The workspace is bind-mounted at /workspace inside the guest. Files written there persist \
+on the host; everything else (installs, /tmp, …) is wiped when you call \`reset_sandbox\`.`,
+        parameters: Type.Object({
+            command: Type.String({
+                description: 'Shell command. Equivalent to `bash -c <command>` inside the sandbox. Multi-line scripts are fine.',
+            }),
+            workdir: Type.Optional(Type.String({
+                description: "Working dir inside the guest. Default `/workspace`.",
+            })),
+            timeout_ms: Type.Optional(Type.Integer({
+                minimum: 1,
+                maximum: MAX_EXEC_TIMEOUT_MS,
+                description: `Override per-call timeout. Hard cap ${MAX_EXEC_TIMEOUT_MS}ms.`,
+            })),
+        }),
+    };
+}
+export async function executeExec(runner, args) {
+    const timeoutMs = clampTimeout(args.timeout_ms);
+    try {
+        const result = await runner.exec({
+            command: args.command,
+            workdir: args.workdir,
+            timeoutMs,
+        });
+        const stdout = truncate(result.stdout);
+        const stderr = truncate(result.stderr);
+        return {
+            ok: result.exitCode === 0 && !result.timedOut,
+            exit_code: result.exitCode,
+            stdout: stdout.text,
+            stderr: stderr.text,
+            truncated: stdout.truncated || stderr.truncated,
+            duration_ms: result.durationMs,
+            timed_out: result.timedOut,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            exit_code: -1,
+            stdout: "",
+            stderr: `exec failed before reaching the sandbox: ${message}`,
+            truncated: false,
+            duration_ms: 0,
+            timed_out: false,
+        };
+    }
+}
+function clampTimeout(raw) {
+    if (typeof raw !== "number" || !Number.isFinite(raw) || raw <= 0) {
+        return DEFAULT_EXEC_TIMEOUT_MS;
+    }
+    return Math.min(raw, MAX_EXEC_TIMEOUT_MS);
+}
+function truncate(s) {
+    if (s.length === 0)
+        return { text: s, truncated: false };
+    let truncated = false;
+    let out = s;
+    // Byte cap first; we approximate bytes with code units which is
+    // tight enough for English-heavy output and safe (we don't grow).
+    if (Buffer.byteLength(out, "utf8") > STDOUT_BYTE_CAP) {
+        // Cut at code-point boundaries via Buffer slicing.
+        const buf = Buffer.from(out, "utf8");
+        out = buf.subarray(0, STDOUT_BYTE_CAP).toString("utf8");
+        truncated = true;
+    }
+    // Then line cap.
+    const lines = out.split("\n");
+    if (lines.length > STDOUT_LINE_CAP) {
+        out = lines.slice(0, STDOUT_LINE_CAP).join("\n");
+        truncated = true;
+    }
+    if (truncated) {
+        out += `\n[output truncated at ${STDOUT_LINE_CAP} lines / ${STDOUT_BYTE_CAP} bytes]`;
+    }
+    return { text: out, truncated };
+}
+export function resetSandboxSchema() {
+    return {
+        name: "reset_sandbox",
+        description: `Tear down the sandbox VM and re-create it from scratch. Use this when \
+\`exec\` keeps failing due to a stuck process, corrupted state, OOM, or runaway services. \
+Files under /workspace survive (they live on the host); installed packages, running daemons, \
+/tmp, and any in-VM state do not.
+
+Idempotent: safe to call even if the sandbox isn't running.`,
+        parameters: Type.Object({}),
+    };
+}
+export async function executeResetSandbox(runner) {
+    try {
+        await runner.reset();
+        const status = await runner.status();
+        return {
+            ok: true,
+            message: "sandbox reset; next exec will start a fresh VM",
+            status,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            message: `reset failed: ${message}`,
+            status: { state: "error", uptimeMs: 0, lastError: message },
+        };
+    }
+}
+export function getSandboxStatusSchema() {
+    return {
+        name: "get_sandbox_status",
+        description: `Return the sandbox's current liveness snapshot: state, uptime, last error \
+(if any), and provider-specific metadata (image, cpus, memory, last exec time, …). Use this \
+when an \`exec\` call returned a confusing error and you want a structured signal before \
+deciding to \`reset_sandbox\`.`,
+        parameters: Type.Object({}),
+    };
+}
+export async function executeGetSandboxStatus(runner) {
+    const s = await runner.status();
+    return {
+        state: s.state,
+        uptime_ms: s.uptimeMs,
+        last_error: s.lastError ?? null,
+        meta: s.meta ?? {},
+    };
+}
+// ─── update_sandbox_config ────────────────────────────────────────
+const CONFIGURABLE_KEYS = [
+    "image",
+    "cpus",
+    "memoryMib",
+    "sandboxName",
+    "idleShutdownMs",
+    "execTimeoutMs",
+];
+export function updateSandboxConfigSchema() {
+    return {
+        name: "update_sandbox_config",
+        description: `Edit this tenant's sandbox config (image / cpus / memory / …). \
+Persists to the tenant config file; the change takes effect for new requests. \
+The currently-running sandbox VM is **not** restarted automatically — call \
+\`reset_sandbox\` after this if you want the new settings to apply right now.
+
+Configurable fields:
+- \`image\` (string): OCI image for the sandbox VM. Default \`python:3.12-slim\`.
+- \`cpus\` (integer): vCPU count.
+- \`memory_mib\` (integer): memory in MiB.
+- \`sandbox_name\` (string): sandbox name; rarely needs changing.
+- \`idle_shutdown_ms\` (integer): idle ms before the VM is paused. 0 disables.
+- \`exec_timeout_ms\` (integer): default per-exec timeout in ms.
+
+Only the fields you pass are touched; omitted fields keep their current value.`,
+        parameters: Type.Object({
+            image: Type.Optional(Type.String()),
+            cpus: Type.Optional(Type.Integer({ minimum: 1 })),
+            memory_mib: Type.Optional(Type.Integer({ minimum: 64 })),
+            sandbox_name: Type.Optional(Type.String()),
+            idle_shutdown_ms: Type.Optional(Type.Integer({ minimum: 0 })),
+            exec_timeout_ms: Type.Optional(Type.Integer({ minimum: 1 })),
+        }),
+    };
+}
+export function executeUpdateSandboxConfig(ctx, args) {
+    // Map snake_case tool args to the camelCase keys the plugin reads.
+    const mapped = {};
+    if (typeof args.image === "string")
+        mapped.image = args.image;
+    if (typeof args.cpus === "number")
+        mapped.cpus = Math.floor(args.cpus);
+    if (typeof args.memory_mib === "number")
+        mapped.memoryMib = Math.floor(args.memory_mib);
+    if (typeof args.sandbox_name === "string")
+        mapped.sandboxName = args.sandbox_name;
+    if (typeof args.idle_shutdown_ms === "number") {
+        mapped.idleShutdownMs = Math.floor(args.idle_shutdown_ms);
+    }
+    if (typeof args.exec_timeout_ms === "number") {
+        mapped.execTimeoutMs = Math.floor(args.exec_timeout_ms);
+    }
+    const changedKeys = Object.keys(mapped);
+    if (changedKeys.length === 0) {
+        return {
+            ok: false,
+            changed: {},
+            reset_required: false,
+            message: "no config keys provided",
+        };
+    }
+    try {
+        const cfg = loadTenantConfig(ctx.tenantId, ctx.homeDir);
+        const plugins = { ...(cfg.plugins ?? {}) };
+        const current = plugins.microsandbox ?? {};
+        const currentConfig = current.config ?? {};
+        const nextConfig = { ...currentConfig, ...mapped };
+        plugins.microsandbox = { ...current, config: nextConfig };
+        writeTenantConfig(ctx.tenantId, { ...cfg, plugins }, ctx.homeDir);
+        return {
+            ok: true,
+            changed: mapped,
+            reset_required: requiresReset(mapped),
+            message: "sandbox config updated; call reset_sandbox to apply to the running VM",
+        };
+    }
+    catch (err) {
+        if (err instanceof TenantConfigForbiddenFieldError) {
+            return {
+                ok: false,
+                changed: {},
+                reset_required: false,
+                message: `tenant config refused: ${err.message}`,
+            };
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            changed: {},
+            reset_required: false,
+            message: `failed to write tenant config: ${message}`,
+        };
+    }
+}
+function requiresReset(changes) {
+    // Anything that affects VM identity / shape requires reset.
+    // execTimeoutMs and idleShutdownMs are read fresh on each call,
+    // so they don't.
+    return Object.keys(changes).some((k) => k === "image" || k === "cpus" || k === "memoryMib" || k === "sandboxName");
+}
+// ─── helpers ───────────────────────────────────────────────────────
+/** True iff the runner's current status permits agent `exec`. We
+ *  expose `exec` for any state except `error` — `starting` /
+ *  `stopped` will block briefly inside the runner before turning
+ *  `running`, which is the right behaviour. */
+export function execGated(status) {
+    return status.state !== "error";
+}
+/** Conservative side-channel for tests / debugging that don't have
+ *  a runner and just want to know if the file system looks like a
+ *  valid tenant home. */
+export function tenantHomeLooksReal(homeDir, tenantId) {
+    try {
+        return fs.statSync(path.join(homeDir, "tenants", tenantId)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=sandbox.js.map

package/packages/server/dist/tools/sandbox.js.map

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

package/packages/server/dist/tools/write-file.d.ts

@@ -0,0 +1,12 @@
+import type { Tool } from "@earendil-works/pi-ai";
+export interface WriteFileToolResult {
+    ok: boolean;
+    text: string;
+    bytesWritten?: number;
+}
+export declare function writeFileSchema(): Tool;
+export declare function executeWriteFile(userHome: string, args: {
+    path: string;
+    content: string;
+}): WriteFileToolResult;
+//# sourceMappingURL=write-file.d.ts.map

package/packages/server/dist/tools/write-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-file.d.ts","sourceRoot":"","sources":["../../src/tools/write-file.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAKlD,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,eAAe,IAAI,IAAI,CAgBtC;AAED,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACtC,mBAAmB,CAqCrB"}

package/packages/server/dist/tools/write-file.js

@@ -0,0 +1,67 @@
+// write_file — agent tool that creates or overwrites a file.
+//
+// Atomic-ish: writes via a `<file>.tmp.<pid>` sibling and renames into
+// place, so a partial write doesn't leave a half-baked target if the
+// process crashes mid-write.
+//
+// Parent directories are created on demand.
+//
+// Refuses to write outside the user home (path-helper enforced).
+import fs from "node:fs";
+import path from "node:path";
+import { Type } from "typebox";
+import { resolveInUserHome, PathOutsideRootError } from "./path-helper.js";
+const MAX_WRITE_BYTES = 5_000_000; // 5 MB
+export function writeFileSchema() {
+    return {
+        name: "write_file",
+        description: "Create or overwrite a file in the workspace. Parent directories are created if " +
+            "missing. Use this for new files or full rewrites; for small targeted changes " +
+            "prefer `edit_file`.",
+        parameters: Type.Object({
+            path: Type.String({
+                description: 'Path relative to the workspace root, e.g. "/notes/today.md".',
+            }),
+            content: Type.String({
+                description: "Full file contents to write. UTF-8 encoded.",
+            }),
+        }),
+    };
+}
+export function executeWriteFile(userHome, args) {
+    let resolved;
+    try {
+        resolved = resolveInUserHome(userHome, args.path);
+    }
+    catch (err) {
+        if (err instanceof PathOutsideRootError) {
+            return { ok: false, text: `path is outside the workspace: ${args.path}` };
+        }
+        throw err;
+    }
+    if (resolved === path.resolve(userHome)) {
+        return { ok: false, text: `cannot write to the workspace root` };
+    }
+    if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) {
+        return { ok: false, text: `is a directory: ${args.path}` };
+    }
+    const buf = Buffer.from(args.content, "utf8");
+    if (buf.length > MAX_WRITE_BYTES) {
+        return {
+            ok: false,
+            text: `content too large: ${buf.length} bytes > ${MAX_WRITE_BYTES} cap`,
+        };
+    }
+    fs.mkdirSync(path.dirname(resolved), { recursive: true });
+    // Write to a temp sibling and rename so partial writes don't trash
+    // the target on crash.
+    const tmp = `${resolved}.tmp.${process.pid}.${Date.now()}`;
+    fs.writeFileSync(tmp, buf);
+    fs.renameSync(tmp, resolved);
+    return {
+        ok: true,
+        text: `wrote ${buf.length} bytes to ${args.path}`,
+        bytesWritten: buf.length,
+    };
+}
+//# sourceMappingURL=write-file.js.map

package/packages/server/dist/tools/write-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-file.js","sourceRoot":"","sources":["../../src/tools/write-file.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,EAAE;AACF,uEAAuE;AACvE,qEAAqE;AACrE,6BAA6B;AAC7B,EAAE;AACF,4CAA4C;AAC5C,EAAE;AACF,iEAAiE;AAEjE,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE/B,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAE3E,MAAM,eAAe,GAAG,SAAS,CAAC,CAAC,OAAO;AAQ1C,MAAM,UAAU,eAAe;IAC7B,OAAO;QACL,IAAI,EAAE,YAAY;QAClB,WAAW,EACT,iFAAiF;YACjF,+EAA+E;YAC/E,qBAAqB;QACvB,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC;YACtB,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC;gBAChB,WAAW,EAAE,8DAA8D;aAC5E,CAAC;YACF,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC;gBACnB,WAAW,EAAE,6CAA6C;aAC3D,CAAC;SACH,CAAC;KACH,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC9B,QAAgB,EAChB,IAAuC;IAEvC,IAAI,QAAgB,CAAC;IACrB,IAAI,CAAC;QACH,QAAQ,GAAG,iBAAiB,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IACpD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,oBAAoB,EAAE,CAAC;YACxC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,kCAAkC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;QAC5E,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;IACD,IAAI,QAAQ,KAAK,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QACxC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,oCAAoC,EAAE,CAAC;IACnE,CAAC;IACD,IAAI,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;QACnE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,mBAAmB,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;IAC7D,CAAC;IAED,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC9C,IAAI,GAAG,CAAC,MAAM,GAAG,eAAe,EAAE,CAAC;QACjC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,sBAAsB,GAAG,CAAC,MAAM,YAAY,eAAe,MAAM;SACxE,CAAC;IACJ,CAAC;IAED,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1D,mEAAmE;IACnE,uBAAuB;IACvB,MAAM,GAAG,GAAG,GAAG,QAAQ,QAAQ,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;IAC3D,EAAE,CAAC,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC3B,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IAE7B,OAAO;QACL,EAAE,EAAE,IAAI;QACR,IAAI,EAAE,SAAS,GAAG,CAAC,MAAM,aAAa,IAAI,CAAC,IAAI,EAAE;QACjD,YAAY,EAAE,GAAG,CAAC,MAAM;KACzB,CAAC;AACJ,CAAC"}

package/packages/server/dist/worker-agents-routes.d.ts

@@ -0,0 +1,11 @@
+import { Router } from "express";
+import type { PluginRegistry } from "./core/plugins/index.js";
+import type { GlobalOps } from "./core/index.js";
+export interface WorkerAgentsRouterOpts {
+    /** Plugin registry, used to surface `workerKinds` declared by
+     *  active plugins so the UI can offer them in the create form. */
+    registry: PluginRegistry;
+    ops: GlobalOps;
+}
+export declare function buildWorkerAgentsRouter(opts: WorkerAgentsRouterOpts): Router;
+//# sourceMappingURL=worker-agents-routes.d.ts.map

package/packages/server/dist/worker-agents-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-agents-routes.d.ts","sourceRoot":"","sources":["../src/worker-agents-routes.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,MAAM,EAAgB,MAAM,SAAS,CAAC;AAS/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AA2BjD,MAAM,WAAW,sBAAsB;IACrC;sEACkE;IAClE,QAAQ,EAAE,cAAc,CAAC;IACzB,GAAG,EAAE,SAAS,CAAC;CAChB;AAkCD,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,sBAAsB,GAC3B,MAAM,CA6NR"}