agent-trellis 0.14.1 → 0.15.0

package/dist/core/canonical.js

@@ -1,99 +1,19 @@
 /**
- * Loads `~/.trellis/` into a `CanonicalSource`. Global only — no `root`
- * parameter, no workspace merge (docs/architecture.md "Global vs.
- * workspace scope"). See openspec/changes/trellis-sync-p1/specs/
- * canonical-source-loading/spec.md for the exact contract this implements.
+ * Loads `~/.trellis/` into a `CanonicalSource`. Global-only by default —
+ * no working-directory consultation; a caller that explicitly discovered a
+ * workspace root (src/lib/workspace.ts `findWorkspaceRoot`) may pass it in
+ * to layer `<workspace>/.agents/` over the global source
+ * (openspec/changes/trellis-workspace-scope, design D2).
  */
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { isMap, isSeq, parse as parseYaml, parseDocument } from "yaml";
 import { ALL_AGENTS, oauthClientMetadata } from "./types.js";
-import { isValidSecretVarName } from "../lib/secretEnv.js";
-function fromServerDefYaml(serverName, def) {
-    const { static_env, env_aliases, auth, ...rest } = def;
-    const out = { ...rest };
-    if (static_env)
-        out.staticEnv = static_env;
-    if (env_aliases)
-        out.envAliases = env_aliases;
-    if (auth !== undefined)
-        out.auth = fromAuthYaml(serverName, auth);
-    return out;
-}
-/**
- * `auth` translation and shape validation
- * (trellis-mcp-oauth-static-client tasks 1.1/1.3): the scalar and the
- * object form share one discriminator — `kind: oauth` — and the object
- * accepts exactly `kind`, `owner`, `client_id`, `client_secret_env`. Everything
- * else is refused here at load, naming the field but never echoing the
- * value: an invalid `client_secret_env` is at best a typo, at worst a
- * pasted secret.
- */
-function fromAuthYaml(serverName, auth) {
-    if (auth === "oauth")
-        return "oauth";
-    if (typeof auth !== "object" || auth === null) {
-        throw new Error(`mcp/servers.yaml: "${serverName}" auth must be the scalar "oauth" or { kind: oauth, client_id?, client_secret_env?, client_name? }`);
-    }
-    const { kind, owner, client_id, client_secret_env, client_name, ...extra } = auth;
-    const unknownKey = Object.keys(extra)[0];
-    if (unknownKey !== undefined) {
-        throw new Error(`mcp/servers.yaml: "${serverName}" auth has unrecognized key "${unknownKey}" — expected kind, owner, client_id, client_secret_env, client_name`);
-    }
-    if (kind !== "oauth") {
-        throw new Error(`mcp/servers.yaml: "${serverName}" auth.kind must be "oauth" — kind is the only recognized discriminator`);
-    }
-    if (client_id !== undefined && typeof client_id !== "string") {
-        throw new Error(`mcp/servers.yaml: "${serverName}" auth.client_id must be a string`);
-    }
-    if (client_secret_env !== undefined && (typeof client_secret_env !== "string" || !isValidSecretVarName(client_secret_env))) {
-        throw new Error(`mcp/servers.yaml: "${serverName}" auth.client_secret_env must be a variable NAME (e.g. FIGMA_CLIENT_SECRET), never a secret value`);
-    }
-    if (client_name !== undefined && typeof client_name !== "string") {
-        throw new Error(`mcp/servers.yaml: "${serverName}" auth.client_name must be a string`);
-    }
-    const out = { kind: "oauth" };
-    if (owner !== undefined && owner !== "agent" && owner !== "trellis")
-        throw new Error(`mcp/servers.yaml: "${serverName}" auth.owner must be agent or trellis`);
-    if (owner !== undefined)
-        out.owner = owner;
-    if (typeof client_id === "string")
-        out.clientId = client_id;
-    if (typeof client_secret_env === "string")
-        out.clientSecretEnv = client_secret_env;
-    if (typeof client_name === "string")
-        out.clientName = client_name;
-    return out;
-}
-/** Inverse of `fromServerDefYaml` (trellis-canonical-cli-crud) — strips
- * `undefined` fields so the written YAML never gets a literal `null`
- * for an omitted optional. */
-export function toServerDefYaml(def) {
-    const { staticEnv, envAliases, auth, ...rest } = def;
-    const out = { ...rest };
-    if (staticEnv)
-        out.static_env = staticEnv;
-    if (envAliases)
-        out.env_aliases = envAliases;
-    if (auth !== undefined) {
-        out.auth =
-            typeof auth === "string"
-                ? auth
-                : {
-                    kind: auth.kind,
-                    ...(auth.owner !== undefined ? { owner: auth.owner } : {}),
-                    ...(auth.clientId !== undefined ? { client_id: auth.clientId } : {}),
-                    ...(auth.clientSecretEnv !== undefined ? { client_secret_env: auth.clientSecretEnv } : {}),
-                    ...(auth.clientName !== undefined ? { client_name: auth.clientName } : {}),
-                };
-    }
-    for (const key of Object.keys(out)) {
-        if (out[key] === undefined)
-            delete out[key];
-    }
-    return out;
-}
+import { fromServerDefYaml, toServerDefYaml } from "./mcpServerDef.js";
+import { loadWorkspaceLayer } from "../lib/workspace.js";
+import { mergeWorkspaceLayer } from "../lib/workspaceMerge.js";
+export { toServerDefYaml } from "./mcpServerDef.js";
 function trellisRoot(homeDir) {
     return join(homeDir, ".trellis");
 }
@@ -565,8 +485,9 @@ function assertAuthMetadataClean(mcp, policy) {
         }
     }
 }
-/** Load the global canonical source from the supplied home directory. */
-export function loadCanonicalSource(homeDir = homedir()) {
+export function loadCanonicalSource(arg = {}) {
+    const options = typeof arg === "string" ? { homeDir: arg } : arg;
+    const homeDir = options.homeDir ?? homedir();
     const root = trellisRoot(homeDir);
     if (!existsSync(root)) {
         throw new Error(`No canonical source at ${root}. Run trellis init before trellis sync.`);
@@ -609,7 +530,7 @@ export function loadCanonicalSource(homeDir = homedir()) {
     const mcp = loadServersYaml(join(root, "mcp", "servers.yaml"));
     const secretsPolicy = loadSecretsPolicyYaml(join(root, "secrets.policy.yaml"), homeDir);
     assertAuthMetadataClean(mcp, secretsPolicy);
-    return {
+    const source = {
         instructionsFile: join(root, "agents.md"),
         managedAgents,
         skills,
@@ -619,4 +540,9 @@ export function loadCanonicalSource(homeDir = homedir()) {
         secretsPolicy,
         diagnostics,
     };
+    if (options.workspaceDir) {
+        const layer = loadWorkspaceLayer(options.workspaceDir, secretsPolicy);
+        return mergeWorkspaceLayer(source, layer);
+    }
+    return source;
 }

package/dist/core/mcpServerDef.d.ts

@@ -0,0 +1,39 @@
+/**
+ * On-disk ⇄ canonical translation for one MCP server entry, shared by
+ * `~/.trellis/mcp/servers.yaml` (YAML) and `<workspace>/.agents/config.json`
+ * (JSON). Both use the identical snake_case field set so there is exactly
+ * one server schema and one validator (trellis-workspace-scope design D1);
+ * the `source` label exists only so diagnostics name the file the user
+ * actually edited.
+ */
+import type { McpServerDef } from "./types.js";
+/**
+ * The on-disk shape for one server entry — `static_env`/`env_aliases`
+ * (snake_case, like every other multi-word key across `.trellis/*.yaml`)
+ * are translated to `McpServerDef.staticEnv`/`envAliases` (camelCase)
+ * below, and `auth`'s object form carries `client_id`/`client_secret_env`/
+ * `client_name` the same way (trellis-mcp-static-env-and-disabled-servers,
+ * trellis-migrate-env-var-alias, trellis-mcp-oauth-static-client,
+ * oauth-client-name).
+ */
+export type McpServerDefYaml = Omit<McpServerDef, "staticEnv" | "envAliases" | "auth"> & {
+    static_env?: Record<string, string>;
+    env_aliases?: Record<string, string>;
+    auth?: McpAuthYaml;
+};
+/** The on-disk `auth`: the `oauth` scalar exactly as before, or the object
+ * form whose keys are snake_case like every other multi-word key in
+ * `.trellis/*.yaml`. Values are `unknown` until `fromAuthYaml` validates
+ * them — a YAML/JSON cast is optimistic, validation is this module's job. */
+export type McpAuthYaml = string | {
+    kind?: unknown;
+    owner?: unknown;
+    client_id?: unknown;
+    client_secret_env?: unknown;
+    client_name?: unknown;
+};
+export declare function fromServerDefYaml(serverName: string, def: McpServerDefYaml, source?: string): McpServerDef;
+/** Inverse of `fromServerDefYaml` (trellis-canonical-cli-crud) — strips
+ * `undefined` fields so the written file never gets a literal `null`
+ * for an omitted optional. */
+export declare function toServerDefYaml(def: McpServerDef): McpServerDefYaml;

package/dist/core/mcpServerDef.js

@@ -0,0 +1,93 @@
+/**
+ * On-disk ⇄ canonical translation for one MCP server entry, shared by
+ * `~/.trellis/mcp/servers.yaml` (YAML) and `<workspace>/.agents/config.json`
+ * (JSON). Both use the identical snake_case field set so there is exactly
+ * one server schema and one validator (trellis-workspace-scope design D1);
+ * the `source` label exists only so diagnostics name the file the user
+ * actually edited.
+ */
+import { isValidSecretVarName } from "../lib/secretEnv.js";
+export function fromServerDefYaml(serverName, def, source = "mcp/servers.yaml") {
+    const { static_env, env_aliases, auth, ...rest } = def;
+    const out = { ...rest };
+    if (static_env)
+        out.staticEnv = static_env;
+    if (env_aliases)
+        out.envAliases = env_aliases;
+    if (auth !== undefined)
+        out.auth = fromAuthYaml(serverName, auth, source);
+    return out;
+}
+/**
+ * `auth` translation and shape validation
+ * (trellis-mcp-oauth-static-client tasks 1.1/1.3): the scalar and the
+ * object form share one discriminator — `kind: oauth` — and the object
+ * accepts exactly `kind`, `owner`, `client_id`, `client_secret_env`. Everything
+ * else is refused here at load, naming the field but never echoing the
+ * value: an invalid `client_secret_env` is at best a typo, at worst a
+ * pasted secret.
+ */
+function fromAuthYaml(serverName, auth, source) {
+    if (auth === "oauth")
+        return "oauth";
+    if (typeof auth !== "object" || auth === null) {
+        throw new Error(`${source}: "${serverName}" auth must be the scalar "oauth" or { kind: oauth, client_id?, client_secret_env?, client_name? }`);
+    }
+    const { kind, owner, client_id, client_secret_env, client_name, ...extra } = auth;
+    const unknownKey = Object.keys(extra)[0];
+    if (unknownKey !== undefined) {
+        throw new Error(`${source}: "${serverName}" auth has unrecognized key "${unknownKey}" — expected kind, owner, client_id, client_secret_env, client_name`);
+    }
+    if (kind !== "oauth") {
+        throw new Error(`${source}: "${serverName}" auth.kind must be "oauth" — kind is the only recognized discriminator`);
+    }
+    if (client_id !== undefined && typeof client_id !== "string") {
+        throw new Error(`${source}: "${serverName}" auth.client_id must be a string`);
+    }
+    if (client_secret_env !== undefined && (typeof client_secret_env !== "string" || !isValidSecretVarName(client_secret_env))) {
+        throw new Error(`${source}: "${serverName}" auth.client_secret_env must be a variable NAME (e.g. FIGMA_CLIENT_SECRET), never a secret value`);
+    }
+    if (client_name !== undefined && typeof client_name !== "string") {
+        throw new Error(`${source}: "${serverName}" auth.client_name must be a string`);
+    }
+    const out = { kind: "oauth" };
+    if (owner !== undefined && owner !== "agent" && owner !== "trellis")
+        throw new Error(`${source}: "${serverName}" auth.owner must be agent or trellis`);
+    if (owner !== undefined)
+        out.owner = owner;
+    if (typeof client_id === "string")
+        out.clientId = client_id;
+    if (typeof client_secret_env === "string")
+        out.clientSecretEnv = client_secret_env;
+    if (typeof client_name === "string")
+        out.clientName = client_name;
+    return out;
+}
+/** Inverse of `fromServerDefYaml` (trellis-canonical-cli-crud) — strips
+ * `undefined` fields so the written file never gets a literal `null`
+ * for an omitted optional. */
+export function toServerDefYaml(def) {
+    const { staticEnv, envAliases, auth, ...rest } = def;
+    const out = { ...rest };
+    if (staticEnv)
+        out.static_env = staticEnv;
+    if (envAliases)
+        out.env_aliases = envAliases;
+    if (auth !== undefined) {
+        out.auth =
+            typeof auth === "string"
+                ? auth
+                : {
+                    kind: auth.kind,
+                    ...(auth.owner !== undefined ? { owner: auth.owner } : {}),
+                    ...(auth.clientId !== undefined ? { client_id: auth.clientId } : {}),
+                    ...(auth.clientSecretEnv !== undefined ? { client_secret_env: auth.clientSecretEnv } : {}),
+                    ...(auth.clientName !== undefined ? { client_name: auth.clientName } : {}),
+                };
+    }
+    for (const key of Object.keys(out)) {
+        if (out[key] === undefined)
+            delete out[key];
+    }
+    return out;
+}

package/dist/core/types.d.ts

@@ -303,10 +303,11 @@ export interface AgentSnapshot {
 }
 export interface CanonicalSource {
     /**
-     * Global (`~/.trellis`) only for now. Project-local `.trellis/` and its
-     * merge-over-global precedence are an explicit non-goal until a later
-     * phase — see docs/roadmap.md. Don't build workspace resolution ahead of
-     * that decision.
+     * Global (`~/.trellis`) by default. When the caller explicitly supplies a
+     * discovered workspace root, the `<workspace>/.agents/` project layer is
+     * merged over the global layer (workspace wins by ID, `enabled: false`
+     * tombstones) and `workspace` below carries the merge's provenance — see
+     * openspec/changes/trellis-workspace-scope.
      */
     instructionsFile: string;
     /** From `~/.trellis/managed.yaml`. Missing file and `agents: []` both
@@ -317,7 +318,41 @@ export interface CanonicalSource {
     memories: MemoryEntry[];
     mcp: McpConfig;
     secretsPolicy: SecretsPolicy;
+    /** Present only when the source was loaded with a workspace layer. */
+    workspace?: WorkspaceLayerInfo;
     /** e.g. a `scope.yaml` entry naming a skill/agent/memory that doesn't
      * exist — recorded, not a load failure. See `loadCanonicalSource`. */
     diagnostics: string[];
 }
+export type LayerProvenance = "global" | "workspace";
+/** Merge metadata produced when a workspace `.agents/` layer is in scope. */
+export interface WorkspaceLayerInfo {
+    /** Absolute path of the workspace root (the directory containing `.agents/`). */
+    root: string;
+    /** `<root>/.agents/AGENTS.md`, when the workspace declares instructions. */
+    instructionsFile?: string;
+    /** Per-server source layer for every entry in `mcp.servers`. */
+    mcpProvenance: Record<string, LayerProvenance>;
+    /** The pre-merge GLOBAL layer's server map — what global (user-level)
+     * delivery must render, layer-preserving (workspace-delivery spec:
+     * "global config files are untouched by the workspace entries"). Includes
+     * shadowed entries with their GLOBAL definitions (zcode resolves same-name
+     * conflicts user-first, so the global def is what zcode will actually use)
+     * and tombstoned entries (a tombstone only removes the server from the
+     * workspace's effective view; the shared user-level files still carry the
+     * global def for every other context). */
+    mcpGlobalServers: Record<string, McpServerDef>;
+    /** Per-skill source layer for every entry in `skills`. */
+    skillProvenance: Record<string, LayerProvenance>;
+    /** The pre-merge GLOBAL layer's skills — what global (user-level)
+     * delivery must symlink, layer-preserving, same invariant as
+     * `mcpGlobalServers`. Includes entries the workspace shadows, with their
+     * GLOBAL definitions: the user-level skill dirs are shared by every
+     * project, so a workspace override only governs project-level delivery.
+     * (zcode's Runtime SkillProvider is the deliberate exception — it serves
+     * the merged view by design, trellis-workspace-scope task 2.2.) */
+    globalSkills: SkillRef[];
+    /** Global entries the workspace overrode or tombstoned, as
+     * `"mcp:<name>"` / `"skill:<name>"` — surfaced by doctor/status. */
+    shadowed: string[];
+}

package/dist/lib/mcpMigrateRead.d.ts

@@ -35,6 +35,30 @@ export interface McpMigrateReadResult {
  * independent derivations of it.
  */
 export declare function resolvedEnvTextMap(def: Pick<McpServerDef, "env" | "envAliases" | "staticEnv">): Record<string, string>;
+/** Shared by claude-code and kiro — both write the identical JSON shape
+ * (`jsonMcp.ts` is their common writer). Deliberately richer than either
+ * probe's own read-side type: adds `headers`, which both probes' own
+ * types currently omit despite it being a real field Trellis itself
+ * writes for http/sse servers into this exact shape (confirmed via
+ * `grep -n "headers" src/probes/kiro.ts src/probes/claude-code.ts
+ * src/adapters/jsonMcp.ts` — only the writer declares it). */
+interface RichJsonServerDef {
+    type?: "stdio" | "http" | "sse";
+    command?: string;
+    args?: string[];
+    url?: string;
+    env?: Record<string, string>;
+    headers?: Record<string, string>;
+}
+/** Also exported for the workspace-migration scanner's zcode reader
+ * (trellis-workspace-scope task 4.1): zcode's project config nests the
+ * same rich-JSON server shape under `mcp.servers`, so the walker there
+ * reuses this per-entry mapping unchanged. */
+export declare function fromRichJsonServerDef(raw: RichJsonServerDef): McpServerDef | undefined;
+/** Also the workspace-migration scanner's JSON reader (trellis-workspace-
+ * scope task 4.1): project-level `.mcp.json`-shape files parse through
+ * the exact same rules as their global counterparts. */
+export declare function readRichJsonMcpDefs(configPath: string): McpMigrateReadResult;
 export declare function readClaudeCodeMcpDefs(homeDir: string): McpMigrateReadResult;
 export declare function readKiroMcpDefs(homeDir: string): McpMigrateReadResult;
 export declare function readKimiCodeMcpDefs(homeDir: string): McpMigrateReadResult;
@@ -81,3 +105,4 @@ export declare function buildCodexMcpReadResult(mcpEntries: CodexMcpEntryRich[],
  * entry is reported as unsupported instead.
  */
 export declare function readCodexMcpDefs(homeDir: string): McpMigrateReadResult;
+export {};

package/dist/lib/mcpMigrateRead.js

@@ -73,7 +73,11 @@ function splitJsonEnvMap(env) {
         result.staticEnv = literal;
     return result;
 }
-function fromRichJsonServerDef(raw) {
+/** Also exported for the workspace-migration scanner's zcode reader
+ * (trellis-workspace-scope task 4.1): zcode's project config nests the
+ * same rich-JSON server shape under `mcp.servers`, so the walker there
+ * reuses this per-entry mapping unchanged. */
+export function fromRichJsonServerDef(raw) {
     if (raw.url) {
         const transport = raw.type === "sse" ? "sse" : "http";
         const def = { transport, url: raw.url };
@@ -89,7 +93,10 @@ function fromRichJsonServerDef(raw) {
     Object.assign(def, splitJsonEnvMap(raw.env));
     return def;
 }
-function readRichJsonMcpDefs(configPath) {
+/** Also the workspace-migration scanner's JSON reader (trellis-workspace-
+ * scope task 4.1): project-level `.mcp.json`-shape files parse through
+ * the exact same rules as their global counterparts. */
+export function readRichJsonMcpDefs(configPath) {
     const parsed = readJsonFile(configPath);
     const entries = [];
     const unsupported = [];

package/dist/lib/skillProvider.js

@@ -4,10 +4,23 @@ import { resolve, relative, sep } from "node:path";
 import { parse as parseYaml } from "yaml";
 import { isInScope } from "../core/adapter.js";
 import { loadCanonicalSource } from "../core/canonical.js";
+import { findWorkspaceRoot } from "./workspace.js";
 import { resolveScope } from "../core/types.js";
 import { buildSkillEntry, parseSkillUri, readSkillFileBytes, toResourceContent } from "./skillManifest.js";
 const MAX_FILE_BYTES = 256 * 1024;
 const SKILL_RESOURCE_PREFIX = "trellis://skills/";
+/**
+ * The Runtime process is spawned by the agent with the agent's own cwd —
+ * inside a repo carrying `.agents/`, skills served over the Runtime
+ * (zcode's delivery path) include the workspace layer, exactly like the
+ * file-delivered agents get their project copies (trellis-workspace-scope
+ * task 2.2). MCP upstream connections are deliberately NOT layered this
+ * way (design D6: workspace servers are direct, agent-owned) — this
+ * helper is used only here, never in the gateway's upstream resolution.
+ */
+function loadSkillCanonical(homeDir) {
+    return loadCanonicalSource({ homeDir, workspaceDir: findWorkspaceRoot(process.cwd()) });
+}
 const SEARCH_TOOL = {
     name: "trellis.skills.search",
     description: "Search in-scope Trellis skills by name or description, then read one selected skill on demand.",
@@ -131,7 +144,7 @@ export class SkillProvider {
     }
     /** `skills/list` — one entry per servable, in-scope skill. */
     listSkillEntries(context) {
-        return this.catalog(loadCanonicalSource(context.homeDir), context.agentId).map(({ entry }) => entry);
+        return this.catalog(loadSkillCanonical(context.homeDir), context.agentId).map(({ entry }) => entry);
     }
     /** `skills/get` — lookup by URI, independent of listing. Out-of-scope and
      * unknown URIs are indistinguishable by design. */
@@ -145,7 +158,7 @@ export class SkillProvider {
         return [SEARCH_TOOL, READ_TOOL, READ_FILE_TOOL];
     }
     async callTool(name, args, context) {
-        const canonical = loadCanonicalSource(context.homeDir);
+        const canonical = loadSkillCanonical(context.homeDir);
         const input = (args ?? {});
         if (name === SEARCH_TOOL.name)
             return this.search(canonical, context.agentId, input);
@@ -156,7 +169,7 @@ export class SkillProvider {
         return errorResult(`unknown skill provider tool "${name}"`);
     }
     listResources(context) {
-        const canonical = loadCanonicalSource(context.homeDir);
+        const canonical = loadSkillCanonical(context.homeDir);
         const legacy = canonical.skills
             .filter((skill) => hasSkillDocument(skill) && isInScope(context.agentId, skill.scope, canonical.managedAgents))
             .map((skill) => ({
@@ -181,7 +194,7 @@ export class SkillProvider {
         if (segments.length !== 2 || segments[1] !== "SKILL.md") {
             throw new Error(`unsupported skill resource URI "${uri.toString()}"`);
         }
-        const canonical = loadCanonicalSource(context.homeDir);
+        const canonical = loadSkillCanonical(context.homeDir);
         const skill = skillFor(canonical, context.agentId, segments[0]);
         if (!skill)
             throw new Error(`skill "${segments[0]}" is not available to ${context.agentId}`);
@@ -192,7 +205,7 @@ export class SkillProvider {
      * computed its digests — the two cannot disagree. */
     readConventionalResource(uri, context) {
         const parsed = parseSkillUri(uri);
-        const canonical = loadCanonicalSource(context.homeDir);
+        const canonical = loadSkillCanonical(context.homeDir);
         const skill = parsed ? skillFor(canonical, context.agentId, parsed.name) : undefined;
         const served = skill && parsed ? this.catalog(canonical, context.agentId).find(({ entry }) => entry.uri === `skill://${parsed.name}/SKILL.md`) : undefined;
         if (!parsed || !skill || !served || !served.entry.resources.some((file) => file.uri === uri)) {

package/dist/lib/workspace.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Workspace (project-level) canonical layer: discovery of the nearest
+ * `.agents/` directory and loading of its `config.json` / `AGENTS.md` /
+ * `skills/` into a `WorkspaceLayer` (openspec trellis-workspace-scope,
+ * design D1/D2). The shape follows the `.agents` Protocol draft's
+ * two-layer model; skills under `.agents/skills/` are additionally read
+ * natively by Codex, pi, and Kimi Code, so the canonical directory is
+ * itself the deliverable for those agents.
+ */
+import type { McpServerDef, SecretsPolicy, SkillRef } from "../core/types.js";
+export declare const WORKSPACE_DIR_NAME = ".agents";
+/** The only `config.json` schema version this implementation understands. */
+export declare const WORKSPACE_CONFIG_VERSION = 1;
+/**
+ * Walk ancestors of `startDir` upward; the first directory containing a
+ * `.agents/` directory is the workspace root. The user's home directory
+ * itself is never a workspace root (a `~/.agents/` global convention, if
+ * one ever exists, is a separate decision), and reaching the filesystem
+ * root yields `null` — pure global-only behavior.
+ */
+export declare function findWorkspaceRoot(startDir: string): string | null;
+export interface WorkspaceLayer {
+    /** Absolute workspace root (the directory containing `.agents/`). */
+    root: string;
+    /** Validated MCP servers from `config.json`, minus tombstones. */
+    servers: Record<string, McpServerDef>;
+    /** Server names declared with `enabled: false` — they disable a same-ID
+     * global entry and render nothing themselves. */
+    tombstones: string[];
+    /** Skills from `.agents/skills/<name>/`. */
+    skills: SkillRef[];
+    /** `.agents/AGENTS.md`, when present. */
+    instructionsFile?: string;
+    diagnostics: string[];
+}
+/** Load `<workspaceDir>/.agents/` into a `WorkspaceLayer`. Every file is
+ * optional; a present-but-invalid `config.json` is a hard error (never a
+ * silent misread), with the secrets boundary enforced against `policy`. */
+export declare function loadWorkspaceLayer(workspaceDir: string, policy: SecretsPolicy): WorkspaceLayer;

package/dist/lib/workspace.js

@@ -0,0 +1,158 @@
+/**
+ * Workspace (project-level) canonical layer: discovery of the nearest
+ * `.agents/` directory and loading of its `config.json` / `AGENTS.md` /
+ * `skills/` into a `WorkspaceLayer` (openspec trellis-workspace-scope,
+ * design D1/D2). The shape follows the `.agents` Protocol draft's
+ * two-layer model; skills under `.agents/skills/` are additionally read
+ * natively by Codex, pi, and Kimi Code, so the canonical directory is
+ * itself the deliverable for those agents.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { oauthClientMetadata } from "../core/types.js";
+import { fromServerDefYaml } from "../core/mcpServerDef.js";
+export const WORKSPACE_DIR_NAME = ".agents";
+/** The only `config.json` schema version this implementation understands. */
+export const WORKSPACE_CONFIG_VERSION = 1;
+const CONFIG_SOURCE_LABEL = ".agents/config.json";
+/**
+ * Walk ancestors of `startDir` upward; the first directory containing a
+ * `.agents/` directory is the workspace root. The user's home directory
+ * itself is never a workspace root (a `~/.agents/` global convention, if
+ * one ever exists, is a separate decision), and reaching the filesystem
+ * root yields `null` — pure global-only behavior.
+ */
+export function findWorkspaceRoot(startDir) {
+    const home = resolve(homedir());
+    let dir = resolve(startDir);
+    while (true) {
+        if (dir === home)
+            return null;
+        const candidate = join(dir, WORKSPACE_DIR_NAME);
+        try {
+            if (statSync(candidate).isDirectory())
+                return dir;
+        }
+        catch {
+            // not present or unreadable — keep walking
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+function isTombstone(def) {
+    return def.enabled === false && def.transport === undefined;
+}
+/** Load `<workspaceDir>/.agents/` into a `WorkspaceLayer`. Every file is
+ * optional; a present-but-invalid `config.json` is a hard error (never a
+ * silent misread), with the secrets boundary enforced against `policy`. */
+export function loadWorkspaceLayer(workspaceDir, policy) {
+    const layerRoot = join(workspaceDir, WORKSPACE_DIR_NAME);
+    const diagnostics = [];
+    const layer = { root: workspaceDir, servers: {}, tombstones: [], skills: [], diagnostics };
+    const configPath = join(layerRoot, "config.json");
+    if (existsSync(configPath)) {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(configPath, "utf-8"));
+        }
+        catch (err) {
+            throw new Error(`${CONFIG_SOURCE_LABEL}: invalid JSON — ${err.message}`);
+        }
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            throw new Error(`${CONFIG_SOURCE_LABEL}: top level must be an object { "version", "mcp" }`);
+        }
+        const { version, mcp, ...extra } = parsed;
+        const configVersion = version === undefined ? WORKSPACE_CONFIG_VERSION : version;
+        if (typeof configVersion !== "number" || !Number.isInteger(configVersion) || configVersion < 1) {
+            throw new Error(`${CONFIG_SOURCE_LABEL}: "version" must be a positive integer, got ${JSON.stringify(version)}`);
+        }
+        if (configVersion > WORKSPACE_CONFIG_VERSION) {
+            throw new Error(`${CONFIG_SOURCE_LABEL}: schema version ${configVersion} is newer than this Trellis understands (${WORKSPACE_CONFIG_VERSION}) — upgrade Trellis`);
+        }
+        for (const key of Object.keys(extra)) {
+            diagnostics.push(`${CONFIG_SOURCE_LABEL}: unrecognized top-level key "${key}" — ignored`);
+        }
+        if (mcp !== undefined) {
+            if (typeof mcp !== "object" || mcp === null || typeof mcp.servers !== "object" || mcp.servers === null || Array.isArray(mcp.servers)) {
+                throw new Error(`${CONFIG_SOURCE_LABEL}: "mcp.servers" must be an object mapping server names to definitions`);
+            }
+            for (const [name, rawDef] of Object.entries(mcp.servers)) {
+                if (typeof rawDef !== "object" || rawDef === null) {
+                    throw new Error(`${CONFIG_SOURCE_LABEL}: "${name}" must be a server definition object or { "enabled": false }`);
+                }
+                if (isTombstone(rawDef)) {
+                    layer.tombstones.push(name);
+                    continue;
+                }
+                // enabled:false WITH a transport is tombstone semantics too — it
+                // disables the same-ID global entry and renders nothing.
+                if (rawDef.enabled === false) {
+                    layer.tombstones.push(name);
+                    continue;
+                }
+                layer.servers[name] = fromServerDefYaml(name, rawDef, CONFIG_SOURCE_LABEL);
+            }
+        }
+    }
+    const instructionsPath = join(layerRoot, "AGENTS.md");
+    if (existsSync(instructionsPath)) {
+        layer.instructionsFile = instructionsPath;
+    }
+    const skillsRoot = join(layerRoot, "skills");
+    let skillEntries = [];
+    try {
+        skillEntries = readdirSync(skillsRoot);
+    }
+    catch {
+        // no skills/ — optional, same as every other layer file
+    }
+    for (const name of skillEntries) {
+        const dir = join(skillsRoot, name);
+        try {
+            if (statSync(dir).isDirectory())
+                layer.skills.push({ name, dir });
+        }
+        catch {
+            // unreadable/broken entry — skip, not a load failure
+        }
+    }
+    assertWorkspaceSecretsClean(layer.servers, policy);
+    return layer;
+}
+/** An exact `${NAME}` value is a reference to the global secret store, not
+ * a literal — the only credential-shaped content allowed in a committable
+ * project layer (same classification as mcpMigrateRead.ts). */
+const VAR_REF_RE = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/;
+/**
+ * Load-time secrets boundary for the project layer (workspace-scope spec
+ * "Secrets stay global-only"): scans the fields a pasted secret could
+ * reach — `env` entries, `staticEnv` values, `headers` values, and OAuth
+ * client metadata — and refuses the load, naming the server and field but
+ * never echoing the value.
+ */
+function assertWorkspaceSecretsClean(servers, policy) {
+    const check = (server, field, value) => {
+        if (value === undefined || VAR_REF_RE.test(value))
+            return;
+        for (const pattern of policy.rejectPatterns) {
+            if (pattern.test(value)) {
+                throw new Error(`${CONFIG_SOURCE_LABEL}: "${server}" ${field} matches a secrets.policy.yaml reject pattern — the project layer is committable and must carry only \${VAR} references; move the value to the global secret store (the offending value is intentionally not printed)`);
+            }
+        }
+    };
+    for (const [name, def] of Object.entries(servers)) {
+        for (const entry of def.env ?? [])
+            check(name, "env", entry);
+        for (const [key, value] of Object.entries(def.staticEnv ?? {}))
+            check(name, `static_env.${key}`, value);
+        for (const [key, value] of Object.entries(def.headers ?? {}))
+            check(name, `headers.${key}`, value);
+        const meta = oauthClientMetadata(def.auth);
+        check(name, "auth.client_id", meta.clientId);
+        check(name, "auth.client_secret_env", meta.clientSecretEnv);
+    }
+}