agent-trellis 0.8.0 → 0.8.2

package/dist/commands/secretsAudit.js

@@ -26,7 +26,9 @@ import { loadCanonicalSource } from "../core/canonical.js";
 import { ClaudeCodeAdapter } from "../adapters/claude-code.js";
 import { CodexAdapter } from "../adapters/codex.js";
 import { KiroAdapter } from "../adapters/kiro.js";
-import { declaredEnvNames, extractJsonEnvVarNames, extractTomlEnvVarNames } from "../lib/envVarNames.js";
+import { ZcodeAdapter } from "../adapters/zcode.js";
+import { declaredEnvNames, extractJsonEnvVarNames, extractTomlEnvVarNames, extractZcodeEnvVarNames } from "../lib/envVarNames.js";
+import { resolveZcodeProfile } from "../probes/zcode.js";
 import { resolveSecretEnv } from "../lib/secretEnv.js";
 /** Only agents in `managedAgents` — a present-but-unmanaged agent's config
  * file is never even read (trellis-managed-agents), same restriction as
@@ -38,6 +40,7 @@ function auditedAgents(homeDir, managedAgents) {
         { id: "claude-code", probe: () => new ClaudeCodeAdapter(homeDir).probe(), configPath: (h) => join(h, ".claude.json"), extractNames: extractJsonEnvVarNames },
         { id: "codex", probe: () => new CodexAdapter(homeDir).probe(), configPath: (h) => join(h, ".codex", "config.toml"), extractNames: extractTomlEnvVarNames },
         { id: "kiro", probe: () => new KiroAdapter(homeDir).probe(), configPath: (h) => join(h, ".kiro", "settings", "mcp.json"), extractNames: extractJsonEnvVarNames },
+        { id: "zcode", probe: () => new ZcodeAdapter(homeDir).probe(), configPath: (h) => resolveZcodeProfile(h)?.configPath ?? join(h, ".zcode", "cli", "config.json"), extractNames: extractZcodeEnvVarNames },
     ];
     return all.filter((a) => managedAgents.includes(a.id));
 }

package/dist/commands/skill.d.ts

@@ -9,6 +9,7 @@
  */
 import type { AgentId } from "../core/types.js";
 import { type BackupSession } from "../lib/backup.js";
+import type { SyncReport } from "./sync.js";
 export type BuiltinSkillUpdateAction = "create" | "update" | "already-current";
 export interface BuiltinSkillUpdatePlan {
     name: "trellis-runtime";
@@ -44,25 +45,53 @@ export interface SkillAddPlan {
     sourceDir?: string;
 }
 export declare function collectSkillAddPlan(name: string, fromPath: string, homeDir?: string): SkillAddPlan;
-export declare function applySkillAddPlan(plan: SkillAddPlan, homeDir?: string): void;
+export declare function applySkillAddPlan(plan: SkillAddPlan, homeDir?: string, backup?: BackupSession): void;
+export interface SkillAddOutcome {
+    plan: SkillAddPlan;
+    sync?: SyncReport;
+}
+/**
+ * See `applyMcpAddWithSync`'s doc comment (mcp.ts) — same split, same
+ * reason: a non-CLI caller needs the structured result a JSON-mode CLI
+ * run prints, without scraping stdout. Also opens its own backup session
+ * around the canonical copy-in, for the same reason `applyMcpAddWithSync`
+ * does (trellis-gui tasks.md 3.5): this direct write used to be the one
+ * path in this file with no backup/rollback trace at all.
+ */
+export declare function applySkillAddWithSync(plan: SkillAddPlan, opts?: {
+    homeDir?: string;
+    dryRun?: boolean;
+    backupSession?: BackupSession;
+}): Promise<SkillAddOutcome>;
 export declare function runSkillAdd(name: string, fromPath: string, opts?: {
     homeDir?: string;
     json?: boolean;
     dryRun?: boolean;
-}): {
+}): Promise<{
     exitCode: number;
-};
+}>;
 export type SkillRemoveAction = "removed" | "not-found";
 export interface SkillRemovePlan {
     name: string;
     action: SkillRemoveAction;
 }
 export declare function collectSkillRemovePlan(name: string, homeDir?: string): SkillRemovePlan;
-export declare function applySkillRemovePlan(plan: SkillRemovePlan, homeDir?: string): void;
+export declare function applySkillRemovePlan(plan: SkillRemovePlan, homeDir?: string, backup?: BackupSession): void;
+export interface SkillRemoveOutcome {
+    plan: SkillRemovePlan;
+    sync?: SyncReport;
+}
+/** See `applySkillAddWithSync`'s doc comment — same split, same reason,
+ * same own-backup-session fix. */
+export declare function applySkillRemoveWithSync(plan: SkillRemovePlan, opts?: {
+    homeDir?: string;
+    dryRun?: boolean;
+    backupSession?: BackupSession;
+}): Promise<SkillRemoveOutcome>;
 export declare function runSkillRemove(name: string, opts?: {
     homeDir?: string;
     json?: boolean;
     dryRun?: boolean;
-}): {
+}): Promise<{
     exitCode: number;
-};
+}>;

package/dist/commands/skill.js

@@ -18,6 +18,7 @@ import { loadCanonicalSource } from "../core/canonical.js";
 import { resolveScope } from "../core/types.js";
 import { isBuiltinSkillName } from "../lib/builtinSkills.js";
 import { openBackupSession } from "../lib/backup.js";
+import { collectSyncReport, printReport as printSyncReport } from "./sync.js";
 function builtinSkillTemplate() {
     const here = dirname(fileURLToPath(import.meta.url));
     return readFileSync(join(here, "..", "..", "schema", "builtin-skills", "trellis-runtime", "SKILL.md"), "utf8");
@@ -97,27 +98,56 @@ export function collectSkillAddPlan(name, fromPath, homeDir = homedir()) {
             return { name, action: "conflict", detail: `canonical skills/${name}/ already exists with different content — resolve by hand` };
     }
 }
-export function applySkillAddPlan(plan, homeDir = homedir()) {
+export function applySkillAddPlan(plan, homeDir = homedir(), backup) {
     if (plan.action !== "create" || !plan.sourceDir)
         return;
     const dest = join(homeDir, ".trellis", "skills", plan.name);
+    if (backup) {
+        backup.createDirFromSource(dest, plan.sourceDir);
+        return;
+    }
     mkdirSync(dest, { recursive: true });
     cpSync(plan.sourceDir, dest, { recursive: true });
 }
-export function runSkillAdd(name, fromPath, opts = {}) {
+/**
+ * See `applyMcpAddWithSync`'s doc comment (mcp.ts) — same split, same
+ * reason: a non-CLI caller needs the structured result a JSON-mode CLI
+ * run prints, without scraping stdout. Also opens its own backup session
+ * around the canonical copy-in, for the same reason `applyMcpAddWithSync`
+ * does (trellis-gui tasks.md 3.5): this direct write used to be the one
+ * path in this file with no backup/rollback trace at all.
+ */
+export async function applySkillAddWithSync(plan, opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
-    const plan = collectSkillAddPlan(name, fromPath, homeDir);
+    const ownSession = !opts.dryRun && !opts.backupSession && plan.action === "create" ? openBackupSession(homeDir, "skill-add") : undefined;
+    const session = opts.backupSession ?? ownSession;
     if (!opts.dryRun && plan.action === "create") {
-        applySkillAddPlan(plan, homeDir);
+        applySkillAddPlan(plan, homeDir, session);
     }
+    ownSession?.finalize();
+    const failed = plan.action === "conflict" || plan.action === "invalid-source";
+    let syncReport;
+    if (!failed && plan.action === "create" && existsSync(join(homeDir, ".trellis"))) {
+        syncReport = await collectSyncReport({ target: "skills", homeDir, dryRun: opts.dryRun });
+    }
+    return { plan, ...(syncReport ? { sync: syncReport } : {}) };
+}
+export async function runSkillAdd(name, fromPath, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const plan = collectSkillAddPlan(name, fromPath, homeDir);
+    const { sync: syncReport } = await applySkillAddWithSync(plan, { homeDir, dryRun: opts.dryRun });
+    const failed = plan.action === "conflict" || plan.action === "invalid-source";
     if (opts.json) {
-        console.log(JSON.stringify(plan, null, 2));
+        console.log(JSON.stringify(syncReport ? { ...plan, sync: syncReport } : plan, null, 2));
     }
     else {
         console.log(`${opts.dryRun ? "[dry run] " : ""}skill add ${name}`);
         console.log(`  [${plan.action}] ${plan.detail}`);
+        if (syncReport)
+            printSyncReport(syncReport, opts.dryRun ?? false);
     }
-    return { exitCode: plan.action === "conflict" || plan.action === "invalid-source" ? 1 : 0 };
+    const syncConflict = syncReport?.reports.some((r) => r.items.some((i) => i.action === "conflict")) ?? false;
+    return { exitCode: failed || syncConflict ? 1 : 0 };
 }
 export function collectSkillRemovePlan(name, homeDir = homedir()) {
     if (isBuiltinSkillName(name))
@@ -125,25 +155,49 @@ export function collectSkillRemovePlan(name, homeDir = homedir()) {
     const dir = join(homeDir, ".trellis", "skills", name);
     return { name, action: existsSync(dir) ? "removed" : "not-found" };
 }
-export function applySkillRemovePlan(plan, homeDir = homedir()) {
+export function applySkillRemovePlan(plan, homeDir = homedir(), backup) {
     if (plan.action !== "removed")
         return;
-    rmSync(join(homeDir, ".trellis", "skills", plan.name), { recursive: true, force: true });
+    const dir = join(homeDir, ".trellis", "skills", plan.name);
+    if (backup) {
+        backup.removeDir(dir);
+        return;
+    }
+    rmSync(dir, { recursive: true, force: true });
 }
-export function runSkillRemove(name, opts = {}) {
+/** See `applySkillAddWithSync`'s doc comment — same split, same reason,
+ * same own-backup-session fix. */
+export async function applySkillRemoveWithSync(plan, opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
-    const plan = collectSkillRemovePlan(name, homeDir);
+    const ownSession = !opts.dryRun && !opts.backupSession && plan.action === "removed" ? openBackupSession(homeDir, "skill-remove") : undefined;
+    const session = opts.backupSession ?? ownSession;
     if (!opts.dryRun) {
-        applySkillRemovePlan(plan, homeDir);
+        applySkillRemovePlan(plan, homeDir, session);
+    }
+    ownSession?.finalize();
+    const failed = plan.action === "not-found";
+    let syncReport;
+    if (!failed && existsSync(join(homeDir, ".trellis"))) {
+        syncReport = await collectSyncReport({ target: "skills", homeDir, dryRun: opts.dryRun });
     }
+    return { plan, ...(syncReport ? { sync: syncReport } : {}) };
+}
+export async function runSkillRemove(name, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const plan = collectSkillRemovePlan(name, homeDir);
+    const { sync: syncReport } = await applySkillRemoveWithSync(plan, { homeDir, dryRun: opts.dryRun });
+    const failed = plan.action === "not-found";
     if (opts.json) {
-        console.log(JSON.stringify(plan, null, 2));
+        console.log(JSON.stringify(syncReport ? { ...plan, sync: syncReport } : plan, null, 2));
     }
     else if (plan.action === "not-found") {
         console.error(`"${name}" is not a canonical skill — nothing to remove.`);
     }
     else {
         console.log(`${opts.dryRun ? "[dry run] " : ""}removed skill "${name}" from canonical source.`);
+        if (syncReport)
+            printSyncReport(syncReport, opts.dryRun ?? false);
     }
-    return { exitCode: plan.action === "not-found" ? 1 : 0 };
+    const syncConflict = syncReport?.reports.some((r) => r.items.some((i) => i.action === "conflict")) ?? false;
+    return { exitCode: failed || syncConflict ? 1 : 0 };
 }

package/dist/commands/sync.js

@@ -12,6 +12,7 @@ import { CodexAdapter } from "../adapters/codex.js";
 import { KiroAdapter } from "../adapters/kiro.js";
 import { PiAdapter } from "../adapters/pi.js";
 import { KimiCodeAdapter } from "../adapters/kimi-code.js";
+import { ZcodeAdapter } from "../adapters/zcode.js";
 import { openBackupSession } from "../lib/backup.js";
 const ADAPTER_FACTORY = {
     "claude-code": (homeDir) => new ClaudeCodeAdapter(homeDir),
@@ -19,6 +20,7 @@ const ADAPTER_FACTORY = {
     kiro: (homeDir) => new KiroAdapter(homeDir),
     pi: (homeDir) => new PiAdapter(homeDir),
     "kimi-code": (homeDir) => new KimiCodeAdapter(homeDir),
+    zcode: (homeDir) => new ZcodeAdapter(homeDir),
 };
 /** Only agents in `canonical.managedAgents` — an agent present on this
  * machine but not managed gets no adapter at all, not a zero-item plan
@@ -60,7 +62,7 @@ export async function collectSyncReport(opts = {}) {
             // out (found via the sandbox: every agent reported "already in
             // sync" even with real create items pending).
             const kind = opts.target === "skills" ? "skill" : "instructions";
-            items = items.filter((item) => item.kind === kind);
+            items = items.filter((item) => item.kind === kind || (kind === "skill" && item.kind === "zcode-skill-control"));
         }
         if (!opts.dryRun) {
             await adapter.apply(items, backup);

package/dist/core/adapter.d.ts

@@ -46,7 +46,7 @@ export interface AdapterPlanItem {
      * a completely different target file and merge mechanism (see
      * `approvedEnvVars` below) from `"mcp"`, not something the other
      * three agents have an equivalent of. */
-    kind: "skill" | "instructions" | "mcp" | "extension" | "kiro-approved-env-vars";
+    kind: "skill" | "instructions" | "mcp" | "extension" | "kiro-approved-env-vars" | "zcode-skill-control";
     /** Human-readable description of one change this adapter would make
      * ("create" / "remove") or why it refused to ("conflict"). */
     description: string;
@@ -88,6 +88,16 @@ export interface AdapterPlanItem {
      * for Kiro, never a subtraction (trellis-kiro-approved-env-vars
      * design.md D3/D4). */
     approvedEnvVars?: string[];
+    /** ZCode Runtime-only isolation. `null` means the previous profile did
+     * not declare the value and restoration must remove the property. */
+    zcodeSkillControls?: {
+        featuresSkill: boolean | null;
+        skillsEnabled: boolean | null;
+        previous?: {
+            featuresSkill: boolean | null;
+            skillsEnabled: boolean | null;
+        };
+    };
 }
 export interface AdapterVerifyResult {
     ok: boolean;

package/dist/core/types.d.ts

@@ -6,7 +6,7 @@
  */
 export type Transport = "stdio" | "http" | "sse";
 export type McpAuthMode = "oauth";
-export type AgentId = "claude-code" | "codex" | "kiro" | "pi" | "kimi-code";
+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

package/dist/core/types.js

@@ -10,6 +10,7 @@ export const ALL_AGENTS = [
     "kiro",
     "pi",
     "kimi-code",
+    "zcode",
 ];
 /**
  * `managedAgents` is the hard outer boundary (trellis-managed-agents

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>;