@guuey/config 0.1.2 → 0.2.0

package/dist/agent.d.ts

@@ -23,7 +23,7 @@
  *
  * Defaults applied by the pod runtime when fields are absent:
  * - `framework`   → `'claude-agent-sdk'`
- * - `mcpServers`  → `{ ggui: { url: 'https://mcp.ggui.ai' } }` (platform default; declaring `mcpServers` REPLACES this — not merged)
+ * - `mcpServers`  → `{ ggui: { url: 'https://mcp.ggui.ai' } }` (platform default; declaring `mcpServers` MERGES ON TOP of this (guuey#24 option A); opt out with `ggui: false`)
  * - `model`       → framework-chosen default (Claude SDK → `claude-sonnet-5`)
  * - `systemPrompt`→ `GUUEY_DEFAULT_SYSTEM_PROMPT` from `./system-prompt`
  * - `auth`        → `'anonymous'`
@@ -97,6 +97,40 @@ declare const McpServerSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         "read-write": "read-write";
     }>>;
 }, z.core.$strict>], "kind">;
+/**
+ * One declared `mcpServers` VALUE: a real server entry, or the literal `false`
+ * — the generative-UI opt-out, valid ONLY under the `ggui` key (enforced by
+ * the agent-level refine; the subtree schema stays lenient by design).
+ */
+export declare const McpServerEntrySchema: z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"colocated">;
+    source: z.ZodString;
+    devPort: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"hosted">;
+    server: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodString>;
+    devPort: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"proxied">;
+    connection: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"external">;
+    url: z.ZodURL;
+    transport: z.ZodOptional<z.ZodEnum<{
+        http: "http";
+        sse: "sse";
+    }>>;
+    federate: z.ZodOptional<z.ZodBoolean>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    devPort: z.ZodOptional<z.ZodNumber>;
+    mcpResourceUrl: z.ZodOptional<z.ZodURL>;
+    profileAccess: z.ZodOptional<z.ZodEnum<{
+        read: "read";
+        "read-write": "read-write";
+    }>>;
+}, z.core.$strict>], "kind">, z.ZodLiteral<false>]>;
+export type DeclaredMcpServers = Record<string, GuueyAgentMcpServer | false>;
 /**
  * Tool-gate block — allowlist applied first (intersect with what the MCP
  * server advertises), then denylist subtracts. Tool names are MCP-namespaced
@@ -171,7 +205,7 @@ declare const DeploySchema: z.ZodObject<{
  * resolve-mcp): whole-snapshot strictness made lowering fail open on any
  * schema field the running consumer predates.
  */
-export declare const McpServersSection: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+export declare const McpServersSection: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"colocated">;
     source: z.ZodString;
     devPort: z.ZodOptional<z.ZodNumber>;
@@ -198,7 +232,7 @@ export declare const McpServersSection: z.ZodRecord<z.ZodString, z.ZodDiscrimina
         read: "read";
         "read-write": "read-write";
     }>>;
-}, z.core.$strict>], "kind">>;
+}, z.core.$strict>], "kind">, z.ZodLiteral<false>]>>;
 export declare const AgentSectionV1: z.ZodObject<{
     mode: z.ZodOptional<z.ZodEnum<{
         code: "code";
@@ -219,7 +253,7 @@ export declare const AgentSectionV1: z.ZodObject<{
     systemPrompt: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
         file: z.ZodString;
     }, z.core.$strict>]>>;
-    mcpServers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+    mcpServers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"colocated">;
         source: z.ZodString;
         devPort: z.ZodOptional<z.ZodNumber>;
@@ -246,7 +280,7 @@ export declare const AgentSectionV1: z.ZodObject<{
             read: "read";
             "read-write": "read-write";
         }>>;
-    }, z.core.$strict>], "kind">>>;
+    }, z.core.$strict>], "kind">, z.ZodLiteral<false>]>>>;
     tools: z.ZodOptional<z.ZodObject<{
         allowlist: z.ZodOptional<z.ZodArray<z.ZodString>>;
         denylist: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -372,14 +406,25 @@ export declare const RESERVED_MCP_SERVER_NAMES: readonly string[];
  */
 export declare function validateReservedServerNames(agent: GuueyAgent | undefined): string[];
 /**
- * Platform default MCP server map. Applied by the pod when `agent.mcpServers`
- * is absent. Exposed here so non-pod consumers (CLI dry-run, lints) can show
- * the effective shape without duplicating the literal.
+ * Platform default MCP server map. Seeded under every declared map by
+ * {@link effectiveMcpServers} (opt out with `ggui: false`). Exposed here so
+ * non-pod consumers (CLI dry-run, lints) can show the effective shape without
+ * duplicating the literal.
  *
  * The ggui server is `kind: 'external'` — it is builder-declared when present
  * or injected by the platform at runtime. Federation still detects it by host
  * (via `isGguiUrl`) regardless of which key it's declared under.
  */
 export declare const DEFAULT_AGENT_MCP_SERVERS: Record<string, GuueyAgentMcpServer>;
+/**
+ * The EFFECTIVE server map (guuey#24, option A): seed the platform default,
+ * layer the declared map on top (explicit wins), drop `ggui: false`. This is
+ * the ONE owner of default-application semantics — the resolution seams
+ * (credential broker, render-tool resolution) call this; declared-map
+ * ITERATION sites use {@link declaredServerEntries} instead.
+ */
+export declare function effectiveMcpServers(declared: DeclaredMcpServers | undefined): Record<string, GuueyAgentMcpServer>;
+/** The declared entries that are real servers (the `ggui: false` opt-out filtered out) — the narrowing every declared-map iteration site uses. */
+export declare function declaredServerEntries(servers: DeclaredMcpServers | undefined): Array<[string, GuueyAgentMcpServer]>;
 export {};
 //# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}

package/dist/agent.js

@@ -23,7 +23,7 @@
  *
  * Defaults applied by the pod runtime when fields are absent:
  * - `framework`   → `'claude-agent-sdk'`
- * - `mcpServers`  → `{ ggui: { url: 'https://mcp.ggui.ai' } }` (platform default; declaring `mcpServers` REPLACES this — not merged)
+ * - `mcpServers`  → `{ ggui: { url: 'https://mcp.ggui.ai' } }` (platform default; declaring `mcpServers` MERGES ON TOP of this (guuey#24 option A); opt out with `ggui: false`)
  * - `model`       → framework-chosen default (Claude SDK → `claude-sonnet-5`)
  * - `systemPrompt`→ `GUUEY_DEFAULT_SYSTEM_PROMPT` from `./system-prompt`
  * - `auth`        → `'anonymous'`
@@ -166,6 +166,12 @@ const McpServerSchema = z.discriminatedUnion('kind', [
     ProxiedMcp,
     ExternalMcp,
 ]);
+/**
+ * One declared `mcpServers` VALUE: a real server entry, or the literal `false`
+ * — the generative-UI opt-out, valid ONLY under the `ggui` key (enforced by
+ * the agent-level refine; the subtree schema stays lenient by design).
+ */
+export const McpServerEntrySchema = z.union([McpServerSchema, z.literal(false)]);
 /**
  * Tool-gate block — allowlist applied first (intersect with what the MCP
  * server advertises), then denylist subtracts. Tool names are MCP-namespaced
@@ -264,7 +270,7 @@ const StorageScopeSchema = z.array(z.enum(['user', 'app']));
  * resolve-mcp): whole-snapshot strictness made lowering fail open on any
  * schema field the running consumer predates.
  */
-export const McpServersSection = z.record(z.string().min(1), McpServerSchema);
+export const McpServersSection = z.record(z.string().min(1), McpServerEntrySchema);
 export const AgentSectionV1 = z.strictObject({
     // ── Deploy routing ──
     /**
@@ -303,18 +309,33 @@ export const AgentSectionV1 = z.strictObject({
     modelProvider: z.enum(['openai', 'openrouter']).optional(),
     systemPrompt: SystemPromptSchema.optional(),
     /**
-     * MCP servers the agent may call. **Replaces** the platform default
-     * (`{ ggui: { kind: 'external', url: 'https://mcp.ggui.ai', transport: 'http' } }`)
-     * when present — not merged. Omit the block to inherit the default; include
-     * `ggui` explicitly to keep it alongside other servers.
+     * MCP servers the agent may call. **Merges on top of** the platform default
+     * (`{ ggui: { kind: 'external', url: 'https://mcp.ggui.ai', transport: 'http' } }`,
+     * guuey#24 option A) — see {@link effectiveMcpServers}. Omit the block to
+     * inherit the default unchanged; declare `ggui` explicitly to override it;
+     * declare `ggui: false` to opt out of it entirely.
      *
-     * Each entry is a discriminated union on `kind`:
+     * Each entry is a discriminated union on `kind`, or the literal `false`
+     * (valid only under the `ggui` key):
      * - `'colocated'` — guuey-managed HTTP child inside the agent pod
      * - `'hosted'`    — guuey-hosted registry MCP (Starter+)
      * - `'proxied'`   — 3rd-party SaaS via mcp-proxy (v2)
      * - `'external'`  — builder-hosted URL (plain or federated)
      */
-    mcpServers: z.record(z.string().min(1), McpServerSchema).optional(),
+    mcpServers: z
+        .record(z.string().min(1), McpServerEntrySchema)
+        .superRefine((servers, ctx) => {
+        for (const [name, entry] of Object.entries(servers)) {
+            if (entry === false && name !== 'ggui') {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: [name],
+                    message: `mcpServers.${name}: false is only valid for the "ggui" key (it opts out of the platform-default generative-UI server) — remove the "${name}" entry instead`,
+                });
+            }
+        }
+    })
+        .optional(),
     tools: ToolGatesSchema.optional(),
     runtime: RuntimeConfigSchema.optional(),
     /** Claude Agent SDK-specific knobs. Only read when `framework: 'claude-agent-sdk'`. */
@@ -424,7 +445,7 @@ export function validateNoLiteralSecrets(agent) {
     const servers = agent?.mcpServers;
     if (!servers)
         return violations;
-    for (const [serverName, server] of Object.entries(servers)) {
+    for (const [serverName, server] of declaredServerEntries(servers)) {
         // Only the `external` union arm carries a `headers` field.
         const headers = 'headers' in server ? server.headers : undefined;
         if (!headers)
@@ -472,7 +493,7 @@ export function validateColocatedServerNames(agent) {
     const servers = agent?.mcpServers;
     if (!servers)
         return violations;
-    for (const [name, server] of Object.entries(servers)) {
+    for (const [name, server] of declaredServerEntries(servers)) {
         if (server.kind === 'colocated' && !isValidColocatedServerName(name)) {
             violations.push(`colocated MCP server name "${name}" is invalid — use only letters, digits, hyphen, underscore (it becomes part of a URL and a storage scope)`);
         }
@@ -499,7 +520,7 @@ export function validateNoProxiedServers(agent) {
     const servers = agent?.mcpServers;
     if (!servers)
         return violations;
-    for (const [name, server] of Object.entries(servers)) {
+    for (const [name, server] of declaredServerEntries(servers)) {
         if (server.kind === 'proxied') {
             violations.push(`MCP server "${name}": kind 'proxied' (the mcp-proxy credential broker) is not yet supported — use 'external', 'hosted', or 'colocated'.`);
         }
@@ -563,9 +584,10 @@ export function validateReservedServerNames(agent) {
     return violations;
 }
 /**
- * Platform default MCP server map. Applied by the pod when `agent.mcpServers`
- * is absent. Exposed here so non-pod consumers (CLI dry-run, lints) can show
- * the effective shape without duplicating the literal.
+ * Platform default MCP server map. Seeded under every declared map by
+ * {@link effectiveMcpServers} (opt out with `ggui: false`). Exposed here so
+ * non-pod consumers (CLI dry-run, lints) can show the effective shape without
+ * duplicating the literal.
  *
  * The ggui server is `kind: 'external'` — it is builder-declared when present
  * or injected by the platform at runtime. Federation still detects it by host
@@ -574,3 +596,23 @@ export function validateReservedServerNames(agent) {
 export const DEFAULT_AGENT_MCP_SERVERS = {
     ggui: { kind: 'external', url: 'https://mcp.ggui.ai', transport: 'http' },
 };
+/**
+ * The EFFECTIVE server map (guuey#24, option A): seed the platform default,
+ * layer the declared map on top (explicit wins), drop `ggui: false`. This is
+ * the ONE owner of default-application semantics — the resolution seams
+ * (credential broker, render-tool resolution) call this; declared-map
+ * ITERATION sites use {@link declaredServerEntries} instead.
+ */
+export function effectiveMcpServers(declared) {
+    const merged = { ...DEFAULT_AGENT_MCP_SERVERS, ...declared };
+    const out = {};
+    for (const [name, entry] of Object.entries(merged)) {
+        if (entry !== false)
+            out[name] = entry;
+    }
+    return out;
+}
+/** The declared entries that are real servers (the `ggui: false` opt-out filtered out) — the narrowing every declared-map iteration site uses. */
+export function declaredServerEntries(servers) {
+    return Object.entries(servers ?? {}).filter((e) => e[1] !== false);
+}

package/dist/schema.d.ts

@@ -77,7 +77,7 @@ export declare const GuueyJsonV1: z.ZodObject<{
         systemPrompt: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
             file: z.ZodString;
         }, z.core.$strict>]>>;
-        mcpServers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+        mcpServers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject<{
             kind: z.ZodLiteral<"colocated">;
             source: z.ZodString;
             devPort: z.ZodOptional<z.ZodNumber>;
@@ -104,7 +104,7 @@ export declare const GuueyJsonV1: z.ZodObject<{
                 read: "read";
                 "read-write": "read-write";
             }>>;
-        }, z.core.$strict>], "kind">>>;
+        }, z.core.$strict>], "kind">, z.ZodLiteral<false>]>>>;
         tools: z.ZodOptional<z.ZodObject<{
             allowlist: z.ZodOptional<z.ZodArray<z.ZodString>>;
             denylist: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guuey/config",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Open-source schemas + loaders for the three guuey config files: agent.json (declarative agent definition), guuey.json (hosted-deploy overlay), and the helper types around them. Consumed by @guuey/cli, the guuey backend, and devs writing their own agent or MCP server.",
   "license": "MIT",
   "type": "module",