@vibedgc/sdk 0.6.4

package/dist/client.js

@@ -0,0 +1,472 @@
+/** Public DGC client. Mirrors sdk/python/dgc_sdk/client.py. */
+import { closeSync, constants as fsConstants, openSync, realpathSync, rmSync, statSync, unlinkSync, writeSync, } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { AuditLog, rememberSecret } from "./audit.js";
+import { DGCCommandRejectedError, DGCConfigError, DGCError, DGCProtocolError, DGCRuntimeError, publicError, } from "./errors.js";
+import { Policy, compileSession, permissionSettings, sandboxPrecheck, sandboxRequirement, toPolicy, } from "./policy.js";
+import { defaultRuntime, isolatedEnv } from "./runtime.js";
+import { Session } from "./session.js";
+import { configDrift, prepareStateDir, stateLock, writeSessionConfig } from "./state.js";
+import { installTools } from "./tools.js";
+import { Transport } from "./transport.js";
+import { UsageLog } from "./usage.js";
+import { PROTOCOL, REQUIRES_CLI, VERSION, } from "./types.js";
+const CONFIG_ATTEMPTS = 3;
+function newId(prefix) {
+    return `${prefix}-${randomUUID().replace(/-/g, "").slice(0, 8)}`;
+}
+function milliseconds(value, name, maximum, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0 || value > maximum) {
+        throw new DGCConfigError(`${name} must be more than 0 and at most ${maximum} milliseconds`);
+    }
+    return value;
+}
+/**
+ * Write a provider key to a private (0600) file inside the 0700 stateDir. The runtime is handed
+ * the path (DGC_API_KEY_FILE), not the key, so the key never sits in the child's initial
+ * environment block, which stays readable in /proc/<pid>/environ. The CLI reads the file and
+ * deletes it at config load, before any tool runs.
+ */
+function writeKeyFile(path, value) {
+    const fd = openSync(path, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_TRUNC, 0o600);
+    try {
+        writeSync(fd, value);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function runtimeArgv(runtime) {
+    if (!Array.isArray(runtime))
+        throw new DGCConfigError("runtime must be an argv array such as ['dgc', 'serve']");
+    if (!runtime.length || runtime.some((item) => typeof item !== "string" || !item || item.includes("\u0000"))) {
+        throw new DGCConfigError("runtime must be a non-empty array of non-empty strings");
+    }
+    return [...runtime];
+}
+function existingDirs(items) {
+    const found = [];
+    for (const item of items) {
+        try {
+            const path = realpathSync(item.startsWith("~/") ? join(homedir(), item.slice(2)) : item);
+            if (statSync(path).isDirectory())
+                found.push(path);
+        }
+        catch { /* not there */ }
+    }
+    return found;
+}
+/** With inheritUserState these would have to be saved into your own ~/.dgc. */
+function rejectInherited(options) {
+    const given = Object.entries(options)
+        .filter(([name, value]) => value !== undefined && value !== null
+        && !(typeof value === "object" && !Array.isArray(value) && !Object.keys(value).length)
+        && !(name === "thinking" && value === "off"))
+        .map(([name]) => name).sort();
+    if (given.length) {
+        throw new DGCConfigError(`inheritUserState runs with your own DGC settings, and DGC would save ${given.join(", ")} `
+            + "into ~/.dgc/config.json; set them with the dgc CLI, or use an isolated stateDir (inheritUserState: false)");
+    }
+}
+/** Refuse an inherited session whose settings differ from what the caller asked for. */
+function checkInherited(ready, requested) {
+    const actual = {
+        model: String(ready.model || ""),
+        baseUrl: String(ready.base_url || "").replace(/\/+$/, ""),
+        mode: String(ready.mode || ""),
+        thinking: String(ready.think || ""),
+    };
+    const wrong = [];
+    for (const [name, value] of Object.entries(requested)) {
+        if (value === undefined)
+            continue;
+        const want = name === "baseUrl" ? value.replace(/\/+$/, "") : value;
+        if (want !== actual[name])
+            wrong.push(`${name}=${JSON.stringify(value)} (your DGC uses ${JSON.stringify(actual[name])})`);
+    }
+    if (wrong.length) {
+        throw new DGCConfigError("inheritUserState uses your own DGC settings and cannot change them without saving into "
+            + `~/.dgc: ${wrong.join("; ")}. Change them with the dgc CLI, or use an isolated stateDir`);
+    }
+}
+/**
+ * Own zero or more isolated DGC sessions. Does not talk to a provider on construction.
+ *
+ * `stateDir` holds this client's isolated HOME, audit and usage logs; it must be private, and
+ * left unset a fresh private temporary directory is used ({@link stateDir}). `inheritEnv` picks
+ * which host environment variables reach the runtime: false (default) passes only basic ones, a
+ * list of names adds those, true passes everything. `startTimeoutMs` bounds the runtime's startup
+ * handshake and `requestTimeoutMs` each control request.
+ */
+export class DGC {
+    sessions = [];
+    closed = false;
+    options;
+    policy;
+    sandbox;
+    runtime;
+    startTimeoutMs;
+    requestTimeoutMs;
+    usageLog;
+    auditLog;
+    /** This client's private state directory (created when it was not given). */
+    stateDir;
+    ownsStateDir;
+    trustWorkspace;
+    constructor(options = {}) {
+        this.options = { ...options };
+        this.policy = toPolicy(options.policy);
+        if (options.inheritUserState) {
+            rejectInherited({
+                model: options.model, baseUrl: options.baseUrl, thinking: options.thinking, extraConfig: options.extraConfig,
+            });
+        }
+        if (options.inheritEnv !== undefined && typeof options.inheritEnv !== "boolean") {
+            if (!Array.isArray(options.inheritEnv))
+                throw new DGCConfigError("inheritEnv must be true, false, or a list of variable names");
+            for (const name of options.inheritEnv) {
+                if (typeof name !== "string" || !name || name.includes("=") || name.includes("\u0000")) {
+                    throw new DGCConfigError(`inheritEnv has an invalid variable name: ${JSON.stringify(name)}`);
+                }
+            }
+        }
+        this.startTimeoutMs = milliseconds(options.startTimeoutMs, "startTimeoutMs", 3_600_000, 30_000);
+        this.requestTimeoutMs = milliseconds(options.requestTimeoutMs, "requestTimeoutMs", 86_400_000, 15_000);
+        this.runtime = options.runtime !== undefined ? runtimeArgv(options.runtime) : defaultRuntime();
+        this.sandbox = sandboxRequirement(options.sandbox);
+        sandboxPrecheck(this.sandbox);
+        this.stateDir = prepareStateDir(options.stateDir);
+        // Only a directory the SDK created for this client is removed on close; an explicit stateDir
+        // (the application's own directory) is always left alone.
+        this.ownsStateDir = options.stateDir === undefined && !options.keepStateDir;
+        this.trustWorkspace = Boolean(options.trustWorkspace);
+        if (options.apiKey)
+            rememberSecret(options.apiKey);
+        this.usageLog = new UsageLog(join(this.stateDir, "usage"));
+        this.auditLog = new AuditLog(join(this.stateDir, "audit"));
+    }
+    get version() {
+        return VERSION;
+    }
+    /** The `dgc serve` argv this client starts. */
+    get rawRuntime() {
+        return [...this.runtime];
+    }
+    async session(options) {
+        if (this.closed)
+            throw new DGCRuntimeError("this DGC client is closed");
+        if (!options || typeof options.cwd !== "string" || !options.cwd)
+            throw new DGCConfigError("cwd must be an existing directory");
+        let workspace;
+        try {
+            workspace = realpathSync(options.cwd);
+            if (!statSync(workspace).isDirectory())
+                throw new Error("not a directory");
+        }
+        catch {
+            throw new DGCConfigError("cwd must be an existing directory");
+        }
+        const inherit = Boolean(this.options.inheritUserState);
+        const [mode, unhandled] = permissionSettings(options.permissions, options.mode, this.options.mode ?? "default", options.onPermission);
+        const requestedMode = options.mode || options.permissions?.mode
+            || (this.options.mode && this.options.mode !== "default" ? this.options.mode : undefined);
+        if (inherit) {
+            rejectInherited({
+                maxTurns: options.maxTurns, verifyCommand: options.verifyCommand, turnBudgetS: options.turnBudgetS,
+                maxTokens: options.maxTokens,
+            });
+        }
+        const requirement = options.sandbox !== undefined ? sandboxRequirement(options.sandbox) : this.sandbox;
+        sandboxPrecheck(requirement);
+        const tools = options.tools ?? [];
+        // The RuntimePolicy and sandbox reach this session's runtime only through its environment
+        // (DGC_SESSION_POLICY); nothing is written to any config.json.
+        const plan = compileSession(this.policy, {
+            cwd: workspace, mode, sandbox: requirement, tools: tools.map((t) => t.name),
+            trustWorkspace: this.trustWorkspace, isolated: !inherit,
+        });
+        const key = options.apiKey ?? this.options.apiKey;
+        const extra = { ...(this.options.extraEnv || {}) };
+        let keyFile = null;
+        if (key) {
+            rememberSecret(key);
+            if (inherit) {
+                // inheritUserState runs as the user's own DGC on their own machine; the key goes in the
+                // environment as before (DGC never saves it into ~/.dgc).
+                extra.DGC_API_KEY = String(key);
+            }
+            else {
+                // An isolated child's environment block stays readable in /proc/<pid>/environ, so the key
+                // travels in a 0600 file inside the 0700 stateDir that the CLI reads and deletes.
+                keyFile = join(this.stateDir, `.apikey-${newId("key")}`);
+                extra.DGC_API_KEY_FILE = keyFile;
+            }
+        }
+        Object.assign(extra, plan.env);
+        let values = null;
+        if (!inherit) {
+            values = {
+                model: options.model || this.options.model,
+                base_url: options.baseUrl || this.options.baseUrl,
+                mode,
+                thinking: options.thinking || this.options.thinking || "off",
+                artifact_autostart: false,
+                artifact_in_plan: false,
+                suggest: false,
+                eta: false,
+                notify: "off",
+                monitor_wake: false,
+                mcp_servers: {},
+                hooks: {},
+                trusted_dirs: [workspace, ...existingDirs(this.policy?.extraReadDirs ?? [])],
+                sandbox: false,
+                sandbox_network: Boolean(this.policy && this.policy.network === "allow"),
+                ...(this.options.extraConfig || {}),
+            };
+            if (options.maxTurns !== undefined)
+                values.max_turns = Math.trunc(options.maxTurns);
+            if (options.turnBudgetS !== undefined)
+                values.turn_budget_s = Math.trunc(options.turnBudgetS);
+            if (options.maxTokens !== undefined)
+                values.max_tokens = Math.trunc(options.maxTokens);
+            if (options.verifyCommand) {
+                values.verify_command = options.verifyCommand;
+                values.verify_before_done = true;
+            }
+        }
+        let env;
+        try {
+            env = isolatedEnv(this.stateDir, extra, inherit, inherit ? undefined : workspace, this.options.inheritEnv ?? false);
+        }
+        catch (error) {
+            if (error instanceof DGCError)
+                throw error;
+            throw new DGCConfigError(`could not prepare the isolated runtime home: ${String(error)}`);
+        }
+        const lock = stateLock(this.stateDir);
+        // Config write, child startup and every save the SDK itself triggers happen under one lock,
+        // so concurrent sessions never read each other's options.
+        const session = await lock.hold(async () => {
+            let started;
+            try {
+                started = await this.start(workspace, env, values, key, keyFile);
+            }
+            finally {
+                // The CLI deletes the key file as it starts; remove any leftover (a failed or skipped
+                // start) so the key never lingers in the stateDir.
+                if (keyFile) {
+                    try {
+                        unlinkSync(keyFile);
+                    }
+                    catch { /* already gone */ }
+                }
+            }
+            const { transport, ready } = started;
+            let hub = null;
+            try {
+                const sandboxStatus = plan.confirm(ready);
+                if (inherit) {
+                    checkInherited(ready, {
+                        model: options.model || this.options.model,
+                        baseUrl: options.baseUrl || this.options.baseUrl,
+                        mode: requestedMode,
+                        thinking: options.thinking || (this.options.thinking && this.options.thinking !== "off" ? this.options.thinking : undefined),
+                    });
+                }
+                if (tools.length) {
+                    hub = await installTools(transport, tools, {
+                        requestId: newId("mcp"), timeoutMs: Math.max(20_000, this.requestTimeoutMs),
+                    });
+                }
+                if ((mode === "acceptEdits" || mode === "auto") && ready.workspace_trusted !== true) {
+                    try {
+                        transport.send({ type: "set_mode", mode, acknowledge_workspace_trust: true, request_id: newId("trust") });
+                    }
+                    catch { /* the run reports a dead backend */ }
+                }
+                return new Session(transport, ready, {
+                    options,
+                    unhandled,
+                    instructions: options.instructions ?? this.options.instructions ?? "",
+                    toolHub: hub,
+                    cwd: workspace,
+                    policy: this.policy,
+                    pricing: this.options.pricing,
+                    department: this.options.department || "",
+                    usageLog: this.usageLog,
+                    auditLog: this.auditLog,
+                    model: String(options.model || this.options.model || ""),
+                    permissionMode: inherit ? String(ready.mode || mode) : mode,
+                    isolated: !inherit,
+                    maxTurns: options.maxTurns,
+                    verifyCommand: options.verifyCommand || "",
+                    stateLock: lock,
+                    excludePaths: inherit ? [join(homedir(), ".dgc"), this.stateDir] : [this.stateDir],
+                    requestTimeoutMs: this.requestTimeoutMs,
+                    sandbox: sandboxStatus,
+                });
+            }
+            catch (error) {
+                // Nothing may outlive a failed setup: not the tool socket, not the dgc serve child.
+                hub?.close();
+                await transport.close();
+                throw error instanceof DGCError && !(error instanceof DGCCommandRejectedError)
+                    ? error : publicError(error, "session setup failed");
+            }
+        });
+        try {
+            await session.bindIdentity();
+        }
+        catch { /* its transcript appears after the first run */ }
+        this.sessions.push(session);
+        return session;
+    }
+    /**
+     * Write this session's config from scratch, then start `dgc serve` on it. A DGC child saves its
+     * whole config when it persists anything; if another session's child did that between our write
+     * and our child's startup, start again.
+     */
+    async start(workspace, env, values, key, keyFile = null) {
+        const drifts = [];
+        const attempts = values !== null ? CONFIG_ATTEMPTS : 1;
+        for (let attempt = 0; attempt < attempts; attempt++) {
+            let written = null;
+            try {
+                // The CLI reads and deletes the key file at startup, so write it before every (re)start.
+                if (keyFile && key)
+                    writeKeyFile(keyFile, String(key));
+                written = values !== null ? writeSessionConfig(this.stateDir, values) : null;
+            }
+            catch (error) {
+                throw new DGCConfigError(`could not prepare the isolated runtime home: ${String(error)}`);
+            }
+            const transport = new Transport(this.runtime, workspace, env);
+            let ready;
+            try {
+                ready = await transport.start(this.startTimeoutMs);
+            }
+            catch (error) {
+                await transport.close();
+                if (error instanceof DGCProtocolError)
+                    throw this.protocolError(error);
+                throw new DGCRuntimeError(this.startFailure(error, transport, key), { cause: error });
+            }
+            const drift = written !== null ? configDrift(this.stateDir, written) : [];
+            const last = drifts[drifts.length - 1];
+            if (!drift.length || (last && last.join() === drift.join() && attempt === attempts - 1)) {
+                // The same difference every time is DGC normalizing its own file, not a race.
+                return { transport, ready };
+            }
+            drifts.push(drift);
+            process.emitWarning(`dgc sdk: isolated config changed while the session started (${drift.slice(0, 5).join(", ")}); `
+                + "starting again", { code: "DGC_SDK" });
+            await transport.close();
+        }
+        throw new DGCRuntimeError("another DGC process kept rewriting this stateDir's config while the session started; "
+            + "use a separate stateDir per process");
+    }
+    protocolError(error) {
+        const offered = error.offeredProtocol;
+        const runtime = this.runtime.join(" ");
+        if (offered === undefined) {
+            return new DGCProtocolError(`the DGC runtime broke protocol v${PROTOCOL}: ${error.message} (runtime: ${runtime})`, { cause: error });
+        }
+        const cli = error.backendVersion || "unknown";
+        const advice = typeof offered === "number" && offered > PROTOCOL
+            ? "Upgrade the SDK (@vibedgc/sdk) to drive this CLI."
+            : `Update the CLI (dgc update), or point DGC_PYTHON or runtime at a DGC that is ${REQUIRES_CLI} or newer.`;
+        return new DGCProtocolError(`DGC SDK ${VERSION} speaks protocol v${PROTOCOL} and needs CLI ${REQUIRES_CLI} or newer; the runtime is CLI `
+            + `${cli} with protocol v${String(offered)} (${runtime}). ${advice}`, { offeredProtocol: offered, backendVersion: error.backendVersion, cause: error });
+    }
+    startFailure(error, transport, key) {
+        let message = `the DGC runtime did not start: ${error instanceof Error ? error.message : String(error)} `
+            + `(runtime: ${this.runtime.join(" ")})`;
+        const tail = transport.stderrTail.trim();
+        if (tail)
+            message += "\nruntime stderr (last lines):\n" + tail.split("\n").slice(-12).join("\n").slice(-2000);
+        for (const secret of new Set([String(key || ""), String(this.options.apiKey || "")])) {
+            if (secret.length >= 4)
+                message = message.split(secret).join("[redacted]");
+        }
+        return message;
+    }
+    /** Open a session on a persisted transcript (`sessionId`, or `latest: true`). */
+    async resume(options) {
+        const session = await this.session(options);
+        const command = { type: "resume_session", request_id: newId("resume") };
+        let path = options.sessionId;
+        const target = options.latest || !options.sessionId ? "the latest session" : JSON.stringify(options.sessionId);
+        let event;
+        try {
+            if (options.latest || !options.sessionId) {
+                command.latest = true;
+            }
+            else {
+                const sessionId = options.sessionId;
+                const looksLikePath = sessionId.endsWith(".json") || sessionId.includes("/") || sessionId.includes("\\");
+                if (!looksLikePath) {
+                    const match = (await session.listSessions()).find((item) => item.id === sessionId);
+                    if (!match)
+                        throw new DGCConfigError(`no persisted session ${JSON.stringify(sessionId)}`);
+                    path = match.path;
+                }
+                command.path = path;
+            }
+            event = await session.transport.request(command, "session", { timeoutMs: this.requestTimeoutMs });
+        }
+        catch (error) {
+            await session.close();
+            const index = this.sessions.indexOf(session);
+            if (index >= 0)
+                this.sessions.splice(index, 1);
+            if (error instanceof DGCCommandRejectedError) {
+                throw new DGCConfigError(`could not resume ${target}: ${error.message}`, { cause: error });
+            }
+            if (error instanceof DGCError)
+                throw error;
+            throw publicError(error, `could not resume ${target}`);
+        }
+        session.sessionId = String(event.session_id || options.sessionId || session.sessionId);
+        session.sessionPath = String(event.path || path || session.sessionPath);
+        await session.discardIdle();
+        try {
+            await session.bindIdentity();
+        }
+        catch { /* keeps the path DGC reported */ }
+        return session;
+    }
+    /**
+     * Usage recorded under this client's stateDir (never the host ~/.dgc): runs, token totals over
+     * runs whose provider reported usage, `unknownUsageRuns` for the rest, cost, per department.
+     */
+    usageReport(department) {
+        return this.usageLog.query({ department });
+    }
+    /** Audit rows (redacted unless `redact: false`), for one session or all. */
+    exportAudit(sessionId, options = {}) {
+        return this.auditLog.export(sessionId, options.redact ?? true);
+    }
+    async close() {
+        this.closed = true;
+        const closing = [];
+        while (this.sessions.length) {
+            const session = this.sessions.pop();
+            if (session)
+                closing.push(session.close());
+        }
+        await Promise.all(closing);
+        if (this.ownsStateDir) {
+            // A stateDir the SDK created holds only this client's throwaway HOME, usage and audit logs;
+            // remove it so nothing (the audit rows included) is left on disk.
+            this.ownsStateDir = false;
+            try {
+                rmSync(this.stateDir, { recursive: true, force: true });
+            }
+            catch { /* best effort */ }
+        }
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Typed failures. Every error the SDK throws is a {@link DGCError}; mirrors the Python SDK's
+ * dgc_sdk.errors. A run that hits its own timeout does not throw: its result has
+ * `status: "failed"` and `reason: "timeout"`.
+ */
+export declare class DGCError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Session or client options are invalid. */
+export declare class DGCConfigError extends DGCError {
+}
+/** The DGC runtime could not start, handshake, stay alive, or carry out a command. */
+export declare class DGCRuntimeError extends DGCError {
+}
+/** The runtime speaks a protocol this SDK does not, or broke the one it offered. */
+export declare class DGCProtocolError extends DGCRuntimeError {
+    /** The protocol a `ready` handshake offered, when that was the problem. */
+    readonly offeredProtocol?: unknown;
+    /** The CLI version the runtime reported, when known. */
+    readonly backendVersion?: string;
+    constructor(message: string, details?: {
+        offeredProtocol?: unknown;
+        backendVersion?: string;
+        cause?: unknown;
+    });
+}
+/**
+ * The runtime refused a command (`command_rejected`, or an `error` naming the request).
+ * `reason` is the runtime's machine-readable code when it sent one (for example
+ * `turn_in_progress` or `session_unavailable`); `command` is the refused command type.
+ */
+export declare class DGCCommandRejectedError extends DGCRuntimeError {
+    readonly reason: string;
+    readonly command: string;
+    constructor(message: string, details?: {
+        reason?: string;
+        command?: string;
+        cause?: unknown;
+    });
+}
+/** A control request, the runtime handshake, or a wait on a run's result ran out of time. */
+export declare class DGCTimeoutError extends DGCError {
+}
+/** A requested capability is not available on this host or runtime. */
+export declare class DGCUnsupportedError extends DGCConfigError {
+}
+/**
+ * The SDK's own error for any failure, keeping its message and details. `context` prefixes the
+ * message. A DGCError keeps its class; anything else becomes a DGCRuntimeError.
+ */
+export declare function publicError(error: unknown, context?: string): DGCError;

package/dist/errors.js

@@ -0,0 +1,70 @@
+/**
+ * Typed failures. Every error the SDK throws is a {@link DGCError}; mirrors the Python SDK's
+ * dgc_sdk.errors. A run that hits its own timeout does not throw: its result has
+ * `status: "failed"` and `reason: "timeout"`.
+ */
+export class DGCError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = new.target.name;
+    }
+}
+/** Session or client options are invalid. */
+export class DGCConfigError extends DGCError {
+}
+/** The DGC runtime could not start, handshake, stay alive, or carry out a command. */
+export class DGCRuntimeError extends DGCError {
+}
+/** The runtime speaks a protocol this SDK does not, or broke the one it offered. */
+export class DGCProtocolError extends DGCRuntimeError {
+    /** The protocol a `ready` handshake offered, when that was the problem. */
+    offeredProtocol;
+    /** The CLI version the runtime reported, when known. */
+    backendVersion;
+    constructor(message, details = {}) {
+        super(message, details.cause === undefined ? undefined : { cause: details.cause });
+        this.offeredProtocol = details.offeredProtocol;
+        this.backendVersion = details.backendVersion;
+    }
+}
+/**
+ * The runtime refused a command (`command_rejected`, or an `error` naming the request).
+ * `reason` is the runtime's machine-readable code when it sent one (for example
+ * `turn_in_progress` or `session_unavailable`); `command` is the refused command type.
+ */
+export class DGCCommandRejectedError extends DGCRuntimeError {
+    reason;
+    command;
+    constructor(message, details = {}) {
+        super(message, details.cause === undefined ? undefined : { cause: details.cause });
+        this.reason = details.reason || "";
+        this.command = details.command || "";
+    }
+}
+/** A control request, the runtime handshake, or a wait on a run's result ran out of time. */
+export class DGCTimeoutError extends DGCError {
+}
+/** A requested capability is not available on this host or runtime. */
+export class DGCUnsupportedError extends DGCConfigError {
+}
+/**
+ * The SDK's own error for any failure, keeping its message and details. `context` prefixes the
+ * message. A DGCError keeps its class; anything else becomes a DGCRuntimeError.
+ */
+export function publicError(error, context = "") {
+    const base = error instanceof Error ? (error.message || error.name) : String(error);
+    const message = context ? `${context}: ${base}` : base;
+    if (error instanceof DGCCommandRejectedError) {
+        return new DGCCommandRejectedError(message, { reason: error.reason, command: error.command, cause: error });
+    }
+    if (error instanceof DGCProtocolError) {
+        return new DGCProtocolError(message, {
+            offeredProtocol: error.offeredProtocol, backendVersion: error.backendVersion, cause: error,
+        });
+    }
+    for (const Kind of [DGCUnsupportedError, DGCTimeoutError, DGCConfigError]) {
+        if (error instanceof Kind)
+            return new Kind(message, { cause: error });
+    }
+    return new DGCRuntimeError(message, { cause: error });
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/** DGC SDK for Node (@vibedgc/sdk). Protocol v14; pair with DGC CLI 0.41.6. */
+export { VERSION, PROTOCOL, REQUIRES_CLI } from "./types.ts";
+export type { AbortSignalLike, AgentInfo, Artifact, Checkpoint, ClientOptions, Denial, FileChange, Goal, HookInfo, McpInputRequest, McpInputResponse, McpServerInfo, Monitor, PermissionAction, PermissionMode, PermissionRequest, PermissionRule, PlanAction, PlanRequest, Pricing, QuestionAnswers, QuestionRequest, ResumeOptions, RunEvent, RunOptions, RunResult, RunStatus, RuntimePolicy, SandboxRequirement, SandboxSetting, SandboxStatus, SessionInfo, SessionOptions, SkillInfo, TaskItem, ToolRecord, UnhandledPolicy, VerificationResult, } from "./types.ts";
+export { DGC } from "./client.ts";
+export { RunHandle, Session } from "./session.ts";
+export { defineTool, type ToolSpec } from "./tools.ts";
+export { assertSupported, extractJson, validate } from "./schema.ts";
+export { DGCCommandRejectedError, DGCConfigError, DGCError, DGCProtocolError, DGCRuntimeError, DGCTimeoutError, DGCUnsupportedError, } from "./errors.ts";
+export { redact, redactText } from "./audit.ts";
+export { costUsd, type UsageReport } from "./usage.ts";

package/dist/index.js

@@ -0,0 +1,9 @@
+/** DGC SDK for Node (@vibedgc/sdk). Protocol v14; pair with DGC CLI 0.41.6. */
+export { VERSION, PROTOCOL, REQUIRES_CLI } from "./types.js";
+export { DGC } from "./client.js";
+export { RunHandle, Session } from "./session.js";
+export { defineTool } from "./tools.js";
+export { assertSupported, extractJson, validate } from "./schema.js";
+export { DGCCommandRejectedError, DGCConfigError, DGCError, DGCProtocolError, DGCRuntimeError, DGCTimeoutError, DGCUnsupportedError, } from "./errors.js";
+export { redact, redactText } from "./audit.js";
+export { costUsd } from "./usage.js";

package/dist/mcp-bridge.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * stdio <-> Unix-socket relay. DGC spawns it as the `app` MCP server; the SDK host owns the tools.
+ *
+ * The session's secret arrives in DGC_SDK_TOOL_TOKEN. The relay drops it from its own
+ * environment, proves it knows it with a first `{"dgc_sdk_bridge":1,"token":...}` line, then
+ * copies NDJSON in both directions. Standard library only.
+ */
+import net from "node:net";
+import process from "node:process";
+
+const TOKEN_ENV = "DGC_SDK_TOOL_TOKEN";
+const socketPath = process.argv[2];
+if (!socketPath) {
+  process.stderr.write("usage: node mcp-bridge.mjs SOCKET  (with DGC_SDK_TOOL_TOKEN set)\n");
+  process.exit(2);
+}
+const token = process.env[TOKEN_ENV] || "";
+delete process.env[TOKEN_ENV];
+if (!token) {
+  process.stderr.write(`dgc-sdk tool bridge: ${TOKEN_ENV} is not set\n`);
+  process.exit(2);
+}
+
+const sock = net.createConnection(socketPath);
+sock.on("error", (error) => {
+  process.stderr.write(`dgc-sdk tool bridge: cannot reach the application: ${error.message || error}\n`);
+  process.exit(1);
+});
+sock.on("connect", () => {
+  sock.write(JSON.stringify({ dgc_sdk_bridge: 1, token }) + "\n");
+  process.stdin.pipe(sock);
+  sock.pipe(process.stdout);
+});
+sock.on("end", () => process.exit(0));
+sock.on("close", () => process.exit(0));