@vibedgc/sdk 0.6.4

package/dist/state.d.ts

@@ -0,0 +1,37 @@
+/** Create `path` (and missing parents) and leave it owner-only (0700). */
+export declare function privateDir(path: string): string;
+/**
+ * A private state directory, created when needed.
+ *
+ * `undefined` makes a fresh `mkdtemp` directory (0700). An existing directory must be owned by
+ * this user and must not be group- or world-writable; a readable one that we own is tightened
+ * to 0700. Anything else is refused, because another local user could have planted files the
+ * DGC child would read.
+ */
+export declare function prepareStateDir(stateDir?: string): string;
+export declare function configPath(stateDir: string): string;
+/**
+ * Serialize isolated-config writes and child startups for one stateDir within this process.
+ * (The Python SDK also takes a cross-process flock; Node has none, so use one stateDir per
+ * process. A config another process rewrote while a session started is still detected and the
+ * start is retried.)
+ */
+export declare class StateLock {
+    private tail;
+    hold<T>(work: () => Promise<T>): Promise<T>;
+}
+export declare function stateLock(stateDir: string): StateLock;
+/**
+ * Atomically replace the isolated config.json with exactly `values` (undefined/null dropped).
+ * Hold {@link stateLock} while calling. Directories are 0700 and the file is 0600. Returns the
+ * values as they read back from JSON, for {@link configDrift}.
+ */
+export declare function writeSessionConfig(stateDir: string, values: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Keys of `expected` whose value in the isolated config.json now differs. A DGC child saves its
+ * whole configuration when it persists anything; if another session's child did that between
+ * our write and our child's startup, our child may have loaded that session's options.
+ */
+export declare function configDrift(stateDir: string, expected: Record<string, unknown>): string[];
+/** Append `line` to an owner-only (0600) file, tightening an existing file's mode. */
+export declare function appendPrivate(path: string, line: string): void;

package/dist/state.js

@@ -0,0 +1,218 @@
+/**
+ * Private SDK state: the `stateDir` tree and the isolated config each session starts from.
+ * Mirrors sdk/python/dgc_sdk/_state.py.
+ *
+ * The isolated `home/.dgc/config.json` is owned by the SDK. Every session rewrites it from
+ * scratch, under a lock, from the options the embedder passed; nothing a previous session, run,
+ * or another local user left in that file is merged back in. That keeps per-session options
+ * (model, verifier, run budgets, trusted_dirs) out of later sessions, and stops a planted file
+ * from running commands (`verify_command`, `autonomous_gate`, `hooks`...). Extra CLI settings
+ * are allowed only when passed explicitly (`new DGC({ extraConfig })`).
+ */
+import { chmodSync, closeSync, existsSync, fchmodSync, fstatSync, fsyncSync, mkdirSync, mkdtempSync, openSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeSync, constants as fsConstants, } from "node:fs";
+import { tmpdir, userInfo } from "node:os";
+import { join, resolve } from "node:path";
+import { randomBytes } from "node:crypto";
+import { DGCConfigError } from "./errors.js";
+function posixOwnerChecks() {
+    return process.platform !== "win32" && typeof process.geteuid === "function";
+}
+/** True for this user's own primary group with no other listed members (umask 002 hosts). */
+function privateGroup(gid) {
+    try {
+        if (typeof process.getegid !== "function" || gid !== process.getegid())
+            return false;
+        const name = userInfo().username;
+        for (const line of readFileSync("/etc/group", "utf8").split("\n")) {
+            const parts = line.split(":");
+            if (parts.length >= 4 && Number(parts[2]) === gid) {
+                return parts[3].split(",").filter(Boolean).every((member) => member === name);
+            }
+        }
+        return true; // the group is not listed: nobody else is a member by name
+    }
+    catch {
+        return false;
+    }
+}
+/** Create `path` (and missing parents) and leave it owner-only (0700). */
+export function privateDir(path) {
+    mkdirSync(path, { recursive: true, mode: 0o700 });
+    if (process.platform !== "win32") {
+        try {
+            if ((statSync(path).mode & 0o777) !== 0o700)
+                chmodSync(path, 0o700);
+        }
+        catch { /* best effort */ }
+    }
+    return path;
+}
+/**
+ * A private state directory, created when needed.
+ *
+ * `undefined` makes a fresh `mkdtemp` directory (0700). An existing directory must be owned by
+ * this user and must not be group- or world-writable; a readable one that we own is tightened
+ * to 0700. Anything else is refused, because another local user could have planted files the
+ * DGC child would read.
+ */
+export function prepareStateDir(stateDir) {
+    if (stateDir === undefined || stateDir === null) {
+        return realpathSync(mkdtempSync(join(tmpdir(), "dgc-sdk-")));
+    }
+    if (typeof stateDir !== "string" || !stateDir.trim()) {
+        throw new DGCConfigError("stateDir must be a non-empty path");
+    }
+    let path = resolve(stateDir.startsWith("~/") ? join(userInfo().homedir, stateDir.slice(2)) : stateDir);
+    const existed = existsSync(path);
+    if (existed && !statSync(path).isDirectory()) {
+        throw new DGCConfigError(`stateDir ${JSON.stringify(path)} exists and is not a directory`);
+    }
+    try {
+        mkdirSync(path, { recursive: true, mode: 0o700 });
+    }
+    catch (error) {
+        throw new DGCConfigError(`could not create stateDir ${JSON.stringify(path)}: ${String(error)}`);
+    }
+    path = realpathSync(path);
+    if (posixOwnerChecks()) {
+        const info = statSync(path);
+        if (info.uid !== process.geteuid()) {
+            throw new DGCConfigError(`stateDir ${JSON.stringify(path)} is owned by another user; use a directory you own `
+                + "(or leave stateDir unset for a private temporary one)");
+        }
+        const mode = info.mode & 0o777;
+        if (existed && ((mode & 0o002) || ((mode & 0o020) && !privateGroup(info.gid)))) {
+            throw new DGCConfigError(`stateDir ${JSON.stringify(path)} is group- or world-writable (mode ${mode.toString(8)}); `
+                + "files in it cannot be trusted. Use a private directory (mode 0700)");
+        }
+        if (mode !== 0o700) {
+            try {
+                chmodSync(path, 0o700);
+            }
+            catch (error) {
+                throw new DGCConfigError(`could not make stateDir ${JSON.stringify(path)} private: ${String(error)}`);
+            }
+        }
+    }
+    return path;
+}
+export function configPath(stateDir) {
+    return join(stateDir, "home", ".dgc", "config.json");
+}
+/**
+ * Serialize isolated-config writes and child startups for one stateDir within this process.
+ * (The Python SDK also takes a cross-process flock; Node has none, so use one stateDir per
+ * process. A config another process rewrote while a session started is still detected and the
+ * start is retried.)
+ */
+export class StateLock {
+    tail = Promise.resolve();
+    async hold(work) {
+        let release;
+        const gate = new Promise((done) => { release = done; });
+        const previous = this.tail;
+        this.tail = previous.then(() => gate);
+        await previous;
+        try {
+            return await work();
+        }
+        finally {
+            release();
+        }
+    }
+}
+const LOCKS = new Map();
+export function stateLock(stateDir) {
+    const key = resolve(stateDir);
+    let lock = LOCKS.get(key);
+    if (!lock) {
+        lock = new StateLock();
+        LOCKS.set(key, lock);
+    }
+    return lock;
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            out[key] = sortKeys(value[key]);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Atomically replace the isolated config.json with exactly `values` (undefined/null dropped).
+ * Hold {@link stateLock} while calling. Directories are 0700 and the file is 0600. Returns the
+ * values as they read back from JSON, for {@link configDrift}.
+ */
+export function writeSessionConfig(stateDir, values) {
+    const payload = {};
+    for (const [key, value] of Object.entries(values)) {
+        if (value !== undefined && value !== null)
+            payload[key] = value;
+    }
+    const text = JSON.stringify(sortKeys(payload), null, 2) + "\n";
+    const home = privateDir(join(stateDir, "home"));
+    const folder = privateDir(join(home, ".dgc"));
+    const path = join(folder, "config.json");
+    const tmp = join(folder, `.config.json.${randomBytes(6).toString("hex")}.tmp`);
+    const fd = openSync(tmp, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL, 0o600);
+    try {
+        writeSync(fd, text);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    try {
+        renameSync(tmp, path);
+    }
+    finally {
+        try {
+            unlinkSync(tmp);
+        }
+        catch { /* renamed */ }
+    }
+    return JSON.parse(text);
+}
+function same(left, right) {
+    return JSON.stringify(sortKeys(left)) === JSON.stringify(sortKeys(right));
+}
+/**
+ * Keys of `expected` whose value in the isolated config.json now differs. A DGC child saves its
+ * whole configuration when it persists anything; if another session's child did that between
+ * our write and our child's startup, our child may have loaded that session's options.
+ */
+export function configDrift(stateDir, expected) {
+    let current;
+    try {
+        current = JSON.parse(readFileSync(configPath(stateDir), "utf8"));
+    }
+    catch {
+        return ["config.json"];
+    }
+    if (!current || typeof current !== "object" || Array.isArray(current))
+        return ["config.json"];
+    const record = current;
+    return Object.keys(expected).filter((key) => !same(record[key], expected[key])).sort();
+}
+/** Append `line` to an owner-only (0600) file, tightening an existing file's mode. */
+export function appendPrivate(path, line) {
+    const fd = openSync(path, fsConstants.O_WRONLY | fsConstants.O_APPEND | fsConstants.O_CREAT, 0o600);
+    try {
+        if (process.platform !== "win32") {
+            try {
+                if (fstatSync(fd).mode & 0o077)
+                    fchmodSync(fd, 0o600);
+            }
+            catch { /* best effort */ }
+        }
+        writeSync(fd, line);
+    }
+    finally {
+        closeSync(fd);
+    }
+}

package/dist/tools.d.ts

@@ -0,0 +1,56 @@
+import type { Frame, Transport } from "./transport.ts";
+export type ToolHandler = (args: Record<string, unknown>) => unknown | Promise<unknown>;
+export type ToolSpec = {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    handler: ToolHandler;
+    /** How long the handler may run (default 30 000 ms; null for no limit). */
+    timeoutMs?: number | null;
+};
+export declare const TOKEN_ENV = "DGC_SDK_TOOL_TOKEN";
+export declare const SERVER_NAME = "app";
+export declare const BRIDGE: string;
+/**
+ * Describe a tool the agent can call (as `mcp__app__<name>`) and this process runs. When the
+ * handler runs past `timeoutMs` the agent is told the call failed, but the handler is not
+ * stopped: make handlers idempotent or bound their own work. Refuse or allow the tool with
+ * `RuntimePolicy.denyTools: ["mcp__app__<name>"]` or `allowTools`.
+ */
+export declare function defineTool(name: string, description: string, inputSchema: Record<string, unknown>, handler: ToolHandler, options?: {
+    timeoutMs?: number | null;
+}): ToolSpec;
+export declare class ToolHub {
+    readonly token: string;
+    socketPath: string;
+    private directory;
+    private server;
+    private readonly tools;
+    private live;
+    /** True once the relay proved it holds the secret. */
+    authenticated: boolean;
+    /** Connections refused for a missing or wrong secret. */
+    rejected: number;
+    constructor(tools: readonly ToolSpec[], socketPath?: string);
+    get toolCount(): number;
+    start(): Promise<void>;
+    close(): void;
+    private removeFiles;
+    /** (runtime, persisted) MCP server specs; the secret rides only in the runtime spec's env. */
+    serverSpec(): {
+        runtime: Frame;
+        persisted: Frame;
+    };
+    private accept;
+    private callHandler;
+    private handle;
+}
+/**
+ * Start the host tool server, register it with DGC as MCP server `app`, and confirm it
+ * connected, authenticated and offered every tool. Throws DGCRuntimeError otherwise, rather than
+ * leaving a session whose model silently lacks the tools.
+ */
+export declare function installTools(transport: Transport, tools: readonly ToolSpec[], options: {
+    requestId: string;
+    timeoutMs: number;
+}): Promise<ToolHub>;

package/dist/tools.js

@@ -0,0 +1,339 @@
+/**
+ * Application tools the agent calls as MCP server `app`, served from this process. Mirrors
+ * sdk/python/dgc_sdk/_mcp_bridge.py.
+ *
+ * DGC runs `node mcp-bridge.mjs SOCKET` with this session's secret in DGC_SDK_TOOL_TOKEN. The
+ * socket lives in a fresh 0700 directory under a random name (never under stateDir, never a
+ * predictable path), and a connection is served only after its first line carries the secret,
+ * so other users, and processes that do not hold the secret, cannot call the tools. One relay
+ * connection is served at a time.
+ */
+import { chmodSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { existsSync, statSync } from "node:fs";
+import net from "node:net";
+import { fileURLToPath } from "node:url";
+import { DGCConfigError, DGCRuntimeError, DGCUnsupportedError } from "./errors.js";
+import { VERSION } from "./types.js";
+export const TOKEN_ENV = "DGC_SDK_TOOL_TOKEN";
+export const SERVER_NAME = "app";
+const HELLO_KEY = "dgc_sdk_bridge";
+const HELLO_TIMEOUT_MS = 10_000;
+const HELLO_MAX = 4096;
+// sun_path holds 104 bytes on macOS and 108 on Linux, terminator included.
+const SOCKET_PATH_MAX = 100;
+export const BRIDGE = fileURLToPath(new URL("./mcp-bridge.mjs", import.meta.url));
+/**
+ * Describe a tool the agent can call (as `mcp__app__<name>`) and this process runs. When the
+ * handler runs past `timeoutMs` the agent is told the call failed, but the handler is not
+ * stopped: make handlers idempotent or bound their own work. Refuse or allow the tool with
+ * `RuntimePolicy.denyTools: ["mcp__app__<name>"]` or `allowTools`.
+ */
+export function defineTool(name, description, inputSchema, handler, options = {}) {
+    if (!name || typeof name !== "string" || !/^[\w-]+$/.test(name) || !/[A-Za-z0-9]/.test(name.replace(/[_-]/g, ""))) {
+        throw new DGCConfigError("tool name must be a non-empty identifier");
+    }
+    if (!description || typeof description !== "string")
+        throw new DGCConfigError("tool description is required");
+    if (!inputSchema || typeof inputSchema !== "object" || Array.isArray(inputSchema)) {
+        throw new DGCConfigError("tool inputSchema must be an object");
+    }
+    if (typeof handler !== "function")
+        throw new DGCConfigError("tool handler must be callable");
+    const timeoutMs = options.timeoutMs === undefined ? 30_000 : options.timeoutMs;
+    if (timeoutMs !== null && (typeof timeoutMs !== "number" || !(timeoutMs > 0) || !Number.isFinite(timeoutMs))) {
+        throw new DGCConfigError("tool timeoutMs must be a positive number of milliseconds, or null");
+    }
+    return { name, description, inputSchema, handler, timeoutMs };
+}
+/** A fresh 0700 directory with a random socket name, short enough for sun_path. */
+function privateSocketPath() {
+    const bases = [];
+    for (const base of [process.env.XDG_RUNTIME_DIR || "", tmpdir(), "/tmp"]) {
+        try {
+            if (base && !bases.includes(base) && statSync(base).isDirectory())
+                bases.push(base);
+        }
+        catch { /* not there */ }
+    }
+    for (const base of bases) {
+        let directory;
+        try {
+            directory = mkdtempSync(join(base, "dgc-"));
+            chmodSync(directory, 0o700);
+        }
+        catch {
+            continue;
+        }
+        const path = join(directory, randomBytes(4).toString("hex") + ".sock");
+        if (Buffer.byteLength(path) <= SOCKET_PATH_MAX)
+            return { directory, path };
+        rmSync(directory, { recursive: true, force: true });
+    }
+    throw new DGCConfigError("custom tools need a Unix socket path under 100 bytes; none of "
+        + `${bases.join(", ") || "the temporary directories"} is short enough (set TMPDIR to a short directory)`);
+}
+function same(left, right) {
+    const a = Buffer.from(left, "utf8");
+    const b = Buffer.from(right, "utf8");
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+export class ToolHub {
+    token = randomBytes(32).toString("base64url");
+    socketPath = "";
+    directory = "";
+    server = null;
+    tools;
+    live = null;
+    /** True once the relay proved it holds the secret. */
+    authenticated = false;
+    /** Connections refused for a missing or wrong secret. */
+    rejected = 0;
+    constructor(tools, socketPath) {
+        this.tools = new Map(tools.map((item) => [item.name, item]));
+        if (socketPath)
+            this.socketPath = socketPath;
+    }
+    get toolCount() {
+        return this.tools.size;
+    }
+    async start() {
+        if (process.platform === "win32") {
+            throw new DGCUnsupportedError("custom tools need Unix domain sockets, which this SDK does not use on Windows");
+        }
+        if (!this.socketPath)
+            ({ directory: this.directory, path: this.socketPath } = privateSocketPath());
+        const server = net.createServer((socket) => this.accept(socket));
+        try {
+            await new Promise((resolve, reject) => {
+                server.once("error", reject);
+                server.listen(this.socketPath, () => {
+                    server.off("error", reject);
+                    resolve();
+                });
+            });
+            chmodSync(this.socketPath, 0o600);
+        }
+        catch (error) {
+            server.close();
+            this.removeFiles();
+            throw new DGCConfigError(`custom tools could not open their socket: ${String(error)}`);
+        }
+        server.on("error", () => { });
+        this.server = server;
+    }
+    close() {
+        try {
+            this.server?.close();
+        }
+        catch { /* */ }
+        this.server = null;
+        try {
+            this.live?.destroy();
+        }
+        catch { /* */ }
+        this.live = null;
+        this.removeFiles();
+    }
+    removeFiles() {
+        try {
+            if (this.socketPath && existsSync(this.socketPath))
+                rmSync(this.socketPath, { force: true });
+        }
+        catch { /* */ }
+        if (this.directory) {
+            rmSync(this.directory, { recursive: true, force: true });
+            this.directory = "";
+        }
+    }
+    /** (runtime, persisted) MCP server specs; the secret rides only in the runtime spec's env. */
+    serverSpec() {
+        const persisted = {
+            transport: "stdio", command: process.execPath, args: [BRIDGE, this.socketPath],
+            env_names: [TOKEN_ENV], log_level: "warning",
+        };
+        return { runtime: { ...persisted, env: { [TOKEN_ENV]: this.token } }, persisted };
+    }
+    accept(socket) {
+        let buf = Buffer.alloc(0);
+        let ready = false;
+        const timer = setTimeout(() => socket.destroy(), HELLO_TIMEOUT_MS);
+        timer.unref();
+        const refuse = () => {
+            clearTimeout(timer);
+            this.rejected += 1;
+            socket.destroy();
+        };
+        socket.on("error", () => { });
+        socket.on("close", () => {
+            clearTimeout(timer);
+            if (this.live === socket)
+                this.live = null;
+        });
+        socket.on("data", (chunk) => {
+            buf = Buffer.concat([buf, chunk]);
+            if (!ready) {
+                const nl = buf.indexOf(0x0a);
+                if (nl < 0) {
+                    if (buf.length > HELLO_MAX)
+                        refuse();
+                    return;
+                }
+                let hello;
+                try {
+                    hello = JSON.parse(buf.subarray(0, nl).toString("utf8"));
+                }
+                catch {
+                    refuse();
+                    return;
+                }
+                const token = hello && typeof hello === "object" ? hello.token : undefined;
+                // One relay at a time: while one is connected, nobody else is served, even with the secret.
+                if (typeof token !== "string" || !same(token, this.token) || (this.live && !this.live.destroyed)) {
+                    refuse();
+                    return;
+                }
+                clearTimeout(timer);
+                ready = true;
+                this.live = socket;
+                this.authenticated = true;
+                buf = buf.subarray(nl + 1);
+            }
+            let nl;
+            while ((nl = buf.indexOf(0x0a)) !== -1) {
+                const line = buf.subarray(0, nl).toString("utf8").trim();
+                buf = buf.subarray(nl + 1);
+                if (!line)
+                    continue;
+                let message;
+                try {
+                    message = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                void this.handle(message).then((reply) => {
+                    if (reply && !socket.destroyed)
+                        socket.write(JSON.stringify(reply) + "\n");
+                });
+            }
+        });
+    }
+    async callHandler(spec, args) {
+        const work = Promise.resolve().then(() => spec.handler(args));
+        const limit = spec.timeoutMs === undefined ? 30_000 : spec.timeoutMs;
+        if (limit === null)
+            return work;
+        let timer;
+        try {
+            return await Promise.race([
+                work,
+                new Promise((_resolve, reject) => {
+                    timer = setTimeout(() => reject(Object.assign(new Error("handler exceeded timeout"), { name: "TimeoutError" })), limit);
+                }),
+            ]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    async handle(message) {
+        const method = String(message.method || "");
+        const id = message.id;
+        if (method === "initialize") {
+            return {
+                jsonrpc: "2.0", id,
+                result: {
+                    protocolVersion: "2025-11-25",
+                    capabilities: { tools: {} },
+                    serverInfo: { name: "dgc-sdk", version: VERSION },
+                },
+            };
+        }
+        if (method === "notifications/initialized" || method === "notifications/cancelled")
+            return null;
+        if (method === "ping")
+            return { jsonrpc: "2.0", id, result: {} };
+        if (method === "tools/list") {
+            const tools = [...this.tools.values()].map((spec) => ({
+                name: spec.name,
+                description: spec.description,
+                inputSchema: spec.inputSchema && Object.keys(spec.inputSchema).length
+                    ? spec.inputSchema : { type: "object", properties: {} },
+            }));
+            return { jsonrpc: "2.0", id, result: { tools } };
+        }
+        if (method === "tools/call") {
+            const params = (message.params && typeof message.params === "object")
+                ? message.params : {};
+            const name = String(params.name || "");
+            const args = (params.arguments && typeof params.arguments === "object")
+                ? params.arguments : {};
+            const spec = this.tools.get(name);
+            if (!spec)
+                return { jsonrpc: "2.0", id, error: { code: -32601, message: `unknown tool ${name}` } };
+            try {
+                const result = await this.callHandler(spec, args);
+                const text = typeof result === "string" ? result : JSON.stringify(result ?? null);
+                return {
+                    jsonrpc: "2.0", id,
+                    result: { content: [{ type: "text", text: String(text).slice(0, 120_000) }], isError: false },
+                };
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                return {
+                    jsonrpc: "2.0", id,
+                    result: { content: [{ type: "text", text: `tool error: ${err.name}: ${err.message}` }], isError: true },
+                };
+            }
+        }
+        if (id !== undefined) {
+            return { jsonrpc: "2.0", id, error: { code: -32601, message: `unsupported method ${method}` } };
+        }
+        return null;
+    }
+}
+function catalogProblem(catalog, expected) {
+    if (catalog.error)
+        return String(catalog.error);
+    const items = Array.isArray(catalog.items) ? catalog.items : [];
+    const entry = items.find((item) => item && typeof item === "object" && item.name === SERVER_NAME);
+    if (!entry)
+        return "the runtime did not register the tool server";
+    const state = String(entry.state || "");
+    if (entry.error || state !== "connected")
+        return String(entry.error || `the tool server is ${state || "not connected"}`);
+    const offered = Number(entry.tool_count || 0);
+    if (offered < expected)
+        return `the tool server offered ${offered} of ${expected} tools`;
+    return "";
+}
+/**
+ * Start the host tool server, register it with DGC as MCP server `app`, and confirm it
+ * connected, authenticated and offered every tool. Throws DGCRuntimeError otherwise, rather than
+ * leaving a session whose model silently lacks the tools.
+ */
+export async function installTools(transport, tools, options) {
+    const hub = new ToolHub(tools);
+    await hub.start();
+    try {
+        const { runtime, persisted } = hub.serverSpec();
+        const catalog = await transport.request({
+            type: "upsert_mcp_server", request_id: options.requestId, name: SERVER_NAME, runtime, persisted,
+        }, "mcp_servers", { timeoutMs: options.timeoutMs });
+        let problem = catalogProblem(catalog, hub.toolCount);
+        if (!problem && !hub.authenticated)
+            problem = "the tool bridge never authenticated to the application";
+        if (problem)
+            throw new DGCRuntimeError(`custom tools failed to start: ${problem}`);
+    }
+    catch (error) {
+        hub.close();
+        throw error;
+    }
+    return hub;
+}