@vibedgc/sdk 0.6.4

package/dist/types.d.ts

@@ -0,0 +1,362 @@
+export declare const VERSION = "0.6.4";
+export declare const PROTOCOL = 14;
+export declare const REQUIRES_CLI = "0.43.4";
+export type PermissionMode = "default" | "acceptEdits" | "plan" | "auto";
+export type PermissionAction = "once" | "always" | "deny";
+export type PlanAction = "auto" | "acceptEdits" | "default" | "reject";
+export type UnhandledPolicy = "deny" | "callback";
+export type SandboxRequirement = "required" | "preferred" | "off";
+/** `sandbox` option: the bare requirement or `{ requirement }`. */
+export type SandboxSetting = SandboxRequirement | {
+    requirement?: SandboxRequirement;
+};
+/**
+ * Whether a session's shell commands run inside the OS sandbox (`session.sandbox`).
+ * `requirement` is what the session asked for (a sandboxed-shell RuntimePolicy asks for at least
+ * "preferred"), `active` whether the runtime confines shell commands, `backend` the confinement
+ * tool (`bwrap` or `sandbox-exec`), and `reason` why a "preferred" sandbox is off.
+ */
+export type SandboxStatus = {
+    requirement: SandboxRequirement;
+    active: boolean;
+    backend: string;
+    reason: string;
+};
+/** A run's state. (0.5.2 listed a "blocked" status that was never produced; see `denials`.) */
+export type RunStatus = "queued" | "running" | "waiting_for_approval" | "completed" | "cancelled" | "failed";
+export type PermissionRequest = {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+    summary?: string;
+    suggestedRule?: string;
+    callId?: string;
+    diff?: string;
+    command?: string;
+};
+export type PlanRequest = {
+    id: string;
+    plan: string;
+    choices: string[];
+};
+export type QuestionRequest = {
+    id: string;
+    questions: Array<{
+        id: string;
+        question: string;
+        header?: string;
+        multiSelect?: boolean;
+        options: Array<{
+            label: string;
+            description?: string;
+            recommended?: boolean;
+        }>;
+    }>;
+    callId?: string;
+};
+export type QuestionAnswers = Record<string, {
+    selected: number[];
+    other?: string;
+}>;
+export type McpInputRequest = {
+    id: string;
+    server: string;
+    kind: string;
+    payload: Record<string, unknown>;
+};
+export type McpInputResponse = {
+    action: "accept" | "decline" | "cancel";
+    content?: Record<string, unknown>;
+};
+export type Goal = {
+    text: string;
+    status: "none" | "active" | "paused" | "completed" | "blocked";
+    elapsedSeconds?: number;
+};
+export type HookInfo = {
+    event: string;
+    configured: number;
+    matchers?: string[];
+    valid?: boolean;
+};
+export type Monitor = {
+    id: string;
+    description?: string;
+    command?: string;
+    state?: string;
+};
+export type PermissionRule = {
+    action: string;
+    rule: string;
+};
+export type McpServerInfo = {
+    name: string;
+    state: string;
+    enabled?: boolean;
+    toolCount?: number;
+    error?: string;
+};
+export type SkillInfo = {
+    name: string;
+    description: string;
+    source: string;
+    enabled: boolean;
+};
+export type AgentInfo = {
+    id: string;
+    state: string;
+    description?: string;
+    parentId?: string | null;
+};
+export type VerificationResult = {
+    ok: boolean | null;
+    command: string;
+    output?: string;
+    exitCode?: number | null;
+};
+export type Artifact = {
+    id: string;
+    name: string;
+    url: string;
+    rel?: string;
+};
+export type ToolRecord = {
+    name: string;
+    callId: string;
+    summary?: string;
+    output?: string;
+    isError?: boolean;
+    isDiff?: boolean;
+    diff?: string;
+    args?: Record<string, unknown>;
+};
+/**
+ * One tool call the run refused (`RunResult.denials`). `source` is a best-effort category of who
+ * refused it: "policy" (a RuntimePolicy or a deny rule), "callback" (your onPermission said deny,
+ * or none answered), "hook" (a PreToolUse hook), "mode" (plan mode, or a turn with nobody to
+ * approve), or "runtime" when it cannot be told apart.
+ */
+export type Denial = {
+    name: string;
+    reason: string;
+    source: "policy" | "callback" | "hook" | "mode" | "runtime";
+    callId: string;
+    args: Record<string, unknown>;
+};
+/**
+ * One file the run changed under the session cwd. `before`/`after` hold the text (up to 1 MB; ""
+ * for binary files or the missing side) and `diff` is a `git apply`-able unified diff ("" when
+ * either side is not text).
+ */
+export type FileChange = {
+    path: string;
+    kind: "added" | "modified" | "deleted";
+    before: string;
+    after: string;
+    root: string;
+    diff: string;
+};
+export type SessionInfo = {
+    id: string;
+    path: string;
+    name?: string;
+    preview?: string;
+    messageCount?: number;
+    when?: string;
+};
+export type Checkpoint = {
+    index: number;
+    preview: string;
+    files: number;
+};
+export type RunEvent = {
+    type: string;
+    data: Record<string, unknown>;
+    runId: string;
+    sessionId: string;
+    /** The prompt, steer or repair this event belongs to, when DGC said. */
+    requestId?: string;
+};
+export type TaskItem = {
+    id: string;
+    content: string;
+    status: "pending" | "in_progress" | "completed" | "blocked" | "cancelled";
+    revision?: number;
+};
+export type RunResult = {
+    sessionId: string;
+    runId: string;
+    status: RunStatus;
+    reason: string;
+    finalText: string;
+    partialText?: string;
+    output?: unknown;
+    /**
+     * Provider token usage for this run's turns (`input_tokens`, `output_tokens`,
+     * `cached_input_tokens`, `reasoning_tokens`, `requests`; `null` when the provider did not
+     * report them, never a guessed 0), `cost_usd` (null without pricing or known tokens),
+     * `usage_known`, `model`, `department`, and DGC's `token_estimate` / `context_used` /
+     * `context_size` (context-window estimates, not billed tokens).
+     */
+    usage: Record<string, unknown>;
+    tools: ToolRecord[];
+    /** Tool calls the run refused (a denied step does not fail the run; the agent is told). */
+    denials?: Denial[];
+    artifacts: Artifact[];
+    documents: Artifact[];
+    /** Files the run added, modified or deleted under the session cwd. */
+    changes?: FileChange[];
+    tasks?: TaskItem[];
+    agents?: AgentInfo[];
+    /**
+     * Evidence about the configured `verifyCommand` (never about an unrelated command); undefined
+     * when none is configured, `ok: null` when nothing shows whether it passed.
+     */
+    verification?: VerificationResult;
+    error?: string;
+};
+export type SessionOptions = {
+    cwd: string;
+    permissions?: {
+        mode?: PermissionMode;
+        unhandled?: UnhandledPolicy;
+    };
+    onPermission?: (request: PermissionRequest) => PermissionAction | Promise<PermissionAction>;
+    onPlan?: (request: PlanRequest) => PlanAction | Promise<PlanAction>;
+    onQuestion?: (request: QuestionRequest) => QuestionAnswers | "dismiss" | Promise<QuestionAnswers | "dismiss">;
+    onMcpInput?: (request: McpInputRequest) => McpInputResponse | Promise<McpInputResponse>;
+    model?: string;
+    baseUrl?: string;
+    apiKey?: string;
+    mode?: PermissionMode;
+    thinking?: string;
+    instructions?: string;
+    /** Cap on tool iterations for every run of this session (this session only). */
+    maxTurns?: number;
+    /** DGC's per-turn time budget in seconds (this session only). */
+    turnBudgetS?: number;
+    /** Maximum output tokens per model reply (this session only). */
+    maxTokens?: number;
+    /**
+     * How long a decision callback (onPermission, onPlan, onQuestion, onMcpInput) may take.
+     * Default 30 000 ms; `null` waits as long as it takes. A cancel always wins.
+     */
+    decisionTimeoutMs?: number | null;
+    /** Command DGC runs before it may finish (verify-before-done), for this session only. */
+    verifyCommand?: string;
+    /** Overrides the client's `sandbox` for this session. */
+    sandbox?: SandboxSetting;
+    tools?: Array<{
+        name: string;
+        description: string;
+        inputSchema: Record<string, unknown>;
+        handler: (args: Record<string, unknown>) => unknown | Promise<unknown>;
+        timeoutMs?: number | null;
+    }>;
+};
+/**
+ * Limits an embedder puts on every session of a DGC client. DGC enforces them in every
+ * permission mode, `auto` included, on the runtime side (the policy travels to each session's
+ * `dgc serve` in its environment and is never saved to any config.json).
+ *
+ * - Tools: `denyTools` / `allowTools` take DGC tool names (`read_file`, `bash`, `web_fetch`, ...)
+ *   and MCP routes (`mcp__app__issue_refund` for a `defineTool` tool named `issue_refund`, or
+ *   `mcp__app__*`). An unknown name throws DGCConfigError. With `allowTools`, every other tool is
+ *   refused (the option picker `propose_options` stays unless denied).
+ * - Paths: DGC's file tools cannot reach outside the session's cwd, except to read inside
+ *   `extraReadDirs`, and cannot reach `denyPathPrefixes` at all (relative prefixes resolve
+ *   against the cwd).
+ * - Network: `network: "deny"` (the default) refuses web fetch, web search, the browser, skill
+ *   downloads, and MCP servers other than the application's own tools.
+ * - Shell: `shell: "sandboxed"` (default) turns the OS sandbox on for the session; in `auto` mode
+ *   the shell runs only there (without a sandbox `bash`/`monitor` are refused, `python` always
+ *   is), and in the other modes each shell command is a permission request for `onPermission`.
+ *   `shell: "screened"` runs the shell unconfined and, in auto mode, refuses commands whose text
+ *   looks like a network call or (with a write tool denied) a file write: best effort only.
+ * - `redactEvents` (default true) redacts secrets in audit rows.
+ */
+export type RuntimePolicy = {
+    network?: "deny" | "allow";
+    denyTools?: string[];
+    allowTools?: string[] | null;
+    extraReadDirs?: string[];
+    denyPathPrefixes?: string[];
+    redactEvents?: boolean;
+    shell?: "sandboxed" | "screened";
+};
+/** USD per 1 000 000 tokens. `cachedInputPerMillion` (0 = the input price) prices cached input. */
+export type Pricing = {
+    inputPerMillion?: number;
+    outputPerMillion?: number;
+    cachedInputPerMillion?: number;
+};
+export type ClientOptions = {
+    runtime?: string[];
+    /**
+     * Holds this client's isolated HOME, audit and usage logs. Must be private (owned by you, not
+     * group/world-writable); left unset, a fresh private temporary directory is used. A
+     * config.json already in it is never merged: every session writes its own from scratch.
+     */
+    stateDir?: string;
+    inheritUserState?: boolean;
+    model?: string;
+    baseUrl?: string;
+    apiKey?: string;
+    mode?: PermissionMode;
+    thinking?: string;
+    extraEnv?: Record<string, string>;
+    /** Host variables the runtime may see besides the basic ones: false (default), names, or true. */
+    inheritEnv?: boolean | string[];
+    instructions?: string;
+    department?: string;
+    pricing?: Pricing;
+    policy?: RuntimePolicy;
+    /** OS sandbox for shell commands: "required", "preferred" or "off" (default). */
+    sandbox?: SandboxSetting;
+    /** Extra DGC settings written into every isolated session's config (the explicit way to add them). */
+    extraConfig?: Record<string, unknown>;
+    /**
+     * Whether a session's workspace may grant itself capabilities: its own `.dgc/permissions.json`
+     * allow rules and its `.dgc/agents` definitions (which choose a model endpoint and a credential
+     * variable). Default false: the workspace can only narrow what runs. Set it when you trust the
+     * checkout as your own machine would.
+     */
+    trustWorkspace?: boolean;
+    /** Keep the temporary stateDir the SDK created (stateDir unset) instead of removing it on close(). */
+    keepStateDir?: boolean;
+    /** Bound on the runtime's startup handshake (default 30 000 ms). */
+    startTimeoutMs?: number;
+    /** Bound on each control request such as listSessions or setGoal (default 15 000 ms). */
+    requestTimeoutMs?: number;
+};
+/**
+ * What `signal` needs from an `AbortSignal` (a standard `AbortController().signal` fits). Declared
+ * here so the package's types do not depend on DOM or Node type libraries.
+ */
+export type AbortSignalLike = {
+    readonly aborted: boolean;
+    addEventListener(type: "abort", listener: () => void, options?: {
+        once?: boolean;
+    }): void;
+    removeEventListener(type: "abort", listener: () => void): void;
+};
+/** Environment variables, as `process.env` holds them. */
+export type Env = Record<string, string | undefined>;
+export type RunOptions = {
+    /**
+     * Limit for each turn of the run (default 180 000 ms; `null` means no limit). When it passes,
+     * the run is cancelled and its result is `status: "failed"`, `reason: "timeout"`.
+     */
+    timeoutMs?: number | null;
+    /** Aborting this signal cancels the run (result `status: "cancelled"`). */
+    signal?: AbortSignalLike;
+    maxTurns?: number;
+    outputSchema?: Record<string, unknown>;
+    repairAttempts?: number;
+    skills?: string[];
+    workflow?: string;
+};
+export type ResumeOptions = SessionOptions & {
+    sessionId?: string;
+    latest?: boolean;
+};

package/dist/types.js

@@ -0,0 +1,3 @@
+export const VERSION = "0.6.4";
+export const PROTOCOL = 14;
+export const REQUIRES_CLI = "0.43.4";

package/dist/usage.d.ts

@@ -0,0 +1,50 @@
+import type { Pricing } from "./types.ts";
+export declare const USAGE_TOTAL_KEYS: readonly ["input_tokens", "output_tokens", "cached_input_tokens", "reasoning_tokens", "requests"];
+export type UsageKey = typeof USAGE_TOTAL_KEYS[number];
+export type UsageTotals = Record<UsageKey, number>;
+export declare function emptyTotals(): UsageTotals;
+export declare function count(value: unknown): number | null;
+/**
+ * Cost of one usage record, or null without pricing or when the token counts are unknown.
+ * `inputTokens` counts every prompt token, cached ones included (as DGC reports them);
+ * `cachedInputTokens` is the part served from a cache, billed at the cached price.
+ */
+export declare function costUsd(inputTokens: number | null, outputTokens: number | null, cachedInputTokens: number | null, pricing: Pricing | undefined): number | null;
+/** The cumulative session totals a `context` event carries, or null if it has none. */
+export declare function usageTotals(event: Record<string, unknown>): UsageTotals | null;
+/** What one turn added, or null when the totals were reset (a new or resumed session). */
+export declare function usageDelta(before: UsageTotals, after: UsageTotals): UsageTotals | null;
+/** False when requests were made but the provider reported no token usage for them. */
+export declare function reported(delta: UsageTotals): boolean;
+export type UsageReport = {
+    runs: number;
+    /** Runs whose provider did not report tokens; their tokens and cost are left out of the sums. */
+    unknownUsageRuns: number;
+    inputTokens: number;
+    outputTokens: number;
+    cachedInputTokens: number;
+    /** Sum over runs with a known cost, or null when none has one. */
+    costUsd: number | null;
+    byDepartment: Array<{
+        department: string;
+        runs: number;
+        unknownUsageRuns: number;
+        inputTokens: number;
+        outputTokens: number;
+        costUsd: number;
+    }>;
+    /** The last 500 rows as recorded (snake_case keys, the same JSONL the Python SDK writes). */
+    rows: Array<Record<string, unknown>>;
+};
+/** Append-only JSONL under the isolated stateDir. Queryable without dgc serve. */
+export declare class UsageLog {
+    readonly directory: string;
+    readonly path: string;
+    constructor(directory: string);
+    record(row: Record<string, unknown>): void;
+    query(options?: {
+        department?: string;
+        since?: number;
+        until?: number;
+    }): UsageReport;
+}

package/dist/usage.js

@@ -0,0 +1,149 @@
+/**
+ * Per-run usage records and cost. Prices are embedder-supplied; DGC does not invent tariffs.
+ * Mirrors sdk/python/dgc_sdk/usage.py.
+ *
+ * Token counts come from the provider usage DGC reports for the session (the `context` event's
+ * cumulative `input_tokens` / `output_tokens` / `cached_input_tokens` totals); a run records the
+ * change across its turns. When the provider reported nothing, the count is `null` (unknown),
+ * never 0. `token_estimate` is DGC's estimate of the conversation's context size, not billed
+ * tokens.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { appendPrivate, privateDir } from "./state.js";
+export const USAGE_TOTAL_KEYS = [
+    "input_tokens", "output_tokens", "cached_input_tokens", "reasoning_tokens", "requests",
+];
+export function emptyTotals() {
+    return { input_tokens: 0, output_tokens: 0, cached_input_tokens: 0, reasoning_tokens: 0, requests: 0 };
+}
+export function count(value) {
+    if (typeof value === "boolean" || value === null || value === undefined || value === "")
+        return null;
+    const number = Number(value);
+    if (!Number.isFinite(number))
+        return null;
+    const whole = Math.trunc(number);
+    return whole >= 0 ? whole : null;
+}
+/**
+ * Cost of one usage record, or null without pricing or when the token counts are unknown.
+ * `inputTokens` counts every prompt token, cached ones included (as DGC reports them);
+ * `cachedInputTokens` is the part served from a cache, billed at the cached price.
+ */
+export function costUsd(inputTokens, outputTokens, cachedInputTokens, pricing) {
+    if (!pricing || inputTokens === null || outputTokens === null)
+        return null;
+    const totalIn = Math.max(0, inputTokens);
+    const cached = Math.min(totalIn, Math.max(0, cachedInputTokens || 0));
+    const inputRate = Number(pricing.inputPerMillion || 0);
+    const cachedRate = Number(pricing.cachedInputPerMillion || 0) || inputRate;
+    const dollars = ((totalIn - cached) / 1_000_000) * inputRate
+        + (cached / 1_000_000) * cachedRate
+        + (Math.max(0, outputTokens) / 1_000_000) * Number(pricing.outputPerMillion || 0);
+    return Math.round(dollars * 1e8) / 1e8;
+}
+/** The cumulative session totals a `context` event carries, or null if it has none. */
+export function usageTotals(event) {
+    const totals = emptyTotals();
+    for (const key of USAGE_TOTAL_KEYS) {
+        const number = count(event[key]);
+        if (number === null) {
+            if (key === "input_tokens" || key === "output_tokens" || key === "requests")
+                return null;
+            continue;
+        }
+        totals[key] = number;
+    }
+    return totals;
+}
+/** What one turn added, or null when the totals were reset (a new or resumed session). */
+export function usageDelta(before, after) {
+    const delta = emptyTotals();
+    for (const key of USAGE_TOTAL_KEYS) {
+        delta[key] = (after[key] || 0) - (before[key] || 0);
+        if (delta[key] < 0)
+            return null;
+    }
+    return delta;
+}
+/** False when requests were made but the provider reported no token usage for them. */
+export function reported(delta) {
+    if ((delta.requests || 0) <= 0)
+        return true;
+    return Boolean(delta.input_tokens || delta.output_tokens);
+}
+function rowKnown(row) {
+    return count(row.input_tokens) !== null && count(row.output_tokens) !== null;
+}
+/** Append-only JSONL under the isolated stateDir. Queryable without dgc serve. */
+export class UsageLog {
+    directory;
+    path;
+    constructor(directory) {
+        this.directory = privateDir(directory);
+        this.path = join(this.directory, "usage.jsonl");
+    }
+    record(row) {
+        const payload = { ts: Date.now() / 1000, ...row };
+        appendPrivate(this.path, JSON.stringify(payload) + "\n");
+    }
+    query(options = {}) {
+        const rows = [];
+        if (existsSync(this.path)) {
+            for (const line of readFileSync(this.path, "utf8").split("\n")) {
+                if (!line.trim())
+                    continue;
+                let row;
+                try {
+                    row = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                if (!row || typeof row !== "object" || Array.isArray(row))
+                    continue;
+                const record = row;
+                if (options.department && String(record.department || "") !== options.department)
+                    continue;
+                const ts = Number(record.ts || 0);
+                if (options.since !== undefined && ts < options.since)
+                    continue;
+                if (options.until !== undefined && ts > options.until)
+                    continue;
+                rows.push(record);
+            }
+        }
+        const known = rows.filter(rowKnown);
+        const costs = known.map((row) => row.cost_usd).filter((value) => typeof value === "number");
+        const buckets = new Map();
+        for (const row of rows) {
+            const key = String(row.department || "");
+            let slot = buckets.get(key);
+            if (!slot) {
+                slot = { department: key, runs: 0, unknownUsageRuns: 0, inputTokens: 0, outputTokens: 0, costUsd: 0 };
+                buckets.set(key, slot);
+            }
+            slot.runs += 1;
+            if (!rowKnown(row)) {
+                slot.unknownUsageRuns += 1;
+                continue;
+            }
+            slot.inputTokens += count(row.input_tokens) || 0;
+            slot.outputTokens += count(row.output_tokens) || 0;
+            if (typeof row.cost_usd === "number")
+                slot.costUsd += row.cost_usd;
+        }
+        const sum = (key) => known.reduce((total, row) => total + (count(row[key]) || 0), 0);
+        return {
+            runs: rows.length,
+            unknownUsageRuns: rows.length - known.length,
+            inputTokens: sum("input_tokens"),
+            outputTokens: sum("output_tokens"),
+            cachedInputTokens: sum("cached_input_tokens"),
+            costUsd: costs.length ? Math.round(costs.reduce((a, b) => a + b, 0) * 1e8) / 1e8 : null,
+            byDepartment: [...buckets.values()],
+            rows: rows.slice(-500),
+        };
+    }
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@vibedgc/sdk",
+  "version": "0.6.4",
+  "description": "Embed the DGC coding harness in applications and CI",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepack": "node scripts/build.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.3",
+    "typescript": "5.9.3"
+  },
+  "keywords": ["dgc", "agent", "sdk", "coding-agent"],
+  "homepage": "https://vibedgc.com/sdk/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OpenPeach-ai/dgc.git",
+    "directory": "sdk/typescript"
+  },
+  "bugs": "https://github.com/OpenPeach-ai/dgc/issues",
+  "license": "Apache-2.0"
+}