@bolt-foundry/gambit-core 0.8.1 → 0.8.5-rc.10

package/esm/src/markdown.js

@@ -1,9 +1,10 @@
 import * as dntShim from "../_dnt.shims.js";
 import { extract } from "../deps/jsr.io/@std/front-matter/1.0.9/any.js";
 import * as path from "../deps/jsr.io/@std/path/1.1.4/mod.js";
-import { BUILTIN_TOOL_NAME_SET, GAMBIT_TOOL_END, GAMBIT_TOOL_INIT, GAMBIT_TOOL_RESPOND, MAX_TOOL_NAME_LENGTH, RESERVED_TOOL_PREFIX, TOOL_NAME_PATTERN, } from "./constants.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;
@@ -15,8 +16,10 @@ const LEGACY_MARKER_WARNINGS = {
     init: false,
     end: false,
 };
+const LEGACY_SCHEMA_WARNINGS = new Set();
+const LEGACY_FRAGMENT_WARNINGS = new Set();
 const INIT_TEXT = `
-You will automatically receive a \`${GAMBIT_TOOL_INIT}\` tool result at the start that provides run/context info.
+You will automatically receive a \`${GAMBIT_TOOL_CONTEXT}\` tool result at the start that provides run/context info.
 `.trim();
 const RESPOND_TEXT = `
 When you are done, call the \`${GAMBIT_TOOL_RESPOND}\` tool with a JSON object that includes your \`payload\` (validated output) and optional \`status\`/ \`message\`/ \`code\`/ \`meta\`. Do not end with normal assistant text; always finish by calling \`${GAMBIT_TOOL_RESPOND}\`.
@@ -30,10 +33,41 @@ function warnLegacyMarker(marker, replacement) {
     LEGACY_MARKER_WARNINGS[marker] = true;
     logger.warn(`[gambit] "gambit://${marker}" is deprecated; use ${replacement} instead.`);
 }
+function warnLegacySchema(resolvedPath, legacy, replacement) {
+    const key = `${resolvedPath}:${legacy}`;
+    if (LEGACY_SCHEMA_WARNINGS.has(key))
+        return;
+    LEGACY_SCHEMA_WARNINGS.add(key);
+    logger.warn(`[gambit] deck at ${resolvedPath} uses deprecated "${legacy}"; rename to "${replacement}"`);
+}
+function warnLegacyFragment(resolvedPath, legacy, replacement) {
+    const key = `${resolvedPath}:${legacy}`;
+    if (LEGACY_FRAGMENT_WARNINGS.has(key))
+        return;
+    LEGACY_FRAGMENT_WARNINGS.add(key);
+    logger.warn(`[gambit] card at ${resolvedPath} uses deprecated "${legacy}"; rename to "${replacement}"`);
+}
 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;
@@ -43,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
@@ -55,13 +89,28 @@ function normalizeDeckRefs(refs, basePath) {
             throw new Error("Deck reference must include a path");
         }
         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;
     });
 }
@@ -78,14 +127,194 @@ 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() : "";
+function normalizeActionIntermediateOutputPolicy(raw, basePath) {
+    const invalid = () => {
+        throw new Error(`[gambit] Invalid intermediateOutput policy for action deck (${basePath}). Expected { emit: "allow" | "deny" }.`);
+    };
+    if (raw === undefined || raw === null) {
+        return { emit: "deny" };
+    }
+    if (typeof raw === "boolean") {
+        return { emit: raw ? "allow" : "deny" };
+    }
+    if (typeof raw === "string") {
+        const emit = raw.trim().toLowerCase();
+        if (emit === "allow" || emit === "deny")
+            return { emit };
+        invalid();
+    }
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        invalid();
+    const emitRaw = raw.emit;
+    if (emitRaw === undefined || emitRaw === null) {
+        return { emit: "deny" };
+    }
+    if (typeof emitRaw === "string") {
+        const emit = emitRaw.trim().toLowerCase();
+        if (emit === "allow" || emit === "deny")
+            return { emit };
+    }
+    invalid();
+    return { emit: "deny" };
+}
+function normalizeActionAsyncStartPolicy(raw, basePath) {
+    const invalid = () => {
+        throw new Error(`[gambit] Invalid asyncStart policy for action deck (${basePath}). Expected { mode: "allow" | "deny" }.`);
+    };
+    if (raw === undefined || raw === null) {
+        return { mode: "deny" };
+    }
+    if (typeof raw === "boolean") {
+        return { mode: raw ? "allow" : "deny" };
+    }
+    if (typeof raw === "string") {
+        const mode = raw.trim().toLowerCase();
+        if (mode === "allow" || mode === "deny")
+            return { mode };
+        invalid();
+    }
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        invalid();
+    const modeRaw = raw.mode;
+    if (modeRaw === undefined || modeRaw === null) {
+        return { mode: "deny" };
+    }
+    if (typeof modeRaw === "string") {
+        const mode = modeRaw.trim().toLowerCase();
+        if (mode === "allow" || mode === "deny")
+            return { mode };
+    }
+    invalid();
+    return { mode: "deny" };
+}
+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})`);
+        }
+        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,
+            intermediateOutput: normalizeActionIntermediateOutputPolicy(rec.intermediateOutput, basePath),
+            asyncStart: normalizeActionAsyncStartPolicy(rec.asyncStart, basePath),
+        };
+        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;
+}
+const CORE_RESPONSE_ITEM_TYPES = new Set([
+    "message",
+    "function_call",
+    "function_call_output",
+    "reasoning",
+]);
+async function normalizeResponseItemExtensions(refs, basePath) {
+    if (!Array.isArray(refs))
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const entry of refs) {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry))
+            continue;
+        const rec = entry;
+        const type = String(rec.type ?? "").trim();
+        if (!type) {
+            throw new Error(`Response item extension must include a type (${basePath})`);
+        }
+        if (!type.includes(":")) {
+            throw new Error(`Response item extension type "${type}" must be namespaced (<namespace>:<type>) (${basePath})`);
+        }
+        if (CORE_RESPONSE_ITEM_TYPES.has(type)) {
+            throw new Error(`Response item extension type "${type}" conflicts with core OpenResponses item types (${basePath})`);
+        }
+        if (seen.has(type)) {
+            throw new Error(`Duplicate response item extension type "${type}" (${basePath})`);
+        }
+        seen.add(type);
+        const dataSchema = await maybeLoadSchema(rec.dataSchema, basePath);
+        if (!dataSchema) {
+            throw new Error(`Response item extension "${type}" must include dataSchema (${basePath})`);
+        }
+        out.push({
+            type: type,
+            dataSchema,
+            description: typeof rec.description === "string"
+                ? rec.description
+                : undefined,
+        });
+    }
+    return out;
 }
 async function expandEmbedsInBody(args) {
     const { body, resolvedPath, stack } = args;
@@ -101,17 +330,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;
         }
@@ -135,17 +364,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
@@ -155,7 +374,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"`);
     }
@@ -168,8 +387,18 @@ export async function loadMarkdownCard(filePath, parentPath, stack = []) {
             throw new Error(`Action name ${a.name} must match ${TOOL_NAME_PATTERN} and be <= ${MAX_TOOL_NAME_LENGTH} characters`);
         }
     });
-    const inputFragment = await maybeLoadSchema(attrs.inputSchema, resolved);
-    const outputFragment = await maybeLoadSchema(attrs.outputSchema, resolved);
+    const legacyInputSchema = attrs.inputSchema;
+    const legacyOutputSchema = attrs.outputSchema;
+    const contextFragment = await maybeLoadSchema(attrs.contextFragment ??
+        legacyInputSchema, resolved);
+    const responseFragment = await maybeLoadSchema(attrs.responseFragment ??
+        legacyOutputSchema, resolved);
+    if (legacyInputSchema !== undefined) {
+        warnLegacyFragment(resolved, "inputSchema", "contextFragment");
+    }
+    if (legacyOutputSchema !== undefined) {
+        warnLegacyFragment(resolved, "outputSchema", "responseFragment");
+    }
     const replaced = await expandEmbedsInBody({
         body,
         resolvedPath: resolved,
@@ -179,6 +408,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,
@@ -189,8 +419,11 @@ export async function loadMarkdownCard(filePath, parentPath, stack = []) {
         testDecks: normalizeDeckRefs(attrs.testDecks, resolved),
         graderDecks: normalizeDeckRefs(attrs.graderDecks, resolved),
         cards: embeddedCards,
-        inputFragment,
-        outputFragment,
+        permissions,
+        contextFragment,
+        responseFragment,
+        inputFragment: contextFragment,
+        outputFragment: responseFragment,
         respond: respondFlag || replaced.respond,
     };
 }
@@ -199,26 +432,34 @@ 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, {
+        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);
+    const graderDecks = normalizeDeckRefs(deckMeta.graders, resolved);
+    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`);
@@ -233,8 +474,18 @@ export async function loadMarkdownDeck(filePath, parentPath) {
         stack: [resolved],
     });
     const cards = replaced.embeds;
-    const inputSchema = await maybeLoadSchema(deckMeta.inputSchema, resolved);
-    const outputSchema = await maybeLoadSchema(deckMeta.outputSchema, resolved);
+    const legacyInputSchema = deckMeta.inputSchema;
+    const legacyOutputSchema = deckMeta.outputSchema;
+    const contextSchema = await maybeLoadSchema(deckMeta.contextSchema ??
+        legacyInputSchema, resolved);
+    const responseSchema = await maybeLoadSchema(deckMeta.responseSchema ??
+        legacyOutputSchema, resolved);
+    if (legacyInputSchema !== undefined) {
+        warnLegacySchema(resolved, "inputSchema", "contextSchema");
+    }
+    if (legacyOutputSchema !== undefined) {
+        warnLegacySchema(resolved, "outputSchema", "responseSchema");
+    }
     const allCards = flattenCards(cards);
     const cleanedBody = replaced.body;
     const allowEnd = Boolean(deckMeta.allowEnd) ||
@@ -246,15 +497,17 @@ 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 mergedInputSchema = inputSchema;
-    let mergedOutputSchema = outputSchema;
+    let mergedContextSchema = contextSchema;
+    let mergedResponseSchema = responseSchema;
     for (const card of allCards) {
-        mergedInputSchema = mergeZodObjects(mergedInputSchema, card.inputFragment);
-        mergedOutputSchema = mergeZodObjects(mergedOutputSchema, card.outputFragment);
+        mergedContextSchema = mergeZodObjects(mergedContextSchema, card.contextFragment);
+        mergedResponseSchema = mergeZodObjects(mergedResponseSchema, card.responseFragment);
     }
+    const mergedInputSchema = mergedContextSchema;
+    const mergedOutputSchema = mergedResponseSchema;
     const normalizeHandler = (cfg, kind) => {
         if (!cfg)
             return undefined;
@@ -287,10 +540,19 @@ export async function loadMarkdownDeck(filePath, parentPath) {
         }
         : undefined;
     const mergedActionDecks = Object.values(mergedActions);
+    const tools = await normalizeExternalTools(deckMeta.tools, resolved);
+    const responseItemExtensions = await normalizeResponseItemExtensions(deckMeta.responseItemExtensions, 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,
@@ -298,19 +560,26 @@ export async function loadMarkdownDeck(filePath, parentPath) {
         allowEnd,
         actionDecks: mergedActionDecks,
         actions: mergedActionDecks,
-        testDecks: mergeDeckRefs(rootTestDecks, embeddedTestDecks),
-        graderDecks: mergeDeckRefs(rootGraderDecks, embeddedGraderDecks),
+        tools,
+        responseItemExtensions,
+        testDecks: mergeDeckRefs(scenarioDecks, rootTestDecks, embeddedTestDecks),
+        graderDecks: mergeDeckRefs(graderDecks, rootGraderDecks, embeddedGraderDecks),
         cards: allCards,
         label: deckMeta.label,
+        startMode: deckMeta.startMode,
         modelParams: deckMeta.modelParams,
         guardrails: deckMeta.guardrails,
+        contextSchema: mergedContextSchema,
+        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) {

package/esm/src/permissions.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Deno-native permission kinds supported by Gambit's permission contract.
+ */
+export declare const PERMISSION_KINDS: readonly ["read", "write", "run", "net", "env"];
+export type PermissionKind = (typeof PERMISSION_KINDS)[number];
+export type PathPermissionInput = boolean | Array<string>;
+export type RunPermissionInput = boolean | Array<string> | {
+    paths?: Array<string>;
+    commands?: Array<string>;
+};
+export type PermissionDeclarationInput = Partial<{
+    read: PathPermissionInput;
+    write: PathPermissionInput;
+    run: RunPermissionInput;
+    net: PathPermissionInput;
+    env: PathPermissionInput;
+}>;
+export type SerializedRunPermission = false | true | {
+    paths: Array<string>;
+    commands: Array<string>;
+};
+export type SerializedPermissionSet = {
+    read: false | true | Array<string>;
+    write: false | true | Array<string>;
+    run: SerializedRunPermission;
+    net: false | true | Array<string>;
+    env: false | true | Array<string>;
+};
+export type PermissionDeclaration = SerializedPermissionSet;
+type NormalizedScope = {
+    all: boolean;
+    values: Set<string>;
+};
+type NormalizedRunScope = {
+    all: boolean;
+    paths: Set<string>;
+    commands: Set<string>;
+};
+export type NormalizedPermissionSet = {
+    baseDir: string;
+    read: NormalizedScope;
+    write: NormalizedScope;
+    run: NormalizedRunScope;
+    net: NormalizedScope;
+    env: NormalizedScope;
+};
+export type PermissionLayerName = "parent" | "workspace" | "declaration" | "reference" | "session" | "host";
+export type PermissionLayerTrace = {
+    name: PermissionLayerName;
+    baseDir: string;
+    requested: SerializedPermissionSet;
+    effective: SerializedPermissionSet;
+};
+export type PermissionTrace = {
+    baseDir: string;
+    effective: SerializedPermissionSet;
+    layers: Array<PermissionLayerTrace>;
+};
+export declare function cloneNormalizedPermissions(input: NormalizedPermissionSet): NormalizedPermissionSet;
+/**
+ * Returns an allow-all permission set anchored to `baseDir`.
+ */
+export declare function allowAllPermissions(baseDir: string): NormalizedPermissionSet;
+/**
+ * Normalizes a permission declaration to a serializable, deterministic shape.
+ *
+ * Relative path grants are resolved against `baseDir`.
+ */
+export declare function normalizePermissionDeclaration(input: PermissionDeclarationInput | undefined, baseDir: string): PermissionDeclaration | undefined;
+/**
+ * Normalizes a declaration to the internal set form used during intersection.
+ */
+export declare function normalizePermissionDeclarationToSet(input: PermissionDeclarationInput | undefined, baseDir: string): NormalizedPermissionSet | undefined;
+/**
+ * Serializes an internal normalized permission set for traces/persistence.
+ */
+export declare function serializePermissions(set: NormalizedPermissionSet): SerializedPermissionSet;
+/**
+ * Computes the monotonic intersection between two permission sets.
+ *
+ * `baseDir` controls how relative checks (`canReadPath`/etc) are evaluated for
+ * the returned set.
+ */
+export declare function intersectPermissions(parent: NormalizedPermissionSet, next: NormalizedPermissionSet, baseDir: string): NormalizedPermissionSet;
+/**
+ * Resolves effective permissions and emits a layer-by-layer permission trace.
+ *
+ * Layer precedence:
+ * 1. `parent` (or host allow-all for roots)
+ * 2. `workspace` (root only)
+ * 3. `declaration` (deck/card declaration)
+ * 4. `reference` (parent reference override)
+ * 5. `session` (root only)
+ */
+export declare function resolveEffectivePermissions(args: {
+    baseDir: string;
+    parent?: NormalizedPermissionSet;
+    workspace?: {
+        baseDir: string;
+        permissions: PermissionDeclarationInput;
+    };
+    declaration?: {
+        baseDir: string;
+        permissions: PermissionDeclarationInput;
+    };
+    reference?: {
+        baseDir: string;
+        permissions: PermissionDeclarationInput;
+    };
+    session?: {
+        baseDir: string;
+        permissions: PermissionDeclarationInput;
+    };
+}): {
+    effective: NormalizedPermissionSet;
+    trace: PermissionTrace;
+};
+/**
+ * Returns whether `targetPath` is readable under `set`.
+ *
+ * Relative paths are resolved against `set.baseDir`.
+ */
+export declare function canReadPath(set: NormalizedPermissionSet, targetPath: string): boolean;
+/**
+ * Returns whether `targetPath` is writable under `set`.
+ *
+ * Relative paths are resolved against `set.baseDir`.
+ */
+export declare function canWritePath(set: NormalizedPermissionSet, targetPath: string): boolean;
+/**
+ * Returns whether `targetPath` is executable via run-path grants.
+ *
+ * Relative paths are resolved against `set.baseDir`.
+ */
+export declare function canRunPath(set: NormalizedPermissionSet, targetPath: string): boolean;
+/**
+ * Returns whether `commandName` is executable via run-command grants.
+ *
+ * This check intentionally does not apply basename/path fallback semantics.
+ */
+export declare function canRunCommand(set: NormalizedPermissionSet, commandName: string): boolean;
+export {};
+//# sourceMappingURL=permissions.d.ts.map