agent-trellis 0.19.0 → 0.21.0

package/dist/lib/mcpToolRegistry.js

@@ -81,12 +81,23 @@ export function allocateExposedToolNames(candidates) {
         // registry (for example `fixture__env` reaching the Runtime provider).
         // Do not add a second provider prefix around it.
         const sourceQualified = normalized.includes("__") || normalized === source || normalized.startsWith(`${source}_`) || normalized.startsWith(`${source}__`);
+        // Narrower than `sourceQualified`: for forced-prefix candidates the
+        // exemption applies only when the tool name already starts with ITS
+        // OWN server's name (a second prefix would be redundant, e.g.
+        // `tanka__tanka_memo_search`). A tool that merely contains `__`
+        // (`b__c`) or gained a `__hash` length bound still needs its server
+        // prefix to be identifiable.
+        const serverRedundant = normalized === source || normalized.startsWith(`${source}_`) || normalized.startsWith(`${source}__`);
         const unique = (counts.get(candidate.toolName) ?? 0) === 1;
-        const base = unique && normalized.length > SHORT_EXPOSED_TOOL_NAME_LENGTH
-            ? normalized
-            : unique && sourceQualified
+        const base = candidate.alwaysPrefix
+            ? serverRedundant
                 ? normalized
-                : prefixedToolName(candidate.serverName, candidate.toolName);
+                : prefixedToolName(candidate.serverName, candidate.toolName)
+            : unique && normalized.length > SHORT_EXPOSED_TOOL_NAME_LENGTH
+                ? normalized
+                : unique && sourceQualified
+                    ? normalized
+                    : prefixedToolName(candidate.serverName, candidate.toolName);
         let exposed = base;
         let suffix = 2;
         while (used.has(exposed)) {
@@ -122,7 +133,7 @@ export class McpToolRegistry {
      */
     add(serverName, upstream, tools) {
         for (const tool of tools)
-            this.candidates.push({ serverName, toolName: tool.name, upstream, tool });
+            this.candidates.push({ serverName, toolName: tool.name, upstream, tool, alwaysPrefix: true });
         this.rebuild();
         const added = tools.map((tool) => this.exposedNameFor(serverName, tool.name)).filter((name) => name !== undefined);
         return { added, skipped: [] };
@@ -141,7 +152,7 @@ export class McpToolRegistry {
         this.candidates.length = 0;
         this.candidates.push(...kept);
         for (const tool of tools)
-            this.candidates.push({ serverName, toolName: tool.name, upstream, tool });
+            this.candidates.push({ serverName, toolName: tool.name, upstream, tool, alwaysPrefix: true });
         this.rebuild();
         const added = tools.map((tool) => this.exposedNameFor(serverName, tool.name)).filter((name) => name !== undefined);
         return { added, skipped: [] };
@@ -154,8 +165,13 @@ export class McpToolRegistry {
         return undefined;
     }
     /** Every registered tool, under its prefixed name, in registration
-     * order. Each tool's own `description`/`inputSchema` and any additional
-     * fields the upstream sent are preserved verbatim; only `name` changes. */
+     * order. Each tool's own `inputSchema` and any additional fields the
+     * upstream sent are preserved verbatim; `name` changes, and the
+     * description gains a trailing `Source: <server>` line so an Agent can
+     * confirm the owning server without relying on the name alone
+     * (mcp-gateway-hosting: "Resold tool metadata identifies its upstream
+     * source"). The upstream's own description text is never altered or
+     * removed — the source line is appended. */
     listTools() {
         this.rebuild();
         return this.order.map((name) => {
@@ -163,7 +179,11 @@ export class McpToolRegistry {
             const title = name === entry.toolName || entry.tool.title !== undefined
                 ? entry.tool.title
                 : `${entry.serverName} / ${entry.toolName}`;
-            return { ...entry.tool, name, ...(title === undefined ? {} : { title }) };
+            const sourceLine = `Source: ${entry.serverName}`;
+            const description = entry.tool.description
+                ? `${entry.tool.description}\n\n${sourceLine}`
+                : sourceLine;
+            return { ...entry.tool, name, description, ...(title === undefined ? {} : { title }) };
         });
     }
     /** The owning upstream and original tool name for a prefixed name, or

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")