agent-trellis 0.20.0 → 0.21.0

package/dist/lib/mcpConnect.js

@@ -14,7 +14,7 @@
  */
 import { Client, StreamableHTTPClientTransport, SSEClientTransport } from "@modelcontextprotocol/client";
 import { StdioClientTransport, getDefaultEnvironment } from "@modelcontextprotocol/client/stdio";
-import { resolveSecretEnv } from "./secretEnv.js";
+import { deliveredName, resolveSecretEnv } from "./secretEnv.js";
 import { extractTemplateVarNames } from "./envVarNames.js";
 export const DEFAULT_CONNECT_TIMEOUT_MS = 10_000;
 const FAILED_TRANSPORT_CLEANUP_TIMEOUT_MS = 1_000;
@@ -73,9 +73,20 @@ export async function connectStdio(def, secretsPolicy, timeoutMs, clientInfo) {
     // `${sourceName}` placeholder text a consumer with no `${VAR}` runtime
     // of its own (like this bridge) would otherwise crash on parsing
     // (trellis-migrate-env-var-alias, the real notion-on-pi bug).
-    const resolved = resolveSecretEnv([...(def.env ?? []), ...Object.values(envAliases)], secretsPolicy);
-    const namedEnv = Object.fromEntries((def.env ?? []).map((name) => [name, resolved[name] ?? ""]));
-    const aliasEnv = Object.fromEntries(Object.entries(envAliases).map(([targetKey, sourceName]) => [targetKey, resolved[sourceName] ?? ""]));
+    //
+    // Entries may be `mxenv://` references: the resolved map is keyed by
+    // DELIVERED name (the `KEY` segment for a reference, the entry itself
+    // for a bare name), and the spawned server receives values under
+    // delivered names — never the raw reference text as a variable name
+    // (mx-env-secret-source spec).
+    const resolved = await resolveSecretEnv([...(def.env ?? []), ...Object.values(envAliases)], secretsPolicy);
+    const namedEnv = Object.fromEntries((def.env ?? []).map((entry) => {
+        const delivered = deliveredName(entry);
+        return [delivered, resolved[delivered] ?? ""];
+    }));
+    const aliasEnv = Object.fromEntries(Object.entries(envAliases).map(([targetKey, sourceName]) => {
+        return [targetKey, resolved[deliveredName(sourceName)] ?? ""];
+    }));
     const transport = new StdioClientTransport({
         command: def.command,
         args: def.args,
@@ -91,11 +102,11 @@ export async function connectStdio(def, secretsPolicy, timeoutMs, clientInfo) {
     });
     return connectWithCleanup(client, transport, timeoutMs, `connect timed out after ${timeoutMs}ms`);
 }
-export function resolveHeaders(def, secretsPolicy) {
+export async function resolveHeaders(def, secretsPolicy) {
     if (!def.headers || Object.keys(def.headers).length === 0)
         return undefined;
     const names = Object.keys(def.headers).flatMap((key) => extractTemplateVarNames(def.headers[key]));
-    const resolved = resolveSecretEnv(names, secretsPolicy);
+    const resolved = await resolveSecretEnv(names, secretsPolicy);
     const result = {};
     for (const [key, template] of Object.entries(def.headers)) {
         result[key] = template.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_match, name) => resolved[name] ?? "");
@@ -104,7 +115,7 @@ export function resolveHeaders(def, secretsPolicy) {
 }
 export async function connectHttp(def, secretsPolicy, timeoutMs, clientInfo, authProvider) {
     const client = new Client(clientInfo, { capabilities: {}, versionNegotiation: { mode: "auto", probe: { timeoutMs } } });
-    const headers = resolveHeaders(def, secretsPolicy);
+    const headers = await resolveHeaders(def, secretsPolicy);
     // authProvider is the SDK's per-request credential seam: `token()` runs
     // as each request's headers are assembled and its result overrides
     // `requestInit`'s Authorization — the alternative to burning a Bearer
@@ -118,7 +129,7 @@ export async function connectHttp(def, secretsPolicy, timeoutMs, clientInfo, aut
 export async function connectSse(def, secretsPolicy, timeoutMs, clientInfo, authProvider) {
     // HTTP+SSE is a legacy transport; it cannot carry modern discovery.
     const client = new Client(clientInfo, { capabilities: {} });
-    const headers = resolveHeaders(def, secretsPolicy);
+    const headers = await resolveHeaders(def, secretsPolicy);
     const opts = {
         ...(headers ? { requestInit: { headers } } : {}),
         ...(authProvider ? { authProvider } : {}),

package/dist/lib/mcpMigrateRead.js

@@ -13,6 +13,7 @@
 import { execFileSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
+import { parseEnvEntry } from "./secretEnv.js";
 import { readJsonFile } from "./probeCommon.js";
 import { readServerEnvTable } from "./tomlSection.js";
 import { resolveZcodeProfile } from "../probes/zcode.js";
@@ -42,8 +43,19 @@ const VAR_REF_RE = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/;
  * independent derivations of it.
  */
 export function resolvedEnvTextMap(def) {
-    const nameRefs = Object.fromEntries((def.env ?? []).map((name) => [name, `\${${name}}`]));
-    const aliasRefs = Object.fromEntries(Object.entries(def.envAliases ?? {}).map(([targetKey, sourceName]) => [targetKey, `\${${sourceName}}`]));
+    // `mxenv://` reference entries render as `${KEY}` under their DELIVERED
+    // name (the KEY segment) — the raw reference text never appears as a
+    // variable name in a native-client config (mx-env-secret-source spec).
+    const nameRefs = Object.fromEntries((def.env ?? []).map((entry) => {
+        const parsed = parseEnvEntry(entry);
+        const delivered = parsed.kind === "invalid" ? entry : parsed.delivered;
+        return [delivered, `\${${delivered}}`];
+    }));
+    const aliasRefs = Object.fromEntries(Object.entries(def.envAliases ?? {}).map(([targetKey, source]) => {
+        const parsed = parseEnvEntry(source);
+        const delivered = parsed.kind === "invalid" ? source : parsed.delivered;
+        return [targetKey, `\${${delivered}}`];
+    }));
     return { ...nameRefs, ...aliasRefs, ...(def.staticEnv ?? {}) };
 }
 function splitJsonEnvMap(env) {

package/dist/lib/secretEnv.d.ts

@@ -4,9 +4,15 @@
  * `process.env[name]` lookup — so they can never disagree about where a
  * declared name's value comes from (design.md D1).
  *
- * Dependency-free by design, same as src/lib/envVarNames.ts: a full
- * dotenv library's quoting/escaping/interpolation rules are more than
- * this narrow need requires (design.md D4).
+ * Entries are either bare environment variable names (byte-identical
+ * legacy semantics: `env_file` sole-source when set, otherwise ambient
+ * `process.env`) or `mxenv://<profile>/<KEY>` references resolved
+ * through the `@morphixai/mxenv-core` SDK and delivered under the `KEY`
+ * segment (mx-env-secret-source spec). The dotenv half stays
+ * dependency-free — a full dotenv library's quoting/escaping/
+ * interpolation rules are more than this narrow need requires — while
+ * the reference grammar is owned by the SDK and never re-implemented
+ * here.
  */
 import type { SecretsPolicy } from "../core/types.js";
 import type { BackupSession } from "./backup.js";
@@ -17,12 +23,51 @@ import type { BackupSession } from "./backup.js";
 export declare function isValidSecretVarName(name: string): boolean;
 export declare function parseDotenv(content: string): Record<string, string>;
 /**
- * `policy.envFile` set: it is the SOLE source — a name absent from it
- * resolves to `undefined`, `process.env` is never consulted (a silent
- * fallback would defeat the isolation this exists to offer). Unset:
- * reads `process.env` directly, identical to every pre-existing caller.
+ * One declared `env` entry / `envAliases` source value, classified.
+ * Strict whole-string matching: an entry is a reference only when the
+ * entire entry is exactly one `mxenv://<profile>/<KEY>` (reconstructed
+ * from the SDK parser's match). Anything containing reference-shaped
+ * text that does not fully match — including the rejected legacy
+ * `mx-env://` scheme, which the SDK parser throws on — is `invalid`,
+ * never a silently-resolved bare name (mx-env-secret-source D6).
  */
-export declare function resolveSecretEnv(names: string[], policy: SecretsPolicy): Record<string, string | undefined>;
+export type SecretEnvEntry = {
+    kind: "ref";
+    profile: string;
+    key: string;
+    delivered: string;
+} | {
+    kind: "name";
+    delivered: string;
+} | {
+    kind: "invalid";
+    entry: string;
+};
+/** Delivered name for an entry (KEY segment for a reference, the entry
+ * itself otherwise; an invalid entry passes through unchanged so error
+ * paths can still name it). The single derivation every renderer and
+ * consumer uses — never re-derive from the raw text. */
+export declare function deliveredName(entry: string): string;
+export declare function parseEnvEntry(entry: string): SecretEnvEntry;
+/**
+ * Result keyed by DELIVERED name: the `KEY` segment for a reference,
+ * the entry itself for a bare name (mx-env-secret-source spec).
+ *
+ * `policy.envFile` set: it is the SOLE source for bare names — a name
+ * absent from it resolves to `undefined`, `process.env` is never
+ * consulted (a silent fallback would defeat the isolation this exists
+ * to offer). Unset: bare names read `process.env` directly, identical
+ * to every pre-existing caller. References NEVER consult `env_file` or
+ * ambient env: they resolve from the composed mxenv profile only, so a
+ * same-named ambient variable cannot shadow the composed value.
+ *
+ * Invalid entries reject the batch with a descriptive error; audit and
+ * the plan pre-check pre-classify to turn them into findings/conflicts
+ * before this point (the bridge only ever sees pre-checked defs).
+ * Compositions are cached per batch (one `ReferenceResolver` per call,
+ * not per name).
+ */
+export declare function resolveSecretEnv(entries: string[], policy: SecretsPolicy): Promise<Record<string, string | undefined>>;
 export type WriteLocalSecretOutcome = "created" | "already-present" | "conflict";
 /**
  * `trellis migrate`'s static-env secret extraction

package/dist/lib/secretEnv.js

@@ -4,12 +4,20 @@
  * `process.env[name]` lookup — so they can never disagree about where a
  * declared name's value comes from (design.md D1).
  *
- * Dependency-free by design, same as src/lib/envVarNames.ts: a full
- * dotenv library's quoting/escaping/interpolation rules are more than
- * this narrow need requires (design.md D4).
+ * Entries are either bare environment variable names (byte-identical
+ * legacy semantics: `env_file` sole-source when set, otherwise ambient
+ * `process.env`) or `mxenv://<profile>/<KEY>` references resolved
+ * through the `@morphixai/mxenv-core` SDK and delivered under the `KEY`
+ * segment (mx-env-secret-source spec). The dotenv half stays
+ * dependency-free — a full dotenv library's quoting/escaping/
+ * interpolation rules are more than this narrow need requires — while
+ * the reference grammar is owned by the SDK and never re-implemented
+ * here.
  */
 import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname } from "node:path";
+import { findMxEnvReferences, loadConfigLayers, ReferenceResolver } from "@morphixai/mxenv-core";
 const LINE_RE = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/;
 const VAR_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /** The name half of LINE_RE, standing alone: what counts as a variable
@@ -34,22 +42,77 @@ export function parseDotenv(content) {
 function loadEnvFile(path) {
     return existsSync(path) ? parseDotenv(readFileSync(path, "utf-8")) : {};
 }
+/** Delivered name for an entry (KEY segment for a reference, the entry
+ * itself otherwise; an invalid entry passes through unchanged so error
+ * paths can still name it). The single derivation every renderer and
+ * consumer uses — never re-derive from the raw text. */
+export function deliveredName(entry) {
+    const parsed = parseEnvEntry(entry);
+    return parsed.kind === "invalid" ? entry : parsed.delivered;
+}
+export function parseEnvEntry(entry) {
+    if (entry.includes("mxenv://") || entry.includes("mx-env://")) {
+        try {
+            const refs = findMxEnvReferences(entry);
+            if (refs.length === 1 && `mxenv://${refs[0].profile}/${refs[0].key}` === entry) {
+                return { kind: "ref", profile: refs[0].profile, key: refs[0].key, delivered: refs[0].key };
+            }
+        }
+        catch {
+            // legacy scheme rejection from the SDK parser — falls through to invalid
+        }
+        return { kind: "invalid", entry };
+    }
+    return { kind: "name", delivered: entry };
+}
 /**
- * `policy.envFile` set: it is the SOLE source — a name absent from it
- * resolves to `undefined`, `process.env` is never consulted (a silent
- * fallback would defeat the isolation this exists to offer). Unset:
- * reads `process.env` directly, identical to every pre-existing caller.
+ * Result keyed by DELIVERED name: the `KEY` segment for a reference,
+ * the entry itself for a bare name (mx-env-secret-source spec).
+ *
+ * `policy.envFile` set: it is the SOLE source for bare names — a name
+ * absent from it resolves to `undefined`, `process.env` is never
+ * consulted (a silent fallback would defeat the isolation this exists
+ * to offer). Unset: bare names read `process.env` directly, identical
+ * to every pre-existing caller. References NEVER consult `env_file` or
+ * ambient env: they resolve from the composed mxenv profile only, so a
+ * same-named ambient variable cannot shadow the composed value.
+ *
+ * Invalid entries reject the batch with a descriptive error; audit and
+ * the plan pre-check pre-classify to turn them into findings/conflicts
+ * before this point (the bridge only ever sees pre-checked defs).
+ * Compositions are cached per batch (one `ReferenceResolver` per call,
+ * not per name).
  */
-export function resolveSecretEnv(names, policy) {
+export async function resolveSecretEnv(entries, policy) {
+    const parsed = entries.map(parseEnvEntry);
+    const invalid = parsed.find((p) => p.kind === "invalid");
+    if (invalid) {
+        throw new Error(`[trellis] invalid mxenv:// reference entry: ${invalid.entry} — expected mxenv://<profile>/<KEY>`);
+    }
     const result = {};
-    if (policy.envFile) {
-        const map = loadEnvFile(policy.envFile);
-        for (const name of names)
-            result[name] = map[name];
+    // Delivered-name collisions (several entries delivering one name):
+    // references are authoritative — a composed value never loses to a bare
+    // name's ambient/file value (ambient must not shadow references); a
+    // DEFINED value never loses to undefined; within one class the first
+    // declaration wins; bare names only fill keys nothing has filled.
+    const refs = parsed.filter((p) => p.kind === "ref");
+    if (refs.length > 0) {
+        const resolver = new ReferenceResolver(loadConfigLayers({ cwd: homedir(), homeDir: homedir() }), {});
+        for (const ref of refs) {
+            if (result[ref.delivered] !== undefined)
+                continue;
+            const { value } = await resolver.valueOf(ref.profile, ref.key);
+            result[ref.delivered] = value;
+        }
     }
-    else {
-        for (const name of names)
-            result[name] = process.env[name];
+    const names = parsed.filter((p) => p.kind === "name");
+    if (names.length > 0) {
+        const fileMap = policy.envFile ? loadEnvFile(policy.envFile) : undefined;
+        for (const name of names) {
+            if (result[name.delivered] !== undefined)
+                continue;
+            result[name.delivered] = fileMap ? fileMap[name.delivered] : process.env[name.delivered];
+        }
     }
     return result;
 }

package/dist/lib/tomlSection.js

@@ -8,6 +8,7 @@
  * ever needs to recognize table headers and render a bounded, known
  * shape (`McpServerDef`), never general TOML.
  */
+import { deliveredName } from "./secretEnv.js";
 /**
  * Matches a TOML table header line, and *only* a table header line — the
  * entire trimmed line must be exactly `[key.path]` or `[[key.path]]`,
@@ -146,7 +147,7 @@ export function renderServerSection(name, def) {
         if (def.args && def.args.length > 0)
             lines.push(`args = ${tomlStringArray(def.args)}`);
         if (def.env && def.env.length > 0)
-            lines.push(`env_vars = ${tomlStringArray(def.env)}`);
+            lines.push(`env_vars = ${tomlStringArray(def.env.map(deliveredName))}`);
     }
     else {
         if (def.url)
@@ -160,7 +161,7 @@ export function renderServerSection(name, def) {
     // expands it from its own ambient environment, the same mechanism
     // `env_vars` already relies on for a same-named reference
     // (trellis-migrate-env-var-alias D3).
-    const aliasEntries = Object.entries(def.envAliases ?? {}).map(([targetKey, sourceName]) => [targetKey, `\${${sourceName}}`]);
+    const aliasEntries = Object.entries(def.envAliases ?? {}).map(([targetKey, sourceName]) => [targetKey, `\${${deliveredName(sourceName)}}`]);
     const staticEnvEntries = [...aliasEntries, ...Object.entries(def.staticEnv ?? {})];
     if (staticEnvEntries.length > 0) {
         lines.push(`[${envHeader(name)}]`);

package/dist/lib/workspaceDoctor.d.ts

@@ -56,4 +56,4 @@ export interface WorkspaceDoctorSection {
     /** zcode's user-level-first deviation notices (empty otherwise). */
     precedenceWarnings: string[];
 }
-export declare function collectWorkspaceDoctorSection(canonical: CanonicalSource): WorkspaceDoctorSection | undefined;
+export declare function collectWorkspaceDoctorSection(canonical: CanonicalSource): Promise<WorkspaceDoctorSection | undefined>;

package/dist/lib/workspaceDoctor.js

@@ -11,7 +11,7 @@
  */
 import { existsSync, readFileSync } from "node:fs";
 import { parse as parseToml } from "smol-toml";
-import { resolveSecretEnv } from "./secretEnv.js";
+import { deliveredName, parseEnvEntry, resolveSecretEnv } from "./secretEnv.js";
 import { loadWorkspaceRendered, workspaceMcpConfigPath, workspacePrecedenceWarnings } from "./workspaceMcp.js";
 const VAR_REF_RE = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/;
 function collectVarRefs(canonical) {
@@ -86,7 +86,7 @@ function unmarkedEntries(agentId, configPath, recorded) {
     }
     return { kind: "ok", names: names.filter((name) => recorded[name] === undefined) };
 }
-export function collectWorkspaceDoctorSection(canonical) {
+export async function collectWorkspaceDoctorSection(canonical) {
     const workspace = canonical.workspace;
     if (!workspace)
         return undefined;
@@ -101,8 +101,12 @@ export function collectWorkspaceDoctorSection(canonical) {
     // overridden.
     const tombstoned = workspace.shadowed.filter((entry) => entry.startsWith("mcp:") && canonical.mcp.servers[entry.slice(4)] === undefined);
     const refs = collectVarRefs(canonical);
-    const resolved = resolveSecretEnv([...new Set(refs.map((r) => r.name))], canonical.secretsPolicy);
-    const unresolvedVars = refs.filter((r) => resolved[r.name] === undefined);
+    // Malformed `mxenv://` entries are unresolved as-is (they name themselves);
+    // they must never reach resolveSecretEnv, which rejects the batch.
+    const invalid = refs.filter((r) => parseEnvEntry(r.name).kind === "invalid");
+    const resolvableRefs = refs.filter((r) => parseEnvEntry(r.name).kind !== "invalid");
+    const resolved = await resolveSecretEnv([...new Set(resolvableRefs.map((r) => r.name))], canonical.secretsPolicy);
+    const unresolvedVars = [...invalid, ...resolvableRefs.filter((r) => resolved[deliveredName(r.name)] === undefined)];
     const manifest = loadWorkspaceRendered(workspace.root);
     const unmigrated = [];
     const tomlFindings = [];

package/dist/lib/workspaceMcp.d.ts

@@ -53,5 +53,5 @@ export declare function renderWorkspaceManifestEntry(agentId: AgentId, name: str
  * `applyWorkspaceMcp`; this exists only for adoption, where no delivery
  * write to that agent's file has happened yet. */
 export declare function recordWorkspaceRendered(workspaceRoot: string, agentId: AgentId, name: string, rendered: unknown, backup: BackupSession): void;
-export declare function planWorkspaceMcp(agentId: AgentId, canonical: CanonicalSource): AdapterPlanItem[];
+export declare function planWorkspaceMcp(agentId: AgentId, canonical: CanonicalSource): Promise<AdapterPlanItem[]>;
 export declare function applyWorkspaceMcp(agentId: AgentId, canonical: CanonicalSource, items: AdapterPlanItem[], backup: BackupSession): void;

package/dist/lib/workspaceMcp.js

@@ -140,7 +140,7 @@ export function recordWorkspaceRendered(workspaceRoot, agentId, name, rendered,
     mkdirSync(dirname(path), { recursive: true });
     backup.writeFile(path, `${JSON.stringify(next, null, 2)}\n`);
 }
-export function planWorkspaceMcp(agentId, canonical) {
+export async function planWorkspaceMcp(agentId, canonical) {
     const workspace = canonical.workspace;
     if (!workspace)
         return [];
@@ -151,7 +151,7 @@ export function planWorkspaceMcp(agentId, canonical) {
     const layer = (item) => ({ ...item, layer: "workspace" });
     if (agentId === "codex") {
         const content = existsSync(configPath) ? readFileSync(configPath, "utf-8") : "";
-        const { desired, conflicts } = resolveMcpPlan(agentId, mcp, canonical.managedAgents, canonical.secretsPolicy);
+        const { desired, conflicts } = await resolveMcpPlan(agentId, mcp, canonical.managedAgents, canonical.secretsPolicy);
         const items = [];
         for (const { name, def } of desired) {
             const current = currentServerSectionText(content, name);
@@ -183,13 +183,13 @@ export function planWorkspaceMcp(agentId, canonical) {
     }
     if (agentId === "zcode") {
         const parsed = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf-8")) : undefined;
-        const items = planZcodeMcp({ configPath, parsed, mcp, managedAgents: canonical.managedAgents, policy: canonical.secretsPolicy, ownership }).map(layer);
+        const items = (await planZcodeMcp({ configPath, parsed, mcp, managedAgents: canonical.managedAgents, policy: canonical.secretsPolicy, ownership })).map(layer);
         const servers = (parsed?.mcp?.servers ?? {});
         return guardUnmarkedOverwrite(items, (item) => servers[item.mcpWrite.name] !== undefined && ownership[item.mcpWrite.name] === undefined);
     }
     const parsed = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf-8")) : undefined;
     const render = agentId === "pi" ? piRenderer : undefined;
-    const planned = planJsonMcp({
+    const planned = (await planJsonMcp({
         configPath,
         parsed,
         mcp,
@@ -198,7 +198,7 @@ export function planWorkspaceMcp(agentId, canonical) {
         policy: canonical.secretsPolicy,
         ownership,
         ...(render ? { render } : {}),
-    }).map(layer);
+    })).map(layer);
     const existing = (parsed?.mcpServers ?? {});
     const guarded = guardUnmarkedOverwrite(planned, (item) => existing[item.mcpWrite.name] !== undefined && ownership[item.mcpWrite.name] === undefined);
     if (agentId !== "pi")