@bolt-foundry/gambit-core 0.8.3 → 0.8.5-rc.4

package/esm/schemas/scenarios/plain_chat_input_optional.d.ts

@@ -0,0 +1,5 @@
+import "../../_dnt.polyfills.js";
+import { z } from "zod";
+declare const plainChatInputOptionalSchema: z.ZodType<string | undefined>;
+export default plainChatInputOptionalSchema;
+//# sourceMappingURL=plain_chat_input_optional.d.ts.map

package/esm/schemas/scenarios/plain_chat_input_optional.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plain_chat_input_optional.d.ts","sourceRoot":"","sources":["../../../src/schemas/scenarios/plain_chat_input_optional.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AACjC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,QAAA,MAAM,4BAA4B,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,GAAG,SAAS,CACnD,CAAC;AAEd,eAAe,4BAA4B,CAAC"}

package/esm/schemas/scenarios/plain_chat_input_optional.js

@@ -0,0 +1,5 @@
+import "../../_dnt.polyfills.js";
+import { z } from "zod";
+const plainChatInputOptionalSchema = z.string()
+    .optional();
+export default plainChatInputOptionalSchema;

package/esm/schemas/scenarios/plain_chat_input_optional.zod.d.ts

@@ -0,0 +1,3 @@
+import "../../_dnt.polyfills.js";
+export { default } from "./plain_chat_input_optional.js";
+//# sourceMappingURL=plain_chat_input_optional.zod.d.ts.map

package/esm/schemas/scenarios/plain_chat_input_optional.zod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plain_chat_input_optional.zod.d.ts","sourceRoot":"","sources":["../../../src/schemas/scenarios/plain_chat_input_optional.zod.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AACjC,OAAO,EAAE,OAAO,EAAE,MAAM,gCAAgC,CAAC"}

package/esm/schemas/scenarios/plain_chat_input_optional.zod.js

@@ -0,0 +1,2 @@
+import "../../_dnt.polyfills.js";
+export { default } from "./plain_chat_input_optional.js";

package/esm/schemas/scenarios/plain_chat_output.d.ts

@@ -0,0 +1,5 @@
+import "../../_dnt.polyfills.js";
+import { z } from "zod";
+declare const plainChatOutputSchema: z.ZodType<string>;
+export default plainChatOutputSchema;
+//# sourceMappingURL=plain_chat_output.d.ts.map

package/esm/schemas/scenarios/plain_chat_output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plain_chat_output.d.ts","sourceRoot":"","sources":["../../../src/schemas/scenarios/plain_chat_output.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AACjC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,QAAA,MAAM,qBAAqB,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAc,CAAC;AAE5D,eAAe,qBAAqB,CAAC"}

package/esm/schemas/scenarios/plain_chat_output.js

@@ -0,0 +1,4 @@
+import "../../_dnt.polyfills.js";
+import { z } from "zod";
+const plainChatOutputSchema = z.string();
+export default plainChatOutputSchema;

package/esm/schemas/scenarios/plain_chat_output.zod.d.ts

@@ -0,0 +1,3 @@
+import "../../_dnt.polyfills.js";
+export { default } from "./plain_chat_output.js";
+//# sourceMappingURL=plain_chat_output.zod.d.ts.map

package/esm/schemas/scenarios/plain_chat_output.zod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plain_chat_output.zod.d.ts","sourceRoot":"","sources":["../../../src/schemas/scenarios/plain_chat_output.zod.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AACjC,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC"}

package/esm/schemas/scenarios/plain_chat_output.zod.js

@@ -0,0 +1,2 @@
+import "../../_dnt.polyfills.js";
+export { default } from "./plain_chat_output.js";

package/esm/src/builtins.d.ts

@@ -1,3 +1,5 @@
 export declare function resolveBuiltinCardPath(target: string): string | undefined;
+export declare function resolveBuiltinSnippetPath(target: string): string | undefined;
 export declare function resolveBuiltinSchemaPath(target: string): string | undefined;
+export declare function resolveBuiltinDeckPath(target: string): string | undefined;
 //# sourceMappingURL=builtins.d.ts.map

package/esm/src/builtins.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../../src/src/builtins.ts"],"names":[],"mappings":"AAYA,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAOzE;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAO3E"}
+{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../../src/src/builtins.ts"],"names":[],"mappings":"AAqBA,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAazE;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAO5E;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAgB3E;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAgBzE"}

package/esm/src/builtins.js

@@ -1,26 +1,70 @@
 import * as path from "../deps/jsr.io/@std/path/1.1.4/mod.js";
 const CARDS_PREFIX = "gambit://cards/";
+const SNIPPETS_PREFIX = "gambit://snippets/";
 const SCHEMAS_PREFIX = "gambit://schemas/";
+const DECKS_PREFIX = "gambit://decks/";
 const CARDS_BASE_URL = new URL("../cards/", globalThis[Symbol.for("import-meta-ponyfill-esmodule")](import.meta).url);
+const SNIPPETS_BASE_URL = new URL("../snippets/", globalThis[Symbol.for("import-meta-ponyfill-esmodule")](import.meta).url);
 const SCHEMAS_BASE_URL = new URL("../schemas/", globalThis[Symbol.for("import-meta-ponyfill-esmodule")](import.meta).url);
+const DECKS_BASE_URL = new URL("../decks/", globalThis[Symbol.for("import-meta-ponyfill-esmodule")](import.meta).url);
+const LEGACY_CARD_WARNINGS = new Set();
+const LEGACY_SCHEMA_WARNINGS = new Set();
+const LEGACY_DECK_WARNINGS = new Set();
+const logger = console;
 function resolveFromBase(base, relative) {
     return path.fromFileUrl(new URL(relative, base));
 }
 export function resolveBuiltinCardPath(target) {
     if (!target.startsWith(CARDS_PREFIX))
         return undefined;
+    if (!LEGACY_CARD_WARNINGS.has(target)) {
+        LEGACY_CARD_WARNINGS.add(target);
+        logger.warn(`[gambit] "${target}" is deprecated; use gambit://snippets instead.`);
+    }
     const relative = target.slice(CARDS_PREFIX.length);
     if (!relative) {
         throw new Error(`Invalid gambit card specifier: ${target}`);
     }
     return resolveFromBase(CARDS_BASE_URL, relative);
 }
+export function resolveBuiltinSnippetPath(target) {
+    if (!target.startsWith(SNIPPETS_PREFIX))
+        return undefined;
+    const relative = target.slice(SNIPPETS_PREFIX.length);
+    if (!relative) {
+        throw new Error(`Invalid gambit snippet specifier: ${target}`);
+    }
+    return resolveFromBase(SNIPPETS_BASE_URL, relative);
+}
 export function resolveBuiltinSchemaPath(target) {
     if (!target.startsWith(SCHEMAS_PREFIX))
         return undefined;
-    const relative = target.slice(SCHEMAS_PREFIX.length);
+    let relative = target.slice(SCHEMAS_PREFIX.length);
     if (!relative) {
         throw new Error(`Invalid gambit schema specifier: ${target}`);
     }
+    if (relative.endsWith(".ts") && !relative.endsWith(".zod.ts")) {
+        if (!LEGACY_SCHEMA_WARNINGS.has(target)) {
+            LEGACY_SCHEMA_WARNINGS.add(target);
+            logger.warn(`[gambit] "${target}" is deprecated; use .zod.ts schema URIs instead.`);
+        }
+        relative = `${relative.slice(0, -3)}.zod.ts`;
+    }
     return resolveFromBase(SCHEMAS_BASE_URL, relative);
 }
+export function resolveBuiltinDeckPath(target) {
+    if (!target.startsWith(DECKS_PREFIX))
+        return undefined;
+    let relative = target.slice(DECKS_PREFIX.length);
+    if (!relative) {
+        throw new Error(`Invalid gambit deck specifier: ${target}`);
+    }
+    if (!relative.endsWith("/PROMPT.md")) {
+        if (!LEGACY_DECK_WARNINGS.has(target)) {
+            LEGACY_DECK_WARNINGS.add(target);
+            logger.warn(`[gambit] "${target}" is deprecated; use gambit://decks/.../PROMPT.md instead.`);
+        }
+        relative = `${relative.replace(/\/?$/, "/")}PROMPT.md`;
+    }
+    return resolveFromBase(DECKS_BASE_URL, relative);
+}

package/esm/src/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/src/loader.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAKV,UAAU,EACV,UAAU,EAEX,MAAM,YAAY,CAAC;AAgMpB,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,EACnB,KAAK,GAAE,KAAK,CAAC,MAAM,CAAM,GACxB,OAAO,CAAC,UAAU,CAAC,CAOrB;AAED,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,UAAU,CAAC,CAsIrB"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/src/loader.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAMV,UAAU,EACV,UAAU,EAEX,MAAM,YAAY,CAAC;AAiPpB,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,EACnB,KAAK,GAAE,KAAK,CAAC,MAAM,CAAM,GACxB,OAAO,CAAC,UAAU,CAAC,CAQrB;AAED,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,UAAU,CAAC,CA4JrB"}

package/esm/src/loader.js

@@ -1,9 +1,11 @@
+import * as dntShim from "../_dnt.shims.js";
 import * as path from "../deps/jsr.io/@std/path/1.1.4/mod.js";
 import { BUILTIN_TOOL_NAME_SET, MAX_TOOL_NAME_LENGTH, RESERVED_TOOL_PREFIX, TOOL_NAME_PATTERN, } from "./constants.js";
 import { isCardDefinition, isDeckDefinition } from "./definitions.js";
+import { normalizePermissionDeclaration, } from "./permissions.js";
 import { mergeZodObjects } from "./schema.js";
 import { isMarkdownFile, loadMarkdownCard, loadMarkdownDeck, } from "./markdown.js";
-import { resolveBuiltinCardPath } from "./builtins.js";
+import { resolveBuiltinCardPath, resolveBuiltinDeckPath, resolveBuiltinSnippetPath, } from "./builtins.js";
 const logger = console;
 const LEGACY_SCHEMA_WARNINGS = new Set();
 const LEGACY_FRAGMENT_WARNINGS = new Set();
@@ -62,7 +64,10 @@ function normalizeActionDecks(actions, basePath) {
         return [];
     return actions.map((a) => ({
         ...a,
-        path: basePath ? path.resolve(path.dirname(basePath), a.path) : a.path,
+        path: a.path.startsWith("gambit://") || !basePath
+            ? a.path
+            : path.resolve(path.dirname(basePath), a.path),
+        permissions: normalizePermissionDeclaration(a.permissions, basePath ? path.dirname(basePath) : dntShim.Deno.cwd()),
     }));
 }
 function normalizeCompanionDecks(decks, basePath) {
@@ -70,9 +75,10 @@ function normalizeCompanionDecks(decks, basePath) {
         return [];
     return decks.map((deck) => ({
         ...deck,
-        path: basePath
-            ? path.resolve(path.dirname(basePath), deck.path)
-            : deck.path,
+        path: deck.path.startsWith("gambit://") || !basePath
+            ? deck.path
+            : path.resolve(path.dirname(basePath), deck.path),
+        permissions: normalizePermissionDeclaration(deck.permissions, basePath ? path.dirname(basePath) : dntShim.Deno.cwd()),
     }));
 }
 function checkReserved(action) {
@@ -85,6 +91,30 @@ function checkReserved(action) {
         throw new Error(`Action name ${action.name} must match ${TOOL_NAME_PATTERN} and be <= ${MAX_TOOL_NAME_LENGTH} characters`);
     }
 }
+function normalizeExternalTools(tools, resolvedPath) {
+    if (!tools)
+        return [];
+    return tools.map((tool) => {
+        const name = String(tool.name ?? "").trim();
+        if (!name) {
+            throw new Error(`External tool must include a name (${resolvedPath})`);
+        }
+        if (name.startsWith(RESERVED_TOOL_PREFIX)) {
+            throw new Error(`External tool name ${name} is reserved (prefix ${RESERVED_TOOL_PREFIX})`);
+        }
+        if (!TOOL_NAME_PATTERN.test(name) ||
+            name.length > MAX_TOOL_NAME_LENGTH) {
+            throw new Error(`External tool name ${name} must match ${TOOL_NAME_PATTERN} and be <= ${MAX_TOOL_NAME_LENGTH} characters`);
+        }
+        return {
+            name,
+            description: typeof tool.description === "string"
+                ? tool.description
+                : undefined,
+            inputSchema: tool.inputSchema,
+        };
+    });
+}
 async function loadCardInternal(cardPath, parentPath, stack = []) {
     const resolved = parentPath
         ? path.resolve(path.dirname(parentPath), cardPath)
@@ -120,28 +150,36 @@ async function loadCardInternal(cardPath, parentPath, stack = []) {
         path: resolved,
         cards: [],
         ...fragments,
+        permissions: normalizePermissionDeclaration(card.permissions, path.dirname(resolved)),
     };
 }
 export async function loadCard(cardPath, parentPath, stack = []) {
     const builtinPath = resolveBuiltinCardPath(cardPath);
-    const normalizedPath = builtinPath ?? cardPath;
+    const snippetPath = resolveBuiltinSnippetPath(cardPath);
+    const normalizedPath = snippetPath ?? builtinPath ?? cardPath;
     if (isMarkdownFile(normalizedPath)) {
         return await loadMarkdownCard(normalizedPath, parentPath, stack);
     }
     return await loadCardInternal(normalizedPath, parentPath, stack);
 }
 export async function loadDeck(deckPath, parentPath) {
-    if (isMarkdownFile(deckPath)) {
-        return await loadMarkdownDeck(deckPath, parentPath);
+    const builtinDeck = resolveBuiltinDeckPath(deckPath);
+    const normalizedDeckPath = builtinDeck ?? deckPath;
+    const markdownParent = builtinDeck ? undefined : parentPath;
+    if (isMarkdownFile(normalizedDeckPath)) {
+        return await loadMarkdownDeck(normalizedDeckPath, markdownParent);
     }
-    const resolved = parentPath
-        ? path.resolve(path.dirname(parentPath), deckPath)
-        : path.resolve(deckPath);
+    const resolved = markdownParent
+        ? path.resolve(path.dirname(markdownParent), normalizedDeckPath)
+        : path.resolve(normalizedDeckPath);
     const mod = await import(toFileUrl(resolved));
     const deck = mod.default;
     if (!isDeckDefinition(deck)) {
         throw new Error(`Deck at ${resolved} did not export a valid deck definition`);
     }
+    if (deck.mcpServers !== undefined) {
+        throw new Error(`Deck-level [[mcpServers]] is unsupported in this phase (${resolved})`);
+    }
     const deckLabel = deck.label;
     const cards = [];
     const mergedActions = {};
@@ -161,6 +199,13 @@ export async function loadDeck(deckPath, parentPath) {
         mergedActions[action.name] = action;
     }
     const actionDecks = Object.values(mergedActions);
+    const tools = normalizeExternalTools(deck.tools, resolved);
+    const actionNames = new Set(actionDecks.map((action) => action.name));
+    for (const tool of tools) {
+        if (actionNames.has(tool.name)) {
+            logger.warn(`[gambit] tool ${tool.name} is shadowed by an action in ${resolved}`);
+        }
+    }
     const schemaAliases = normalizeDeckSchemas(deck, resolved);
     let inputSchema = schemaAliases.inputSchema;
     let outputSchema = schemaAliases.outputSchema;
@@ -220,6 +265,7 @@ export async function loadDeck(deckPath, parentPath) {
         actions: actionDecks,
         testDecks: normalizeCompanionDecks(deck.testDecks, resolved),
         graderDecks: normalizeCompanionDecks(deck.graderDecks, resolved),
+        tools,
         contextSchema,
         responseSchema,
         inputSchema,
@@ -227,6 +273,7 @@ export async function loadDeck(deckPath, parentPath) {
         executor,
         handlers,
         respond: deck.respond,
+        permissions: normalizePermissionDeclaration(deck.permissions, path.dirname(resolved)),
     };
 }
 function flattenCards(cards) {

package/esm/src/markdown.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/src/markdown.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAIV,UAAU,EACV,UAAU,EAEX,MAAM,YAAY,CAAC;AA+LpB,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,EACnB,KAAK,GAAE,KAAK,CAAC,MAAM,CAAM,GACxB,OAAO,CAAC,UAAU,CAAC,CA0GrB;AAED,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,UAAU,CAAC,CAgMrB;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAExD"}
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/src/markdown.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAKV,UAAU,EACV,UAAU,EAEX,MAAM,YAAY,CAAC;AAuVpB,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,EACnB,KAAK,GAAE,KAAK,CAAC,MAAM,CAAM,GACxB,OAAO,CAAC,UAAU,CAAC,CAsGrB;AAED,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,UAAU,CAAC,CAqPrB;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAExD"}

package/esm/src/markdown.js

@@ -4,6 +4,7 @@ import * as path from "../deps/jsr.io/@std/path/1.1.4/mod.js";
 import { BUILTIN_TOOL_NAME_SET, GAMBIT_TOOL_CONTEXT, GAMBIT_TOOL_END, GAMBIT_TOOL_RESPOND, MAX_TOOL_NAME_LENGTH, RESERVED_TOOL_PREFIX, TOOL_NAME_PATTERN, } from "./constants.js";
 import { isCardDefinition } from "./definitions.js";
 import { loadCard } from "./loader.js";
+import { normalizePermissionDeclaration, } from "./permissions.js";
 import { mergeZodObjects } from "./schema.js";
 import { resolveBuiltinSchemaPath } from "./builtins.js";
 const logger = console;
@@ -50,6 +51,23 @@ function toFileUrl(p) {
     const abs = path.resolve(p);
     return path.toFileUrl(abs).href;
 }
+function startsWithFrontMatterDelimiter(raw) {
+    const normalized = raw.startsWith("\uFEFF") ? raw.slice(1) : raw;
+    const trimmed = normalized.trimStart();
+    return /^(\+\+\+|---)\s*(\r?\n|$)/.test(trimmed);
+}
+function parseFrontMatterOrRaw(raw, resolvedPath) {
+    try {
+        return extract(raw);
+    }
+    catch (err) {
+        if (!startsWithFrontMatterDelimiter(raw)) {
+            return { attrs: {}, body: raw };
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to parse front matter in ${resolvedPath}: ${message}`);
+    }
+}
 async function maybeLoadSchema(schemaPath, basePath) {
     if (!schemaPath || typeof schemaPath !== "string")
         return undefined;
@@ -59,7 +77,7 @@ async function maybeLoadSchema(schemaPath, basePath) {
     const mod = await import(toFileUrl(resolved));
     return mod.default;
 }
-function normalizeDeckRefs(refs, basePath) {
+function normalizeDeckRefs(refs, basePath, opts) {
     if (!Array.isArray(refs))
         return [];
     return refs
@@ -70,14 +88,32 @@ function normalizeDeckRefs(refs, basePath) {
         if (!p) {
             throw new Error("Deck reference must include a path");
         }
+        if (opts?.requirePrompt && !p.endsWith("PROMPT.md")) {
+            throw new Error(`Deck reference must point to PROMPT.md (${basePath})`);
+        }
         const normalized = { ...rec };
-        normalized.path = path.resolve(path.dirname(basePath), p);
+        normalized.path = p.startsWith("gambit://")
+            ? p
+            : path.resolve(path.dirname(basePath), p);
         if (typeof rec.description !== "string")
             delete normalized.description;
         if (typeof rec.label !== "string")
             delete normalized.label;
         if (typeof rec.id !== "string")
             delete normalized.id;
+        if (rec.permissions !== undefined) {
+            const parsed = normalizePermissionDeclaration(rec.permissions, path.dirname(basePath));
+            if (parsed)
+                normalized.permissions = parsed;
+        }
+        if (opts?.requireDescription) {
+            const desc = typeof rec.description === "string"
+                ? rec.description.trim()
+                : "";
+            if (!desc) {
+                throw new Error(`Action deck must include a description (${basePath})`);
+            }
+        }
         return normalized;
     });
 }
@@ -94,14 +130,92 @@ function mergeDeckRefs(...lists) {
     }
     return Array.from(merged.values());
 }
-function normalizeActionDecks(entries, basePath) {
-    return normalizeDeckRefs(entries, basePath).map((entry) => {
-        const name = "name" in entry ? String(entry.name ?? "").trim() : "";
+async function normalizeActionDecks(entries, basePath, opts) {
+    if (!Array.isArray(entries))
+        return [];
+    const out = [];
+    for (const rawEntry of entries) {
+        if (!rawEntry || typeof rawEntry !== "object")
+            continue;
+        const rec = rawEntry;
+        const name = String(rec.name ?? "").trim();
         if (!name) {
             throw new Error(`Action deck must include a name (${basePath})`);
         }
-        return { ...entry, name };
-    });
+        const desc = typeof rec.description === "string"
+            ? rec.description.trim()
+            : "";
+        if (opts?.requireDescription && !desc) {
+            throw new Error(`Action deck must include a description (${basePath})`);
+        }
+        const rawPath = typeof rec.path === "string" ? rec.path.trim() : "";
+        const rawExecute = typeof rec.execute === "string"
+            ? rec.execute.trim()
+            : "";
+        const hasPath = rawPath.length > 0;
+        const hasExecute = rawExecute.length > 0;
+        if (hasPath === hasExecute) {
+            throw new Error(`Action deck must include exactly one of path or execute (${basePath})`);
+        }
+        if (hasPath && opts?.requirePrompt && !rawPath.endsWith("PROMPT.md")) {
+            throw new Error(`Deck reference must point to PROMPT.md (${basePath})`);
+        }
+        const actionContextSchema = await maybeLoadSchema(rec.contextSchema, basePath);
+        const actionResponseSchema = await maybeLoadSchema(rec.responseSchema, basePath);
+        if (hasExecute && (!actionContextSchema || !actionResponseSchema)) {
+            throw new Error(`Action execute target must include contextSchema and responseSchema (${basePath})`);
+        }
+        const selectedTarget = hasPath ? rawPath : rawExecute;
+        const normalizedPath = selectedTarget.startsWith("gambit://")
+            ? selectedTarget
+            : path.resolve(path.dirname(basePath), selectedTarget);
+        const normalized = {
+            name,
+            path: normalizedPath,
+            description: desc || undefined,
+            label: typeof rec.label === "string" ? rec.label : undefined,
+            id: typeof rec.id === "string" ? rec.id : undefined,
+            execute: hasExecute ? normalizedPath : undefined,
+            contextSchema: actionContextSchema,
+            responseSchema: actionResponseSchema,
+        };
+        if (rec.permissions !== undefined) {
+            const parsed = normalizePermissionDeclaration(rec.permissions, path.dirname(basePath));
+            if (parsed)
+                normalized.permissions = parsed;
+        }
+        out.push(normalized);
+    }
+    return out;
+}
+async function normalizeExternalTools(refs, basePath) {
+    if (!Array.isArray(refs))
+        return [];
+    const out = [];
+    for (const entry of refs) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const rec = entry;
+        const name = String(rec.name ?? "").trim();
+        if (!name) {
+            throw new Error(`External tool must include a name (${basePath})`);
+        }
+        if (name.startsWith(RESERVED_TOOL_PREFIX)) {
+            throw new Error(`External tool name ${name} is reserved (prefix ${RESERVED_TOOL_PREFIX})`);
+        }
+        if (!TOOL_NAME_PATTERN.test(name) || name.length > MAX_TOOL_NAME_LENGTH) {
+            throw new Error(`External tool name ${name} must match ${TOOL_NAME_PATTERN} and be <= ${MAX_TOOL_NAME_LENGTH} characters`);
+        }
+        const inputSchema = await maybeLoadSchema(rec.inputSchema, basePath);
+        out.push({
+            name,
+            description: typeof rec.description === "string"
+                ? rec.description
+                : undefined,
+            inputSchema,
+        });
+    }
+    return out;
 }
 async function expandEmbedsInBody(args) {
     const { body, resolvedPath, stack } = args;
@@ -117,17 +231,17 @@ async function expandEmbedsInBody(args) {
         const target = match[1];
         out += body.slice(lastIndex, matchIndex);
         if (target === RESPOND_MARKER) {
-            warnLegacyMarker("respond", "gambit://cards/respond.card.md");
+            warnLegacyMarker("respond", "gambit://snippets/respond.md");
             respond = true;
             out += RESPOND_TEXT;
         }
         else if (target === INIT_MARKER) {
-            warnLegacyMarker("init", "gambit://cards/context.card.md");
+            warnLegacyMarker("init", "gambit://snippets/context.md");
             initHint = true;
             out += INIT_TEXT;
         }
         else if (target === END_MARKER) {
-            warnLegacyMarker("end", "gambit://cards/end.card.md");
+            warnLegacyMarker("end", "gambit://snippets/end.md");
             endHint = true;
             out += END_TEXT;
         }
@@ -151,17 +265,7 @@ export async function loadMarkdownCard(filePath, parentPath, stack = []) {
     }
     const nextStack = [...stack, resolved];
     const raw = await dntShim.Deno.readTextFile(resolved);
-    let attrs;
-    let body;
-    try {
-        const parsed = extract(raw);
-        attrs = parsed.attrs;
-        body = parsed.body;
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        throw new Error(`Failed to parse front matter in ${resolved}: ${message}`);
-    }
+    const { attrs, body } = parseFrontMatterOrRaw(raw, resolved);
     const candidate = attrs;
     if (isCardDefinition(candidate)) {
         // treat attrs as ts-shaped card
@@ -171,7 +275,7 @@ export async function loadMarkdownCard(filePath, parentPath, stack = []) {
     }
     const hasNewActionField = attrs.actionDecks;
     const legacyActions = attrs.actions;
-    const actionDecks = normalizeActionDecks(hasNewActionField ?? legacyActions, resolved);
+    const actionDecks = await normalizeActionDecks(hasNewActionField ?? legacyActions, resolved);
     if (!hasNewActionField && legacyActions) {
         logger.warn(`[gambit] card at ${resolved} uses deprecated "actions"; rename to "actionDecks"`);
     }
@@ -205,6 +309,7 @@ export async function loadMarkdownCard(filePath, parentPath, stack = []) {
     const embeddedCards = replaced.embeds;
     const respondFlag = Boolean(attrs.respond);
     const allowEndFlag = Boolean(attrs.allowEnd);
+    const permissions = normalizePermissionDeclaration(attrs.permissions, path.dirname(resolved));
     return {
         kind: "gambit.card",
         path: resolved,
@@ -215,6 +320,7 @@ export async function loadMarkdownCard(filePath, parentPath, stack = []) {
         testDecks: normalizeDeckRefs(attrs.testDecks, resolved),
         graderDecks: normalizeDeckRefs(attrs.graderDecks, resolved),
         cards: embeddedCards,
+        permissions,
         contextFragment,
         responseFragment,
         inputFragment: contextFragment,
@@ -227,26 +333,35 @@ export async function loadMarkdownDeck(filePath, parentPath) {
         ? path.resolve(path.dirname(parentPath), filePath)
         : path.resolve(filePath);
     const raw = await dntShim.Deno.readTextFile(resolved);
-    let attrs;
-    let body;
-    try {
-        const parsed = extract(raw);
-        attrs = parsed.attrs;
-        body = parsed.body;
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        throw new Error(`Failed to parse front matter in ${resolved}: ${message}`);
-    }
+    const { attrs, body } = parseFrontMatterOrRaw(raw, resolved);
     const deckAttrs = attrs;
     const deckMeta = (deckAttrs.deck ?? deckAttrs);
+    if (deckMeta.mcpServers !== undefined) {
+        throw new Error(`Deck-level [[mcpServers]] is unsupported in this phase (${resolved})`);
+    }
+    if (deckMeta.execute !== undefined) {
+        throw new Error(`Top-level execute in PROMPT.md is unsupported (${resolved})`);
+    }
     const hasNewActionDecks = deckMeta.actionDecks;
-    const legacyDeckActions = deckMeta.actions;
-    const actionDecks = normalizeActionDecks(hasNewActionDecks ?? legacyDeckActions, resolved);
-    if (!hasNewActionDecks && legacyDeckActions) {
-        logger.warn(`[gambit] deck at ${resolved} uses deprecated "actions"; rename to "actionDecks"`);
+    const canonicalActions = deckMeta.actions;
+    const actionDecks = await normalizeActionDecks(canonicalActions, resolved, {
+        requirePrompt: true,
+        requireDescription: true,
+    });
+    const legacyActionDecks = await normalizeActionDecks(hasNewActionDecks, resolved);
+    if (hasNewActionDecks) {
+        logger.warn(`[gambit] deck at ${resolved} uses deprecated "actionDecks"; use "[[actions]]" instead.`);
     }
-    actionDecks.forEach((a) => {
+    if (deckMeta.testDecks) {
+        logger.warn(`[gambit] deck at ${resolved} uses deprecated "testDecks"; use "[[scenarios]]" instead.`);
+    }
+    if (deckMeta.graderDecks) {
+        logger.warn(`[gambit] deck at ${resolved} uses deprecated "graderDecks"; use "[[graders]]" instead.`);
+    }
+    const scenarioDecks = normalizeDeckRefs(deckMeta.scenarios, resolved, { requirePrompt: true });
+    const graderDecks = normalizeDeckRefs(deckMeta.graders, resolved, { requirePrompt: true });
+    const allActionDecks = [...actionDecks, ...legacyActionDecks];
+    allActionDecks.forEach((a) => {
         if (a.name.startsWith(RESERVED_TOOL_PREFIX) &&
             !BUILTIN_TOOL_NAME_SET.has(a.name)) {
             throw new Error(`Action name ${a.name} is reserved`);
@@ -284,7 +399,7 @@ export async function loadMarkdownDeck(filePath, parentPath) {
             mergedActions[action.name] = action;
         }
     }
-    for (const action of actionDecks) {
+    for (const action of allActionDecks) {
         mergedActions[action.name] = action;
     }
     let mergedContextSchema = contextSchema;
@@ -327,10 +442,18 @@ export async function loadMarkdownDeck(filePath, parentPath) {
         }
         : undefined;
     const mergedActionDecks = Object.values(mergedActions);
+    const tools = await normalizeExternalTools(deckMeta.tools, resolved);
+    const actionNameSet = new Set(mergedActionDecks.map((action) => action.name));
+    for (const tool of tools) {
+        if (actionNameSet.has(tool.name)) {
+            logger.warn(`[gambit] tool ${tool.name} is shadowed by an action in ${resolved}`);
+        }
+    }
     const rootTestDecks = normalizeDeckRefs(deckMeta.testDecks, resolved);
     const rootGraderDecks = normalizeDeckRefs(deckMeta.graderDecks, resolved);
     const embeddedTestDecks = allCards.flatMap((card) => card.testDecks ?? []);
     const embeddedGraderDecks = allCards.flatMap((card) => card.graderDecks ?? []);
+    const permissions = normalizePermissionDeclaration(deckMeta.permissions, path.dirname(resolved));
     return {
         kind: "gambit.deck",
         path: resolved,
@@ -338,8 +461,9 @@ export async function loadMarkdownDeck(filePath, parentPath) {
         allowEnd,
         actionDecks: mergedActionDecks,
         actions: mergedActionDecks,
-        testDecks: mergeDeckRefs(rootTestDecks, embeddedTestDecks),
-        graderDecks: mergeDeckRefs(rootGraderDecks, embeddedGraderDecks),
+        tools,
+        testDecks: mergeDeckRefs(scenarioDecks, rootTestDecks, embeddedTestDecks),
+        graderDecks: mergeDeckRefs(graderDecks, rootGraderDecks, embeddedGraderDecks),
         cards: allCards,
         label: deckMeta.label,
         startMode: deckMeta.startMode,
@@ -349,11 +473,13 @@ export async function loadMarkdownDeck(filePath, parentPath) {
         responseSchema: mergedResponseSchema,
         inputSchema: mergedInputSchema,
         outputSchema: mergedOutputSchema,
+        executor: undefined,
         handlers,
         respond: Boolean(deckMeta.respond) ||
             replaced.respond ||
             allCards.some((c) => c.respond),
         inlineEmbeds: true,
+        permissions,
     };
 }
 export function isMarkdownFile(filePath) {