agent-trellis 0.8.0 → 0.9.0

package/dist/lib/agentBridge.js

@@ -0,0 +1,367 @@
+/**
+ * Cross-Agent delegation (trellis-agent-bridge): lets a managed Agent call
+ * another managed Agent's own verified non-interactive/headless mode as a
+ * one-shot subprocess call, so each Agent's strengths can be used without a
+ * central orchestrator or any cross-machine protocol.
+ *
+ * Configuration lives at `~/.trellis/mcp/agent-bridge.yaml`, sibling to
+ * `servers.yaml`, and is fully optional — its absence means zero behavior
+ * change (design.md Migration Plan).
+ */
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { ALL_AGENTS } from "../core/types.js";
+export const DEFAULT_DELEGATION_TIMEOUT_MS = 120_000;
+export const DEFAULT_MAX_DELEGATION_DEPTH = 2;
+/** Carries the current delegation depth down the real process tree — the
+ * gateway that receives a delegated call inherits this from its spawning
+ * shell, so depth travels with the chain itself without a live shared
+ * registry (design.md Decision 3). */
+export const DELEGATION_DEPTH_ENV = "TRELLIS_DELEGATION_DEPTH";
+const PROMPT_PLACEHOLDER = "{prompt}";
+const PERSONA_PLACEHOLDER = "{persona}";
+const SESSION_PLACEHOLDER = "{sessionId}";
+const FORCE_KILL_GRACE_MS = 5_000;
+export function agentBridgePath(homeDir) {
+    return join(homeDir, ".trellis", "mcp", "agent-bridge.yaml");
+}
+/** Reads the current chain depth from an environment map (defaults to
+ * `process.env`, injectable for tests). Anything absent or malformed
+ * reads as depth 0 — the safe "not part of a chain yet" default. */
+export function readDelegationDepth(env = process.env) {
+    const raw = env[DELEGATION_DEPTH_ENV];
+    const parsed = raw ? Number.parseInt(raw, 10) : 0;
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : 0;
+}
+const OUTPUT_FORMATS = ["text", "json", "stream-json"];
+const STREAM_PROTOCOLS = ["claude", "zcode"];
+export function loadAgentBridgeConfig(homeDir) {
+    const path = agentBridgePath(homeDir);
+    if (!existsSync(path))
+        return { targets: {} };
+    const parsed = (parseYaml(readFileSync(path, "utf-8")) ?? {});
+    if (parsed.maxDepth !== undefined && (!Number.isInteger(parsed.maxDepth) || parsed.maxDepth < 1)) {
+        throw new Error(`agent-bridge.yaml: "maxDepth" must be a positive integer`);
+    }
+    const targets = {};
+    for (const [agentId, raw] of Object.entries(parsed.targets ?? {})) {
+        if (!raw)
+            continue;
+        if (!ALL_AGENTS.includes(agentId)) {
+            throw new Error(`agent-bridge.yaml: "${agentId}" is not a supported Agent id`);
+        }
+        if (!raw.command || !Array.isArray(raw.args) || raw.args.length === 0) {
+            throw new Error(`agent-bridge.yaml: target "${agentId}" must declare "command" and a non-empty "args"`);
+        }
+        if (raw.resumeArgs !== undefined && (!Array.isArray(raw.resumeArgs) || raw.resumeArgs.length === 0)) {
+            throw new Error(`agent-bridge.yaml: target "${agentId}" has an invalid "resumeArgs"`);
+        }
+        if (raw.outputFormat !== undefined && !OUTPUT_FORMATS.includes(raw.outputFormat)) {
+            throw new Error(`agent-bridge.yaml: target "${agentId}" has unknown outputFormat "${raw.outputFormat}"`);
+        }
+        if (raw.streamProtocol !== undefined && !STREAM_PROTOCOLS.includes(raw.streamProtocol)) {
+            throw new Error(`agent-bridge.yaml: target "${agentId}" has unknown streamProtocol "${raw.streamProtocol}"`);
+        }
+        targets[agentId] = {
+            command: raw.command,
+            args: raw.args,
+            ...(raw.resumeArgs ? { resumeArgs: raw.resumeArgs } : {}),
+            ...(raw.outputFormat ? { outputFormat: raw.outputFormat } : {}),
+            ...(raw.streamProtocol ? { streamProtocol: raw.streamProtocol } : {}),
+            ...(raw.timeoutMs ? { timeoutMs: raw.timeoutMs } : {}),
+            ...(raw.tags ? { tags: raw.tags } : {}),
+            ...(raw.persona ? { persona: raw.persona } : {}),
+        };
+    }
+    return { targets, ...(parsed.maxDepth !== undefined ? { maxDepth: parsed.maxDepth } : {}) };
+}
+/** Shared SIGTERM→SIGKILL escalation used by both a timeout firing and a
+ * caller-initiated cancellation (streaming only) — kept as one function so
+ * the two call sites can never drift. */
+function killWithEscalation(child) {
+    child.kill("SIGTERM");
+    const forceKill = setTimeout(() => child.kill("SIGKILL"), FORCE_KILL_GRACE_MS);
+    forceKill.unref?.();
+}
+function buildArgs(template, vars) {
+    return template.map((arg) => {
+        if (arg === PROMPT_PLACEHOLDER)
+            return vars.prompt;
+        if (arg === PERSONA_PLACEHOLDER)
+            return vars.persona ?? "";
+        if (arg === SESSION_PLACEHOLDER)
+            return vars.sessionId ?? "";
+        return arg;
+    });
+}
+/** Best-effort output extraction from a `json`/`stream-json` target's
+ * stdout: the response text plus, when present, a session id the caller
+ * can pass back as `sessionId` in a later call to resume this exact
+ * conversation. A parse failure or unrecognized shape degrades to the raw
+ * trimmed output with no session id, rather than throwing — a CLI's
+ * output-format change should surface as a stranger answer, not a crash
+ * (design.md Risks). */
+function extractOutput(raw, outputFormat) {
+    const trimmed = raw.trim();
+    if (outputFormat !== "json" && outputFormat !== "stream-json")
+        return { output: trimmed };
+    const lines = trimmed.split("\n").filter((line) => line.trim().length > 0);
+    const lastLine = lines[lines.length - 1] ?? trimmed;
+    try {
+        const parsed = JSON.parse(lastLine);
+        if (typeof parsed === "string")
+            return { output: parsed };
+        if (parsed && typeof parsed === "object") {
+            const record = parsed;
+            let output;
+            for (const key of ["result", "output", "text", "response", "message"]) {
+                if (typeof record[key] === "string") {
+                    output = record[key];
+                    break;
+                }
+            }
+            let sessionId;
+            for (const key of ["session_id", "sessionId"]) {
+                if (typeof record[key] === "string") {
+                    sessionId = record[key];
+                    break;
+                }
+            }
+            return { output: output ?? JSON.stringify(parsed), ...(sessionId ? { sessionId } : {}) };
+        }
+    }
+    catch {
+        // fall through to raw text
+    }
+    return { output: trimmed };
+}
+/** Spawns the target's verified non-interactive invocation, enforces
+ * `timeoutMs` with SIGTERM-then-SIGKILL escalation, and normalizes the
+ * result into one envelope regardless of which CLI is underneath. Does
+ * NOT itself enforce a depth ceiling — refusing at the limit is the
+ * caller's job (AgentBridgeProvider), since only it knows the configured
+ * `maxDepth`; this function only propagates whatever depth it's given. */
+export async function runDelegatedCall(targetAgent, target, prompt, opts) {
+    const timeoutMs = opts?.timeoutMs ?? target.timeoutMs ?? DEFAULT_DELEGATION_TIMEOUT_MS;
+    const persona = opts?.persona ?? target.persona;
+    let template = target.args;
+    if (opts?.sessionId) {
+        if (!target.resumeArgs) {
+            return { status: "failed", output: `agent "${targetAgent}" has no resumeArgs configured — cannot resume sessionId "${opts.sessionId}"`, durationMs: 0, targetAgent };
+        }
+        template = target.resumeArgs;
+    }
+    const hasPersonaSlot = template.includes(PERSONA_PLACEHOLDER);
+    const effectivePrompt = persona && !hasPersonaSlot ? `[Persona: ${persona}]\n\n${prompt}` : prompt;
+    const args = buildArgs(template, { prompt: effectivePrompt, persona, sessionId: opts?.sessionId });
+    const childEnv = { ...process.env, [DELEGATION_DEPTH_ENV]: String((opts?.depth ?? 0) + 1) };
+    const start = Date.now();
+    return new Promise((resolve) => {
+        let settled = false;
+        let stdout = "";
+        let stderr = "";
+        const child = spawn(target.command, args, { cwd: opts?.cwd, env: childEnv, stdio: ["ignore", "pipe", "pipe"] });
+        const killTimer = setTimeout(() => killWithEscalation(child), timeoutMs);
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(killTimer);
+            resolve(value);
+        };
+        child.stdout?.on("data", (chunk) => { stdout += chunk.toString("utf-8"); });
+        child.stderr?.on("data", (chunk) => { stderr += chunk.toString("utf-8"); });
+        child.on("error", (err) => finish({ status: "failed", output: err.message, durationMs: Date.now() - start, targetAgent }));
+        child.on("close", (code, signal) => {
+            const durationMs = Date.now() - start;
+            if (signal === "SIGTERM" || signal === "SIGKILL") {
+                finish({ status: "timeout", output: (stdout || stderr).trim(), durationMs, targetAgent });
+                return;
+            }
+            if (code !== 0) {
+                finish({ status: "failed", output: (stderr || stdout).trim(), durationMs, targetAgent });
+                return;
+            }
+            finish({ status: "completed", ...extractOutput(stdout, target.outputFormat), durationMs, targetAgent });
+        });
+    });
+}
+export function tryParseClaudeStreamJsonLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return undefined;
+    let json;
+    try {
+        json = JSON.parse(trimmed);
+    }
+    catch {
+        return undefined;
+    }
+    if (!json || typeof json !== "object")
+        return undefined;
+    const record = json;
+    if (record.type === "system" && record.subtype === "init") {
+        const sessionId = typeof record.session_id === "string" ? record.session_id : undefined;
+        return { kind: "init", ...(sessionId ? { sessionId } : {}) };
+    }
+    if (record.type === "result") {
+        const output = typeof record.result === "string" ? record.result : "";
+        const sessionId = typeof record.session_id === "string" ? record.session_id : undefined;
+        return { kind: "final", output, ...(sessionId ? { sessionId } : {}) };
+    }
+    if (record.type === "assistant" || record.type === "user") {
+        const message = record.message;
+        const content = Array.isArray(message?.content) ? message.content : undefined;
+        if (!content)
+            return undefined;
+        for (const block of content) {
+            if (!block || typeof block !== "object")
+                continue;
+            const b = block;
+            if (b.type === "text" && typeof b.text === "string")
+                return { kind: "text-delta", text: b.text };
+            if (b.type === "tool_use" && typeof b.id === "string" && typeof b.name === "string") {
+                return { kind: "tool-call", toolCallId: b.id, name: b.name, input: b.input };
+            }
+            if (b.type === "tool_result" && typeof b.tool_use_id === "string") {
+                return { kind: "tool-result", toolCallId: b.tool_use_id, output: b.content };
+            }
+        }
+        return undefined;
+    }
+    return undefined;
+}
+/** ZCode's documented headless result envelope is deliberately distinct from
+ * Claude-compatible streams: `{ type: "result", response, sessionId }`.
+ * Intermediate ZCode protocol events evolve with the runtime, so unknown
+ * records remain raw chunks rather than being guessed into false tool/text
+ * events. */
+export function tryParseZcodeStreamJsonLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return undefined;
+    let json;
+    try {
+        json = JSON.parse(trimmed);
+    }
+    catch {
+        return undefined;
+    }
+    if (!json || typeof json !== "object")
+        return undefined;
+    const record = json;
+    if (record.type !== "result" || typeof record.response !== "string")
+        return undefined;
+    const sessionId = typeof record.sessionId === "string" ? record.sessionId : undefined;
+    return { kind: "final", output: record.response, protocol: "zcode", ...(sessionId ? { sessionId } : {}) };
+}
+/** Streaming counterpart to `runDelegatedCall`: same argv-building,
+ * timeout escalation, and persona/session handling, but emits `onChunk`
+ * for every line of stdout as it arrives instead of buffering until the
+ * process exits, and supports cooperative cancellation via `signal`. Takes
+ * a plain `string` target id (not `AgentId`) so it can serve both a future
+ * streaming MCP delegation tool and today's GUI chat feature, whose
+ * targets come from `chat-agents.yaml` and are not required to be one of
+ * the fully-managed Agents in `ALL_AGENTS`. */
+export async function runDelegatedCallStreaming(targetAgent, target, prompt, opts) {
+    const timeoutMs = opts.timeoutMs ?? target.timeoutMs ?? DEFAULT_DELEGATION_TIMEOUT_MS;
+    const persona = opts.persona ?? target.persona;
+    let template = target.args;
+    if (opts.sessionId) {
+        if (!target.resumeArgs) {
+            return {
+                status: "failed",
+                output: `agent "${targetAgent}" has no resumeArgs configured — cannot resume sessionId "${opts.sessionId}"`,
+                durationMs: 0,
+                targetAgent,
+            };
+        }
+        template = target.resumeArgs;
+    }
+    const hasPersonaSlot = template.includes(PERSONA_PLACEHOLDER);
+    const effectivePrompt = persona && !hasPersonaSlot ? `[Persona: ${persona}]\n\n${prompt}` : prompt;
+    const args = buildArgs(template, { prompt: effectivePrompt, persona, sessionId: opts.sessionId });
+    const childEnv = { ...process.env, [DELEGATION_DEPTH_ENV]: String((opts.depth ?? 0) + 1) };
+    const start = Date.now();
+    const isStreamJson = target.outputFormat === "stream-json";
+    return new Promise((resolve) => {
+        let settled = false;
+        let lineBuffer = "";
+        let stdoutAll = "";
+        let stderr = "";
+        let structuredOutput = "";
+        let sessionId;
+        let cancelled = false;
+        const child = spawn(target.command, args, { cwd: opts.cwd, env: childEnv, stdio: ["ignore", "pipe", "pipe"] });
+        const killTimer = setTimeout(() => killWithEscalation(child), timeoutMs);
+        const onAbort = () => {
+            cancelled = true;
+            killWithEscalation(child);
+        };
+        opts.signal?.addEventListener("abort", onAbort);
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(killTimer);
+            opts.signal?.removeEventListener("abort", onAbort);
+            resolve(value);
+        };
+        const emitLine = (line) => {
+            if (!line)
+                return;
+            let parsed;
+            if (isStreamJson) {
+                parsed = target.streamProtocol === "zcode" ? tryParseZcodeStreamJsonLine(line) : tryParseClaudeStreamJsonLine(line);
+                if (parsed?.kind === "text-delta")
+                    structuredOutput += structuredOutput ? `\n${parsed.text}` : parsed.text;
+                if (parsed?.kind === "final")
+                    structuredOutput = parsed.output;
+                if (parsed?.kind === "init" && parsed.sessionId)
+                    sessionId = parsed.sessionId;
+                if (parsed?.kind === "final" && parsed.sessionId)
+                    sessionId = parsed.sessionId;
+            }
+            opts.onChunk({ raw: line, ...(parsed ? { parsed } : {}) });
+        };
+        child.stdout?.on("data", (chunk) => {
+            const text = chunk.toString("utf-8");
+            stdoutAll += text;
+            lineBuffer += text;
+            const lines = lineBuffer.split("\n");
+            lineBuffer = lines.pop() ?? "";
+            for (const line of lines)
+                emitLine(line);
+        });
+        child.stderr?.on("data", (chunk) => { stderr += chunk.toString("utf-8"); });
+        child.on("error", (err) => finish({ status: "failed", output: err.message, durationMs: Date.now() - start, targetAgent }));
+        child.on("close", (code, signal) => {
+            if (lineBuffer) {
+                emitLine(lineBuffer);
+                lineBuffer = "";
+            }
+            const durationMs = Date.now() - start;
+            const finalOutput = isStreamJson ? structuredOutput : stdoutAll;
+            if (cancelled) {
+                finish({ status: "cancelled", output: finalOutput.trim(), durationMs, targetAgent, ...(sessionId ? { sessionId } : {}) });
+                return;
+            }
+            if (signal === "SIGTERM" || signal === "SIGKILL") {
+                finish({ status: "timeout", output: (finalOutput || stderr).trim(), durationMs, targetAgent, ...(sessionId ? { sessionId } : {}) });
+                return;
+            }
+            if (code !== 0) {
+                finish({ status: "failed", output: (stderr || finalOutput).trim(), durationMs, targetAgent });
+                return;
+            }
+            if (isStreamJson) {
+                finish({ status: "completed", output: finalOutput.trim(), durationMs, targetAgent, ...(sessionId ? { sessionId } : {}) });
+                return;
+            }
+            const extracted = extractOutput(stdoutAll, target.outputFormat);
+            finish({ status: "completed", output: extracted.output, durationMs, targetAgent, ...(extracted.sessionId ? { sessionId: extracted.sessionId } : {}) });
+        });
+    });
+}

package/dist/lib/agentBridgeProvider.d.ts

@@ -0,0 +1,14 @@
+import type { CallToolResult, Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { RuntimeContext, TrellisProvider } from "./mcpRuntime.js";
+/** Exposes every `agent-bridge.yaml` target — other than the calling
+ * Agent itself — as one MCP tool per target Agent. Routing which target
+ * to call stays with the caller's own model, exactly like ordinary MCP
+ * tool selection; this provider only executes the call once chosen, and
+ * refuses one that would exceed the configured delegation depth before
+ * ever spawning a process. */
+export declare class AgentBridgeProvider implements TrellisProvider {
+    readonly id = "agent_bridge";
+    private readonly toolTargets;
+    listTools(context: RuntimeContext): Tool[];
+    callTool(name: string, args: unknown, context: RuntimeContext): Promise<CallToolResult>;
+}

package/dist/lib/agentBridgeProvider.js

@@ -0,0 +1,95 @@
+import { DEFAULT_MAX_DELEGATION_DEPTH, loadAgentBridgeConfig, readDelegationDepth, runDelegatedCall } from "./agentBridge.js";
+import { resolveZcodeProfile } from "../probes/zcode.js";
+function toolNameFor(agentId) {
+    return `trellis.agent_bridge.run_${agentId.replaceAll("-", "_")}`;
+}
+function toolFor(agentId, target) {
+    const tagText = target.tags?.length ? ` Good for: ${target.tags.join(", ")}.` : "";
+    const resumeText = target.resumeArgs
+        ? " Pass a prior call's returned sessionId to continue that exact conversation."
+        : " Does not support resuming a prior conversation — every call starts fresh.";
+    return {
+        name: toolNameFor(agentId),
+        description: `Delegate a one-shot prompt to "${agentId}"'s own non-interactive mode and return its result.${tagText} Optionally set "persona" to shape how it responds for this call.${resumeText} Requires explicit confirm=true — this spawns a real subprocess with real side effects, not a read-only lookup.`,
+        inputSchema: {
+            type: "object",
+            properties: {
+                prompt: { type: "string" },
+                persona: { type: "string", description: "Overrides this target's default persona/role for this call only." },
+                sessionId: { type: "string", description: "Resume a prior call's conversation instead of starting fresh; requires the target to support resuming." },
+                cwd: { type: "string" },
+                timeoutMs: { type: "number" },
+                confirm: { type: "boolean" },
+            },
+            required: ["prompt", "confirm"],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    };
+}
+function result(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }], structuredContent: value };
+}
+function failure(message) {
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+/** Exposes every `agent-bridge.yaml` target — other than the calling
+ * Agent itself — as one MCP tool per target Agent. Routing which target
+ * to call stays with the caller's own model, exactly like ordinary MCP
+ * tool selection; this provider only executes the call once chosen, and
+ * refuses one that would exceed the configured delegation depth before
+ * ever spawning a process. */
+export class AgentBridgeProvider {
+    id = "agent_bridge";
+    toolTargets = new Map();
+    listTools(context) {
+        const config = loadAgentBridgeConfig(context.homeDir);
+        this.toolTargets.clear();
+        const tools = [];
+        for (const [agentId, target] of Object.entries(config.targets)) {
+            if (agentId === context.agentId)
+                continue;
+            const tool = toolFor(agentId, target);
+            this.toolTargets.set(tool.name, agentId);
+            tools.push(tool);
+        }
+        return tools;
+    }
+    async callTool(name, args, context) {
+        const input = (args ?? {});
+        const targetAgent = this.toolTargets.get(name);
+        if (!targetAgent)
+            return failure(`unknown agent bridge tool "${name}"`);
+        if (input.confirm !== true)
+            return failure(`agent bridge call "${name}" requires confirm=true — it spawns a real subprocess with real side effects`);
+        const prompt = String(input.prompt ?? "").trim();
+        if (!prompt)
+            return failure("prompt must not be empty");
+        const config = loadAgentBridgeConfig(context.homeDir);
+        const target = config.targets[targetAgent];
+        if (!target)
+            return failure(`agent "${targetAgent}" is no longer configured for delegation`);
+        if (targetAgent === "zcode") {
+            const profile = resolveZcodeProfile(context.homeDir);
+            if (!profile?.supportsExecution || target.command !== profile.executable) {
+                return failure("zcode delegation requires a compatible public zcode CLI selected by the local ZCode probe");
+            }
+        }
+        const maxDepth = config.maxDepth ?? DEFAULT_MAX_DELEGATION_DEPTH;
+        const currentDepth = readDelegationDepth();
+        if (currentDepth >= maxDepth) {
+            return failure(`delegation depth limit reached (${currentDepth}/${maxDepth}) — refusing to call "${targetAgent}" to avoid a delegation cycle`);
+        }
+        try {
+            const cwd = typeof input.cwd === "string" ? input.cwd : undefined;
+            const timeoutMs = typeof input.timeoutMs === "number" ? input.timeoutMs : undefined;
+            const persona = typeof input.persona === "string" && input.persona.trim() ? input.persona : undefined;
+            const sessionId = typeof input.sessionId === "string" && input.sessionId.trim() ? input.sessionId : undefined;
+            const outcome = await runDelegatedCall(targetAgent, target, prompt, { cwd, timeoutMs, persona, sessionId, depth: currentDepth });
+            return result(outcome);
+        }
+        catch (error) {
+            return failure(error instanceof Error ? error.message : String(error));
+        }
+    }
+}

package/dist/lib/backup.d.ts

@@ -31,6 +31,38 @@ export type BackupOperation = {
     kind: "symlink-remove";
     path: string;
     beforeLinkTarget: string;
+}
+/** A whole directory created where none existed — e.g. `skill add`
+ * copying a canonical Skill in. New operations carry the resulting
+ * directory digest so rollback can refuse a tree edited after the run;
+ * the optional field preserves compatibility with old backup manifests. */
+ | {
+    kind: "dir-create";
+    path: string;
+    afterDigest?: string;
+}
+/** A whole directory removed — e.g. `skill remove`. `beforeDir` is a
+ * full recursive copy of the directory's pre-removal content, stored
+ * under this run's own directory — the directory equivalent of
+ * `file-overwrite`'s single-file `beforeFile` snapshot. Conflict
+ * detection is existence-only (does the path exist again since this
+ * run), not a deep content hash — a directory tree's content-drift
+ * check would need its own manifest of per-file hashes, which no
+ * caller of this module has needed yet; if that changes, extend here
+ * rather than approximating silently. */
+ | {
+    kind: "dir-remove";
+    path: string;
+    beforeDir: string;
+}
+/** A whole directory replaced in-place.  The before-tree snapshot and the
+ * exact after-tree digest let rollback refuse a locally edited remote Skill
+ * instead of overwriting it. */
+ | {
+    kind: "dir-replace";
+    path: string;
+    beforeDir: string;
+    afterDigest: string;
 };
 export interface BackupManifest {
     runId: string;
@@ -44,6 +76,16 @@ export interface BackupSession {
     createSymlink(path: string, linkTarget: string): Promise<void>;
     repairSymlink(path: string, oldLinkTarget: string, newLinkTarget: string): Promise<void>;
     removeSymlink(path: string, oldLinkTarget: string): Promise<void>;
+    /** Copies `sourceDir`'s content to `path` (which must not already
+     * exist) and records it as a `dir-create`. */
+    createDirFromSource(path: string, sourceDir: string): void;
+    /** Snapshots `path`'s current content into this run's own storage,
+     * then removes it, and records it as a `dir-remove`. */
+    removeDir(path: string): void;
+    /** Snapshots an existing directory then copies `sourceDir` in its place,
+     * recorded as one operation so rollback can restore it without an
+     * intermediate same-path conflict. */
+    replaceDirFromSource(path: string, sourceDir: string): void;
     hasOperations(): boolean;
     /** Writes manifest.json. No-op (creates nothing) if zero operations
      * were ever recorded. */

package/dist/lib/backup.js

@@ -9,9 +9,10 @@
  * that never records anything creates nothing on disk.
  */
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { readlink, rm, symlink } from "node:fs/promises";
-import { basename, join } from "node:path";
+import { basename, dirname, join } from "node:path";
+import { directoryDigest } from "./dirDigest.js";
 function sha256(content) {
     return `sha256:${createHash("sha256").update(content).digest("hex")}`;
 }
@@ -60,6 +61,7 @@ export function openBackupSession(homeDir, command) {
     const operations = [];
     let dirCreated = false;
     let fileIndex = 0;
+    let dirIndex = 0;
     function ensureDir() {
         if (dirCreated)
             return;
@@ -87,7 +89,12 @@ export function openBackupSession(homeDir, command) {
             else {
                 operations.push({ kind: "file-create", path, afterHash });
             }
-            writeFileSync(path, content);
+            // A lock/provenance update must not leave a partially-written JSON file
+            // if the process stops mid-write.  This also strengthens the existing
+            // backup-aware file writes without changing their manifest contract.
+            const temporary = join(dirname(path), `.${basename(path)}.${process.pid}.${fileIndex}.tmp`);
+            writeFileSync(temporary, content);
+            renameSync(temporary, path);
         },
         async createSymlink(path, linkTarget) {
             ensureDir();
@@ -106,6 +113,32 @@ export function openBackupSession(homeDir, command) {
             await rm(path, { force: true });
             operations.push({ kind: "symlink-remove", path, beforeLinkTarget: oldLinkTarget });
         },
+        createDirFromSource(path, sourceDir) {
+            ensureDir();
+            mkdirSync(path, { recursive: true });
+            cpSync(sourceDir, path, { recursive: true });
+            operations.push({ kind: "dir-create", path, afterDigest: directoryDigest(path) });
+        },
+        removeDir(path) {
+            ensureDir();
+            const relSnapshot = join("dirs", `${dirIndex}-${basename(path)}`);
+            dirIndex += 1;
+            cpSync(path, join(runDir, relSnapshot), { recursive: true });
+            rmSync(path, { recursive: true, force: true });
+            operations.push({ kind: "dir-remove", path, beforeDir: relSnapshot });
+        },
+        replaceDirFromSource(path, sourceDir) {
+            if (!existsSync(path))
+                throw new Error(`Cannot replace missing directory: ${path}`);
+            ensureDir();
+            const relSnapshot = join("dirs", `${dirIndex}-${basename(path)}`);
+            dirIndex += 1;
+            cpSync(path, join(runDir, relSnapshot), { recursive: true });
+            rmSync(path, { recursive: true, force: true });
+            mkdirSync(path, { recursive: true });
+            cpSync(sourceDir, path, { recursive: true });
+            operations.push({ kind: "dir-replace", path, beforeDir: relSnapshot, afterDigest: directoryDigest(path) });
+        },
         hasOperations() {
             return operations.length > 0;
         },

package/dist/lib/chatAgents.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Config for the GUI's in-app chat feature: which CLI agents can be chatted
+ * with from the desktop app, keyed by an arbitrary string id (not `AgentId`
+ * — chat targets are not necessarily fully-managed Agents with adapters,
+ * sync, and probes; they're just "a non-interactive CLI I can spawn and
+ * stream from"). Kept as its own file + config path, sibling to
+ * `agent-bridge.yaml`, so delegation's `ALL_AGENTS` constraint (needed for
+ * the cross-Agent-delegation use case) never has to bend for chat's needs.
+ *
+ * Configuration lives at `~/.trellis/mcp/chat-agents.yaml`. Its absence
+ * means zero targets, not an error — the same "optional, additive" shape
+ * as `agent-bridge.yaml`.
+ */
+import type { StreamProtocol } from "./agentBridge.js";
+export type ChatAgentOutputFormat = "text" | "json" | "stream-json";
+export interface ChatAgentTargetConfig {
+    /** Human-readable name shown in the GUI's agent picker, e.g. "Claude Code". */
+    label: string;
+    /** Binary to spawn, e.g. "claude", "qoder". */
+    command: string;
+    /** Argv template for a fresh call. One element may be the literal
+     * placeholder `"{prompt}"`, substituted with the caller's message at
+     * call time. */
+    args: string[];
+    /** Argv template used instead of `args` when the caller supplies a
+     * `sessionId` to resume — must reference `"{sessionId}"`. */
+    resumeArgs?: string[];
+    /** How to interpret stdout. Omit for plain text. */
+    outputFormat?: ChatAgentOutputFormat;
+    /** Optional stream parser for a CLI with a non-Claude event envelope. */
+    streamProtocol?: StreamProtocol;
+    timeoutMs?: number;
+    /** Free-text, informational only — surfaced in the GUI as a hint. */
+    tags?: string[];
+    /** Default persona/role text applied to every call to this target. */
+    persona?: string;
+}
+export interface ChatAgentConfig {
+    targets: Record<string, ChatAgentTargetConfig>;
+}
+export declare function chatAgentsPath(homeDir: string): string;
+export declare function loadChatAgentConfig(homeDir: string): ChatAgentConfig;