@guuey/config 0.16.11 → 0.16.12

package/dist/agent.d.ts

@@ -191,6 +191,42 @@ declare const RuntimeConfigSchema: z.ZodObject<{
 declare const SystemPromptSchema: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
     file: z.ZodString;
 }, z.core.$strict>]>;
+/**
+ * One mode of a multi-mode agent (guuey#527). `systemPromptAppend` extends
+ * the base prompt (inline string or a `{ file }` the loader inlines);
+ * `systemPrompt` replaces it wholesale — exactly ONE of the two (the
+ * refine on {@link ModesSchema} enforces the xor). `tools.allowlist`, when
+ * present, must be a subset of the base allowlist — the WRITE GATE enforces
+ * that (the schema can't see the base), so a mode only ever narrows.
+ * `audience` is accepted for forward-compat but the SERVER hardcodes the
+ * binding for the recognized pair in tonight's slice.
+ */
+declare const ModeSchema: z.ZodObject<{
+    systemPromptAppend: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        file: z.ZodString;
+    }, z.core.$strict>]>>;
+    systemPrompt: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        file: z.ZodString;
+    }, z.core.$strict>]>>;
+    tools: z.ZodOptional<z.ZodObject<{
+        allowlist: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        denylist: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    audience: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        guest: "guest";
+        authenticated: "authenticated";
+        byo: "byo";
+    }>>>;
+}, z.core.$strict>;
+/**
+ * Does the BASE tool allowlist permit `entry`? (guuey#527 subset rule.)
+ * A base pattern covers `entry` when it is `*`, an exact match, or a
+ * `prefix.*` wildcard whose prefix `entry` falls under. This is the SAME
+ * coverage semantics the pod's gate applies at call time, so "the mode's
+ * allowlist is a subset" means exactly "every mode tool the base already
+ * permits" — a mode can only ever NARROW, never widen.
+ */
+export declare function baseAllowlistPermits(baseAllowlist: readonly string[] | undefined, entry: string): boolean;
 /**
  * Bedrock-style invocation endpoint config.
  *
@@ -328,6 +364,24 @@ export declare const AgentSectionV1: z.ZodObject<{
         allowlist: z.ZodOptional<z.ZodArray<z.ZodString>>;
         denylist: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
+    modes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        systemPromptAppend: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            file: z.ZodString;
+        }, z.core.$strict>]>>;
+        systemPrompt: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            file: z.ZodString;
+        }, z.core.$strict>]>>;
+        tools: z.ZodOptional<z.ZodObject<{
+            allowlist: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            denylist: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+        audience: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            guest: "guest";
+            authenticated: "authenticated";
+            byo: "byo";
+        }>>>;
+    }, z.core.$strict>>>;
+    defaultMode: z.ZodOptional<z.ZodString>;
     runtime: z.ZodOptional<z.ZodObject<{
         maxTurns: z.ZodOptional<z.ZodNumber>;
         temperature: z.ZodOptional<z.ZodNumber>;
@@ -387,6 +441,45 @@ export type GuueyAgentRuntime = z.infer<typeof RuntimeConfigSchema>;
 export type GuueyAgentSystemPrompt = z.infer<typeof SystemPromptSchema>;
 /** Endpoint config type. */
 export type GuueyAgentEndpoint = z.infer<typeof EndpointConfigSchema>;
+/** One declared mode's shape. */
+export type GuueyAgentMode = z.infer<typeof ModeSchema>;
+/** The v1 mode axis — the caller's REAL auth state, server-derived. */
+export type ModeAudienceClass = 'guest' | 'auth';
+/** The result of {@link applyAgentMode} — the effective snapshot + provenance. */
+export interface AppliedAgentMode {
+    /** The snapshot to SERVE this invoke (a new object when a mode applied; the same reference otherwise). */
+    agent: GuueyAgent;
+    /** The mode key actually applied, or `null` when serving the bare base. */
+    applied: string | null;
+    /** Present when the resolution took a non-obvious branch (all fail-soft). */
+    fallback?: 'unknown-mode' | 'pin-clamped' | 'auth-undeclared';
+}
+/**
+ * Resolve + apply one invoke's agent mode (guuey#527/#566 — the guest/auth
+ * axis, founder-refined 2026-08-31: "letting them use guest mode vs auth
+ * mode is the correct definition").
+ *
+ * SELECTION is SERVER-DERIVED: `audience` is the caller's REAL auth state
+ * (the pod maps anonymous → 'guest', authenticated → 'auth') — never a
+ * client claim. The `pin` (the widget/SDK `mode` param) may only choose
+ * WITHIN permission: an authed caller may pin 'guest' (preview-as-visitor);
+ * a guest pinning 'auth' is CLAMPED to guest ('pin-clamped'), and an
+ * unrecognized pin key is ignored ('unknown-mode') — fail-soft always, an
+ * embed never breaks.
+ *
+ * Fallback chain: the selected key's def; an undeclared 'auth' falls to
+ * 'guest''s def ('auth-undeclared' — an app that only configures the
+ * visitor rep serves everyone that rep, which IS hire-a-rep); still
+ * nothing → base. `defaultMode` is deprecated and not consulted.
+ *
+ * Application (unchanged from the first cut, test-pinned): `systemPrompt`
+ * REPLACES the base; `systemPromptAppend` = base + "\n\n" + append; an
+ * EMPTY def serves the base by SAME REFERENCE (callers detect no-override
+ * by identity); `tools` replaces with the write-gate-proven subset; a
+ * `{ file }` prompt is unusable at serve time → base. Pure — never
+ * mutates inputs.
+ */
+export declare function applyAgentMode(agent: GuueyAgent, pin: string | undefined, audience: ModeAudienceClass): AppliedAgentMode;
 /** Deploy config type. */
 export type GuueyAgentDeploy = z.infer<typeof DeploySchema>;
 /**
@@ -427,6 +520,14 @@ export declare const RESERVED_MEMORY_SERVER_NAME = "guuey-memory";
  * platform entry at invoke time.
  */
 export declare const RESERVED_PROFILE_SERVER_NAME = "guuey-profile";
+/**
+ * The reserved colocated key the auto-injected human-handoff MCP is booted +
+ * spliced under (guuey#552, spec 2026-08-31-human-handoff-v1-design.md).
+ * NEVER builder-declarable — mirrors {@link RESERVED_MEMORY_SERVER_NAME}'s
+ * reservation for the same reason; the handoff child's own server advertises
+ * this name and its aud is `colocatedResourceUrl(appId, this)`.
+ */
+export declare const RESERVED_HANDOFF_SERVER_NAME = "guuey-handoff";
 /**
  * Every `mcpServers` map key the platform reserves. Extensible — one entry
  * today ({@link RESERVED_MEMORY_SERVER_NAME}); future platform-injected

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

@@ -279,6 +279,58 @@ const SystemPromptSchema = z.union([
     z.string().min(1),
     z.strictObject({ file: z.string().min(1) }),
 ]);
+/**
+ * One mode of a multi-mode agent (guuey#527). `systemPromptAppend` extends
+ * the base prompt (inline string or a `{ file }` the loader inlines);
+ * `systemPrompt` replaces it wholesale — exactly ONE of the two (the
+ * refine on {@link ModesSchema} enforces the xor). `tools.allowlist`, when
+ * present, must be a subset of the base allowlist — the WRITE GATE enforces
+ * that (the schema can't see the base), so a mode only ever narrows.
+ * `audience` is accepted for forward-compat but the SERVER hardcodes the
+ * binding for the recognized pair in tonight's slice.
+ */
+const ModeSchema = z.strictObject({
+    systemPromptAppend: SystemPromptSchema.optional(),
+    systemPrompt: SystemPromptSchema.optional(),
+    tools: ToolGatesSchema.optional(),
+    audience: z.array(z.enum(['guest', 'authenticated', 'byo'])).optional(),
+});
+/**
+ * The `agent.modes` map (guuey#527). Mode keys are short machine
+ * identifiers (`rep`, `agent`, …) — the court-key grammar, reused. Each
+ * value is a {@link ModeSchema}; a mode declares AT MOST one of
+ * `systemPromptAppend` / `systemPrompt` (both = a contradiction the
+ * manifest must not carry).
+ */
+const MODE_KEY_RE = /^[a-z][a-z0-9-]{0,31}$/;
+const ModesSchema = z
+    .record(z.string().regex(MODE_KEY_RE), ModeSchema)
+    .refine((modes) => Object.values(modes).every((m) => !(m.systemPromptAppend !== undefined && m.systemPrompt !== undefined)), { message: 'a mode declares at most one of systemPromptAppend / systemPrompt, never both' });
+/**
+ * Does the BASE tool allowlist permit `entry`? (guuey#527 subset rule.)
+ * A base pattern covers `entry` when it is `*`, an exact match, or a
+ * `prefix.*` wildcard whose prefix `entry` falls under. This is the SAME
+ * coverage semantics the pod's gate applies at call time, so "the mode's
+ * allowlist is a subset" means exactly "every mode tool the base already
+ * permits" — a mode can only ever NARROW, never widen.
+ */
+export function baseAllowlistPermits(baseAllowlist, entry) {
+    // No base allowlist = the model may call anything, so any mode entry is
+    // trivially permitted (the mode is still a real narrowing of "anything").
+    if (baseAllowlist === undefined)
+        return true;
+    return baseAllowlist.some((b) => {
+        if (b === '*')
+            return true;
+        if (b === entry)
+            return true;
+        if (b.endsWith('.*')) {
+            const prefix = b.slice(0, -1); // keep the dot: "platform." covers "platform.whoami"
+            return entry.startsWith(prefix);
+        }
+        return false;
+    });
+}
 /**
  * Bedrock-style invocation endpoint config.
  *
@@ -423,6 +475,28 @@ export const AgentSectionV1 = z.strictObject({
     })
         .optional(),
     tools: ToolGatesSchema.optional(),
+    /**
+     * Multi-mode agent (guuey#527) — ONE agent, per-mode prompt overlays on
+     * the base `systemPrompt` + a per-mode tool SUBSET of the base allowlist.
+     * THE AXIS (founder-refined 2026-08-31, the final word): modes are the
+     * AUDIENCE'S AUTH STATE — v1 recognizes exactly `guest` (website
+     * visitors; the hire-a-rep mode) and `auth` (signed-in users; navigated
+     * separately in studio). SELECTION is SERVER-DERIVED from the caller's
+     * REAL auth state ({@link applyAgentMode}) — an anonymous caller
+     * structurally cannot claim auth mode; the widget/SDK `mode` param is a
+     * PIN within permission (authed may pin `guest` to preview-as-visitor;
+     * a guest pinning `auth` clamps). `defaultMode` and per-mode `audience`
+     * are v1-DEPRECATED (parseable, not consulted — derivation replaced
+     * both); the grammar stays key-agnostic for future axes.
+     *
+     * Each mode: exactly one of `systemPromptAppend` (extend the base — the
+     * common case) or `systemPrompt` (full replace); an optional `tools`
+     * allowlist that must be a SUBSET of the base `agent.tools.allowlist`
+     * (the write gate enforces it — a mode can only ever NARROW).
+     */
+    modes: ModesSchema.optional(),
+    /** The mode a caller with no audience match resolves to (a declared mode key). */
+    defaultMode: z.string().min(1).optional(),
     runtime: RuntimeConfigSchema.optional(),
     /** Claude Agent SDK-specific knobs. Only read when `framework: 'claude-agent-sdk'`. */
     claude: ClaudeFrameworkConfigSchema.optional(),
@@ -444,7 +518,122 @@ export const AgentSectionV1 = z.strictObject({
     endpoint: EndpointConfigSchema.optional(),
     // ── Deploy ──
     deploy: DeploySchema.optional(),
+}).superRefine((agent, ctx) => {
+    // guuey#527 — the mode tool SUBSET rule, enforced at parse time (CLI
+    // loader AND server both run this): a mode's tool allowlist may only
+    // contain tools the BASE allowlist already permits. A mode narrows,
+    // never widens — the one privilege-adjacent axis, closed here.
+    if (agent.modes === undefined)
+        return;
+    const base = agent.tools?.allowlist;
+    for (const [mode, def] of Object.entries(agent.modes)) {
+        const modeAllow = def.tools?.allowlist;
+        if (modeAllow === undefined)
+            continue;
+        for (const entry of modeAllow) {
+            if (!baseAllowlistPermits(base, entry)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ['modes', mode, 'tools', 'allowlist'],
+                    message: `mode "${mode}" allows tool "${entry}" which the base agent.tools.allowlist does not permit — a mode can only narrow the base tools, never widen them`,
+                });
+            }
+        }
+    }
+    // A declared defaultMode must name a declared mode.
+    if (agent.defaultMode !== undefined && agent.modes[agent.defaultMode] === undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['defaultMode'],
+            message: `defaultMode "${agent.defaultMode}" is not a declared mode (${Object.keys(agent.modes).join(', ') || 'none'})`,
+        });
+    }
 });
+/**
+ * Resolve + apply one invoke's agent mode (guuey#527/#566 — the guest/auth
+ * axis, founder-refined 2026-08-31: "letting them use guest mode vs auth
+ * mode is the correct definition").
+ *
+ * SELECTION is SERVER-DERIVED: `audience` is the caller's REAL auth state
+ * (the pod maps anonymous → 'guest', authenticated → 'auth') — never a
+ * client claim. The `pin` (the widget/SDK `mode` param) may only choose
+ * WITHIN permission: an authed caller may pin 'guest' (preview-as-visitor);
+ * a guest pinning 'auth' is CLAMPED to guest ('pin-clamped'), and an
+ * unrecognized pin key is ignored ('unknown-mode') — fail-soft always, an
+ * embed never breaks.
+ *
+ * Fallback chain: the selected key's def; an undeclared 'auth' falls to
+ * 'guest''s def ('auth-undeclared' — an app that only configures the
+ * visitor rep serves everyone that rep, which IS hire-a-rep); still
+ * nothing → base. `defaultMode` is deprecated and not consulted.
+ *
+ * Application (unchanged from the first cut, test-pinned): `systemPrompt`
+ * REPLACES the base; `systemPromptAppend` = base + "\n\n" + append; an
+ * EMPTY def serves the base by SAME REFERENCE (callers detect no-override
+ * by identity); `tools` replaces with the write-gate-proven subset; a
+ * `{ file }` prompt is unusable at serve time → base. Pure — never
+ * mutates inputs.
+ */
+export function applyAgentMode(agent, pin, audience) {
+    const modes = agent.modes;
+    if (modes === undefined)
+        return { agent, applied: null };
+    // ── Selection: derived, then the pin within permission ──────────────
+    let fallback;
+    let selected = audience;
+    if (pin !== undefined && pin !== audience) {
+        if (pin !== 'guest' && pin !== 'auth') {
+            fallback = 'unknown-mode'; // ignored; pure derivation stands
+        }
+        else if (pin === 'auth' && audience === 'guest') {
+            fallback = 'pin-clamped'; // a guest cannot claim auth mode
+        }
+        else {
+            selected = pin; // authed pinning 'guest' — preview-as-visitor
+        }
+    }
+    // ── Fallback chain: selected → guest → base ─────────────────────────
+    let applied = selected;
+    let def = modes[selected];
+    if (def === undefined && selected === 'auth') {
+        def = modes['guest'];
+        if (def !== undefined) {
+            applied = 'guest';
+            fallback = fallback ?? 'auth-undeclared';
+        }
+    }
+    if (def === undefined) {
+        return { agent, applied: null, ...(fallback !== undefined ? { fallback } : {}) };
+    }
+    // ── Application (unchanged) ─────────────────────────────────────────
+    // An EMPTY def (legal — "at most one") IS the base: same reference out,
+    // so callers can cheaply detect "nothing to override" by identity.
+    if (def.systemPrompt === undefined && def.systemPromptAppend === undefined && def.tools === undefined) {
+        return { agent, applied, ...(fallback !== undefined ? { fallback } : {}) };
+    }
+    const basePrompt = typeof agent.systemPrompt === 'string' ? agent.systemPrompt : undefined;
+    let systemPrompt = agent.systemPrompt;
+    if (typeof def.systemPrompt === 'string') {
+        systemPrompt = def.systemPrompt;
+    }
+    else if (typeof def.systemPromptAppend === 'string') {
+        systemPrompt =
+            basePrompt !== undefined ? `${basePrompt}\n\n${def.systemPromptAppend}` : def.systemPromptAppend;
+    }
+    else if (def.systemPrompt !== undefined || def.systemPromptAppend !== undefined) {
+        // { file } shape — unusable at serve time; base verbatim.
+        return { agent, applied: null, ...(fallback !== undefined ? { fallback } : {}) };
+    }
+    return {
+        agent: {
+            ...agent,
+            ...(systemPrompt !== undefined ? { systemPrompt } : {}),
+            ...(def.tools !== undefined ? { tools: def.tools } : {}),
+        },
+        applied,
+        ...(fallback !== undefined ? { fallback } : {}),
+    };
+}
 // ── No-literal-secrets validation (deploy-time contract enforcement) ──────────
 //
 // The schema (McpServerSchema JSDoc) requires secrets in `mcpServers[].headers`
@@ -613,6 +802,14 @@ export const RESERVED_MEMORY_SERVER_NAME = 'guuey-memory';
  * platform entry at invoke time.
  */
 export const RESERVED_PROFILE_SERVER_NAME = 'guuey-profile';
+/**
+ * The reserved colocated key the auto-injected human-handoff MCP is booted +
+ * spliced under (guuey#552, spec 2026-08-31-human-handoff-v1-design.md).
+ * NEVER builder-declarable — mirrors {@link RESERVED_MEMORY_SERVER_NAME}'s
+ * reservation for the same reason; the handoff child's own server advertises
+ * this name and its aud is `colocatedResourceUrl(appId, this)`.
+ */
+export const RESERVED_HANDOFF_SERVER_NAME = 'guuey-handoff';
 /**
  * Every `mcpServers` map key the platform reserves. Extensible — one entry
  * today ({@link RESERVED_MEMORY_SERVER_NAME}); future platform-injected
@@ -621,6 +818,7 @@ export const RESERVED_PROFILE_SERVER_NAME = 'guuey-profile';
 export const RESERVED_MCP_SERVER_NAMES = [
     RESERVED_MEMORY_SERVER_NAME,
     RESERVED_PROFILE_SERVER_NAME,
+    RESERVED_HANDOFF_SERVER_NAME,
 ];
 /**
  * Validate that no `agent.mcpServers` entry uses a platform-RESERVED name

package/dist/app.d.ts

@@ -35,9 +35,9 @@ export type AppUserAuthMode = (typeof APP_USER_AUTH_MODES)[number];
  */
 export declare const AppAccessV1: z.ZodObject<{
     userAuthMode: z.ZodOptional<z.ZodEnum<{
+        byo: "byo";
         anonymous: "anonymous";
         native_pool: "native_pool";
-        byo: "byo";
     }>>;
     userAuthConfig: z.ZodOptional<z.ZodNullable<z.ZodObject<{
         issuerUrl: z.ZodString;
@@ -110,9 +110,9 @@ export declare const AppSectionV1: z.ZodObject<{
     customDomain: z.ZodOptional<z.ZodString>;
     access: z.ZodOptional<z.ZodObject<{
         userAuthMode: z.ZodOptional<z.ZodEnum<{
+            byo: "byo";
             anonymous: "anonymous";
             native_pool: "native_pool";
-            byo: "byo";
         }>>;
         userAuthConfig: z.ZodOptional<z.ZodNullable<z.ZodObject<{
             issuerUrl: z.ZodString;

package/dist/schema.d.ts

@@ -189,6 +189,24 @@ export declare const GuueyJsonV1: z.ZodObject<{
             allowlist: z.ZodOptional<z.ZodArray<z.ZodString>>;
             denylist: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>>;
+        modes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            systemPromptAppend: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                file: z.ZodString;
+            }, z.core.$strict>]>>;
+            systemPrompt: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                file: z.ZodString;
+            }, z.core.$strict>]>>;
+            tools: z.ZodOptional<z.ZodObject<{
+                allowlist: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                denylist: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>>;
+            audience: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                guest: "guest";
+                authenticated: "authenticated";
+                byo: "byo";
+            }>>>;
+        }, z.core.$strict>>>;
+        defaultMode: z.ZodOptional<z.ZodString>;
         runtime: z.ZodOptional<z.ZodObject<{
             maxTurns: z.ZodOptional<z.ZodNumber>;
             temperature: z.ZodOptional<z.ZodNumber>;
@@ -245,9 +263,9 @@ export declare const GuueyJsonV1: z.ZodObject<{
         customDomain: z.ZodOptional<z.ZodString>;
         access: z.ZodOptional<z.ZodObject<{
             userAuthMode: z.ZodOptional<z.ZodEnum<{
+                byo: "byo";
                 anonymous: "anonymous";
                 native_pool: "native_pool";
-                byo: "byo";
             }>>;
             userAuthConfig: z.ZodOptional<z.ZodNullable<z.ZodObject<{
                 issuerUrl: z.ZodString;

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;;;;;;;;;;;;;;;;;;;;;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"}
+{"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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guuey/config",
-  "version": "0.16.11",
+  "version": "0.16.12",
   "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",
@@ -35,7 +35,7 @@
     "@types/node": "^24.0.0",
     "typescript": "^5.0.0",
     "vitest": "^3.2.7",
-    "@guuey/chat": "0.16.11"
+    "@guuey/chat": "0.16.12"
   },
   "publishConfig": {
     "access": "public"