agent-trellis 0.21.0 → 0.22.0

package/dist/core/canonical.js

@@ -13,6 +13,8 @@ import { ALL_AGENTS, oauthClientMetadata } from "./types.js";
 import { fromServerDefYaml, toServerDefYaml } from "./mcpServerDef.js";
 import { loadWorkspaceLayer } from "../lib/workspace.js";
 import { mergeWorkspaceLayer } from "../lib/workspaceMerge.js";
+import { registeredSkillScope } from "../lib/skillScope.js";
+import { isBuiltinSkillName } from "../lib/builtinSkills.js";
 export { toServerDefYaml } from "./mcpServerDef.js";
 function trellisRoot(homeDir) {
     return join(homeDir, ".trellis");
@@ -166,6 +168,9 @@ export function validateSkillScopeYaml(path) {
         const doc = parseDocument(readFileSync(path, "utf-8"));
         if (doc.errors.length > 0)
             throw new Error(doc.errors.map((error) => error.message).join("; "));
+        const skills = doc.get("skills", true);
+        if (skills !== undefined && !isMap(skills))
+            throw new Error("skills must be a map of names to agent lists");
         return { ok: true };
     }
     catch (err) {
@@ -174,8 +179,7 @@ export function validateSkillScopeYaml(path) {
 }
 /**
  * Sets one Skill's canonical scope without rebuilding unrelated hand-authored
- * scope entries.  `undefined` removes this Skill's explicit entry and
- * therefore restores the normal all-managed default.
+ * scope entries. `undefined` removes registration, pausing distribution.
  */
 export function writeSkillScopeYaml(path, name, scope, backup) {
     if (!existsSync(path) && scope === undefined)
@@ -428,9 +432,6 @@ export function ensureShellEnvSource(rcPath, envFilePath, backup) {
     mkdirSync(dirname(rcPath), { recursive: true });
     persistText(rcPath, `${existing}${separator}${block}`, backup);
 }
-/** `undefined` if the name has no entry in scope.yaml's map — "shared with
- * 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, never "everyone." An unrecognized id is dropped with a
  * diagnostic, same posture as an unrecognized scope.yaml agent id. */
@@ -455,9 +456,9 @@ function scopeFor(map, name) {
     return map?.[name];
 }
 function validAgentIds(scope) {
-    if (!scope)
+    if (scope === undefined)
         return true;
-    return scope.every((id) => ALL_AGENTS.includes(id));
+    return Array.isArray(scope) && scope.every((id) => ALL_AGENTS.includes(id));
 }
 /**
  * Load-time literal-value scan for OAuth client metadata
@@ -497,7 +498,13 @@ export function loadCanonicalSource(arg = {}) {
     const scopeYaml = loadScopeYaml(join(root, "scope.yaml"));
     const skillDirs = listSkillDirs(join(root, "skills"));
     const knownSkillNames = new Set(skillDirs.map((s) => s.name));
-    const skills = skillDirs.map(({ name, dir }) => ({ name, dir, scope: scopeFor(scopeYaml.skills, name) }));
+    const skills = skillDirs.map(({ name, dir }) => {
+        const declared = scopeFor(scopeYaml.skills, name);
+        if (declared === undefined && !isBuiltinSkillName(name)) {
+            diagnostics.push(`scope.yaml: skill "${name}" has no registered agents — distribution paused; run trellis skill scope ${name} --agents <ids>`);
+        }
+        return { name, dir, scope: isBuiltinSkillName(name) && declared === undefined ? undefined : registeredSkillScope(declared) };
+    });
     const agentFiles = listMarkdownFiles(join(root, "agents"));
     const knownAgentProfileNames = new Set(agentFiles.map((a) => a.name));
     const agents = agentFiles.map(({ name, file }) => ({
@@ -523,7 +530,7 @@ export function loadCanonicalSource(arg = {}) {
                 diagnostics.push(`scope.yaml: "${section}.${name}" does not match any known ${section.slice(0, -1)} — ignored`);
             }
             else if (!validAgentIds(map?.[name])) {
-                diagnostics.push(`scope.yaml: "${section}.${name}" lists an unrecognized agent id — ignored`);
+                diagnostics.push(`scope.yaml: "${section}.${name}" lists an unrecognized agent id${section === "skills" ? " — distribution paused" : " — ignored"}`);
             }
         }
     }

package/dist/core/types.d.ts

@@ -39,11 +39,9 @@ export declare function oauthClientMetadata(auth: McpAuthMode | McpAuthConfig |
 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 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".
+ * Omitted scope resolves to the managed set. Custom skills are registered
+ * explicitly by the canonical/workspace loaders: missing or invalid skill
+ * registration becomes `[]` (paused). Other capability defaults are unchanged.
  */
 export type Scope = AgentId[] | undefined;
 /**
@@ -69,7 +67,9 @@ export interface McpServerDef {
     /** http/sse only */
     url?: string;
     /**
-     * http/sse only. Values are `${VAR}` references, same discipline as
+     * http/sse only. Values are `${VAR}` or `${mxenv://profile/KEY}` templates,
+     * the latter requiring Trellis-hosted resolution (gateway/runtime/pi).
+     * Same discipline as
      * `env` — never a real value. Codex has no generic headers concept;
      * only the single shape `{ Authorization: "Bearer ${VAR}" }` is
      * expressible there (trellis-mcp-transport-auth design.md D4) — any
@@ -190,7 +190,8 @@ export interface SkillRef {
      * filename is case-sensitive on at least one target agent (Codex). */
     dir: string;
     /**
-     * Omit for "all agents" (the default). Deliberately NOT read from
+     * Explicit applicable agents; unregistered custom skills load as `[]`.
+     * Package-owned built-ins may supply their own default. NOT read from
      * SKILL.md's own frontmatter — Codex validates SKILL.md frontmatter
      * against an allow-list of known keys and rejects unknown ones (see
      * docs/research.md), so a Trellis-only field embedded there would break

package/dist/lib/envVarNames.d.ts

@@ -7,7 +7,11 @@
  * still more machinery than this one narrow extraction needs.
  */
 import type { McpServerDef } from "../core/types.js";
-/** Every `${NAME}` occurrence in a string — a header value can in
+export declare function replaceTemplateVars(value: string, replace: (entry: string) => string): string;
+/** Report only the header's name, never a potentially sensitive template. */
+export declare function invalidHeaderTemplate(headers: Record<string, string> | undefined): string | undefined;
+/** Every `${NAME}` or `${mxenv://profile/KEY}` occurrence in a string,
+ * including malformed placeholders for validation — a header value can in
  * principle reference more than one name (trellis-mcp-transport-auth
  * design.md D6), same extraction `env`'s single-name-per-value case
  * already needed, just generalized. */

package/dist/lib/envVarNames.js

@@ -6,8 +6,21 @@
  * there is no round-trip-fidelity concern here, but a full parser is
  * still more machinery than this one narrow extraction needs.
  */
-const TEMPLATE_VAR_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
-/** Every `${NAME}` occurrence in a string — a header value can in
+// Keep malformed placeholders visible too: a misspelled reference scheme
+// must reach validation rather than silently survive as literal header text.
+const TEMPLATE_VAR_RE = /\$\{([^{}]*)\}/g;
+export function replaceTemplateVars(value, replace) {
+    return value.replace(TEMPLATE_VAR_RE, (_match, entry) => replace(entry));
+}
+/** Report only the header's name, never a potentially sensitive template. */
+export function invalidHeaderTemplate(headers) {
+    return Object.entries(headers ?? {}).find(([, value]) => {
+        const literal = replaceTemplateVars(value, () => "");
+        return literal.includes("${") || /mx-?env:\/\//.test(literal);
+    })?.[0];
+}
+/** Every `${NAME}` or `${mxenv://profile/KEY}` occurrence in a string,
+ * including malformed placeholders for validation — a header value can in
  * principle reference more than one name (trellis-mcp-transport-auth
  * design.md D6), same extraction `env`'s single-name-per-value case
  * already needed, just generalized. */

package/dist/lib/mcpConnect.js

@@ -14,8 +14,8 @@
  */
 import { Client, StreamableHTTPClientTransport, SSEClientTransport } from "@modelcontextprotocol/client";
 import { StdioClientTransport, getDefaultEnvironment } from "@modelcontextprotocol/client/stdio";
-import { deliveredName, resolveSecretEnv } from "./secretEnv.js";
-import { extractTemplateVarNames } from "./envVarNames.js";
+import { deliveredName, isValidSecretVarName, parseEnvEntry, resolveSecretEntries, resolveSecretEnv } from "./secretEnv.js";
+import { extractTemplateVarNames, invalidHeaderTemplate, replaceTemplateVars } from "./envVarNames.js";
 export const DEFAULT_CONNECT_TIMEOUT_MS = 10_000;
 const FAILED_TRANSPORT_CLEANUP_TIMEOUT_MS = 1_000;
 /**
@@ -105,11 +105,25 @@ export async function connectStdio(def, secretsPolicy, timeoutMs, clientInfo) {
 export async function resolveHeaders(def, secretsPolicy) {
     if (!def.headers || Object.keys(def.headers).length === 0)
         return undefined;
+    const invalidHeader = invalidHeaderTemplate(def.headers);
+    if (invalidHeader !== undefined)
+        throw new Error(`[trellis] invalid reference template in header ${invalidHeader} — use \${VAR} or \${mxenv://<profile>/<KEY>}`);
     const names = Object.keys(def.headers).flatMap((key) => extractTemplateVarNames(def.headers[key]));
-    const resolved = await resolveSecretEnv(names, secretsPolicy);
+    for (const name of names) {
+        const entry = parseEnvEntry(name);
+        if (entry.kind === "invalid" || (entry.kind === "name" && !isValidSecretVarName(name))) {
+            throw new Error(`[trellis] invalid header reference: ${name} — expected a variable name or mxenv://<profile>/<KEY>`);
+        }
+    }
+    const resolved = await resolveSecretEntries(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] ?? "");
+        result[key] = replaceTemplateVars(template, (name) => {
+            if (parseEnvEntry(name).kind === "ref" && !resolved[name]) {
+                throw new Error(`[trellis] unresolved header reference: ${name}`);
+            }
+            return resolved[name] ?? "";
+        });
     }
     return result;
 }

package/dist/lib/secretEnv.d.ts

@@ -50,9 +50,6 @@ export type SecretEnvEntry = {
 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
@@ -66,7 +63,14 @@ export declare function parseEnvEntry(entry: string): SecretEnvEntry;
  * before this point (the bridge only ever sees pre-checked defs).
  * Compositions are cached per batch (one `ReferenceResolver` per call,
  * not per name).
- */
+ * Raw-entry keys preserve provenance when headers mix two profiles with
+ * the same KEY, or a reference and a bare name. Values stay in memory. */
+export declare function resolveSecretEntries(entries: string[], policy: SecretsPolicy): Promise<Record<string, string | undefined>>;
+export declare class SecretReferenceError extends Error {
+    readonly entry: string;
+    constructor(entry: string);
+}
+/** Compatibility view keyed by delivered name (KEY for a reference). */
 export declare function resolveSecretEnv(entries: string[], policy: SecretsPolicy): Promise<Record<string, string | undefined>>;
 export type WriteLocalSecretOutcome = "created" | "already-present" | "conflict";
 /**

package/dist/lib/secretEnv.js

@@ -51,7 +51,7 @@ export function deliveredName(entry) {
     return parsed.kind === "invalid" ? entry : parsed.delivered;
 }
 export function parseEnvEntry(entry) {
-    if (entry.includes("mxenv://") || entry.includes("mx-env://")) {
+    if (entry.includes("://")) {
         try {
             const refs = findMxEnvReferences(entry);
             if (refs.length === 1 && `mxenv://${refs[0].profile}/${refs[0].key}` === entry) {
@@ -66,9 +66,6 @@ export function parseEnvEntry(entry) {
     return { kind: "name", delivered: entry };
 }
 /**
- * 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
@@ -82,27 +79,38 @@ export function parseEnvEntry(entry) {
  * before this point (the bridge only ever sees pre-checked defs).
  * Compositions are cached per batch (one `ReferenceResolver` per call,
  * not per name).
- */
-export async function resolveSecretEnv(entries, policy) {
+ * Raw-entry keys preserve provenance when headers mix two profiles with
+ * the same KEY, or a reference and a bare name. Values stay in memory. */
+export async function resolveSecretEntries(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 = {};
-    // 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.
+    // Cache compositions once per batch; raw keys keep profiles distinct.
     const refs = parsed.filter((p) => p.kind === "ref");
     if (refs.length > 0) {
-        const resolver = new ReferenceResolver(loadConfigLayers({ cwd: homedir(), homeDir: homedir() }), {});
+        let resolver;
+        try {
+            resolver = new ReferenceResolver(loadConfigLayers({ cwd: homedir(), homeDir: homedir() }), {});
+        }
+        catch {
+            throw new SecretReferenceError(entries[parsed.indexOf(refs[0])]);
+        }
         for (const ref of refs) {
-            if (result[ref.delivered] !== undefined)
+            const entry = `mxenv://${ref.profile}/${ref.key}`;
+            if (Object.hasOwn(result, entry))
                 continue;
-            const { value } = await resolver.valueOf(ref.profile, ref.key);
-            result[ref.delivered] = value;
+            try {
+                const { value } = await resolver.valueOf(ref.profile, ref.key);
+                result[entry] = value;
+            }
+            catch {
+                // Provider errors may contain credential material. Report only the
+                // reference, never propagate provider output to logs or audit.
+                throw new SecretReferenceError(entry);
+            }
         }
     }
     const names = parsed.filter((p) => p.kind === "name");
@@ -116,6 +124,27 @@ export async function resolveSecretEnv(entries, policy) {
     }
     return result;
 }
+export class SecretReferenceError extends Error {
+    entry;
+    constructor(entry) {
+        super(`[trellis] could not resolve mxenv reference ${entry} — check the profile, KEY and provider configuration`);
+        this.entry = entry;
+    }
+}
+/** Compatibility view keyed by delivered name (KEY for a reference). */
+export async function resolveSecretEnv(entries, policy) {
+    const values = await resolveSecretEntries(entries, policy);
+    const result = {};
+    // Preserve the existing delivered-name collision rules for env/envAliases.
+    const ordered = [...entries.filter((entry) => parseEnvEntry(entry).kind === "ref"),
+        ...entries.filter((entry) => parseEnvEntry(entry).kind !== "ref")];
+    for (const entry of ordered) {
+        const name = deliveredName(entry);
+        if (result[name] === undefined)
+            result[name] = values[entry];
+    }
+    return result;
+}
 /**
  * `trellis migrate`'s static-env secret extraction
  * (trellis-migrate-extract-static-env-secrets design.md D4) — appends

package/dist/lib/skillScope.d.ts

@@ -0,0 +1,14 @@
+import { type AgentId } from "../core/types.js";
+import { type ScopeSelectorRaw } from "./scopeSelection.js";
+export declare function registeredSkillScope(value: unknown): AgentId[];
+export declare function readSkillScopes(path: string): Record<string, unknown>;
+export declare function selectSkillScope(raw: ScopeSelectorRaw, managed: readonly AgentId[]): {
+    scope: AgentId[];
+} | {
+    error: string;
+};
+export declare function requestSkillScope(raw: ScopeSelectorRaw, managed: readonly AgentId[], interactive: boolean): Promise<{
+    scope: AgentId[];
+} | {
+    error: string;
+}>;

package/dist/lib/skillScope.js

@@ -0,0 +1,40 @@
+/** Skill scope is a registry, not an exceptions list. Unregistered or
+ * invalid entries stay paused until applicable agents are selected. */
+import { existsSync, readFileSync } from "node:fs";
+import { parse as parseYaml } from "yaml";
+import { ALL_AGENTS } from "../core/types.js";
+import { resolveScopeSelection } from "./scopeSelection.js";
+import { canUseInteractivePicker, runMultiSelectPicker } from "./terminalPicker.js";
+export function registeredSkillScope(value) {
+    return Array.isArray(value) && value.every((id) => ALL_AGENTS.includes(id)) ? [...new Set(value)] : [];
+}
+export function readSkillScopes(path) {
+    if (!existsSync(path))
+        return {};
+    const doc = parseYaml(readFileSync(path, "utf8"));
+    if (doc?.skills === undefined)
+        return {};
+    if (typeof doc.skills !== "object" || doc.skills === null || Array.isArray(doc.skills)) {
+        throw new Error(`${path}: skills must be a map of skill names to agent lists`);
+    }
+    return doc.skills;
+}
+export function selectSkillScope(raw, managed) {
+    const selected = resolveScopeSelection(raw, managed);
+    if (!selected.ok)
+        return { error: selected.detail };
+    // Even "all" records today's set. Managing another agent later must
+    // never expand the compatibility decision made for an existing skill.
+    return { scope: selected.scope ?? [...managed] };
+}
+export async function requestSkillScope(raw, managed, interactive) {
+    if (raw.agents !== undefined || raw.all || raw.none)
+        return selectSkillScope(raw, managed);
+    if (!interactive || !canUseInteractivePicker()) {
+        return { error: "choose applicable agents with --agents <ids>, --all or --none; no scope is selected automatically" };
+    }
+    if (managed.length === 0)
+        return { error: "no managed agents — run trellis onboard, or use --none to import a paused skill" };
+    const indices = await runMultiSelectPicker([...managed], managed.map(() => false), undefined, "选择这个 skill 适用的 agent（不选则暂停分发）");
+    return indices === null ? { error: "skill import cancelled" } : { scope: indices.map((index) => managed[index]) };
+}

package/dist/lib/workspace.js

@@ -12,6 +12,7 @@ import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { oauthClientMetadata } from "../core/types.js";
 import { fromServerDefYaml } from "../core/mcpServerDef.js";
+import { readSkillScopes, registeredSkillScope } from "./skillScope.js";
 export const WORKSPACE_DIR_NAME = ".agents";
 /** The only `config.json` schema version this implementation understands. */
 export const WORKSPACE_CONFIG_VERSION = 1;
@@ -103,6 +104,7 @@ export function loadWorkspaceLayer(workspaceDir, policy) {
         layer.instructionsFile = instructionsPath;
     }
     const skillsRoot = join(layerRoot, "skills");
+    const scopes = readSkillScopes(join(layerRoot, "scope.yaml"));
     let skillEntries = [];
     try {
         skillEntries = readdirSync(skillsRoot);
@@ -113,8 +115,11 @@ export function loadWorkspaceLayer(workspaceDir, policy) {
     for (const name of skillEntries) {
         const dir = join(skillsRoot, name);
         try {
-            if (statSync(dir).isDirectory())
-                layer.skills.push({ name, dir });
+            if (statSync(dir).isDirectory()) {
+                layer.skills.push({ name, dir, scope: registeredSkillScope(scopes[name]) });
+                if (!Object.hasOwn(scopes, name))
+                    diagnostics.push(`.agents/scope.yaml: skill "${name}" has no registered agents — Trellis distribution paused`);
+            }
         }
         catch {
             // unreadable/broken entry — skip, not a load failure