agent-trellis 0.9.1 → 0.11.0

package/dist/commands/skill.d.ts

@@ -1,5 +1,5 @@
 /**
- * `trellis skill list|add|remove` — command-line CRUD for canonical
+ * `trellis skill list|add|remove|scope` — command-line CRUD for canonical
  * skills (trellis-canonical-cli-crud), an alternative to hand-editing
  * `~/.trellis/skills/<name>/SKILL.md` directly. `add`'s conflict
  * decision and `remove`'s "sync will un-sync it" behavior both reuse
@@ -10,6 +10,7 @@
 import type { AgentId } from "../core/types.js";
 import { type BackupSession } from "../lib/backup.js";
 import type { SyncReport } from "./sync.js";
+import { type ScopeSelectorRaw } from "../lib/scopeSelection.js";
 import type { RemoteSkillLockEntry } from "../lib/remoteSkillLock.js";
 export type BuiltinSkillUpdateAction = "create" | "update" | "already-current";
 export interface BuiltinSkillUpdatePlan {
@@ -97,3 +98,46 @@ export declare function runSkillRemove(name: string, opts?: {
 }): Promise<{
     exitCode: number;
 }>;
+export type SkillScopeAction = "updated" | "already-set" | "not-found" | "invalid-input";
+export interface SkillScopePlan {
+    name: string;
+    action: SkillScopeAction;
+    detail: string;
+    /** What will be recorded in `scope.yaml`; `undefined` clears the explicit
+     * scope so the skill reaches every managed agent. Set when the selection was
+     * valid, whatever the action. */
+    scope?: AgentId[];
+    mode?: "all" | "none" | "explicit";
+    /** True when a full selection was dropped instead of recorded
+     * (trellis-scope-editing-and-auth-status design.md D3). */
+    normalizedFromFull?: boolean;
+    /** The agents that will actually receive the skill afterwards. */
+    effective?: readonly AgentId[];
+}
+/**
+ * `skill scope <name> --agents a,b | --all | --none`
+ * (trellis-scope-editing-and-auth-status tasks.md 1.1). Plan only — the write
+ * and the cascade sync live in `applySkillScopeWithSync`.
+ */
+export declare function collectSkillScopePlan(name: string | undefined, raw: ScopeSelectorRaw, homeDir?: string): SkillScopePlan;
+export interface SkillScopeOutcome {
+    plan: SkillScopePlan;
+    writeError?: string;
+    sync?: SyncReport;
+}
+/** Write inside a backup session so `trellis rollback` covers it, then the
+ * same skills sync `add` / `remove` run — narrowing is converged by
+ * `symlinkPlan`'s existing "canonical entry gone or scoped away" removal
+ * (design.md D5). */
+export declare function applySkillScopeWithSync(plan: SkillScopePlan, opts?: {
+    homeDir?: string;
+    dryRun?: boolean;
+    backupSession?: BackupSession;
+}): Promise<SkillScopeOutcome>;
+export declare function runSkillScope(name: string | undefined, raw: ScopeSelectorRaw, opts?: {
+    homeDir?: string;
+    json?: boolean;
+    dryRun?: boolean;
+}): Promise<{
+    exitCode: number;
+}>;

package/dist/commands/skill.js

@@ -1,5 +1,5 @@
 /**
- * `trellis skill list|add|remove` — command-line CRUD for canonical
+ * `trellis skill list|add|remove|scope` — command-line CRUD for canonical
  * skills (trellis-canonical-cli-crud), an alternative to hand-editing
  * `~/.trellis/skills/<name>/SKILL.md` directly. `add`'s conflict
  * decision and `remove`'s "sync will un-sync it" behavior both reuse
@@ -14,12 +14,13 @@ import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { decideDirImport } from "../lib/dirEquals.js";
 import { findSkillFile } from "../lib/skillFile.js";
-import { loadCanonicalSource } from "../core/canonical.js";
+import { loadCanonicalSource, writeSkillScopeYaml } from "../core/canonical.js";
 import { resolveScope } from "../core/types.js";
 import { isBuiltinSkillName } from "../lib/builtinSkills.js";
 import { openBackupSession } from "../lib/backup.js";
 import { collectSyncReport, printReport as printSyncReport } from "./sync.js";
 import { remoteSkillProvenance } from "./remoteSkill.js";
+import { describeScope, resolveScopeSelection, sameScope } from "../lib/scopeSelection.js";
 function builtinSkillTemplate() {
     const here = dirname(fileURLToPath(import.meta.url));
     return readFileSync(join(here, "..", "..", "schema", "builtin-skills", "trellis-runtime", "SKILL.md"), "utf8");
@@ -205,3 +206,83 @@ export async function runSkillRemove(name, opts = {}) {
     const syncConflict = syncReport?.reports.some((r) => r.items.some((i) => i.action === "conflict")) ?? false;
     return { exitCode: failed || syncConflict ? 1 : 0 };
 }
+/**
+ * `skill scope <name> --agents a,b | --all | --none`
+ * (trellis-scope-editing-and-auth-status tasks.md 1.1). Plan only — the write
+ * and the cascade sync live in `applySkillScopeWithSync`.
+ */
+export function collectSkillScopePlan(name, raw, homeDir = homedir()) {
+    if (!name)
+        return { name: "(none)", action: "invalid-input", detail: "usage: trellis skill scope <name> --agents <ids> | --all | --none" };
+    if (isBuiltinSkillName(name)) {
+        return { name, action: "invalid-input", detail: `"${name}" is a Trellis package-owned Skill — its scope is not editable` };
+    }
+    const canonical = loadCanonicalSource(homeDir);
+    const selection = resolveScopeSelection(raw, canonical.managedAgents);
+    if (!selection.ok)
+        return { name, action: "invalid-input", detail: selection.detail };
+    const skill = canonical.skills.find((candidate) => candidate.name === name);
+    if (!skill)
+        return { name, action: "not-found", detail: `no canonical skill named "${name}"` };
+    const base = {
+        name,
+        scope: selection.scope,
+        mode: selection.mode,
+        normalizedFromFull: selection.normalizedFromFull,
+        effective: resolveScope(selection.scope, canonical.managedAgents),
+    };
+    const summary = describeScope(selection.scope, canonical.managedAgents);
+    const normalized = selection.normalizedFromFull ? " (every managed agent selected — recorded as the default, so a newly managed agent is included)" : "";
+    if (sameScope(skill.scope, selection.scope)) {
+        return { ...base, action: "already-set", detail: `scope is already ${summary}` };
+    }
+    return { ...base, action: "updated", detail: `set scope to ${summary}${normalized}` };
+}
+/** Write inside a backup session so `trellis rollback` covers it, then the
+ * same skills sync `add` / `remove` run — narrowing is converged by
+ * `symlinkPlan`'s existing "canonical entry gone or scoped away" removal
+ * (design.md D5). */
+export async function applySkillScopeWithSync(plan, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const ownSession = !opts.dryRun && !opts.backupSession && plan.action === "updated" ? openBackupSession(homeDir, "skill-scope") : undefined;
+    const session = opts.backupSession ?? ownSession;
+    let writeError;
+    if (!opts.dryRun && plan.action === "updated") {
+        const result = writeSkillScopeYaml(join(homeDir, ".trellis", "scope.yaml"), plan.name, plan.scope, session);
+        if (!result.ok)
+            writeError = result.error;
+    }
+    ownSession?.finalize();
+    let syncReport;
+    if (!writeError && plan.action === "updated" && existsSync(join(homeDir, ".trellis"))) {
+        syncReport = await collectSyncReport({ target: "skills", homeDir, dryRun: opts.dryRun });
+    }
+    return { plan, ...(writeError ? { writeError } : {}), ...(syncReport ? { sync: syncReport } : {}) };
+}
+export async function runSkillScope(name, raw, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    let outcome;
+    try {
+        outcome = await applySkillScopeWithSync(collectSkillScopePlan(name, raw, homeDir), { homeDir, dryRun: opts.dryRun });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return { exitCode: 1 };
+    }
+    const { plan, writeError, sync: syncReport } = outcome;
+    if (opts.json) {
+        const payload = writeError ? { ...plan, writeError } : plan;
+        console.log(JSON.stringify(syncReport ? { ...payload, sync: syncReport } : payload, null, 2));
+    }
+    else {
+        console.log(`${opts.dryRun ? "[dry run] " : ""}skill scope ${plan.name}`);
+        console.log(`  [${plan.action}] ${plan.detail}`);
+        if (writeError)
+            console.error(`  write failed: ${writeError}`);
+        if (syncReport)
+            printSyncReport(syncReport, opts.dryRun ?? false);
+    }
+    const failed = plan.action === "invalid-input" || plan.action === "not-found" || Boolean(writeError);
+    const syncConflict = syncReport?.reports.some((r) => r.items.some((i) => i.action === "conflict")) ?? false;
+    return { exitCode: failed || syncConflict ? 1 : 0 };
+}

package/dist/core/canonical.d.ts

@@ -10,13 +10,23 @@ import type { BackupSession } from "../lib/backup.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; every other field happens to already be a single word, so no
- * server-def field needed this treatment before
- * (trellis-mcp-static-env-and-disabled-servers, trellis-migrate-env-var-alias).
+ * below, and `auth`'s object form carries `client_id`/`client_secret_env`
+ * the same way (trellis-mcp-static-env-and-disabled-servers,
+ * trellis-migrate-env-var-alias, trellis-mcp-oauth-static-client).
  */
-type McpServerDefYaml = Omit<McpServerDef, "staticEnv" | "envAliases"> & {
+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 cast is optimistic, validation is this module's job. */
+type McpAuthYaml = string | {
+    kind?: unknown;
+    client_id?: unknown;
+    client_secret_env?: unknown;
 };
 /** Inverse of `fromServerDefYaml` (trellis-canonical-cli-crud) — strips
  * `undefined` fields so the written YAML never gets a literal `null`
@@ -127,13 +137,6 @@ export declare function ensureGitignoreEntry(gitignorePath: string, line: string
  * `export` prefix of its own.
  */
 export declare function ensureShellEnvSource(rcPath: string, envFilePath: string, backup?: BackupSession): void;
-/**
- * `homeDir` defaults to the real `~` and is only ever overridden for tests
- * and `scripts/sandbox.sh` — the same seam P0's probes use
- * (src/probes/*.ts) and for the same reason: never touch a developer's
- * real dotfiles from a test. It is not a workspace/project root — see
- * specs/canonical-source-loading's global-only requirement, which this
- * parameter does not weaken.
- */
+/** Load the global canonical source from the supplied home directory. */
 export declare function loadCanonicalSource(homeDir?: string): CanonicalSource;
 export {};

package/dist/core/canonical.js

@@ -8,26 +8,75 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSy
 import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { isMap, isSeq, parse as parseYaml, parseDocument } from "yaml";
-import { ALL_AGENTS } from "./types.js";
-function fromServerDefYaml(def) {
-    const { static_env, env_aliases, ...rest } = def;
+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`, `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? }`);
+    }
+    const { kind, client_id, client_secret_env, ...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, client_id, client_secret_env`);
+    }
+    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`);
+    }
+    const out = { kind: "oauth" };
+    if (typeof client_id === "string")
+        out.clientId = client_id;
+    if (typeof client_secret_env === "string")
+        out.clientSecretEnv = client_secret_env;
     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, ...rest } = 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.clientId !== undefined ? { client_id: auth.clientId } : {}),
+                    ...(auth.clientSecretEnv !== undefined ? { client_secret_env: auth.clientSecretEnv } : {}),
+                };
+    }
     for (const key of Object.keys(out)) {
         if (out[key] === undefined)
             delete out[key];
@@ -83,7 +132,7 @@ function loadServersYaml(path) {
         return { servers: {}, knownHostInjected: [] };
     }
     const parsed = (parseYaml(readFileSync(path, "utf-8")) ?? {});
-    const servers = Object.fromEntries(Object.entries(parsed.servers ?? {}).map(([name, def]) => [name, fromServerDefYaml(def)]));
+    const servers = Object.fromEntries(Object.entries(parsed.servers ?? {}).map(([name, def]) => [name, fromServerDefYaml(name, def)]));
     return {
         servers,
         knownHostInjected: parsed.known_host_injected ?? [],
@@ -452,7 +501,7 @@ export function ensureShellEnvSource(rcPath, envFilePath, backup) {
  * 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 (D1), never "everyone." An unrecognized id is dropped with a
+ * agents, never "everyone." An unrecognized id is dropped with a
  * diagnostic, same posture as an unrecognized scope.yaml agent id. */
 function loadManagedYaml(path, diagnostics) {
     if (!existsSync(path)) {
@@ -480,17 +529,36 @@ function validAgentIds(scope) {
     return scope.every((id) => ALL_AGENTS.includes(id));
 }
 /**
- * `homeDir` defaults to the real `~` and is only ever overridden for tests
- * and `scripts/sandbox.sh` — the same seam P0's probes use
- * (src/probes/*.ts) and for the same reason: never touch a developer's
- * real dotfiles from a test. It is not a workspace/project root — see
- * specs/canonical-source-loading's global-only requirement, which this
- * parameter does not weaken.
+ * Load-time literal-value scan for OAuth client metadata
+ * (trellis-mcp-oauth-static-client task 1.2). `secrets audit` reports
+ * whole-file pattern hits as findings; this check goes further for the
+ * two fields a pasted secret is most likely to reach and refuses the
+ * load outright — the offending server and field are named, the value
+ * never printed.
  */
+function assertAuthMetadataClean(mcp, policy) {
+    for (const [name, def] of Object.entries(mcp.servers)) {
+        const meta = oauthClientMetadata(def.auth);
+        const fields = [
+            ["client_id", meta.clientId],
+            ["client_secret_env", meta.clientSecretEnv],
+        ];
+        for (const [field, value] of fields) {
+            if (value === undefined)
+                continue;
+            for (const pattern of policy.rejectPatterns) {
+                if (pattern.test(value)) {
+                    throw new Error(`mcp/servers.yaml: "${name}" auth.${field} matches a secrets.policy.yaml reject pattern — client_id must be the provider-published id, client_secret_env a variable name; the offending value is intentionally not printed`);
+                }
+            }
+        }
+    }
+}
+/** Load the global canonical source from the supplied home directory. */
 export function loadCanonicalSource(homeDir = homedir()) {
     const root = trellisRoot(homeDir);
     if (!existsSync(root)) {
-        throw new Error(`No canonical source at ${root}. Create it before running trellis sync — see docs/architecture.md's canonical schema.`);
+        throw new Error(`No canonical source at ${root}. Run trellis init before trellis sync.`);
     }
     const diagnostics = [];
     const managedAgents = loadManagedYaml(join(root, "managed.yaml"), diagnostics);
@@ -527,17 +595,17 @@ 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 {
         instructionsFile: join(root, "agents.md"),
         managedAgents,
         skills,
         agents,
         memories,
-        mcp: loadServersYaml(join(root, "mcp", "servers.yaml")),
-        // P2's pre-write guard (src/adapters/mcpPlan.ts) uses its own narrow,
-        // hardcoded floor instead of this field — see design.md D1 in
-        // trellis-secrets-audit-p3.
-        secretsPolicy: loadSecretsPolicyYaml(join(root, "secrets.policy.yaml"), homeDir),
+        mcp,
+        secretsPolicy,
         diagnostics,
     };
 }

package/dist/core/types.d.ts

@@ -6,6 +6,29 @@
  */
 export type Transport = "stdio" | "http" | "sse";
 export type McpAuthMode = "oauth";
+/**
+ * Object form of the OAuth classification (trellis-mcp-oauth-static-client
+ * design.md D1). `kind` is the only discriminator; `client_id` is a public
+ * literal by design; `client_secret_env` is a variable NAME resolved
+ * through the secrets policy at authorization time. There is deliberately
+ * no field for a secret value in any form.
+ */
+export interface McpAuthConfig {
+    kind: McpAuthMode;
+    clientId?: string;
+    clientSecretEnv?: string;
+}
+/** True when `auth` classifies the server as OAuth, in either form. Every
+ * former `def.auth === "oauth"` check must go through this now that the
+ * object form exists — a strict-equality check would silently strip the
+ * OAuth routing from metadata-bearing servers. */
+export declare function isOAuthAuth(auth: McpAuthMode | McpAuthConfig | undefined): boolean;
+/** The pre-registered client metadata a classification carries. A scalar
+ * carries none — both forms route identically (design.md D1). */
+export declare function oauthClientMetadata(auth: McpAuthMode | McpAuthConfig | undefined): {
+    clientId?: string;
+    clientSecretEnv?: string;
+};
 export type AgentId = "claude-code" | "codex" | "kiro" | "pi" | "kimi-code" | "zcode";
 export declare const ALL_AGENTS: readonly AgentId[];
 /**
@@ -28,8 +51,11 @@ export declare function resolveScope(scope: Scope, managedAgents: readonly Agent
 export interface McpServerDef {
     transport: Transport;
     /** Explicit authorization classification. Absence means ordinary MCP;
-     * Trellis never infers OAuth from a URL or a transient 401. */
-    auth?: McpAuthMode;
+     * Trellis never infers OAuth from a URL or a transient 401. The scalar
+     * form and a metadata-less object are equivalent — metadata extends the
+     * authorization flow, it never changes routing
+     * (trellis-mcp-oauth-static-client design.md D1). */
+    auth?: McpAuthMode | McpAuthConfig;
     /** stdio only */
     command?: string;
     args?: string[];

package/dist/core/types.js

@@ -4,6 +4,25 @@
  * for what a "canonical source" object looks like in memory; the YAML/MD
  * files on disk are its serialization, not the other way around.
  */
+/** True when `auth` classifies the server as OAuth, in either form. Every
+ * former `def.auth === "oauth"` check must go through this now that the
+ * object form exists — a strict-equality check would silently strip the
+ * OAuth routing from metadata-bearing servers. */
+export function isOAuthAuth(auth) {
+    return auth === "oauth" || (typeof auth === "object" && auth !== null && auth.kind === "oauth");
+}
+/** The pre-registered client metadata a classification carries. A scalar
+ * carries none — both forms route identically (design.md D1). */
+export function oauthClientMetadata(auth) {
+    if (typeof auth !== "object" || auth === null)
+        return {};
+    const meta = {};
+    if (auth.clientId !== undefined)
+        meta.clientId = auth.clientId;
+    if (auth.clientSecretEnv !== undefined)
+        meta.clientSecretEnv = auth.clientSecretEnv;
+    return meta;
+}
 export const ALL_AGENTS = [
     "claude-code",
     "codex",

package/dist/lib/mcpRuntime.d.ts

@@ -2,6 +2,7 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import type { CallToolResult, GetPromptResult, Implementation, Prompt, ReadResourceResult, Resource, Tool } from "@modelcontextprotocol/sdk/types.js";
 import type { AgentId } from "../core/types.js";
 import type { GatewayBackend } from "./gatewayBackend.js";
+import type { SkillEntry } from "./skillManifest.js";
 export interface RuntimeContext {
     agentId: AgentId;
     homeDir: string;
@@ -14,6 +15,9 @@ export interface TrellisProvider {
     readResource?(uri: URL, context: RuntimeContext): Promise<ReadResourceResult> | ReadResourceResult;
     listPrompts?(context: RuntimeContext): Promise<Prompt[]> | Prompt[];
     getPrompt?(name: string, args: Record<string, string> | undefined, context: RuntimeContext): Promise<GetPromptResult> | GetPromptResult;
+    /** Skills-over-MCP `skills/list` and `skills/get` (trellis-skills-over-mcp). */
+    listSkillEntries?(context: RuntimeContext): Promise<SkillEntry[]> | SkillEntry[];
+    getSkillEntry?(uri: string, context: RuntimeContext): Promise<SkillEntry | undefined> | SkillEntry | undefined;
     close?(): Promise<void>;
 }
 export declare class BuiltinRegistry {
@@ -29,6 +33,8 @@ export declare class BuiltinRegistry {
     callTool(name: string, args: unknown, context: RuntimeContext): Promise<CallToolResult>;
     listResources(context: RuntimeContext): Promise<Resource[]>;
     readResource(uri: URL, context: RuntimeContext): Promise<ReadResourceResult>;
+    listSkills(context: RuntimeContext): Promise<SkillEntry[]>;
+    getSkill(uri: string, context: RuntimeContext): Promise<SkillEntry | undefined>;
     listPrompts(context: RuntimeContext): Promise<Prompt[]>;
     getPrompt(name: string, args: Record<string, string> | undefined, context: RuntimeContext): Promise<GetPromptResult>;
     close(): Promise<void>;

package/dist/lib/mcpRuntime.js

@@ -1,5 +1,5 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, ErrorCode, McpError, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { allocateExposedToolNames } from "./mcpToolRegistry.js";
 function compactBuiltinToolName(name) {
     return name.startsWith("trellis.") ? name.slice("trellis.".length).replaceAll(".", "_") : name;
@@ -106,6 +106,35 @@ export class BuiltinRegistry {
             throw new Error(`unknown Trellis resource "${key}"`);
         return provider.readResource(uri, context);
     }
+    async listSkills(context) {
+        const skills = [];
+        for (const provider of this.providers) {
+            if (!provider.listSkillEntries)
+                continue;
+            try {
+                skills.push(...(await provider.listSkillEntries(context)));
+            }
+            catch (err) {
+                this.warn(providerError(provider.id, err));
+            }
+        }
+        return skills;
+    }
+    async getSkill(uri, context) {
+        for (const provider of this.providers) {
+            if (!provider.getSkillEntry)
+                continue;
+            try {
+                const entry = await provider.getSkillEntry(uri, context);
+                if (entry)
+                    return entry;
+            }
+            catch (err) {
+                this.warn(providerError(provider.id, err));
+            }
+        }
+        return undefined;
+    }
     async listPrompts(context) {
         const prompts = [];
         this.promptOwners.clear();
@@ -181,5 +210,27 @@ export function createRuntimeServer(serverInfo, context, registry) {
     server.setRequestHandler(ReadResourceRequestSchema, async (request) => registry.readResource(new URL(request.params.uri), context));
     server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: await registry.listPrompts(context) }));
     server.setRequestHandler(GetPromptRequestSchema, async (request) => registry.getPrompt(request.params.name, request.params.arguments, context));
+    // `skills/list` and `skills/get` are not in this SDK's schema set (it speaks
+    // at most 2025-11-25), so they are answered through the SDK's fallback for
+    // methods with no registered handler, which keeps the extension free of a new
+    // direct zod dependency. The extension itself is deliberately NOT declared in
+    // the capabilities above: the specification declares it only through
+    // `server/discover`, which this revision lacks, and inventing another field
+    // would claim a protocol nobody defined (trellis-skills-over-mcp D4). Any
+    // other unknown method keeps the SDK's usual "method not found".
+    server.fallbackRequestHandler = async (request) => {
+        const cache = { resultType: "complete", ttlMs: 0, cacheScope: "private" };
+        if (request.method === "skills/list") {
+            return { ...cache, skills: await registry.listSkills(context) };
+        }
+        if (request.method === "skills/get") {
+            const uri = request.params?.uri;
+            const entry = typeof uri === "string" ? await registry.getSkill(uri, context) : undefined;
+            if (!entry)
+                throw new McpError(ErrorCode.InvalidParams, "unknown skill");
+            return { ...cache, skill: entry };
+        }
+        throw new McpError(ErrorCode.MethodNotFound, `Method not found: ${request.method}`);
+    };
     return server;
 }

package/dist/lib/oauth/flow.d.ts

@@ -2,6 +2,12 @@
  * The interactive half: dynamic client registration (RFC 7591) plus the
  * authorization-code grant with PKCE (RFC 6749 §4.1, RFC 7636).
  *
+ * Registration is a fallback, not a requirement: a caller that already
+ * holds a pre-registered `client_id` passes it in and the RFC 7591 step
+ * is skipped entirely (trellis-mcp-oauth-static-client design.md D3) —
+ * some providers refuse registration outright, and those are exactly the
+ * ones that publish a client for third-party use instead.
+ *
  * Only ever reached from `trellis mcp auth`, run by a human. The gateway
  * must never call into this file: it is spawned silently by an agent,
  * typically with no terminal and no display, so it can neither show a
@@ -31,6 +37,13 @@ export interface AuthorizeOptions {
  * endpoint — that is a legitimate configuration (a pre-registered
  * client), not an error, so the caller falls back to whatever client id
  * it was given.
+ *
+ * A refused registration is the one failure a human can actually fix, so
+ * the AS's own OAuth error code is read out of the response body rather
+ * than collapsed into a bare status: `unauthorized_client` is the
+ * provider saying "this server is not open to registration", which is
+ * precisely when a pre-registered `client_id` is the answer
+ * (trellis-mcp-oauth-static-client design.md D3).
  */
 export declare function registerClient(metadata: AuthorizationServerMetadata, redirectUri: string, opts?: {
     fetchImpl?: FetchLike;

package/dist/lib/oauth/flow.js

@@ -2,6 +2,12 @@
  * The interactive half: dynamic client registration (RFC 7591) plus the
  * authorization-code grant with PKCE (RFC 6749 §4.1, RFC 7636).
  *
+ * Registration is a fallback, not a requirement: a caller that already
+ * holds a pre-registered `client_id` passes it in and the RFC 7591 step
+ * is skipped entirely (trellis-mcp-oauth-static-client design.md D3) —
+ * some providers refuse registration outright, and those are exactly the
+ * ones that publish a client for third-party use instead.
+ *
  * Only ever reached from `trellis mcp auth`, run by a human. The gateway
  * must never call into this file: it is spawned silently by an agent,
  * typically with no terminal and no display, so it can neither show a
@@ -17,6 +23,13 @@ export class AuthorizationError extends Error {
  * endpoint — that is a legitimate configuration (a pre-registered
  * client), not an error, so the caller falls back to whatever client id
  * it was given.
+ *
+ * A refused registration is the one failure a human can actually fix, so
+ * the AS's own OAuth error code is read out of the response body rather
+ * than collapsed into a bare status: `unauthorized_client` is the
+ * provider saying "this server is not open to registration", which is
+ * precisely when a pre-registered `client_id` is the answer
+ * (trellis-mcp-oauth-static-client design.md D3).
  */
 export async function registerClient(metadata, redirectUri, opts = {}) {
     if (!metadata.registrationEndpoint)
@@ -35,7 +48,10 @@ export async function registerClient(metadata, redirectUri, opts = {}) {
         }),
     });
     if (!response.ok) {
-        throw new AuthorizationError(`dynamic client registration failed with HTTP ${response.status}`);
+        const code = await readOAuthErrorCode(response);
+        throw new AuthorizationError(code
+            ? `dynamic client registration was refused (${code})`
+            : `dynamic client registration failed with HTTP ${response.status}`);
     }
     const payload = (await response.json());
     if (!payload.client_id) {
@@ -46,6 +62,22 @@ export async function registerClient(metadata, redirectUri, opts = {}) {
         out.clientSecret = payload.client_secret;
     return out;
 }
+/** RFC 6749 §5.2 error body. Best-effort by design: a registration
+ * endpoint that answers with plain text or an empty body still produces
+ * a usable error, just a less specific one. */
+async function readOAuthErrorCode(response) {
+    try {
+        const payload = (await response.json());
+        return typeof payload.error === "string" ? payload.error : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Provider-neutral remediation, appended wherever registration is the
+ * thing that failed. Names the exact file and key so the fix needs no
+ * further search. */
+const STATIC_CLIENT_REMEDIATION = "register a client with the provider and set auth.client_id (plus auth.client_secret_env if the provider requires a secret) under this server in ~/.trellis/mcp/servers.yaml";
 /** A one-shot loopback listener for the redirect. Bound to 127.0.0.1
  * explicitly, never 0.0.0.0: the authorization code arrives in this URL,
  * and a listener on all interfaces would accept it from the network. */
@@ -101,9 +133,22 @@ export async function authorize(serverName, metadata, opts = {}) {
         let clientId = opts.clientId;
         let clientSecret = opts.clientSecret;
         if (!clientId) {
-            const registered = await registerClient(metadata, redirectUri, { fetchImpl, scope: opts.scope });
+            // The AS cannot register us AND canonical carries no client_id — the
+            // one dead end a person has to resolve by hand, so it is reported as
+            // such rather than as a generic registration failure
+            // (trellis-mcp-oauth-static-client design.md D3, task 2.3).
+            let registered;
+            try {
+                registered = await registerClient(metadata, redirectUri, { fetchImpl, scope: opts.scope });
+            }
+            catch (err) {
+                if (err instanceof AuthorizationError) {
+                    throw new AuthorizationError(`"${serverName}": ${err.message} — ${STATIC_CLIENT_REMEDIATION}`);
+                }
+                throw err;
+            }
             if (!registered) {
-                throw new AuthorizationError(`"${serverName}"'s authorization server offers no dynamic client registration, and no client_id is configured for it`);
+                throw new AuthorizationError(`"${serverName}"'s authorization server offers no dynamic client registration — ${STATIC_CLIENT_REMEDIATION}`);
             }
             clientId = registered.clientId;
             clientSecret = registered.clientSecret;