@guuey/config 0.8.0 → 0.9.0

package/dist/agent.d.ts

@@ -66,8 +66,12 @@ export type ProfileAccess = z.infer<typeof ProfileAccessSchema>;
  * Discriminated union on `kind` — one slot per hosting mode:
  * - `colocated` — guuey-managed HTTP child inside the agent pod
  * - `hosted`    — guuey-hosted registry MCP (Starter+)
- * - `proxied`   — 3rd-party SaaS via mcp-proxy credential broker (v2)
- * - `external`  — builder-hosted, reached by URL (plain or federated)
+ * - `external`  — reached by URL: builder-hosted (plain / federated /
+ *                 caller-forwarded) or third-party OAuth (`credential: 'oauth'`)
+ *
+ * (`kind: 'proxied'` — the pre-registration placeholder the mcp-proxy broker
+ * once reserved — is gone: `credential: 'oauth'` on an `external` entry IS
+ * that arm, guuey#178 D1.)
  */
 declare const McpServerSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"colocated">;
@@ -78,9 +82,6 @@ declare const McpServerSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     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;
@@ -89,7 +90,10 @@ declare const McpServerSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         sse: "sse";
     }>>;
     federate: z.ZodOptional<z.ZodBoolean>;
-    credential: z.ZodOptional<z.ZodLiteral<"caller">>;
+    credential: z.ZodOptional<z.ZodEnum<{
+        caller: "caller";
+        oauth: "oauth";
+    }>>;
     headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     devPort: z.ZodOptional<z.ZodNumber>;
     mcpResourceUrl: z.ZodOptional<z.ZodURL>;
@@ -112,9 +116,6 @@ export declare const McpServerEntrySchema: z.ZodUnion<readonly [z.ZodDiscriminat
     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;
@@ -123,7 +124,10 @@ export declare const McpServerEntrySchema: z.ZodUnion<readonly [z.ZodDiscriminat
         sse: "sse";
     }>>;
     federate: z.ZodOptional<z.ZodBoolean>;
-    credential: z.ZodOptional<z.ZodLiteral<"caller">>;
+    credential: z.ZodOptional<z.ZodEnum<{
+        caller: "caller";
+        oauth: "oauth";
+    }>>;
     headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     devPort: z.ZodOptional<z.ZodNumber>;
     mcpResourceUrl: z.ZodOptional<z.ZodURL>;
@@ -251,9 +255,6 @@ export declare const McpServersSection: z.ZodRecord<z.ZodString, z.ZodUnion<read
     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;
@@ -262,7 +263,10 @@ export declare const McpServersSection: z.ZodRecord<z.ZodString, z.ZodUnion<read
         sse: "sse";
     }>>;
     federate: z.ZodOptional<z.ZodBoolean>;
-    credential: z.ZodOptional<z.ZodLiteral<"caller">>;
+    credential: z.ZodOptional<z.ZodEnum<{
+        caller: "caller";
+        oauth: "oauth";
+    }>>;
     headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     devPort: z.ZodOptional<z.ZodNumber>;
     mcpResourceUrl: z.ZodOptional<z.ZodURL>;
@@ -300,9 +304,6 @@ export declare const AgentSectionV1: z.ZodObject<{
         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;
@@ -311,7 +312,10 @@ export declare const AgentSectionV1: z.ZodObject<{
             sse: "sse";
         }>>;
         federate: z.ZodOptional<z.ZodBoolean>;
-        credential: z.ZodOptional<z.ZodLiteral<"caller">>;
+        credential: z.ZodOptional<z.ZodEnum<{
+            caller: "caller";
+            oauth: "oauth";
+        }>>;
         headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         devPort: z.ZodOptional<z.ZodNumber>;
         mcpResourceUrl: z.ZodOptional<z.ZodURL>;
@@ -409,12 +413,6 @@ export declare function validateNoLiteralSecrets(agent: GuueyAgent | undefined):
  * violation messages (empty = clean).
  */
 export declare function validateColocatedServerNames(agent: GuueyAgent | undefined): string[];
-/**
- * Validate that no `agent.mcpServers` entry uses `kind: 'proxied'`. Returns a
- * list of human-readable violation messages (empty = clean), one per proxied
- * entry, naming the server so the builder knows which ref to change.
- */
-export declare function validateNoProxiedServers(agent: GuueyAgent | undefined): string[];
 /**
  * The reserved colocated key the auto-injected memory MCP is booted + spliced
  * under (memmcp). NEVER builder-declarable — the memory child's own server
@@ -441,7 +439,7 @@ export declare const RESERVED_MCP_SERVER_NAMES: readonly string[];
  * reserved, not just one hosting mode; a builder must not shadow it as
  * `colocated`, `external`, or anything else). Returns a list of human-readable
  * violation messages (empty = clean), one per reserved entry. Mirrors
- * {@link validateNoProxiedServers}'s shape.
+ * {@link validateColocatedServerNames}'s shape.
  */
 export declare function validateReservedServerNames(agent: GuueyAgent | undefined): string[];
 /** One parsed `tools.allowlist` / `tools.denylist` entry. */

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,6EAKnB,CAAC;AACX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAS/D;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;EAAiC,CAAC;AAClE,uEAAuE;AACvE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AA+GhE;;;;;;;;GAQG;AACH,QAAA,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAKnB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;mDAA+C,CAAC;AACjF,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,mBAAmB,GAAG,KAAK,CAAC,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,QAAA,MAAM,eAAe;;;kBAGnB,CAAC;AAEH;;;;;;;;GAQG;AACH,QAAA,MAAM,mBAAmB;;;kBAGvB,CAAC;AAcH;;;;GAIG;AACH,QAAA,MAAM,kBAAkB;;oBAGtB,CAAC;AAEH;;;;;;GAMG;AACH,QAAA,MAAM,oBAAoB;;;kBAGxB,CAAC;AAEH;;;;;;;;;;GAUG;AACH,QAAA,MAAM,YAAY;;;;;;;;;kBAKhB,CAAC;AA8BH;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE;IAAE,OAAO,CAAC,EAAE,aAAa,CAAC,MAAM,GAAG,KAAK,CAAC,CAAA;CAAE,GAAG,SAAS,GAAG,OAAO,CAGxG;AAED;;;;;GAKG;AACH;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;oDAAoD,CAAC;AAEnF,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA4FzB,CAAC;AAEH,kEAAkE;AAClE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAExD,oCAAoC;AACpC,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAElE,4BAA4B;AAC5B,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAElE,iCAAiC;AACjC,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEpE,kDAAkD;AAClD,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAExE,4BAA4B;AAC5B,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAEtE,0BAA0B;AAC1B,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAuE5D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,UAAU,GAAG,SAAS,GAC5B,MAAM,EAAE,CAiCV;AAeD;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,UAAU,GAAG,SAAS,GAC5B,MAAM,EAAE,CAaV;AAaD;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,UAAU,GAAG,SAAS,GAC5B,MAAM,EAAE,CAaV;AAgBD;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,iBAAiB,CAAC;AAE1D;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,kBAAkB,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EAGtD,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,UAAU,GAAG,SAAS,GAC5B,MAAM,EAAE,CAaV;AAgBD,6DAA6D;AAC7D,MAAM,MAAM,aAAa;AACvB,oDAAoD;AAClD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AACvD,iDAAiD;GAC/C;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACxC,wFAAwF;GACtF;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AASnC;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAmBjF;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,GAAG,MAAM,EAAE,CAK3E;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,GAAG,MAAM,EAAE,CAoBzE;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAEzE,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,kBAAkB,GAAG,SAAS,GACvC,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAOrC;AAED,kJAAkJ;AAClJ,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,kBAAkB,GAAG,SAAS,GACtC,KAAK,CAAC,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAItC"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,6EAKnB,CAAC;AACX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAS/D;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;EAAiC,CAAC;AAClE,uEAAuE;AACvE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAyIhE;;;;;;;;;;;;GAYG;AACH,QAAA,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAInB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;mDAA+C,CAAC;AACjF,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,mBAAmB,GAAG,KAAK,CAAC,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,QAAA,MAAM,eAAe;;;kBAGnB,CAAC;AAEH;;;;;;;;GAQG;AACH,QAAA,MAAM,mBAAmB;;;kBAGvB,CAAC;AAcH;;;;GAIG;AACH,QAAA,MAAM,kBAAkB;;oBAGtB,CAAC;AAEH;;;;;;GAMG;AACH,QAAA,MAAM,oBAAoB;;;kBAGxB,CAAC;AAEH;;;;;;;;;;GAUG;AACH,QAAA,MAAM,YAAY;;;;;;;;;kBAKhB,CAAC;AA8BH;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE;IAAE,OAAO,CAAC,EAAE,aAAa,CAAC,MAAM,GAAG,KAAK,CAAC,CAAA;CAAE,GAAG,SAAS,GAAG,OAAO,CAGxG;AAED;;;;;GAKG;AACH;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;oDAAoD,CAAC;AAEnF,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA4FzB,CAAC;AAEH,kEAAkE;AAClE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAExD,oCAAoC;AACpC,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAElE,4BAA4B;AAC5B,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAElE,iCAAiC;AACjC,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEpE,kDAAkD;AAClD,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAExE,4BAA4B;AAC5B,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAEtE,0BAA0B;AAC1B,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAuE5D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,UAAU,GAAG,SAAS,GAC5B,MAAM,EAAE,CAiCV;AAeD;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,UAAU,GAAG,SAAS,GAC5B,MAAM,EAAE,CAaV;AAgBD;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,iBAAiB,CAAC;AAE1D;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,kBAAkB,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EAGtD,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,UAAU,GAAG,SAAS,GAC5B,MAAM,EAAE,CAaV;AAgBD,6DAA6D;AAC7D,MAAM,MAAM,aAAa;AACvB,oDAAoD;AAClD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AACvD,iDAAiD;GAC/C;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACxC,wFAAwF;GACtF;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AASnC;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAmBjF;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,GAAG,MAAM,EAAE,CAK3E;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,GAAG,MAAM,EAAE,CAoBzE;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAEzE,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,kBAAkB,GAAG,SAAS,GACvC,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAOrC;AAED,kJAAkJ;AAClJ,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,kBAAkB,GAAG,SAAS,GACtC,KAAK,CAAC,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAItC"}

package/dist/agent.js

@@ -107,21 +107,18 @@ const HostedMcp = z
     message: 'hosted MCP needs `server`and/or`source`',
 });
 /**
- * `kind: 'proxied'` — a 3rd-party SaaS MCP reached through the mcp-proxy
- * credential broker (Case C). Schema is present now; runtime support lands v2.
- */
-const ProxiedMcp = z.strictObject({
-    kind: z.literal('proxied'),
-    /** mcp-proxy connection id (not yet available — rides with the mcp-proxy credential broker). */
-    connection: z.string().min(1),
-});
-/**
- * `kind: 'external'` — builder-hosted MCP at an arbitrary URL.
+ * `kind: 'external'` — any MCP reached by URL: builder-hosted, or a
+ * third-party SaaS server (Linear, Notion, GitHub, …).
  *
+ * One map, three credential sources + one forward (guuey#178 D1):
  * - `transport` defaults to `'http'` (StreamableHTTP).
+ * - static `headers` (values may use `${env.NAME}`) — API-key servers.
  * - `federate: true` makes guuey mint a per-invoke JWT with `aud = url` that
- *   the builder's MCP validates against the guuey JWKS. Omit for plain URL +
- *   optional static `headers`.
+ *   the builder's MCP validates against the guuey JWKS.
+ * - `credential: 'oauth'` — the server's users sign in with the server's OWN
+ *   OAuth authorization server; guuey brokers the dance and the token
+ *   (see the field doc). URL + `credential: 'oauth'` is the whole
+ *   declaration — nothing is builder-registered; discovery does the rest.
  * - `credential: 'caller'` forwards the invoke's own byo-verified bearer as
  *   this server's per-turn credential (guuey#179) — see the field doc.
  */
@@ -149,8 +146,23 @@ const ExternalMcp = z
      * which app receives its token); FIRST-PARTY USE ONLY for now — gate this
      * (URL allowlist or console warning) before opening it to arbitrary
      * builders. Mutually exclusive with `federate: true`.
+     *
+     * `'oauth'` — the FOURTH mode (guuey#178): the server is a third-party
+     * MCP whose end users must sign in with the server's own OAuth
+     * authorization server (RFC 9728 / 8414 discovery, PKCE, RFC 8707
+     * resource). guuey runs the dance ONCE per (user, server) from a
+     * consent card in the chat, seals the token in the platform's
+     * credential broker, and the agent's calls to this server go through
+     * the broker's gateway (`https://mcp.<apex>/brokered/<appId>/<name>/`),
+     * which injects the user's token per call — the agent pod never holds
+     * the third-party token. The deploy-controller lowers this entry by
+     * setting {@link mcpResourceUrl} to that route while `url` keeps the
+     * upstream. Deploy-only: `guuey dev` has no lowered snapshot. Mutually
+     * exclusive with `federate: true` (the broker route IS the federation
+     * target) and with a declared `authorization` header (the broker
+     * injects the only Authorization this server ever sees).
      */
-    credential: z.literal('caller').optional(),
+    credential: z.enum(['caller', 'oauth']).optional(),
     /** Static headers forwarded on every request. Values may use `${env.NAME}` placeholders. */
     headers: HeadersSchema.optional(),
     /** Local dev-loop port (`guuey dev`) this MCP is served on for name→localhost URL resolution. */
@@ -170,6 +182,13 @@ const ExternalMcp = z
 })
     .refine((v) => !(v.credential === 'caller' && v.federate === true), {
     message: "credential: 'caller' cannot be combined with federate: true — the forwarded caller bearer IS the credential; a minted federation token would shadow it",
+})
+    .refine((v) => !(v.credential === 'oauth' && v.federate === true), {
+    message: "credential: 'oauth' cannot be combined with federate: true — the brokered gateway route IS this server's federation target; the pod mints for it automatically",
+})
+    .refine((v) => !(v.credential === 'oauth' &&
+    Object.keys(v.headers ?? {}).some((h) => h.toLowerCase() === 'authorization')), {
+    message: "credential: 'oauth' cannot be combined with an `authorization` header — the credential broker injects the user's OAuth token as the only Authorization this server sees",
 });
 /**
  * A single MCP server entry inside `agent.mcpServers`.
@@ -177,13 +196,16 @@ const ExternalMcp = z
  * Discriminated union on `kind` — one slot per hosting mode:
  * - `colocated` — guuey-managed HTTP child inside the agent pod
  * - `hosted`    — guuey-hosted registry MCP (Starter+)
- * - `proxied`   — 3rd-party SaaS via mcp-proxy credential broker (v2)
- * - `external`  — builder-hosted, reached by URL (plain or federated)
+ * - `external`  — reached by URL: builder-hosted (plain / federated /
+ *                 caller-forwarded) or third-party OAuth (`credential: 'oauth'`)
+ *
+ * (`kind: 'proxied'` — the pre-registration placeholder the mcp-proxy broker
+ * once reserved — is gone: `credential: 'oauth'` on an `external` entry IS
+ * that arm, guuey#178 D1.)
  */
 const McpServerSchema = z.discriminatedUnion('kind', [
     ColocatedMcp,
     HostedMcp,
-    ProxiedMcp,
     ExternalMcp,
 ]);
 /**
@@ -383,8 +405,8 @@ export const AgentSectionV1 = z.strictObject({
      * (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)
+     * - `'external'`  — reached by URL (plain / federated / caller-forwarded /
+     *                   third-party OAuth via `credential: 'oauth'`)
      */
     mcpServers: z
         .record(z.string().min(1), McpServerEntrySchema)
@@ -564,33 +586,6 @@ export function validateColocatedServerNames(agent) {
     }
     return violations;
 }
-// ── No-proxied-servers validation (deploy-time contract enforcement) ────────
-//
-// `kind: 'proxied'` keeps its schema arm (the documented mcp-proxy
-// credential-broker deferral — wires when the 2nd stored-creds customer signs
-// up) but has NO runtime support today: a pod that booted one would silently
-// miss those tools. `validateNoProxiedServers` is the synchronous deploy-time
-// pre-flight (mirrors `validateColocatedServerNames`'s shape) that rejects it
-// with a fast, actionable error. The deploy-controller's
-// `resolveMcpServersInSnapshot` carries the authoritative backstop throw for
-// code deploys, which never pass through this validator.
-/**
- * Validate that no `agent.mcpServers` entry uses `kind: 'proxied'`. Returns a
- * list of human-readable violation messages (empty = clean), one per proxied
- * entry, naming the server so the builder knows which ref to change.
- */
-export function validateNoProxiedServers(agent) {
-    const violations = [];
-    const servers = agent?.mcpServers;
-    if (!servers)
-        return violations;
-    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'.`);
-        }
-    }
-    return violations;
-}
 // ── Reserved platform MCP server names (deploy-time reservation) ────────────
 //
 // Some `mcpServers` map keys are OWNED by the platform: the runtime splices a
@@ -633,7 +628,7 @@ export const RESERVED_MCP_SERVER_NAMES = [
  * reserved, not just one hosting mode; a builder must not shadow it as
  * `colocated`, `external`, or anything else). Returns a list of human-readable
  * violation messages (empty = clean), one per reserved entry. Mirrors
- * {@link validateNoProxiedServers}'s shape.
+ * {@link validateColocatedServerNames}'s shape.
  */
 export function validateReservedServerNames(agent) {
     const violations = [];

package/dist/loader.d.ts

@@ -13,7 +13,9 @@ export declare const DEFAULT_FIND_MAX_DEPTH = 8;
 export declare function findGuueyJson(startDir?: string, maxDepth?: number): string | null;
 /**
  * Read + parse `guuey.json` from `path`. Throws if the file is missing,
- * unreadable, malformed JSON, or fails schema validation.
+ * unreadable, malformed JSON, declares a `schema` version this package
+ * cannot honor (`GuueyJsonSchemaError` — `SCHEMA_TOO_NEW` / `SCHEMA_UNSUPPORTED`,
+ * see `assertSupportedGuueyJsonSchema`), or fails schema validation.
  *
  * Does NOT resolve `agent.systemPrompt.file` references. Use
  * {@link loadGuueyJson} for file resolution.

package/dist/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAuBA,OAAO,EAEL,WAAW,EAEZ,MAAM,aAAa,CAAC;AAErB,wEAAwE;AACxE,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,GAAE,MAAsB,EAChC,QAAQ,GAAE,MAA+B,GACxC,MAAM,GAAG,IAAI,CAUf;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAa3D;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI,CAIvE;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,oCAAoC;IACpC,GAAG,EAAE,WAAW,CAAC;IACjB;;;;;OAKG;IACH,oBAAoB,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAI7D;AAyCD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,iBAAiB,GAAG,WAAW,CAM1E"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAuBA,OAAO,EAEL,WAAW,EAGZ,MAAM,aAAa,CAAC;AAErB,wEAAwE;AACxE,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,GAAE,MAAsB,EAChC,QAAQ,GAAE,MAA+B,GACxC,MAAM,GAAG,IAAI,CAUf;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAgB3D;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI,CAIvE;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,oCAAoC;IACpC,GAAG,EAAE,WAAW,CAAC;IACjB;;;;;OAKG;IACH,oBAAoB,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAI7D;AAyCD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,iBAAiB,GAAG,WAAW,CAM1E"}

package/dist/loader.js

@@ -21,7 +21,7 @@
  */
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
-import { GUUEY_JSON_FILENAME, parseGuueyJson, } from './schema.js';
+import { GUUEY_JSON_FILENAME, assertSupportedGuueyJsonSchema, parseGuueyJson, } from './schema.js';
 /** How many parent directories `findGuueyJson` will walk by default. */
 export const DEFAULT_FIND_MAX_DEPTH = 8;
 /**
@@ -48,7 +48,9 @@ export function findGuueyJson(startDir = process.cwd(), maxDepth = DEFAULT_FIND_
 }
 /**
  * Read + parse `guuey.json` from `path`. Throws if the file is missing,
- * unreadable, malformed JSON, or fails schema validation.
+ * unreadable, malformed JSON, declares a `schema` version this package
+ * cannot honor (`GuueyJsonSchemaError` — `SCHEMA_TOO_NEW` / `SCHEMA_UNSUPPORTED`,
+ * see `assertSupportedGuueyJsonSchema`), or fails schema validation.
  *
  * Does NOT resolve `agent.systemPrompt.file` references. Use
  * {@link loadGuueyJson} for file resolution.
@@ -66,6 +68,9 @@ export function readGuueyJsonFile(path) {
         const msg = err instanceof Error ? err.message : String(err);
         throw new Error(`guuey.json at ${path} is not valid JSON: ${msg}`);
     }
+    // Version gate BEFORE the shape parse: a too-new document must say
+    // "upgrade", not `at "schema": expected "1"` (guuey#248 b2).
+    assertSupportedGuueyJsonSchema(json);
     return parseGuueyJson(json);
 }
 /**

package/dist/schema.d.ts

@@ -41,6 +41,85 @@ import { z } from 'zod';
 import { type GuueyAgent } from './agent.js';
 import { type GuueyApp } from './app.js';
 import { type GuueyGguiSection } from './ggui.js';
+/**
+ * The ONE `guuey.json` `schema` value this package understands — the
+ * schema-version stance (guuey#248 b2):
+ *
+ * - The root `schema` is a decimal integer string (`"1"`, `"2"`, …), bumped
+ *   only on a change that an older reader cannot interpret correctly.
+ * - A document declaring a NEWER schema than this constant is refused
+ *   everywhere: the CLI (`SCHEMA_TOO_NEW` — upgrade `@guuey/cli`) and the
+ *   reconcile / deploy-trigger APIs (`400 SCHEMA_UNSUPPORTED`). Never
+ *   "best-effort parse what we recognize" — the unknown half is precisely
+ *   the half that matters.
+ * - A document declaring an OLDER schema is accepted only when a migration
+ *   to this version exists. Today there is exactly one version and no
+ *   migrations, so the rule collapses to equal-or-refuse; when `"2"` ships,
+ *   the `1 → 2` migration lands in this package and BOTH sides (CLI + API)
+ *   pick it up through {@link classifyGuueyJsonSchema}.
+ *
+ * The CLI and the platform API compare against the SAME constant (both
+ * consume this package), so "the CLI accepted it but the API refused it"
+ * can only ever mean a version skew between the two — which is exactly the
+ * message the API's refusal names.
+ */
+export declare const SUPPORTED_GUUEY_JSON_SCHEMA = "1";
+/**
+ * Where a raw `guuey.json` document's `schema` sits relative to
+ * {@link SUPPORTED_GUUEY_JSON_SCHEMA}:
+ *
+ * - `supported` — equal (or an older version a migration exists for; none
+ *   today).
+ * - `newer` — a later version than this reader knows: refuse + upgrade.
+ * - `older` — an earlier version with NO migration: refuse.
+ * - `invalid` — absent, not a string, or not a decimal integer string; the
+ *   full schema parse reports the precise issue, this verdict only says the
+ *   version-gate cannot even compare.
+ */
+export type GuueyJsonSchemaVerdict = {
+    kind: 'supported';
+    found: string;
+} | {
+    kind: 'newer';
+    found: string;
+} | {
+    kind: 'older';
+    found: string;
+} | {
+    kind: 'invalid';
+    found: string | undefined;
+};
+/**
+ * Classify a raw (JSON-decoded, NOT yet schema-parsed) document's root
+ * `schema` against {@link SUPPORTED_GUUEY_JSON_SCHEMA}. Pure; never throws.
+ * Run it BEFORE `parseGuueyJson` so a too-new document gets the "upgrade
+ * your CLI" face instead of zod's `expected "1"` at the first field.
+ */
+export declare function classifyGuueyJsonSchema(raw: unknown): GuueyJsonSchemaVerdict;
+/**
+ * Thrown by {@link assertSupportedGuueyJsonSchema} — carries the code the
+ * CLI prints and the API maps to its 400 (`SCHEMA_TOO_NEW` = upgrade the
+ * reader; `SCHEMA_UNSUPPORTED` = an older version no migration exists for).
+ * The message already names the found + supported versions and the remedy.
+ */
+export declare class GuueyJsonSchemaError extends Error {
+    readonly code: 'SCHEMA_TOO_NEW' | 'SCHEMA_UNSUPPORTED';
+    readonly found: string;
+    constructor(code: 'SCHEMA_TOO_NEW' | 'SCHEMA_UNSUPPORTED', found: string, message: string);
+}
+/**
+ * Refuse a document whose `schema` this reader cannot honor. `invalid`
+ * verdicts pass through untouched — the schema parse that follows reports
+ * the precise issue (`at "schema": expected "1"`), which is the right face
+ * for a typo; this gate exists for the version SKEW cases only.
+ *
+ * Runs inside `readGuueyJsonFile` / `loadGuueyJson` (every CLI read of a
+ * checked-in file — `deploy`, `dev`, `agent apply`, …) and in the platform's
+ * reconcile + deploy-trigger handlers, so both ends of the wire refuse the
+ * same documents for the same reason. The message names the remedy for the
+ * only reader outside the platform: the CLI.
+ */
+export declare function assertSupportedGuueyJsonSchema(raw: unknown): void;
 /**
  * Top-level guuey.json v1 schema.
  *
@@ -86,9 +165,6 @@ export declare const GuueyJsonV1: z.ZodObject<{
             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;
@@ -97,7 +173,10 @@ export declare const GuueyJsonV1: z.ZodObject<{
                 sse: "sse";
             }>>;
             federate: z.ZodOptional<z.ZodBoolean>;
-            credential: z.ZodOptional<z.ZodLiteral<"caller">>;
+            credential: z.ZodOptional<z.ZodEnum<{
+                caller: "caller";
+                oauth: "oauth";
+            }>>;
             headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
             devPort: z.ZodOptional<z.ZodNumber>;
             mcpResourceUrl: z.ZodOptional<z.ZodURL>;

package/dist/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,EAAgB,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,EAAiB,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAEjE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAmDtB,CAAC;AAEH,kDAAkD;AAClD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAG3D,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAC;AAEvD;;;GAGG;AACH,eAAO,MAAM,mBAAmB,eAAe,CAAC;AAEhD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,CAExD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,OAAO,GACX,UAAU,CAAC,OAAO,WAAW,CAAC,SAAS,CAAC,CAE1C"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,EAAgB,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,EAAiB,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,sBAAsB,GAC9B;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEnD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,GAAG,sBAAsB,CAY5E;AAED;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;aAE3B,IAAI,EAAE,gBAAgB,GAAG,oBAAoB;aAC7C,KAAK,EAAE,MAAM;gBADb,IAAI,EAAE,gBAAgB,GAAG,oBAAoB,EAC7C,KAAK,EAAE,MAAM,EAC7B,OAAO,EAAE,MAAM;CAKlB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAkBjE;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAmDtB,CAAC;AAEH,kDAAkD;AAClD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAG3D,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAC;AAEvD;;;GAGG;AACH,eAAO,MAAM,mBAAmB,eAAe,CAAC;AAEhD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,CAExD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,OAAO,GACX,UAAU,CAAC,OAAO,WAAW,CAAC,SAAS,CAAC,CAE1C"}

package/dist/schema.js

@@ -41,6 +41,87 @@ import { z } from 'zod';
 import { AgentSectionV1 } from './agent.js';
 import { AppSectionV1 } from './app.js';
 import { GguiSectionV1 } from './ggui.js';
+/**
+ * The ONE `guuey.json` `schema` value this package understands — the
+ * schema-version stance (guuey#248 b2):
+ *
+ * - The root `schema` is a decimal integer string (`"1"`, `"2"`, …), bumped
+ *   only on a change that an older reader cannot interpret correctly.
+ * - A document declaring a NEWER schema than this constant is refused
+ *   everywhere: the CLI (`SCHEMA_TOO_NEW` — upgrade `@guuey/cli`) and the
+ *   reconcile / deploy-trigger APIs (`400 SCHEMA_UNSUPPORTED`). Never
+ *   "best-effort parse what we recognize" — the unknown half is precisely
+ *   the half that matters.
+ * - A document declaring an OLDER schema is accepted only when a migration
+ *   to this version exists. Today there is exactly one version and no
+ *   migrations, so the rule collapses to equal-or-refuse; when `"2"` ships,
+ *   the `1 → 2` migration lands in this package and BOTH sides (CLI + API)
+ *   pick it up through {@link classifyGuueyJsonSchema}.
+ *
+ * The CLI and the platform API compare against the SAME constant (both
+ * consume this package), so "the CLI accepted it but the API refused it"
+ * can only ever mean a version skew between the two — which is exactly the
+ * message the API's refusal names.
+ */
+export const SUPPORTED_GUUEY_JSON_SCHEMA = '1';
+/**
+ * Classify a raw (JSON-decoded, NOT yet schema-parsed) document's root
+ * `schema` against {@link SUPPORTED_GUUEY_JSON_SCHEMA}. Pure; never throws.
+ * Run it BEFORE `parseGuueyJson` so a too-new document gets the "upgrade
+ * your CLI" face instead of zod's `expected "1"` at the first field.
+ */
+export function classifyGuueyJsonSchema(raw) {
+    const found = raw !== null && typeof raw === 'object' && 'schema' in raw
+        ? raw.schema
+        : undefined;
+    if (typeof found !== 'string' || !/^[1-9][0-9]*$/.test(found)) {
+        return { kind: 'invalid', found: typeof found === 'string' ? found : undefined };
+    }
+    const have = Number.parseInt(SUPPORTED_GUUEY_JSON_SCHEMA, 10);
+    const got = Number.parseInt(found, 10);
+    if (got === have)
+        return { kind: 'supported', found };
+    return got > have ? { kind: 'newer', found } : { kind: 'older', found };
+}
+/**
+ * Thrown by {@link assertSupportedGuueyJsonSchema} — carries the code the
+ * CLI prints and the API maps to its 400 (`SCHEMA_TOO_NEW` = upgrade the
+ * reader; `SCHEMA_UNSUPPORTED` = an older version no migration exists for).
+ * The message already names the found + supported versions and the remedy.
+ */
+export class GuueyJsonSchemaError extends Error {
+    code;
+    found;
+    constructor(code, found, message) {
+        super(message);
+        this.code = code;
+        this.found = found;
+        this.name = 'GuueyJsonSchemaError';
+    }
+}
+/**
+ * Refuse a document whose `schema` this reader cannot honor. `invalid`
+ * verdicts pass through untouched — the schema parse that follows reports
+ * the precise issue (`at "schema": expected "1"`), which is the right face
+ * for a typo; this gate exists for the version SKEW cases only.
+ *
+ * Runs inside `readGuueyJsonFile` / `loadGuueyJson` (every CLI read of a
+ * checked-in file — `deploy`, `dev`, `agent apply`, …) and in the platform's
+ * reconcile + deploy-trigger handlers, so both ends of the wire refuse the
+ * same documents for the same reason. The message names the remedy for the
+ * only reader outside the platform: the CLI.
+ */
+export function assertSupportedGuueyJsonSchema(raw) {
+    const verdict = classifyGuueyJsonSchema(raw);
+    if (verdict.kind === 'newer') {
+        throw new GuueyJsonSchemaError('SCHEMA_TOO_NEW', verdict.found, `guuey.json declares schema "${verdict.found}", but this reader understands schema "${SUPPORTED_GUUEY_JSON_SCHEMA}" only. ` +
+            'Upgrade the tool reading it — for the CLI: npm i -g @guuey/cli@latest — and re-run.');
+    }
+    if (verdict.kind === 'older') {
+        throw new GuueyJsonSchemaError('SCHEMA_UNSUPPORTED', verdict.found, `guuey.json declares schema "${verdict.found}", but no migration to schema "${SUPPORTED_GUUEY_JSON_SCHEMA}" exists — ` +
+            `set "schema": "${SUPPORTED_GUUEY_JSON_SCHEMA}" and update the document to the current shape.`);
+    }
+}
 /**
  * Top-level guuey.json v1 schema.
  *
@@ -54,7 +135,7 @@ import { GguiSectionV1 } from './ggui.js';
  * Re-exports the sub-section types for consumer convenience.
  */
 export const GuueyJsonV1 = z.strictObject({
-    schema: z.literal('1'),
+    schema: z.literal(SUPPORTED_GUUEY_JSON_SCHEMA),
     /** Stable agent identifier minted by the control plane on first `guuey create`. */
     appId: z.string().min(1).max(128).optional(),
     /** Workspace the project lives under. Optional — personal apps + freshly-linked apps. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guuey/config",
-  "version": "0.8.0",
+  "version": "0.9.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",