@chrok/dsh-braid 0.0.0-stage → 0.3.2

package/dist/schema.js

@@ -0,0 +1,93 @@
+import { Type } from "@sinclair/typebox";
+const StringEnum = (values, options = {}) => Type.Union(values.map(value => Type.Literal(value)), options);
+const text = (description) => Type.String({ minLength: 1, pattern: "\\S", ...(description ? { description } : {}) });
+const prompt = () => Type.Union([
+    text("Instructions for this node; it does not receive the parent conversation."),
+    Type.Object({
+        template: text("Exact key in promptTemplates."),
+        variables: Type.Record(Type.String(), Type.String(), {
+            description: "Exactly the template's placeholder names with string values; use {} if there are no placeholders. No missing or extra keys.",
+        }),
+    }, { additionalProperties: false }),
+], { description: "Required for execute/decision; optional for merge/integrate. A non-blank instruction string or a reference to a declared prompt template." });
+const timeout = (scope) => Type.Optional(Type.Number({
+    exclusiveMinimum: 0,
+    maximum: 2_147_483_647,
+    description: scope === "graph"
+        ? "Total wall-clock timeout in milliseconds, including queueing and pauses. Updates/resume do not reset it; reserve time for final integration. Omit for no time limit."
+        : "Timeout in milliseconds per node execution; omit for no time limit.",
+}));
+const toolBudget = (unit) => Type.Optional(Type.Integer({
+    minimum: 1,
+    maximum: Number.MAX_SAFE_INTEGER,
+    description: `Maximum tool ${unit} per node, including decide and rejected requests; omit for no limit`,
+}));
+const commonNodeParameters = {
+    id: text("Unique node definition ID; edges refer to this exact ID. This is not an executionId."),
+    model: Type.Optional(text("Model override as provider/model-id; omit to use the parent model.")),
+    notifyOnCompletion: Type.Optional(Type.Boolean({ description: "Send an execution completion reminder; default false. Does not pause scheduling." })),
+    pauseAfter: Type.Optional(Type.Boolean({ description: "Hold this execution's outgoing dependencies until braid_resume or an atomic braid_update with resume. Sends a pause reminder." })),
+    requireSuccess: Type.Optional(Type.Boolean({ description: "If true, failure aborts the entire job and cancels running siblings. Default false: unconditional successors can recover." })),
+};
+const workspace = Type.Optional(StringEnum(["read-only", "worktree"], {
+    description: "Only for execute/decision; omit for merge/integrate. Defaults to worktree in Git. Both modes use fresh predecessor snapshots; read-only disables writes and shell tools. Outside Git, all workers are read-only.",
+}));
+// Keep all fields visible in one object. Kimi sessions using object-variant
+// unions repeatedly emitted bare merge nodes instead of intended executions.
+// Core validates the conditional requirements before starting or changing a job.
+export const nodeParameters = Type.Object({
+    id: commonNodeParameters.id,
+    type: StringEnum(["execute", "decision", "merge", "integrate"], {
+        description: "execute: analyze/implement; decision: choose a route; merge: combine predecessor checkpoints in an isolated worktree; integrate: apply predecessor changes to the invoking checkout.",
+    }),
+    prompt: Type.Optional(prompt()),
+    choices: Type.Optional(Type.Array(text(), { minItems: 1, uniqueItems: true, description: "Required only for decision; omit for every other type. Distinct routing labels used by decide and outgoing choice edges." })),
+    workspace,
+    model: commonNodeParameters.model,
+    notifyOnCompletion: commonNodeParameters.notifyOnCompletion,
+    pauseAfter: commonNodeParameters.pauseAfter,
+    requireSuccess: commonNodeParameters.requireSuccess,
+}, { additionalProperties: false, description: "execute/decision REQUIRE prompt; decision also REQUIRES choices. merge/integrate may omit prompt but MUST omit choices and workspace. Omit unused optional fields. All types accept model, notifyOnCompletion, pauseAfter, and requireSuccess." });
+const edgeFields = {
+    from: text("Source node ID."),
+    to: text("Target node ID."),
+    choice: Type.Optional(text("Only for a decision source: one exact declared choice. Omit for an unconditional dependency, including error recovery.")),
+    feedback: Type.Optional(text("Loop ID, only on the single back edge from its decision to its entry. Requires choice and a matching loops definition; not a boolean. Cannot be combined with executionId.")),
+};
+const edgeParameters = Type.Object(edgeFields, { additionalProperties: false });
+export const updateEdgeParameters = Type.Object({
+    ...edgeFields,
+    executionId: Type.Optional(text("Pin a completed historical source execution from braid_status; from must match that execution's node ID. Available only in braid_update, never in the initial graph.")),
+}, { additionalProperties: false });
+export const loopParameters = Type.Object({
+    id: text("Unique loop ID referenced by exactly one edge.feedback."),
+    entry: text("Node ID where every iteration starts; the feedback edge must target this node."),
+    maxIterations: Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER, description: "Total rounds including the first, not the number of retries. Choosing feedback on the last round fails with LOOP_LIMIT." }),
+}, { additionalProperties: false, description: "A bounded loop with one entry and a decision that selects retry or exit. The body is acyclic after removing the feedback edge; external edges enter only at entry and leave only from that decision. Loops cannot overlap or nest." });
+const templateDescription = "Named prompt strings. Placeholders use {{name}} with names matching [A-Za-z_][A-Za-z0-9_]*. Node variables must match exactly; string values are inserted literally.";
+const templates = Type.Record(Type.String(), text(), { description: templateDescription });
+export const braidParameters = Type.Object({
+    goal: text("Shared goal included in every worker's context."),
+    nodes: Type.Array(nodeParameters, { minItems: 1 }),
+    edges: Type.Array(edgeParameters, { description: "Dependencies between node IDs; use [] for independent roots. Cycles require a declared loop and explicit feedback edge. Historical executionId is not allowed at submission." }),
+    promptTemplates: Type.Optional(templates), loops: Type.Optional(Type.Array(loopParameters)),
+    options: Type.Optional(Type.Object({
+        maxConcurrency: Type.Optional(Type.Integer({ minimum: 1, description: "Maximum simultaneous node executions; default 4." })),
+        maxExecutions: Type.Optional(Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER, description: "Total execution limit across all iterations and updates; default 1000." })),
+        nodeTimeoutMs: timeout("node"), graphTimeoutMs: timeout("graph"), maxToolRounds: toolBudget("rounds"), maxToolCalls: toolBudget("calls"),
+    }, { additionalProperties: false })),
+}, { additionalProperties: false });
+const BRAID_FILESYSTEM_GUIDANCE = "Every execute/decision activation gets a fresh worktree in Git, based on its predecessor execution checkpoint (roots use the initial job snapshot). Set workspace=read-only to disable writes. Multiple independent code snapshots require an explicit merge node. " +
+    "merge combines selected predecessor checkpoints into a new isolated worktree; integrate writes selected changes to the invoking checkout while preserving user edits. Workers apply changes with Git/file tools, then call finish_merge using executionId for each source; finish_merge only records dispositions and does not apply changes. There is no automatic final integration. " +
+    "Do not set workspace on merge/integrate nodes. Checkpoints remain recoverable after cleanup. Optional failed predecessors pass errors and partial work along unconditional edges; requireSuccess=true makes failure abort the job. " +
+    "Nodes have local read/ls/grep/find and Git inspection; writable nodes have write/edit and shell tools for dependencies, builds, and tests, while merge/integrate also have local Git integration tools. Search tools require local rg. Outside Git all filesystem access is read-only; read-only nodes have no shell. Worktrees are not an OS sandbox: prompts constrain shell writes and shared resources. Checkpoints omit ignored new files. Parent extension/MCP tools and recursive Braid calls are not provided. Nodes should verify their changes; the parent reviews results and performs any remaining validation after integration.";
+export const BRAID_USAGE_GUIDANCE = [
+    "Braid is a proactive execution primitive, not only a user-requested command.",
+    "Selection rule: for a code review, bug investigation, design comparison, test-planning request, or change spanning multiple files, call braid FIRST when two or more concerns can be handled independently. Nodes can analyze the project and implement changes in isolated Git worktrees. Do this without waiting for the user to say Braid; do not read everything in the parent and then decide whether to delegate.",
+    BRAID_FILESYSTEM_GUIDANCE,
+    "For repeated instructions, define promptTemplates once and use prompt={template: name, variables: {name: value}} on nodes. Values are strings inserted literally into {{name}} placeholders; plain-string prompts remain supported.",
+    "When Braid fits, submit a graph: use parallel execute nodes for independent analysis or implementation, execute nodes to synthesize findings, merge nodes to combine code snapshots, and integrate nodes to apply changes to the working branch. The tool returns a jobId immediately. Continue independent work or finish your turn while it runs; do not poll repeatedly. A completion reminder will resume you. Use braid_status with the jobId to retrieve terminal outputs before relying on them.",
+    "Set notifyOnCompletion=true on selected nodes to receive intermediate success/failure reminders. Use braid_status({jobId, executionId}) to retrieve the exact execution; nodeId selects the latest instance. Use pauseAfter=true to hold outgoing scheduling. Definitions can always be changed with braid_update using expectedRevision; existing executions retain their captured inputs. Use resume in the same update to apply changes and release held executions atomically, or braid_resume for no graph changes.",
+    "Make the delegation choice once per user request. Reminders and definition errors are not new tasks. Check the accepted node types and settings in the tool response. If the same definition problem recurs, stop resubmitting and report the concrete mismatch; do not launch repeated probe/replacement jobs. In braid_update, add new nodes together with their dependencies and loops: a node added without incoming edges can start immediately, even while another execution is paused.",
+    "Do not use braid for a simple one-step answer, a trivial direct edit, a single shell command, or when decomposition adds no value. Writable nodes can implement and test their work. The parent reviews results and performs any remaining validation after Braid completes.",
+].join("\n");

package/dist/shell-tools.d.ts

@@ -0,0 +1,2 @@
+/** Own the entire process group through completion, cancellation, and timeout. */
+export declare function runCommand(shell: string, args: string[], cwd: string, signal: AbortSignal, timeout?: number): Promise<string>;

package/dist/shell-tools.js

@@ -0,0 +1,90 @@
+import { execFile, spawn } from "node:child_process";
+import { constants } from "node:os";
+import { join } from "node:path";
+/** Own the entire process group through completion, cancellation, and timeout. */
+export async function runCommand(shell, args, cwd, signal, timeout) {
+    let output = "";
+    const onData = (data) => { output = (output + data.toString()).slice(-50_000); };
+    signal?.throwIfAborted();
+    if (timeout !== undefined && (!Number.isFinite(timeout) || timeout <= 0 || timeout * 1000 > 2_147_483_647))
+        throw new Error("Invalid timeout: expected positive seconds within the timer limit");
+    const child = spawn(shell, args, {
+        cwd, detached: process.platform !== "win32", windowsHide: true,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    const closed = new Promise(resolve => child.once("close", () => resolve()));
+    const exited = new Promise((resolve, reject) => {
+        child.once("error", reject);
+        child.once("exit", resolve);
+    });
+    child.stdout.on("data", onData);
+    child.stderr.on("data", onData);
+    let termination;
+    const terminate = () => termination ??= (async () => {
+        if (!child.pid)
+            return;
+        if (process.platform === "win32") {
+            await new Promise((resolve, reject) => {
+                execFile(join(process.env.SystemRoot ?? "C:\\Windows", "System32", "taskkill.exe"), ["/F", "/T", "/PID", String(child.pid)], { windowsHide: true }, error => {
+                    // taskkill reports 128 when the process has already exited.
+                    if (error && error.code !== 128)
+                        reject(error);
+                    else
+                        resolve();
+                });
+            });
+        }
+        else {
+            try {
+                process.kill(-child.pid, "SIGKILL");
+            }
+            catch (error) {
+                if (error.code !== "ESRCH")
+                    throw error;
+            }
+        }
+    })();
+    // The completion path awaits termination; event handlers must not create
+    // unhandled rejections while the shell is still exiting.
+    const stop = () => { void terminate().catch(() => { }); };
+    let timedOut = false;
+    const timer = timeout === undefined ? undefined : setTimeout(() => {
+        timedOut = true;
+        stop();
+    }, timeout * 1000);
+    signal?.addEventListener("abort", stop, { once: true });
+    if (signal?.aborted)
+        stop();
+    let exitCode;
+    try {
+        exitCode = await exited;
+    }
+    finally {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", stop);
+        // Stop leftover children even on successful command completion. Commands
+        // cannot leave a server/watch process writing during checkpoint/cleanup.
+        try {
+            await terminate();
+        }
+        finally {
+            // A daemon can leave the process group while holding inherited pipes.
+            // Bound pipe draining; this process-group cleanup is not an OS sandbox.
+            const drainTimer = setTimeout(() => {
+                child.stdout.destroy();
+                child.stderr.destroy();
+            }, 250);
+            try {
+                await closed;
+            }
+            finally {
+                clearTimeout(drainTimer);
+            }
+        }
+    }
+    if (signal?.aborted)
+        throw new Error("aborted");
+    if (timedOut)
+        throw new Error(`timeout:${timeout}`);
+    return JSON.stringify({ output, exitCode: exitCode ?? (child.signalCode ? 128 + (constants.signals[child.signalCode] ?? 0) : 1) });
+}

package/dist/tools.d.ts

@@ -0,0 +1,46 @@
+import type { ToolDefinition, ToolRunContext } from "@deepseek-ai/dsh-tools";
+import type { BraidJobs, JobSnapshot } from "./jobs.js";
+export declare function graphReceipt(job: JobSnapshot): {
+    nodes: ({
+        model?: string;
+        type: "execute";
+        id: string;
+        notifyOnCompletion?: boolean;
+        requireSuccess?: boolean;
+        pauseAfter?: boolean;
+        workspace?: "read-only" | "worktree";
+    } | {
+        model?: string;
+        type: "decision";
+        id: string;
+        notifyOnCompletion?: boolean;
+        requireSuccess?: boolean;
+        pauseAfter?: boolean;
+        workspace?: "read-only" | "worktree";
+        choices: readonly string[];
+    } | {
+        model?: string;
+        type: "merge";
+        id: string;
+        notifyOnCompletion?: boolean;
+        requireSuccess?: boolean;
+        pauseAfter?: boolean;
+    } | {
+        model?: string;
+        type: "integrate";
+        id: string;
+        notifyOnCompletion?: boolean;
+        requireSuccess?: boolean;
+        pauseAfter?: boolean;
+    })[];
+    edges: readonly import("@chrok/braid").Edge[];
+    loops: readonly import("@chrok/braid").LoopDefinition[];
+};
+/** Keep the canonical value lossless; save large responses before returning a bounded preview. */
+export declare function boundedResult(value: object): Promise<object>;
+export declare function createBraidTools(getJobs: (context: ToolRunContext) => BraidJobs, submit: (args: {
+    goal: string;
+    nodes: unknown[];
+    edges: unknown[];
+    options?: object;
+}, context: ToolRunContext) => object): ToolDefinition[];

package/dist/tools.js

@@ -0,0 +1,86 @@
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Type } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import { braidParameters, nodeParameters, updateEdgeParameters, loopParameters } from "./schema.js";
+const id = Type.String({ minLength: 1, pattern: "\\S" });
+const revision = Type.Integer({ minimum: 0 });
+export function graphReceipt(job) {
+    return {
+        nodes: job.execution.graph.nodes.map(({ prompt: _prompt, ...node }) => node),
+        edges: job.execution.graph.edges, loops: job.execution.graph.loops ?? [],
+    };
+}
+/** Keep the canonical value lossless; save large responses before returning a bounded preview. */
+export async function boundedResult(value) {
+    const full = JSON.stringify(value, null, 2);
+    if (Buffer.byteLength(full) <= 50_000)
+        return JSON.parse(full);
+    const directory = await mkdtemp(join(tmpdir(), "braid-dsh-result-"));
+    const fullOutputPath = join(directory, "result.json");
+    await writeFile(fullOutputPath, full, { mode: 0o600 });
+    const control = value;
+    return JSON.parse(JSON.stringify({ jobId: control.jobId, canonicalJobId: control.canonicalJobId, handle: control.handle, status: control.status,
+        execution: control.execution && { status: control.execution.status, revision: control.execution.revision, pausedExecutionIds: control.execution.pausedExecutionIds },
+        usage: control.usage, fullOutputPath, truncated: true, preview: full.slice(0, 10_000) }));
+}
+export function createBraidTools(getJobs, submit) {
+    function tool(name, description, parameters, execute) {
+        // TypeBox's symbol metadata is local validation state, not lossless wire JSON.
+        return { name, description, parameters: JSON.parse(JSON.stringify(parameters)),
+            output: { schema: { type: "object", additionalProperties: true }, render: (_args, value) => [{ type: "text", text: JSON.stringify(value) }] },
+            async execute(args, context) {
+                context.signal.throwIfAborted();
+                if (!Value.Check(parameters, args))
+                    throw new Error(`Invalid ${name} arguments: ${[...Value.Errors(parameters, args)].map(error => `${error.path} ${error.message}`).join("; ")}`);
+                return boundedResult(await execute(args, context));
+            }, };
+    }
+    return [
+        tool("braid", "Start a background Braid graph before nontrivial engineering work with independent concerns. Returns jobId immediately. Supports execute/decision/merge/integrate, promptTemplates, bounded loops, worktree isolation, pauseAfter and notifyOnCompletion. Omit workspace on merge/integrate. No automatic integration. Continue independent work; retrieve results after the completion reminder instead of polling.", braidParameters, submit),
+        tool("braid_status", "Retrieve progress and results by exact jobId handle or UUID. Omit all IDs to list this agent's jobs. executionId selects an exact invocation; nodeId selects its latest invocation. Control fields contain the CURRENT revision and paused IDs. Large results provide a fullOutputPath. usage includes completed provider rounds from failed workers and cache tokens; reads do not add charges.", Type.Object({
+            jobId: Type.Optional(id), nodeId: Type.Optional(id), executionId: Type.Optional(id),
+        }, { additionalProperties: false }), (args, context) => {
+            const jobs = getJobs(context);
+            if (!args.jobId) {
+                if (args.nodeId || args.executionId)
+                    throw new Error("nodeId/executionId requires jobId");
+                return { jobs: jobs.list() };
+            }
+            const job = jobs.get(args.jobId);
+            return args.nodeId || args.executionId ? {
+                jobId: job.jobId, handle: job.handle, status: job.status,
+                execution: { status: job.execution.status, revision: job.execution.revision, pausedExecutionIds: job.execution.pausedExecutionIds },
+                node: jobs.getNode(args.jobId, args.nodeId, args.executionId),
+            } : job;
+        }),
+        tool("braid_cancel", "Cancel a background job. Foreground cancellation does not stop Braid jobs.", Type.Object({ jobId: id }, { additionalProperties: false }), (args, context) => {
+            const jobs = getJobs(context), job = jobs.get(args.jobId);
+            return { jobId: job.handle, canonicalJobId: job.jobId, cancelled: jobs.cancel(args.jobId) };
+        }),
+        tool("braid_update", "Atomically edit live definitions and optionally resume paused executions at expectedRevision. Upserts replace complete definitions. Include new nodes and all dependencies/loops in the SAME update: disconnected roots may start immediately. removeEdges matches exact identities, not wildcards. Rejected patches have no effects; retry the complete corrected patch. Finalized jobs cannot be reopened.", Type.Object({
+            jobId: id, expectedRevision: revision,
+            upsertNodes: Type.Optional(Type.Array(nodeParameters)), removeNodeIds: Type.Optional(Type.Array(id)),
+            addEdges: Type.Optional(Type.Array(updateEdgeParameters)), removeEdges: Type.Optional(Type.Array(updateEdgeParameters)),
+            promptTemplates: Type.Optional(Type.Record(Type.String(), id)), loops: Type.Optional(Type.Array(loopParameters)),
+            resume: Type.Optional(Type.Array(id, { uniqueItems: true })),
+        }, { additionalProperties: false }), (args, context) => {
+            const { jobId, ...patch } = args;
+            let job;
+            try {
+                job = getJobs(context).update(jobId, patch);
+            }
+            catch (error) {
+                throw new Error(`Braid update rejected; no changes or resumes applied. ${error instanceof Error ? error.message : String(error)}. Retry the complete corrected patch with dependencies, loops, and resume IDs.`);
+            }
+            return { jobId: job.handle, canonicalJobId: job.jobId, revision: job.execution.revision, pausedExecutionIds: job.execution.pausedExecutionIds, graph: graphReceipt(job) };
+        }),
+        tool("braid_resume", "Release selected paused execution IDs at expectedRevision. This does not reset budgets or deadlines.", Type.Object({
+            jobId: id, expectedRevision: revision, executionIds: Type.Array(id, { minItems: 1, uniqueItems: true }),
+        }, { additionalProperties: false }), (args, context) => {
+            const job = getJobs(context).resume(args.jobId, args.executionIds, args.expectedRevision);
+            return { jobId: job.handle, canonicalJobId: job.jobId, revision: job.execution.revision, pausedExecutionIds: job.execution.pausedExecutionIds };
+        }),
+    ];
+}

package/dist/worker-tools.d.ts

@@ -0,0 +1,9 @@
+import type { ModelRequest, NodeWorkspace } from "@chrok/braid";
+export interface WorkerTool {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    writes: boolean;
+    execute(args: unknown): Promise<string>;
+}
+export declare function createWorkerTools(request: ModelRequest, workspace: NodeWorkspace): Promise<WorkerTool[]>;

package/dist/worker-tools.js

@@ -0,0 +1,81 @@
+import { readdir, open } from "node:fs/promises";
+import { constants } from "node:fs";
+import { resolve } from "node:path";
+import { execFileSync } from "node:child_process";
+import { Type } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import { createWriteOperations } from "./write-tools.js";
+import { runCommand } from "./shell-tools.js";
+export async function createWorkerTools(request, workspace) {
+    const cwd = workspace.workingDirectory, signal = request.signal;
+    const tools = [];
+    function add(name, description, parameters, writes, execute) {
+        tools.push({ name, description, parameters, writes, async execute(args) {
+                signal.throwIfAborted();
+                if (!Value.Check(parameters, args))
+                    throw new Error(`Invalid ${name} arguments: ${[...Value.Errors(parameters, args)].map(error => `${error.path} ${error.message}`).join("; ")}`);
+                const result = await execute(args);
+                signal.throwIfAborted();
+                return result;
+            } });
+    }
+    const path = Type.String({ minLength: 1 });
+    add("read", "Read a UTF-8 file, with optional byte offset. Returns at most 50 KB; use the next offset for more.", Type.Object({
+        path, offset: Type.Optional(Type.Integer({ minimum: 0 })),
+    }, { additionalProperties: false }), false, async (args) => {
+        // Do not block opening a FIFO before the regular-file check can reject it.
+        const file = await open(resolve(cwd, args.path), constants.O_RDONLY | constants.O_NONBLOCK);
+        try {
+            if (!(await file.stat()).isFile())
+                throw new Error("read requires a regular file");
+            const buffer = Buffer.alloc(50_000);
+            const { bytesRead } = await file.read(buffer, 0, buffer.length, args.offset ?? 0);
+            // Leave incomplete UTF-8 characters for the next window instead of corrupting them.
+            const text = new TextDecoder().decode(buffer.subarray(0, bytesRead), { stream: bytesRead === buffer.length });
+            const consumed = bytesRead === buffer.length ? Math.min(bytesRead, Buffer.byteLength(text)) : bytesRead;
+            return JSON.stringify({ text, nextOffset: (args.offset ?? 0) + consumed, eof: bytesRead < buffer.length });
+        }
+        finally {
+            await file.close();
+        }
+    });
+    add("ls", "List a directory (up to 1000 entries).", Type.Object({ path: Type.Optional(path) }, { additionalProperties: false }), false, async (args) => {
+        const entries = await readdir(resolve(cwd, args.path ?? "."), { withFileTypes: true });
+        return JSON.stringify({ entries: entries.slice(0, 1000).map(entry => entry.name + (entry.isDirectory() ? "/" : "")), truncated: entries.length > 1000 });
+    });
+    // Search is exposed only when rg is installed. No automatic downloads.
+    try {
+        execFileSync("rg", ["--version"], { stdio: "ignore", timeout: 2000 });
+        add("grep", "Search file content using ripgrep. Output is bounded to the last 50 KB.", Type.Object({ pattern: Type.String(), path: Type.Optional(path) }, { additionalProperties: false }), false, args => runCommand("rg", ["--no-config", "-n", "--", args.pattern, args.path ?? "."], cwd, signal));
+        add("find", "Find file paths by glob using ripgrep; respects ignore rules. Output is bounded to the last 50 KB.", Type.Object({ pattern: path }, { additionalProperties: false }), false, args => runCommand("rg", ["--no-config", "--files", "--glob", args.pattern], cwd, signal));
+    }
+    catch { /* ls and read remain available without rg. */ }
+    const root = workspace.mode === "read-only" ? undefined : workspace.mode === "integrate" ? workspace.sourceRoot : workspace.worktreeRoot;
+    if (root) {
+        const writes = await createWriteOperations(cwd, root, signal, async () => {
+            if (!request.git)
+                return [];
+            const result = await request.git(["ls-files", "--stage", "-z"]);
+            if (result.exitCode !== 0)
+                throw new Error("Cannot validate submodule write boundaries");
+            return result.stdout.split("\0").filter(entry => entry.startsWith("160000 ")).map(entry => entry.slice(entry.indexOf("\t") + 1));
+        });
+        add("write", "Write a UTF-8 file inside the assigned workspace; create parent directories as needed.", Type.Object({ path, content: Type.String() }, { additionalProperties: false }), true, async (args) => {
+            await writes.write(args.path, args.content);
+            return "File written.";
+        });
+        add("edit", "Replace exactly one occurrence of oldText with newText in a workspace file.", Type.Object({ path, oldText: Type.String({ minLength: 1 }), newText: Type.String() }, { additionalProperties: false }), true, async (args) => {
+            const content = await writes.read(args.path);
+            const first = content.indexOf(args.oldText);
+            if (first < 0 || content.indexOf(args.oldText, first + 1) >= 0)
+                throw new Error("oldText must match exactly once");
+            await writes.write(args.path, content.slice(0, first) + args.newText + content.slice(first + args.oldText.length));
+            return "File edited.";
+        });
+        const shellParameters = Type.Object({ command: path, timeout: Type.Optional(Type.Number({ exclusiveMinimum: 0, maximum: 2_147_483.647 })) }, { additionalProperties: false });
+        add("bash", "Run a foreground shell command in the assigned workspace. timeout is seconds. Output retains the last 50 KB. Host permissions apply; do not daemonize.", shellParameters, true, args => runCommand("bash", ["-c", args.command], cwd, signal, args.timeout));
+        if (process.platform === "win32")
+            add("powershell", "Run a foreground PowerShell command in the assigned workspace. timeout is seconds.", shellParameters, true, args => runCommand("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", args.command], cwd, signal, args.timeout));
+    }
+    return tools;
+}

package/dist/write-tools.d.ts

@@ -0,0 +1,5 @@
+/** Enforce the write boundary in filesystem operations, not in model instructions. */
+export declare function createWriteOperations(cwd: string, root: string, signal: AbortSignal, readOnlyPaths?: () => Promise<string[]>): Promise<{
+    read: (path: string) => Promise<string>;
+    write: (path: string, content: string) => Promise<void>;
+}>;

package/dist/write-tools.js

@@ -0,0 +1,70 @@
+import { constants } from "node:fs";
+import { lstat, mkdir, open, readFile, realpath } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+/** Enforce the write boundary in filesystem operations, not in model instructions. */
+export async function createWriteOperations(cwd, root, signal, readOnlyPaths = async () => []) {
+    const boundary = await realpath(root);
+    const gitMetadata = await lstat(join(boundary, ".git"));
+    const checked = async (path) => {
+        signal.throwIfAborted();
+        const target = resolve(path);
+        // Callers can pass a lexical /tmp path while realpath uses /private/tmp on macOS.
+        const outside = (path) => path === ".." || path.startsWith(`..${sep}`) || isAbsolute(path);
+        let relativePath = relative(root, target);
+        if (outside(relativePath))
+            relativePath = relative(boundary, target);
+        if (outside(relativePath))
+            throw new Error("Writes are allowed only inside this node's worktree");
+        if ((await readOnlyPaths()).some(path => relativePath === path || relativePath.startsWith(`${path}${sep}`)))
+            throw new Error("Writing inside submodules is not supported");
+        const parts = relativePath.split(sep).filter(Boolean);
+        if (parts.some(part => part.toLowerCase() === ".git"))
+            throw new Error("Writing Git metadata is not allowed");
+        let current = boundary;
+        // Reject symlinks, including dangling links and linked parent directories.
+        for (const part of parts) {
+            current = join(current, part);
+            try {
+                const stat = await lstat(current);
+                // Also catch filesystem-specific aliases of .git (case/Unicode/streams).
+                if (stat.dev === gitMetadata.dev && stat.ino === gitMetadata.ino)
+                    throw new Error("Writing Git metadata is not allowed");
+                if (stat.isSymbolicLink())
+                    throw new Error("Writing through symlinks is not allowed");
+                if (!stat.isDirectory() && (!stat.isFile() || stat.nlink > 1))
+                    throw new Error("Writing special files or hard links is not allowed");
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+        }
+        signal.throwIfAborted();
+        return current;
+    };
+    const writeFile = async (path, content) => {
+        const target = await checked(path);
+        // O_NOFOLLOW prevents following a replaced final symlink. Nodes have no
+        // operations that create links or rename directories; workspaces are private.
+        const file = await open(target, constants.O_WRONLY | constants.O_CREAT | constants.O_NOFOLLOW, 0o644);
+        try {
+            const stat = await file.stat();
+            if (!stat.isFile() || stat.nlink > 1)
+                throw new Error("Writing special files or hard links is not allowed");
+            signal.throwIfAborted();
+            await file.truncate(0);
+            await file.writeFile(content, "utf8");
+        }
+        finally {
+            await file.close();
+        }
+    };
+    return {
+        read: async (path) => readFile(await checked(resolve(cwd, path)), "utf8"),
+        write: async (path, content) => {
+            const target = await checked(resolve(cwd, path));
+            await mkdir(await checked(resolve(target, "..")), { recursive: true });
+            await writeFile(target, content);
+        },
+    };
+}

package/package.json

@@ -1,6 +1,119 @@
 {
   "name": "@chrok/dsh-braid",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.2",
+  "license": "MIT",
+  "description": "DeepSeek Harness plugin for Braid: background agent graphs, bounded loops, live updates, and execution progress",
+  "type": "module",
+  "dependencies": {
+    "@chrok/braid": "0.3.2",
+    "@sinclair/typebox": "^0.34.41"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.4",
+    "@deepseek-ai/dsh-agent": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-commands": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-jobs": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-llm": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-typert-protocol": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-typert-registry": "0.2.0-rc.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "~4.0.4",
+    "@deepseek-ai/dsh-agent": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-api-gateway": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-chat": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-sidebar-right": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-tool": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-commands": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-jobs": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-jobs-local": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-llm": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-session": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-typert-protocol": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-typert-registry": "0.2.0-rc.2",
+    "@types/jsdom": "21.1.7",
+    "@types/node": "^22.0.0",
+    "@types/react": "18.3.28",
+    "@types/react-dom": "18.3.7",
+    "esbuild": "0.28.2",
+    "jsdom": "26.1.0",
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "scripts": {
+    "check": "tsc --noEmit && tsc -p tsconfig.client.json --noEmit",
+    "test": "node build-client.mjs && tsx --tsconfig tsconfig.json --test test/*.test.ts test/*.test.mjs test/client/*.test.tsx",
+    "build": "node ../../scripts/build.mjs dsh",
+    "prepack": "npm run build"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Epsirom/braid.git",
+    "directory": "integrations/dsh"
+  },
+  "homepage": "https://github.com/Epsirom/braid/tree/main/integrations/dsh#readme",
+  "bugs": {
+    "url": "https://github.com/Epsirom/braid/issues"
+  },
+  "keywords": [
+    "dsh-plugin",
+    "llm",
+    "ai-agents",
+    "agents",
+    "agent-orchestration",
+    "graph",
+    "bounded-loops",
+    "git-worktree",
+    "typescript"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "cordis.patch.yml"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json",
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-api-gateway",
+        "@deepseek-ai/dsh-client-ui-renderer",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-sidebar-right",
+        "@deepseek-ai/dsh-client-ui-tool"
+      ]
+    }
+  }
+}