@guuey/config 0.6.1 → 0.7.1

package/dist/agent.d.ts

@@ -134,9 +134,33 @@ export declare const McpServerEntrySchema: z.ZodUnion<readonly [z.ZodDiscriminat
 }, z.core.$strict>], "kind">, z.ZodLiteral<false>]>;
 export type DeclaredMcpServers = Record<string, GuueyAgentMcpServer | false>;
 /**
- * Tool-gate block — allowlist applied first (intersect with what the MCP
- * server advertises), then denylist subtracts. Tool names are MCP-namespaced
- * (`"<server>.<tool>"`). Bare names match across all connected servers.
+ * Tool-gate block — `allowlist` first (the model may call ONLY these), then
+ * `denylist` subtracts (removed from the model's catalog outright). Both
+ * optional; both empty/absent → every tool of every connected server.
+ *
+ * Entry shapes (guuey#234 — the ONE grammar, parsed by
+ * {@link parseToolGateEntry}, validated at deploy time by
+ * {@link validateToolGates}, and translated to the framework's own tool
+ * names by the host at turn time):
+ *
+ * - `"<server>.<tool>"` — one tool of one declared MCP server
+ *   (`"todoist.create_task"`).
+ * - `"<server>.*"`      — every tool of one declared server (`"ggui.*"`).
+ * - `"<tool>"`          — a bare name: that tool on EVERY connected server
+ *   (`"search"`), and — for a Claude agent on a GuueyFS-armed pod — the
+ *   built-in file tool of that name (`"Bash"`, `"Write"`, …).
+ *
+ * `<server>` must name a server this agent connects: a declared
+ * `mcpServers` key, the platform default `ggui` (unless opted out with
+ * `ggui: false`), or a platform-injected reserved server
+ * ({@link RESERVED_MCP_SERVER_NAMES}). The framework-internal spellings
+ * (`mcp__server__tool`) are NOT accepted — write the config grammar and
+ * let the host translate.
+ *
+ * Runtime posture (Claude): a tool the model picks that is NOT in an explicit
+ * allowlist is DENIED with a message the model can read — never routed to an
+ * interactive prompt (a headless pod has no one to answer one). Deny-listed
+ * tools never reach the model's catalog at all.
  */
 declare const ToolGatesSchema: z.ZodObject<{
     allowlist: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -409,6 +433,51 @@ export declare const RESERVED_MCP_SERVER_NAMES: readonly string[];
  * {@link validateNoProxiedServers}'s shape.
  */
 export declare function validateReservedServerNames(agent: GuueyAgent | undefined): string[];
+/** One parsed `tools.allowlist` / `tools.denylist` entry. */
+export type ToolGateEntry = 
+/** `"<server>.<tool>"` — one tool of one server. */
+{
+    kind: 'server-tool';
+    server: string;
+    tool: string;
+}
+/** `"<server>.*"` — every tool of one server. */
+ | {
+    kind: 'server-all';
+    server: string;
+}
+/** `"<tool>"` — that tool on every connected server (and the built-in of that name). */
+ | {
+    kind: 'bare';
+    tool: string;
+};
+/**
+ * Parse one tool-gate entry per the {@link ToolGatesSchema} grammar. Returns
+ * the parsed shape, or a human-readable reason string when the entry is
+ * malformed (never throws — callers decide whether to reject or report).
+ */
+export declare function parseToolGateEntry(raw: string): ToolGateEntry | {
+    error: string;
+};
+/**
+ * The server names a tool-gate entry may qualify with: every EFFECTIVE server
+ * (declared map with the platform default seeded and `ggui: false` honoured —
+ * {@link effectiveMcpServers}) plus the platform-injected reserved servers
+ * ({@link RESERVED_MCP_SERVER_NAMES}: memory / profile, spliced at invoke time
+ * for authenticated callers).
+ */
+export declare function toolGateServerNames(agent: GuueyAgent | undefined): string[];
+/**
+ * Validate `agent.tools.allowlist` / `agent.tools.denylist` at deploy time
+ * (guuey#234). Every entry must parse per {@link parseToolGateEntry}, and a
+ * server-qualified entry must name a server this agent connects
+ * ({@link toolGateServerNames}). Returns a list of human-readable violation
+ * messages (empty = clean). Tool-level existence against a server's live
+ * manifest is NOT checked here (a hosted server's tool set is only known once
+ * it is connected) — that is why the host DENIES an unlisted pick at turn time
+ * instead of prompting.
+ */
+export declare function validateToolGates(agent: GuueyAgent | undefined): string[];
 /**
  * Platform default MCP server map. Seeded under every declared map by
  * {@link effectiveMcpServers} (opt out with `ggui: false`). Exposed here so

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

@@ -193,9 +193,33 @@ const McpServerSchema = z.discriminatedUnion('kind', [
  */
 export const McpServerEntrySchema = z.union([McpServerSchema, z.literal(false)]);
 /**
- * Tool-gate block — allowlist applied first (intersect with what the MCP
- * server advertises), then denylist subtracts. Tool names are MCP-namespaced
- * (`"<server>.<tool>"`). Bare names match across all connected servers.
+ * Tool-gate block — `allowlist` first (the model may call ONLY these), then
+ * `denylist` subtracts (removed from the model's catalog outright). Both
+ * optional; both empty/absent → every tool of every connected server.
+ *
+ * Entry shapes (guuey#234 — the ONE grammar, parsed by
+ * {@link parseToolGateEntry}, validated at deploy time by
+ * {@link validateToolGates}, and translated to the framework's own tool
+ * names by the host at turn time):
+ *
+ * - `"<server>.<tool>"` — one tool of one declared MCP server
+ *   (`"todoist.create_task"`).
+ * - `"<server>.*"`      — every tool of one declared server (`"ggui.*"`).
+ * - `"<tool>"`          — a bare name: that tool on EVERY connected server
+ *   (`"search"`), and — for a Claude agent on a GuueyFS-armed pod — the
+ *   built-in file tool of that name (`"Bash"`, `"Write"`, …).
+ *
+ * `<server>` must name a server this agent connects: a declared
+ * `mcpServers` key, the platform default `ggui` (unless opted out with
+ * `ggui: false`), or a platform-injected reserved server
+ * ({@link RESERVED_MCP_SERVER_NAMES}). The framework-internal spellings
+ * (`mcp__server__tool`) are NOT accepted — write the config grammar and
+ * let the host translate.
+ *
+ * Runtime posture (Claude): a tool the model picks that is NOT in an explicit
+ * allowlist is DENIED with a message the model can read — never routed to an
+ * interactive prompt (a headless pod has no one to answer one). Deny-listed
+ * tools never reach the model's catalog at all.
  */
 const ToolGatesSchema = z.strictObject({
     allowlist: z.array(z.string().min(1)).optional(),
@@ -607,6 +631,85 @@ export function validateReservedServerNames(agent) {
     }
     return violations;
 }
+/**
+ * The framework-internal MCP tool-name prefix (Claude Agent SDK:
+ * `mcp__<server>__<tool>`). Rejected in config — builders write the
+ * `<server>.<tool>` grammar; the host translates.
+ */
+const SDK_INTERNAL_TOOL_PREFIX = /^mcp__/;
+/**
+ * Parse one tool-gate entry per the {@link ToolGatesSchema} grammar. Returns
+ * the parsed shape, or a human-readable reason string when the entry is
+ * malformed (never throws — callers decide whether to reject or report).
+ */
+export function parseToolGateEntry(raw) {
+    const entry = raw.trim();
+    if (entry.length === 0)
+        return { error: 'empty entry' };
+    if (SDK_INTERNAL_TOOL_PREFIX.test(entry)) {
+        return {
+            error: `"${entry}" uses the framework-internal spelling — write "<server>.<tool>" (or "<server>.*", or a bare tool name) instead`,
+        };
+    }
+    const dot = entry.indexOf('.');
+    if (dot === -1)
+        return { kind: 'bare', tool: entry };
+    const server = entry.slice(0, dot);
+    const tool = entry.slice(dot + 1);
+    if (server.length === 0)
+        return { error: `"${entry}" has an empty server name before the dot` };
+    if (tool.length === 0)
+        return { error: `"${entry}" has an empty tool name after the dot` };
+    if (tool === '*')
+        return { kind: 'server-all', server };
+    if (tool.includes('*')) {
+        return { error: `"${entry}": wildcards are only valid as the whole tool part ("${server}.*")` };
+    }
+    return { kind: 'server-tool', server, tool };
+}
+/**
+ * The server names a tool-gate entry may qualify with: every EFFECTIVE server
+ * (declared map with the platform default seeded and `ggui: false` honoured —
+ * {@link effectiveMcpServers}) plus the platform-injected reserved servers
+ * ({@link RESERVED_MCP_SERVER_NAMES}: memory / profile, spliced at invoke time
+ * for authenticated callers).
+ */
+export function toolGateServerNames(agent) {
+    return [
+        ...Object.keys(effectiveMcpServers(agent?.mcpServers)),
+        ...RESERVED_MCP_SERVER_NAMES,
+    ];
+}
+/**
+ * Validate `agent.tools.allowlist` / `agent.tools.denylist` at deploy time
+ * (guuey#234). Every entry must parse per {@link parseToolGateEntry}, and a
+ * server-qualified entry must name a server this agent connects
+ * ({@link toolGateServerNames}). Returns a list of human-readable violation
+ * messages (empty = clean). Tool-level existence against a server's live
+ * manifest is NOT checked here (a hosted server's tool set is only known once
+ * it is connected) — that is why the host DENIES an unlisted pick at turn time
+ * instead of prompting.
+ */
+export function validateToolGates(agent) {
+    const violations = [];
+    const gates = agent?.tools;
+    if (!gates)
+        return violations;
+    const known = new Set(toolGateServerNames(agent));
+    for (const list of ['allowlist', 'denylist']) {
+        for (const raw of gates[list] ?? []) {
+            const parsed = parseToolGateEntry(raw);
+            if ('error' in parsed) {
+                violations.push(`tools.${list}: ${parsed.error}`);
+                continue;
+            }
+            if (parsed.kind !== 'bare' && !known.has(parsed.server)) {
+                violations.push(`tools.${list}: "${raw}" names MCP server "${parsed.server}", which this agent does not connect — declare it under mcpServers or use one of: ${[...known].join(', ')}`);
+            }
+        }
+    }
+    return violations;
+}
 /**
  * Platform default MCP server map. Seeded under every declared map by
  * {@link effectiveMcpServers} (opt out with `ggui: false`). Exposed here so

package/package.json

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