@guuey/config 0.1.0 → 0.1.2

package/dist/agent.d.ts

@@ -49,20 +49,30 @@ import { z } from 'zod';
  */
 export declare const AGENT_FRAMEWORKS: readonly ["claude-agent-sdk", "openai-agents-sdk", "google-adk", "vanilla"];
 export type AgentFramework = (typeof AGENT_FRAMEWORKS)[number];
+/**
+ * Cross-app profile access posture. `'read'` = the agent may recall the
+ * user's cross-app profile; `'read-write'` additionally lets it write this
+ * app's section. Absent = no profile access (default-closed, consent-gated).
+ */
+export declare const ProfileAccessSchema: z.ZodEnum<{
+    read: "read";
+    "read-write": "read-write";
+}>;
+/** Static TypeScript type derived from {@link ProfileAccessSchema}. */
+export type ProfileAccess = z.infer<typeof ProfileAccessSchema>;
 /**
  * A single MCP server entry inside `agent.mcpServers`.
  *
  * Discriminated union on `kind` — one slot per hosting mode:
- * - `colocated` — stdio child inside the agent pod
+ * - `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)
  */
 declare const McpServerSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"colocated">;
-    command: z.ZodString;
-    args: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    source: z.ZodString;
+    devPort: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"hosted">;
     server: z.ZodOptional<z.ZodString>;
@@ -81,6 +91,11 @@ declare const McpServerSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     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">;
 /**
  * Tool-gate block — allowlist applied first (intersect with what the MCP
@@ -150,6 +165,40 @@ declare const DeploySchema: z.ZodObject<{
  * Exported as a zod object so the top-level `GuueyJsonV1` schema (in
  * `./schema.ts`) can nest it. Static type via {@link GuueyAgent}.
  */
+/**
+ * The `agent.mcpServers` map alone — for consumers that resolve/lower the
+ * servers SUBTREE without validating the whole snapshot (deploy-controller's
+ * 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<{
+    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">>;
 export declare const AgentSectionV1: z.ZodObject<{
     mode: z.ZodOptional<z.ZodEnum<{
         code: "code";
@@ -161,6 +210,7 @@ export declare const AgentSectionV1: z.ZodObject<{
         "google-adk": "google-adk";
         vanilla: "vanilla";
     }>>;
+    entry: z.ZodOptional<z.ZodString>;
     model: z.ZodOptional<z.ZodString>;
     modelProvider: z.ZodOptional<z.ZodEnum<{
         openai: "openai";
@@ -171,9 +221,8 @@ export declare const AgentSectionV1: z.ZodObject<{
     }, z.core.$strict>]>>;
     mcpServers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"colocated">;
-        command: z.ZodString;
-        args: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        source: z.ZodString;
+        devPort: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"hosted">;
         server: z.ZodOptional<z.ZodString>;
@@ -192,6 +241,11 @@ export declare const AgentSectionV1: z.ZodObject<{
         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">>>;
     tools: z.ZodOptional<z.ZodObject<{
         allowlist: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -223,6 +277,10 @@ export declare const AgentSectionV1: z.ZodObject<{
         user: "user";
         app: "app";
     }>>>;
+    profileAccess: z.ZodOptional<z.ZodEnum<{
+        read: "read";
+        "read-write": "read-write";
+    }>>;
     env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     secrets: z.ZodOptional<z.ZodArray<z.ZodString>>;
     endpoint: z.ZodOptional<z.ZodObject<{
@@ -270,6 +328,49 @@ export type GuueyAgentDeploy = z.infer<typeof DeploySchema>;
  * `X-API-Key: ${env.KEY}`) and non-secret literals (`Content-Type`) pass.
  */
 export declare function validateNoLiteralSecrets(agent: GuueyAgent | undefined): string[];
+/**
+ * Validate that every `kind: 'colocated'` entry's NAME (the `mcpServers`
+ * map key) is safe to compose into `colocatedResourceUrl` — i.e. passes
+ * {@link isValidColocatedServerName} (from `./colocated.ts`, the single
+ * source of truth for the rule). Returns a list of human-readable
+ * 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
+ * advertises this same name and its aud is `colocatedResourceUrl(appId, this)`.
+ */
+export declare const RESERVED_MEMORY_SERVER_NAME = "guuey-memory";
+/**
+ * The reserved colocated key the auto-injected cross-app profile MCP is
+ * booted + spliced under (profile T1+). NEVER builder-declarable — mirrors
+ * {@link RESERVED_MEMORY_SERVER_NAME}'s reservation for the same reason: a
+ * builder-declared server under this key would be silently replaced by the
+ * platform entry at invoke time.
+ */
+export declare const RESERVED_PROFILE_SERVER_NAME = "guuey-profile";
+/**
+ * Every `mcpServers` map key the platform reserves. Extensible — one entry
+ * today ({@link RESERVED_MEMORY_SERVER_NAME}); future platform-injected
+ * servers add their key here and inherit the deploy-time rejection for free.
+ */
+export declare const RESERVED_MCP_SERVER_NAMES: readonly string[];
+/**
+ * Validate that no `agent.mcpServers` entry uses a platform-RESERVED name
+ * ({@link RESERVED_MCP_SERVER_NAMES}) — regardless of `kind` (the key is
+ * 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.
+ */
+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

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;AAGxB;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,6EAKnB,CAAC;AACX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAoF/D;;;;;;;;GAQG;AACH,QAAA,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;4BAKnB,CAAC;AAEH;;;;GAIG;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;AAsBH;;;;;GAKG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAoEzB,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;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAEzE,CAAC"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}

package/dist/agent.js

@@ -41,6 +41,7 @@
  */
 import { z } from 'zod';
 import { AGENT_SIZES } from './hosting.js';
+import { isValidColocatedServerName } from './colocated.js';
 /**
  * Supported framework adapters. The pod runtime selects the matching
  * `@guuey/framework-*` adapter at boot. `vanilla` skips the framework
@@ -61,18 +62,25 @@ export const AGENT_FRAMEWORKS = [
  */
 const HeadersSchema = z.record(z.string().min(1), z.string());
 /**
- * `kind: 'colocated'` — MCP server runs as a stdio child **inside the agent
- * pod** (co-locate = same gVisor sandbox). COGS: ~$0 (rides the agent pod).
- * Nocode runtime spawns `command [args…]` at boot.
+ * Cross-app profile access posture. `'read'` = the agent may recall the
+ * user's cross-app profile; `'read-write'` additionally lets it write this
+ * app's section. Absent = no profile access (default-closed, consent-gated).
+ */
+export const ProfileAccessSchema = z.enum(['read', 'read-write']);
+/**
+ * `kind: 'colocated'` — MCP server runs as a guuey-managed HTTP child
+ * **inside the agent pod** (co-locate = same gVisor sandbox). COGS: ~$0
+ * (rides the agent pod). `source` is a project-relative path the Router
+ * lowering builds/boots as a local HTTP server; `devPort` mirrors the
+ * `hosted`/`external` dev-loop story (name→localhost URL resolution for
+ * `guuey dev`).
  */
 const ColocatedMcp = z.strictObject({
     kind: z.literal('colocated'),
-    /** Executable name or path. Required. */
-    command: z.string().min(1),
-    /** Argv beyond `command`. */
-    args: z.array(z.string()).optional(),
-    /** Static headers (less common for stdio, but supported for symmetry). */
-    headers: HeadersSchema.optional(),
+    /** Source directory relative to `guuey.json`. Required. */
+    source: z.string().min(1),
+    /** Local dev-loop port (`guuey dev`) this MCP is served on for name→localhost URL resolution. */
+    devPort: z.number().int().min(1).max(65535).optional(),
 });
 /**
  * `kind: 'hosted'` — a workspace-owned registry MCP running on guuey's
@@ -104,7 +112,7 @@ const HostedMcp = z
  */
 const ProxiedMcp = z.strictObject({
     kind: z.literal('proxied'),
-    /** mcp-proxy connection id (from `guuey connections add`). */
+    /** mcp-proxy connection id (not yet available — rides with the mcp-proxy credential broker). */
     connection: z.string().min(1),
 });
 /**
@@ -130,12 +138,24 @@ const ExternalMcp = z.strictObject({
     headers: HeadersSchema.optional(),
     /** Local dev-loop port (`guuey dev`) this MCP is served on for name→localhost URL resolution. */
     devPort: z.number().int().min(1).max(65535).optional(),
+    /**
+     * INTERNAL — set only by Router lowering; when present the federation mint
+     * uses this as the RFC 8707 resource instead of `url`.
+     */
+    mcpResourceUrl: z.url().optional(),
+    /**
+     * INTERNAL — set only by Router lowering when this entry is the spliced
+     * profile MCP; carries the agent's `profileAccess` posture onto the entry
+     * itself so the profile child's tool gate (read vs read-write) survives
+     * independent of the top-level `agent.profileAccess` field.
+     */
+    profileAccess: ProfileAccessSchema.optional(),
 });
 /**
  * A single MCP server entry inside `agent.mcpServers`.
  *
  * Discriminated union on `kind` — one slot per hosting mode:
- * - `colocated` — stdio child inside the agent pod
+ * - `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)
@@ -238,6 +258,13 @@ const StorageScopeSchema = z.array(z.enum(['user', 'app']));
  * Exported as a zod object so the top-level `GuueyJsonV1` schema (in
  * `./schema.ts`) can nest it. Static type via {@link GuueyAgent}.
  */
+/**
+ * The `agent.mcpServers` map alone — for consumers that resolve/lower the
+ * servers SUBTREE without validating the whole snapshot (deploy-controller's
+ * 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 AgentSectionV1 = z.strictObject({
     // ── Deploy routing ──
     /**
@@ -256,6 +283,14 @@ export const AgentSectionV1 = z.strictObject({
     mode: z.enum(['code', 'declarative']).optional(),
     // ── Framework + runtime ──
     framework: z.enum(AGENT_FRAMEWORKS).optional(),
+    /**
+     * Graceful code-mode: a module (path relative to the project root, built
+     * output) whose default export is the framework-native agent object or a
+     * factory `(guuey: GuueyContext) => agent`. The platform host imports and
+     * runs it — the dev writes zero harness code. Mutually exclusive with the
+     * full-worker `worker` field (which wins when both are present).
+     */
+    entry: z.string().min(1).optional(),
     model: z.string().min(1).optional(),
     /**
      * Managed-LLM provider selector — only meaningful for
@@ -274,7 +309,7 @@ export const AgentSectionV1 = z.strictObject({
      * `ggui` explicitly to keep it alongside other servers.
      *
      * Each entry is a discriminated union on `kind`:
-     * - `'colocated'` — stdio child inside the agent pod
+     * - `'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)
@@ -288,6 +323,7 @@ export const AgentSectionV1 = z.strictObject({
     auth: AuthSchema.optional(),
     memory: MemorySchema.optional(),
     storage: StorageScopeSchema.optional(),
+    profileAccess: ProfileAccessSchema.optional(),
     // ── Env + secrets ──
     /** Literal non-sensitive env vars baked into the pod at boot. */
     env: z.record(z.string().min(1), z.string()).optional(),
@@ -389,7 +425,7 @@ export function validateNoLiteralSecrets(agent) {
     if (!servers)
         return violations;
     for (const [serverName, server] of Object.entries(servers)) {
-        // Only `colocated` and `external` union arms carry a `headers` field.
+        // Only the `external` union arm carries a `headers` field.
         const headers = 'headers' in server ? server.headers : undefined;
         if (!headers)
             continue;
@@ -412,6 +448,120 @@ export function validateNoLiteralSecrets(agent) {
     }
     return violations;
 }
+// ── No-invalid-colocated-names validation (deploy-time contract enforcement) ──
+//
+// `agent.mcpServers`' key is schema-typed only `z.string().min(1)` — any
+// non-empty string parses. But at pod boot, `lowerColocated` composes the
+// KEY (not just `source`) into `colocatedResourceUrl(appId, name)`, which
+// THROWS for anything outside `/^[A-Za-z0-9_-]+$/` (see `./colocated.ts`).
+// An invalid colocated name therefore parses fine client-side and only
+// fails once the pod is already booting, as an unactionable
+// `POD_FATAL_BOOT_ERROR` crash-loop. `validateColocatedServerNames` is the
+// deploy-time pre-flight that catches it first — mirrors
+// `validateNoLiteralSecrets`'s shape (explicit lint, called by
+// `@guuey/cli`'s `commands/deploy.ts` right before upload).
+/**
+ * Validate that every `kind: 'colocated'` entry's NAME (the `mcpServers`
+ * map key) is safe to compose into `colocatedResourceUrl` — i.e. passes
+ * {@link isValidColocatedServerName} (from `./colocated.ts`, the single
+ * source of truth for the rule). Returns a list of human-readable
+ * violation messages (empty = clean).
+ */
+export function validateColocatedServerNames(agent) {
+    const violations = [];
+    const servers = agent?.mcpServers;
+    if (!servers)
+        return violations;
+    for (const [name, server] of Object.entries(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)`);
+        }
+    }
+    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 Object.entries(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
+// platform-managed entry under them (memmcp — the auto-injected memory MCP is
+// spliced under `guuey-memory` for authenticated invokes; see
+// `nocode-runtime/src/run-seam.ts` + `boot-colocated.ts`). A builder that
+// declares a server under a reserved key would (a) boot as builder code under
+// the same key the platform child owns, and (b) be silently REPLACED by the
+// platform entry at invoke time. `validateReservedServerNames` is the
+// synchronous deploy-time pre-flight that rejects it with a fast, actionable
+// 400 — the primary guard; the run-seam collision guard is defense-in-depth for
+// stale pre-validator snapshots. Single source of the reserved literal: this
+// module. The boot/splice layer (`boot-colocated.ts`) imports it from here.
+/**
+ * The reserved colocated key the auto-injected memory MCP is booted + spliced
+ * under (memmcp). NEVER builder-declarable — the memory child's own server
+ * advertises this same name and its aud is `colocatedResourceUrl(appId, this)`.
+ */
+export const RESERVED_MEMORY_SERVER_NAME = 'guuey-memory';
+/**
+ * The reserved colocated key the auto-injected cross-app profile MCP is
+ * booted + spliced under (profile T1+). NEVER builder-declarable — mirrors
+ * {@link RESERVED_MEMORY_SERVER_NAME}'s reservation for the same reason: a
+ * builder-declared server under this key would be silently replaced by the
+ * platform entry at invoke time.
+ */
+export const RESERVED_PROFILE_SERVER_NAME = 'guuey-profile';
+/**
+ * Every `mcpServers` map key the platform reserves. Extensible — one entry
+ * today ({@link RESERVED_MEMORY_SERVER_NAME}); future platform-injected
+ * servers add their key here and inherit the deploy-time rejection for free.
+ */
+export const RESERVED_MCP_SERVER_NAMES = [
+    RESERVED_MEMORY_SERVER_NAME,
+    RESERVED_PROFILE_SERVER_NAME,
+];
+/**
+ * Validate that no `agent.mcpServers` entry uses a platform-RESERVED name
+ * ({@link RESERVED_MCP_SERVER_NAMES}) — regardless of `kind` (the key is
+ * 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.
+ */
+export function validateReservedServerNames(agent) {
+    const violations = [];
+    const servers = agent?.mcpServers;
+    if (!servers)
+        return violations;
+    for (const name of Object.keys(servers)) {
+        if (RESERVED_MCP_SERVER_NAMES.includes(name)) {
+            violations.push(`MCP server "${name}": that name is reserved by the platform (an auto-injected server uses it) — rename this server.`);
+        }
+    }
+    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

package/dist/browser.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `@guuey/config/browser` — the package minus `loader.js`.
+ *
+ * `loader.js` imports `node:fs` (guuey.json file resolution), which a
+ * browser bundler cannot chunk — importing the root barrel from client
+ * code fails `next build` outright (Turbopack: "does not support
+ * external modules (request: node:fs)"). Browser consumers (Guuey
+ * Studio's agent-config) import this entry instead; Node consumers
+ * (CLI, backend, pods) keep the root barrel.
+ *
+ * Every module re-exported here must stay free of Node builtins.
+ */
+export * from './schema.js';
+export * from './agent.js';
+export * from './app.js';
+export * from './ggui.js';
+export * from './hosting.js';
+export * from './system-prompt.js';
+export * from './registry.js';
+export * from './guuey-context.js';
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC"}

package/dist/browser.js

@@ -0,0 +1,20 @@
+/**
+ * `@guuey/config/browser` — the package minus `loader.js`.
+ *
+ * `loader.js` imports `node:fs` (guuey.json file resolution), which a
+ * browser bundler cannot chunk — importing the root barrel from client
+ * code fails `next build` outright (Turbopack: "does not support
+ * external modules (request: node:fs)"). Browser consumers (Guuey
+ * Studio's agent-config) import this entry instead; Node consumers
+ * (CLI, backend, pods) keep the root barrel.
+ *
+ * Every module re-exported here must stay free of Node builtins.
+ */
+export * from './schema.js';
+export * from './agent.js';
+export * from './app.js';
+export * from './ggui.js';
+export * from './hosting.js';
+export * from './system-prompt.js';
+export * from './registry.js';
+export * from './guuey-context.js';

package/dist/colocated.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Synthetic resource-URL helper for `kind: 'colocated'` MCP servers.
+ *
+ * A colocated MCP has no real network URL (it's a guuey-managed HTTP child
+ * inside the agent pod, reached over a loopback/localhost hop the Router
+ * wires up) — but RFC 8707 federation still needs a stable `aud`/resource
+ * value to mint against, and `@guuey/state`'s KV needs a stable scope key.
+ * `colocatedResourceUrl` composes both from `(appId, serverName)`.
+ *
+ * The returned URL is consumed by `backend/amplify/functions/oidcMint/
+ * handler.ts`'s `parseMcpResourceUrl`, which requires: `https://` prefix,
+ * a trailing `/`, and a total length ≤ 512 chars. Both segments are
+ * validated against `/^[A-Za-z0-9_-]+$/` BEFORE composing the URL — they
+ * are used verbatim as URL path segments AND as a KV scope key, so an
+ * unvalidated segment (e.g. containing `/` or whitespace) could smuggle an
+ * extra path segment or break the scope contract.
+ */
+/**
+ * The synthetic origin every colocated resource URL lives on. Guuey-owned
+ * and compile-time-fixed (NOT env-varying — the host never resolves; it
+ * exists only as a stable RFC 8707 `aud` / KV-scope namespace), so
+ * consumers that must recognize "is this URL guuey-controlled?" (e.g. the
+ * stateApi admin-ownership walk's origin filter) import THIS constant
+ * instead of re-declaring the string or threading a new env var.
+ */
+export declare const COLOCATED_ORIGIN = "https://colocated.guuey.com";
+/**
+ * Whether `value` is safe to use as a `colocatedResourceUrl` path segment /
+ * KV scope key (letters, digits, hyphen, underscore only). Single source of
+ * truth for that rule — reused by {@link assertSafeSegment} here AND by
+ * `./agent.ts#validateColocatedServerNames` (the CLI deploy-time check
+ * `@guuey/cli`'s `commands/deploy.ts` runs before upload), so a bad
+ * colocated server name is rejected before deploy instead of surfacing only
+ * as a `POD_FATAL_BOOT_ERROR` crash-loop when the pod's `lowerColocated`
+ * calls `colocatedResourceUrl` at boot.
+ */
+export declare function isValidColocatedServerName(value: string): boolean;
+/**
+ * Build the synthetic `https://colocated.guuey.com/<appId>/<serverName>/`
+ * resource URL for a colocated MCP server. Throws if either segment fails
+ * the safe-segment check.
+ */
+export declare function colocatedResourceUrl(appId: string, serverName: string): string;
+//# sourceMappingURL=colocated.d.ts.map

package/dist/colocated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"colocated.d.ts","sourceRoot":"","sources":["../src/colocated.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,gCAAgC,CAAC;AAE9D;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEjE;AAUD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAI9E"}

package/dist/colocated.js

@@ -0,0 +1,55 @@
+/**
+ * Synthetic resource-URL helper for `kind: 'colocated'` MCP servers.
+ *
+ * A colocated MCP has no real network URL (it's a guuey-managed HTTP child
+ * inside the agent pod, reached over a loopback/localhost hop the Router
+ * wires up) — but RFC 8707 federation still needs a stable `aud`/resource
+ * value to mint against, and `@guuey/state`'s KV needs a stable scope key.
+ * `colocatedResourceUrl` composes both from `(appId, serverName)`.
+ *
+ * The returned URL is consumed by `backend/amplify/functions/oidcMint/
+ * handler.ts`'s `parseMcpResourceUrl`, which requires: `https://` prefix,
+ * a trailing `/`, and a total length ≤ 512 chars. Both segments are
+ * validated against `/^[A-Za-z0-9_-]+$/` BEFORE composing the URL — they
+ * are used verbatim as URL path segments AND as a KV scope key, so an
+ * unvalidated segment (e.g. containing `/` or whitespace) could smuggle an
+ * extra path segment or break the scope contract.
+ */
+const SAFE_SEGMENT_RE = /^[A-Za-z0-9_-]+$/;
+/**
+ * The synthetic origin every colocated resource URL lives on. Guuey-owned
+ * and compile-time-fixed (NOT env-varying — the host never resolves; it
+ * exists only as a stable RFC 8707 `aud` / KV-scope namespace), so
+ * consumers that must recognize "is this URL guuey-controlled?" (e.g. the
+ * stateApi admin-ownership walk's origin filter) import THIS constant
+ * instead of re-declaring the string or threading a new env var.
+ */
+export const COLOCATED_ORIGIN = 'https://colocated.guuey.com';
+/**
+ * Whether `value` is safe to use as a `colocatedResourceUrl` path segment /
+ * KV scope key (letters, digits, hyphen, underscore only). Single source of
+ * truth for that rule — reused by {@link assertSafeSegment} here AND by
+ * `./agent.ts#validateColocatedServerNames` (the CLI deploy-time check
+ * `@guuey/cli`'s `commands/deploy.ts` runs before upload), so a bad
+ * colocated server name is rejected before deploy instead of surfacing only
+ * as a `POD_FATAL_BOOT_ERROR` crash-loop when the pod's `lowerColocated`
+ * calls `colocatedResourceUrl` at boot.
+ */
+export function isValidColocatedServerName(value) {
+    return SAFE_SEGMENT_RE.test(value);
+}
+function assertSafeSegment(value, label) {
+    if (!isValidColocatedServerName(value)) {
+        throw new Error(`colocatedResourceUrl: ${label} "${value}" must match ${SAFE_SEGMENT_RE.source} (it composes a URL path segment and a KV scope key)`);
+    }
+}
+/**
+ * Build the synthetic `https://colocated.guuey.com/<appId>/<serverName>/`
+ * resource URL for a colocated MCP server. Throws if either segment fails
+ * the safe-segment check.
+ */
+export function colocatedResourceUrl(appId, serverName) {
+    assertSafeSegment(appId, 'appId');
+    assertSafeSegment(serverName, 'serverName');
+    return `${COLOCATED_ORIGIN}/${appId}/${serverName}/`;
+}