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

package/esm/src/loader.js

@@ -1,20 +1,135 @@
+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();
+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 normalizeDeckSchemas(deck, resolvedPath) {
+    if (deck.inputSchema !== undefined) {
+        warnLegacySchema(resolvedPath, "inputSchema", "contextSchema");
+    }
+    if (deck.outputSchema !== undefined) {
+        warnLegacySchema(resolvedPath, "outputSchema", "responseSchema");
+    }
+    const contextSchema = deck.contextSchema ?? deck.inputSchema;
+    const responseSchema = deck.responseSchema ?? deck.outputSchema;
+    return {
+        contextSchema,
+        responseSchema,
+        inputSchema: contextSchema,
+        outputSchema: responseSchema,
+    };
+}
+function normalizeCardFragments(card, resolvedPath) {
+    if (card.inputFragment !== undefined) {
+        warnLegacyFragment(resolvedPath, "inputFragment", "contextFragment");
+    }
+    if (card.outputFragment !== undefined) {
+        warnLegacyFragment(resolvedPath, "outputFragment", "responseFragment");
+    }
+    const contextFragment = card.contextFragment ?? card.inputFragment;
+    const responseFragment = card.responseFragment ?? card.outputFragment;
+    return {
+        contextFragment,
+        responseFragment,
+        inputFragment: contextFragment,
+        outputFragment: responseFragment,
+    };
+}
 function toFileUrl(p) {
     const abs = path.resolve(p);
     return path.toFileUrl(abs).href;
 }
+function normalizeActionIntermediateOutputPolicy(raw, context) {
+    const invalid = () => {
+        throw new Error(`[gambit] Invalid intermediateOutput policy for ${context}. 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, context) {
+    const invalid = () => {
+        throw new Error(`[gambit] Invalid asyncStart policy for ${context}. 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" };
+}
 function normalizeActionDecks(actions, basePath) {
     if (!actions)
         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),
+        intermediateOutput: normalizeActionIntermediateOutputPolicy(a.intermediateOutput, `action "${a.name}"`),
+        asyncStart: normalizeActionAsyncStartPolicy(a.asyncStart, `action "${a.name}"`),
+        permissions: normalizePermissionDeclaration(a.permissions, basePath ? path.dirname(basePath) : dntShim.Deno.cwd()),
     }));
 }
 function normalizeCompanionDecks(decks, basePath) {
@@ -22,9 +137,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) {
@@ -37,6 +153,67 @@ 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,
+        };
+    });
+}
+const CORE_RESPONSE_ITEM_TYPES = new Set([
+    "message",
+    "function_call",
+    "function_call_output",
+    "reasoning",
+]);
+function normalizeResponseItemExtensions(extensions, resolvedPath) {
+    if (!extensions)
+        return [];
+    const seen = new Set();
+    return extensions.map((entry) => {
+        const type = String(entry.type ?? "").trim();
+        if (!type) {
+            throw new Error(`Response item extension in ${resolvedPath} must include a type`);
+        }
+        if (!type.includes(":")) {
+            throw new Error(`Response item extension type "${type}" in ${resolvedPath} must be namespaced (expected "<namespace>:<type>")`);
+        }
+        if (CORE_RESPONSE_ITEM_TYPES.has(type)) {
+            throw new Error(`Response item extension type "${type}" in ${resolvedPath} conflicts with core OpenResponses item types`);
+        }
+        if (seen.has(type)) {
+            throw new Error(`Duplicate response item extension type "${type}" in ${resolvedPath}`);
+        }
+        seen.add(type);
+        if (!entry.dataSchema) {
+            throw new Error(`Response item extension "${type}" in ${resolvedPath} must include dataSchema`);
+        }
+        return {
+            type: type,
+            dataSchema: entry.dataSchema,
+            description: typeof entry.description === "string"
+                ? entry.description
+                : undefined,
+        };
+    });
+}
 async function loadCardInternal(cardPath, parentPath, stack = []) {
     const resolved = parentPath
         ? path.resolve(path.dirname(parentPath), cardPath)
@@ -61,6 +238,7 @@ async function loadCardInternal(cardPath, parentPath, stack = []) {
     const graderDecks = normalizeCompanionDecks(card.graderDecks, resolved);
     actionDecks.forEach(checkReserved);
     const { label: _l, ...rest } = card;
+    const fragments = normalizeCardFragments(card, resolved);
     return {
         ...rest,
         label: cardLabel,
@@ -70,28 +248,37 @@ async function loadCardInternal(cardPath, parentPath, stack = []) {
         graderDecks,
         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 = {};
@@ -111,12 +298,27 @@ export async function loadDeck(deckPath, parentPath) {
         mergedActions[action.name] = action;
     }
     const actionDecks = Object.values(mergedActions);
-    let inputSchema = deck.inputSchema;
-    let outputSchema = deck.outputSchema;
+    const tools = normalizeExternalTools(deck.tools, resolved);
+    const responseItemExtensions = normalizeResponseItemExtensions(deck.responseItemExtensions, 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;
+    let contextSchema = schemaAliases.contextSchema;
+    let responseSchema = schemaAliases.responseSchema;
     for (const card of allCards) {
         inputSchema = mergeZodObjects(inputSchema, card.inputFragment);
         outputSchema = mergeZodObjects(outputSchema, card.outputFragment);
+        contextSchema = mergeZodObjects(contextSchema, card.contextFragment);
+        responseSchema = mergeZodObjects(responseSchema, card.responseFragment);
     }
+    inputSchema = contextSchema;
+    outputSchema = responseSchema;
     const executor = typeof deck.run === "function"
         ? deck.run
         : typeof deck.execute === "function"
@@ -163,11 +365,16 @@ export async function loadDeck(deckPath, parentPath) {
         actions: actionDecks,
         testDecks: normalizeCompanionDecks(deck.testDecks, resolved),
         graderDecks: normalizeCompanionDecks(deck.graderDecks, resolved),
+        tools,
+        responseItemExtensions,
+        contextSchema,
+        responseSchema,
         inputSchema,
         outputSchema,
         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;AAmKpB,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,EACnB,KAAK,GAAE,KAAK,CAAC,MAAM,CAAM,GACxB,OAAO,CAAC,UAAU,CAAC,CA8FrB;AAED,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,UAAU,CAAC,CAgLrB;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,EAGX,MAAM,YAAY,CAAC;AA8cpB,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,CAuPrB;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAExD"}