agent-trellis 0.7.0 → 0.8.2

package/dist/core/canonical.js

@@ -89,8 +89,39 @@ function loadServersYaml(path) {
         knownHostInjected: parsed.known_host_injected ?? [],
         hub: parsed.hub,
         gateway: fromGatewayYaml(parsed.gateway),
+        routes: fromRoutesYaml(parsed.routes),
+        runtime: fromRuntimeYaml(parsed.runtime),
     };
 }
+function fromRuntimeYaml(runtime) {
+    if (!runtime?.delivery)
+        return undefined;
+    const delivery = {};
+    for (const [rawAgent, rawDelivery] of Object.entries(runtime.delivery)) {
+        if (!ALL_AGENTS.includes(rawAgent))
+            continue;
+        if (rawDelivery !== "native" && rawDelivery !== "mcp" && rawDelivery !== "both")
+            continue;
+        delivery[rawAgent] = rawDelivery;
+    }
+    return Object.keys(delivery).length > 0 ? { delivery } : undefined;
+}
+function fromRoutesYaml(routes) {
+    if (!routes)
+        return undefined;
+    const out = {};
+    for (const [rawAgent, rawRoute] of Object.entries(routes)) {
+        if (!ALL_AGENTS.includes(rawAgent))
+            continue;
+        if (!rawRoute?.mode || !["direct", "gateway", "hub"].includes(rawRoute.mode))
+            continue;
+        out[rawAgent] = {
+            mode: rawRoute.mode,
+            ...(rawRoute.servers ? { servers: rawRoute.servers } : {}),
+        };
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
 /**
  * A `gateway:` block with no `enabled` key reads as off, not as on — the
  * only safe default for a field whose whole effect is to stop writing the
@@ -137,7 +168,15 @@ function forceBlockStyle(node) {
         node.flow = false;
     }
 }
-export function upsertServerYaml(path, name, def) {
+function persistText(path, content, backup) {
+    if (existsSync(path) && readFileSync(path, "utf-8") === content)
+        return;
+    if (backup)
+        backup.writeFile(path, content);
+    else
+        writeFileSync(path, content);
+}
+export function upsertServerYaml(path, name, def, backup) {
     if (!existsSync(path)) {
         return { ok: false, error: `${path} does not exist — run \`trellis init\` first` };
     }
@@ -151,12 +190,12 @@ export function upsertServerYaml(path, name, def) {
     doc.setIn(["servers", name], toServerDefYaml(def));
     forceBlockStyle(doc.get("servers", true));
     forceBlockStyle(doc.getIn(["servers", name], true));
-    writeFileSync(path, doc.toString());
+    persistText(path, doc.toString(), backup);
     return { ok: true };
 }
 /** Inverse of `upsertServerYaml` — same preservation guarantee, same
  * refusal posture on a missing/unparseable file. */
-export function removeServerYaml(path, name) {
+export function removeServerYaml(path, name, backup) {
     if (!existsSync(path)) {
         return { ok: false, error: `${path} does not exist — run \`trellis init\` first` };
     }
@@ -168,7 +207,7 @@ export function removeServerYaml(path, name) {
         return { ok: false, error: `could not parse ${path}: ${err instanceof Error ? err.message : String(err)}` };
     }
     doc.deleteIn(["servers", name]);
-    writeFileSync(path, doc.toString());
+    persistText(path, doc.toString(), backup);
     return { ok: true };
 }
 /**
@@ -181,7 +220,7 @@ export function removeServerYaml(path, name) {
  * starter file). Selecting one mode always clears the other two
  * (design.md D3) — never left for the caller to remember.
  */
-export function writeMcpModeYaml(path, mode) {
+export function writeMcpModeYaml(path, mode, backup) {
     if (!existsSync(path)) {
         return { ok: false, error: `${path} does not exist — run \`trellis init\` first` };
     }
@@ -214,7 +253,56 @@ export function writeMcpModeYaml(path, mode) {
             forceBlockStyle(doc.get("gateway", true));
             break;
     }
-    writeFileSync(path, doc.toString());
+    persistText(path, doc.toString(), backup);
+    return { ok: true };
+}
+/** Writes explicit per-agent routes while preserving legacy hub/gateway
+ * shorthand. An empty route map removes the optional key. */
+export function writeMcpRoutesYaml(path, routes, backup) {
+    if (!existsSync(path)) {
+        return { ok: false, error: `${path} does not exist — run \`trellis init\` first` };
+    }
+    let doc;
+    try {
+        doc = parseDocument(readFileSync(path, "utf-8"));
+    }
+    catch (err) {
+        return { ok: false, error: `could not parse ${path}: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    const serialized = Object.fromEntries(Object.entries(routes).map(([agent, route]) => [agent, { mode: route.mode, ...(route.servers ? { servers: route.servers } : {}) }]));
+    if (Object.keys(serialized).length === 0) {
+        doc.delete("routes");
+    }
+    else {
+        doc.set("routes", serialized);
+        forceBlockStyle(doc.get("routes", true));
+    }
+    persistText(path, doc.toString(), backup);
+    return { ok: true };
+}
+/** Writes per-agent capability delivery preferences into servers.yaml.
+ * Omitted entries continue to use the native default. */
+export function writeMcpRuntimeDeliveryYaml(path, delivery, backup) {
+    if (!existsSync(path)) {
+        return { ok: false, error: path + " does not exist — run trellis init first" };
+    }
+    let doc;
+    try {
+        doc = parseDocument(readFileSync(path, "utf-8"));
+    }
+    catch (err) {
+        return { ok: false, error: `could not parse ${path}: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    const serialized = Object.fromEntries(Object.entries(delivery).map(([agent, mode]) => [agent, mode]));
+    if (Object.keys(serialized).length === 0) {
+        doc.delete("runtime");
+    }
+    else {
+        doc.setIn(["runtime", "delivery"], serialized);
+        forceBlockStyle(doc.get("runtime", true));
+        forceBlockStyle(doc.getIn(["runtime", "delivery"], true));
+    }
+    persistText(path, doc.toString(), backup);
     return { ok: true };
 }
 function loadSecretsPolicyYaml(path, homeDir) {
@@ -240,7 +328,7 @@ function loadSecretsPolicyYaml(path, homeDir) {
  * `varName` to `allowed_vars` only if not already present (dedup, same
  * "already there is a no-op" rule every other Trellis writer follows).
  */
-export function writeSecretsPolicyExtraction(path, extraction) {
+export function writeSecretsPolicyExtraction(path, extraction, backup) {
     if (!existsSync(path)) {
         return { ok: false, error: `${path} does not exist — run \`trellis init\` first` };
     }
@@ -262,7 +350,7 @@ export function writeSecretsPolicyExtraction(path, extraction) {
         doc.set("allowed_vars", [...currentAllowedVars, extraction.varName]);
         forceBlockStyle(doc.get("allowed_vars", true));
     }
-    writeFileSync(path, doc.toString());
+    persistText(path, doc.toString(), backup);
     return { ok: true };
 }
 /**
@@ -275,13 +363,13 @@ export function writeSecretsPolicyExtraction(path, extraction) {
  * init`'s own bootstrap, so a machine that never extracts a secret never
  * gains this file at all.
  */
-export function ensureGitignoreEntry(gitignorePath, line) {
+export function ensureGitignoreEntry(gitignorePath, line, backup) {
     const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, "utf-8") : "";
     const lines = existing.split("\n").map((l) => l.trim());
     if (lines.includes(line))
         return;
     const separator = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
-    writeFileSync(gitignorePath, `${existing}${separator}${line}\n`);
+    persistText(gitignorePath, `${existing}${separator}${line}\n`, backup);
 }
 const SHELL_ENV_SOURCE_MARKER = "# >>> trellis mcp secrets >>>";
 const SHELL_ENV_SOURCE_END_MARKER = "# <<< trellis mcp secrets <<<";
@@ -297,17 +385,17 @@ const SHELL_ENV_SOURCE_END_MARKER = "# <<< trellis mcp secrets <<<";
  * lines `parseDotenv` already expects, so that format never needs an
  * `export` prefix of its own.
  */
-export function ensureShellEnvSource(rcPath, envFilePath) {
+export function ensureShellEnvSource(rcPath, envFilePath, backup) {
     const existing = existsSync(rcPath) ? readFileSync(rcPath, "utf-8") : "";
     if (existing.includes(SHELL_ENV_SOURCE_MARKER))
         return;
     const separator = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
     const block = `${SHELL_ENV_SOURCE_MARKER}\nif [ -f "${envFilePath}" ]; then\n  set -a\n  source "${envFilePath}"\n  set +a\nfi\n${SHELL_ENV_SOURCE_END_MARKER}\n`;
     mkdirSync(dirname(rcPath), { recursive: true });
-    writeFileSync(rcPath, `${existing}${separator}${block}`);
+    persistText(rcPath, `${existing}${separator}${block}`, backup);
 }
 /** `undefined` if the name has no entry in scope.yaml's map — "shared with
- * all four agents," the default. A recognized but empty list is left as
+ * all managed agents by default. A recognized but empty list is left as
  * authored (an explicitly agent-less scope), not coerced to "all". */
 /** Missing file and `agents: []` both resolve to `[]` — zero managed
  * agents (D1), never "everyone." An unrecognized id is dropped with a

package/dist/core/capabilitySelection.d.ts

@@ -0,0 +1,45 @@
+import type { AgentId, CapabilityDelivery, CanonicalSource, McpRouteMode } from "./types.js";
+export type NameSelection = "all" | "none" | string[];
+export interface CapabilitySelection {
+    skills: NameSelection;
+    mcpServers: NameSelection;
+    memories: NameSelection;
+    memoryMigration: "all" | "none";
+    mcpRoutes: Partial<Record<AgentId, {
+        mode: McpRouteMode;
+        servers?: string[];
+    }>>;
+    runtimeDelivery: Partial<Record<AgentId, CapabilityDelivery>>;
+}
+export interface CapabilityItem {
+    name: string;
+    displayName: string;
+    fingerprint?: string;
+    status: "new" | "unchanged" | "changed" | "unsupported";
+    detail?: string;
+}
+export interface UnsupportedCapabilitySource {
+    name: string;
+    detail: string;
+}
+export interface CapabilityInventory {
+    skills: CapabilityItem[];
+    mcpServers: CapabilityItem[];
+    canonicalMemories: CapabilityItem[];
+    nativeMemory: UnsupportedCapabilitySource[];
+}
+export type SelectionFileResult = {
+    ok: true;
+    selection: CapabilitySelection;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function parseCapabilitySelectionFile(path: string): SelectionFileResult;
+export declare function defaultCapabilitySelection(): CapabilitySelection;
+export declare function resolveSelectedNames(selection: NameSelection, available: readonly string[]): string[];
+export declare function selectionContains(selection: NameSelection, name: string): boolean;
+export declare function buildCapabilityInventory(source: {
+    skillNames: readonly string[];
+    mcpServerNames: readonly string[];
+}, canonical: Pick<CanonicalSource, "skills" | "mcp" | "memories">, nativeMemory?: UnsupportedCapabilitySource[]): CapabilityInventory;

package/dist/core/capabilitySelection.js

@@ -0,0 +1,124 @@
+import { existsSync, readFileSync } from "node:fs";
+import { parse as parseYaml } from "yaml";
+import { ALL_AGENTS } from "./types.js";
+const ALL_SELECTION = {
+    skills: "all",
+    mcpServers: "all",
+    memories: "all",
+    memoryMigration: "all",
+    mcpRoutes: {},
+    runtimeDelivery: {},
+};
+function parseNameSelection(value, field) {
+    if (value === undefined)
+        return "all";
+    if (value === "all" || value === "none")
+        return value;
+    if (Array.isArray(value) && value.every((item) => typeof item === "string" && item.length > 0)) {
+        return [...new Set(value)];
+    }
+    throw new Error(`${field} must be "all", "none", or a list of names`);
+}
+function parseRoutes(value) {
+    if (value === undefined)
+        return {};
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("mcp_routes must be a map of agent ids to route definitions");
+    }
+    const routes = {};
+    for (const [rawAgent, rawRoute] of Object.entries(value)) {
+        if (!ALL_AGENTS.includes(rawAgent)) {
+            throw new Error(`mcp_routes contains unknown agent "${rawAgent}"`);
+        }
+        if (typeof rawRoute !== "object" || rawRoute === null || Array.isArray(rawRoute)) {
+            throw new Error(`mcp_routes.${rawAgent} must be a route object`);
+        }
+        const route = rawRoute;
+        if (route.mode !== "direct" && route.mode !== "gateway" && route.mode !== "hub") {
+            throw new Error(`mcp_routes.${rawAgent}.mode must be direct, gateway, or hub`);
+        }
+        if (route.servers !== undefined && (!Array.isArray(route.servers) || !route.servers.every((item) => typeof item === "string" && item.length > 0))) {
+            throw new Error(`mcp_routes.${rawAgent}.servers must be a list of names`);
+        }
+        routes[rawAgent] = {
+            mode: route.mode,
+            ...(route.servers ? { servers: [...new Set(route.servers)] } : {}),
+        };
+    }
+    return routes;
+}
+function parseRuntimeDelivery(value) {
+    if (value === undefined)
+        return {};
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("runtime_delivery must be a map of agent ids to native, mcp, or both");
+    }
+    const delivery = {};
+    for (const [rawAgent, rawMode] of Object.entries(value)) {
+        if (!ALL_AGENTS.includes(rawAgent)) {
+            throw new Error(`runtime_delivery contains unknown agent "${rawAgent}"`);
+        }
+        if (rawMode !== "native" && rawMode !== "mcp" && rawMode !== "both") {
+            throw new Error(`runtime_delivery.${rawAgent} must be native, mcp, or both`);
+        }
+        delivery[rawAgent] = rawMode;
+    }
+    return delivery;
+}
+export function parseCapabilitySelectionFile(path) {
+    if (!existsSync(path))
+        return { ok: false, error: `selection file does not exist: ${path}` };
+    try {
+        const parsed = (parseYaml(readFileSync(path, "utf8")) ?? {});
+        return {
+            ok: true,
+            selection: {
+                skills: parseNameSelection(parsed.skills, "skills"),
+                mcpServers: parseNameSelection(parsed.mcp_servers, "mcp_servers"),
+                memories: parseNameSelection(parsed.memories, "memories"),
+                memoryMigration: parsed.memory_migration === undefined || parsed.memory_migration === "all" ? "all" : parsed.memory_migration === "none" ? "none" : (() => { throw new Error('memory_migration must be "all" or "none"'); })(),
+                mcpRoutes: parseRoutes(parsed.mcp_routes),
+                runtimeDelivery: parseRuntimeDelivery(parsed.runtime_delivery),
+            },
+        };
+    }
+    catch (err) {
+        return { ok: false, error: `could not parse selection file ${path}: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+export function defaultCapabilitySelection() {
+    return { ...ALL_SELECTION, mcpRoutes: {}, runtimeDelivery: {} };
+}
+export function resolveSelectedNames(selection, available) {
+    if (selection === "all")
+        return [...available];
+    if (selection === "none")
+        return [];
+    const availableSet = new Set(available);
+    return [...new Set(selection.filter((name) => availableSet.has(name)))];
+}
+export function selectionContains(selection, name) {
+    return selection === "all" || (selection !== "none" && selection.includes(name));
+}
+export function buildCapabilityInventory(source, canonical, nativeMemory = []) {
+    const canonicalSkills = new Set(canonical.skills.map((skill) => skill.name));
+    const canonicalMcp = new Set(Object.keys(canonical.mcp.servers));
+    return {
+        skills: source.skillNames.map((name) => ({
+            name,
+            displayName: name,
+            status: canonicalSkills.has(name) ? "unchanged" : "new",
+        })),
+        mcpServers: source.mcpServerNames.map((name) => ({
+            name,
+            displayName: name,
+            status: canonicalMcp.has(name) ? "unchanged" : "new",
+        })),
+        canonicalMemories: canonical.memories.map((memory) => ({
+            name: memory.name,
+            displayName: memory.name,
+            status: "unchanged",
+        })),
+        nativeMemory,
+    };
+}

package/dist/core/types.d.ts

@@ -5,11 +5,12 @@
  * files on disk are its serialization, not the other way around.
  */
 export type Transport = "stdio" | "http" | "sse";
-export type AgentId = "claude-code" | "codex" | "kiro" | "pi";
+export type McpAuthMode = "oauth";
+export type AgentId = "claude-code" | "codex" | "kiro" | "pi" | "kimi-code" | "zcode";
 export declare const ALL_AGENTS: readonly AgentId[];
 /**
  * Every scopable item (skill, subagent, memory entry, MCP server) defaults
- * to "all four agents" when `scope` is omitted — sharing everywhere is the
+ * to all managed agents when `scope` is omitted — sharing everywhere is the
  * common case Trellis exists for; restricting to specific agents is the
  * exception and must be declared explicitly. See docs/architecture.md
  * "Private / agent-specific capabilities".
@@ -26,6 +27,9 @@ export type Scope = AgentId[] | undefined;
 export declare function resolveScope(scope: Scope, managedAgents: readonly AgentId[]): readonly AgentId[];
 export interface McpServerDef {
     transport: Transport;
+    /** Explicit authorization classification. Absence means ordinary MCP;
+     * Trellis never infers OAuth from a URL or a transient 401. */
+    auth?: McpAuthMode;
     /** stdio only */
     command?: string;
     args?: string[];
@@ -109,6 +113,18 @@ export interface GatewayConfig {
      */
     agents?: AgentId[];
 }
+export type McpRouteMode = "direct" | "gateway" | "hub";
+export interface McpRoute {
+    mode: McpRouteMode;
+    /** Omit to expose every eligible canonical server for this agent. */
+    servers?: string[];
+}
+export type CapabilityDelivery = "native" | "mcp" | "both";
+export interface McpRuntimeConfig {
+    /** Per-agent delivery for Trellis-owned capabilities and upstream MCP.
+     * Omitted means native, preserving the existing adapter behavior. */
+    delivery?: Partial<Record<AgentId, CapabilityDelivery>>;
+}
 export interface McpConfig {
     servers: Record<string, McpServerDef>;
     /**
@@ -127,7 +143,14 @@ export interface McpConfig {
      * two mean different things and may both be set, in which case gateway
      * wins per agent (trellis-mcp-gateway-hosting design.md D5/D6). */
     gateway?: GatewayConfig;
+    /** Optional per-agent route overrides. Explicit routes take precedence
+     * over the legacy hub/gateway shorthand for the named agent. */
+    routes?: Partial<Record<AgentId, McpRoute>>;
+    /** Optional runtime delivery preferences. */
+    runtime?: McpRuntimeConfig;
 }
+export declare function capabilityDeliveryForAgent(agentId: AgentId, mcp: McpConfig): CapabilityDelivery;
+export declare function usesNativeCapabilityDelivery(agentId: AgentId, mcp: McpConfig): boolean;
 export interface SkillRef {
     name: string;
     /** Absolute path to the skill's directory. Must contain `SKILL.md` — the

package/dist/core/types.js

@@ -9,6 +9,8 @@ export const ALL_AGENTS = [
     "codex",
     "kiro",
     "pi",
+    "kimi-code",
+    "zcode",
 ];
 /**
  * `managedAgents` is the hard outer boundary (trellis-managed-agents
@@ -22,3 +24,9 @@ export function resolveScope(scope, managedAgents) {
     const candidates = scope ?? managedAgents;
     return candidates.filter((id) => managedAgents.includes(id));
 }
+export function capabilityDeliveryForAgent(agentId, mcp) {
+    return mcp.runtime?.delivery?.[agentId] ?? "native";
+}
+export function usesNativeCapabilityDelivery(agentId, mcp) {
+    return capabilityDeliveryForAgent(agentId, mcp) !== "mcp";
+}

package/dist/lib/agentBridge.d.ts

@@ -0,0 +1,169 @@
+/**
+ * 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 { type AgentId } from "../core/types.js";
+export type AgentBridgeOutputFormat = "text" | "json" | "stream-json";
+export type StreamProtocol = "claude" | "zcode";
+export interface AgentBridgeTargetConfig {
+    /** Binary to spawn, e.g. "codex", "claude", "pi", "kimi". */
+    command: string;
+    /** Argv template for a fresh call. One element may be the literal
+     * placeholder `"{prompt}"`, substituted with the caller's prompt (and
+     * persona, if the target has no dedicated persona flag — see
+     * `PERSONA_PLACEHOLDER`) at call time — covers a trailing positional
+     * prompt (Codex, Claude Code, pi) and a flag-value prompt (Kimi Code's
+     * `-p, --prompt <prompt>`) with the same shape. */
+    args: string[];
+    /** Argv template used instead of `args` when the caller supplies a
+     * `sessionId` to resume — must reference `"{sessionId}"`. Omitting this
+     * means the target does not support resuming a prior session; a call
+     * that supplies `sessionId` against such a target fails with a clear
+     * error rather than silently starting a fresh session. */
+    resumeArgs?: string[];
+    /** How to interpret stdout. Omit for plain text. */
+    outputFormat?: AgentBridgeOutputFormat;
+    /** Selects a verified event envelope for stream-json output. Omit for
+     * Claude-compatible streams, which remains the existing default. */
+    streamProtocol?: StreamProtocol;
+    timeoutMs?: number;
+    /** Free-text, informational only — surfaced in the exposed tool's
+     * description so a caller can judge fit; never validated against a
+     * taxonomy. */
+    tags?: string[];
+    /** Default persona/role text applied to every call to this target
+     * unless a call overrides it. Substituted into `"{persona}"` when the
+     * chosen argv template has that placeholder; otherwise prepended to the
+     * prompt as a framing line, so every target gets persona support even
+     * without a native system-prompt flag. */
+    persona?: string;
+}
+export interface AgentBridgeConfig {
+    targets: Partial<Record<AgentId, AgentBridgeTargetConfig>>;
+    /** Maximum delegation chain depth before a call is refused, to bound
+     * A→B→A (or longer) cycles. Defaults to `DEFAULT_MAX_DELEGATION_DEPTH`. */
+    maxDepth?: number;
+}
+export declare const DEFAULT_DELEGATION_TIMEOUT_MS = 120000;
+export declare 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 declare const DELEGATION_DEPTH_ENV = "TRELLIS_DELEGATION_DEPTH";
+export declare function agentBridgePath(homeDir: string): string;
+/** 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 declare function readDelegationDepth(env?: NodeJS.ProcessEnv): number;
+export declare function loadAgentBridgeConfig(homeDir: string): AgentBridgeConfig;
+export interface DelegatedCallResult {
+    status: "completed" | "failed" | "timeout";
+    output: string;
+    durationMs: number;
+    targetAgent: AgentId;
+    /** Present when the target reported one (best-effort extraction from
+     * `json`/`stream-json` output). Pass back as `sessionId` in a later
+     * call to continue this exact conversation, if the target has
+     * `resumeArgs` configured. */
+    sessionId?: string;
+}
+export interface RunDelegatedCallOptions {
+    cwd?: string;
+    timeoutMs?: number;
+    /** Overrides the target's default `persona` for this call only. */
+    persona?: string;
+    /** Resume a prior conversation instead of starting a fresh one.
+     * Requires the target to have `resumeArgs` configured. */
+    sessionId?: string;
+    /** The chain depth *before* this call (0 for a call that isn't itself
+     * part of a delegation chain). The spawned child sees `depth + 1`. */
+    depth?: number;
+}
+/** 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 declare function runDelegatedCall(targetAgent: AgentId, target: AgentBridgeTargetConfig, prompt: string, opts?: RunDelegatedCallOptions): Promise<DelegatedCallResult>;
+/** Best-effort structured interpretation of one line of a `stream-json`
+ * target's stdout, covering the four shapes documented by the community
+ * for Claude Code's non-interactive stream-json output (there is no
+ * official Anthropic schema — see upstream issue #24612): a `system/init`
+ * line, an `assistant` message carrying text or a `tool_use` block, a
+ * `user` message carrying a `tool_result` block, and the final `result`
+ * line. Anything that doesn't parse as JSON, or parses but doesn't match
+ * one of these shapes, returns `undefined` — the caller falls back to
+ * displaying the raw line rather than guessing. */
+export type ParsedStreamEvent = {
+    kind: "init";
+    sessionId?: string;
+} | {
+    kind: "text-delta";
+    text: string;
+} | {
+    kind: "tool-call";
+    toolCallId: string;
+    name: string;
+    input: unknown;
+} | {
+    kind: "tool-result";
+    toolCallId: string;
+    output: unknown;
+} | {
+    kind: "final";
+    output: string;
+    sessionId?: string;
+    protocol?: "zcode";
+};
+export declare function tryParseClaudeStreamJsonLine(line: string): ParsedStreamEvent | 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 declare function tryParseZcodeStreamJsonLine(line: string): ParsedStreamEvent | undefined;
+export interface StreamChunk {
+    /** Raw text as received from the child, one line (no trailing newline). */
+    raw: string;
+    /** Present only when `outputFormat: "stream-json"` and the line matched
+     * a recognized Claude Code shape — see `tryParseClaudeStreamJsonLine`. */
+    parsed?: ParsedStreamEvent;
+}
+export interface DelegatedStreamResult {
+    status: "completed" | "failed" | "timeout" | "cancelled";
+    output: string;
+    durationMs: number;
+    /** Chat targets are identified by an arbitrary string id (`chat-agents.yaml`
+     * has no `AgentId` constraint — see `chatAgents.ts`), unlike
+     * `DelegatedCallResult.targetAgent` which is always a real managed Agent. */
+    targetAgent: string;
+    sessionId?: string;
+}
+export interface RunDelegatedCallStreamingOptions extends Omit<RunDelegatedCallOptions, "depth"> {
+    /** Called once per line of stdout, as it arrives — not batched until the
+     * process exits, unlike `runDelegatedCall`. */
+    onChunk: (chunk: StreamChunk) => void;
+    /** The chain depth before this call, same meaning as
+     * `RunDelegatedCallOptions.depth`. */
+    depth?: number;
+    /** Aborting triggers the same SIGTERM→SIGKILL escalation as a timeout;
+     * the returned result has `status: "cancelled"` instead of `"timeout"`. */
+    signal?: AbortSignal;
+}
+/** 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 declare function runDelegatedCallStreaming(targetAgent: string, target: AgentBridgeTargetConfig, prompt: string, opts: RunDelegatedCallStreamingOptions): Promise<DelegatedStreamResult>;