@bolt-foundry/gambit-core 0.5.3-dev

package/esm/src/constants.js

@@ -0,0 +1,20 @@
+export const DEFAULT_GUARDRAILS = {
+    maxDepth: 3,
+    maxPasses: 10,
+    timeoutMs: 120_000,
+};
+export const RESERVED_TOOL_PREFIX = "gambit_";
+export const TOOL_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export const MAX_TOOL_NAME_LENGTH = 64;
+export const GAMBIT_TOOL_INIT = "gambit_init";
+export const GAMBIT_TOOL_RESPOND = "gambit_respond";
+export const GAMBIT_TOOL_COMPLETE = "gambit_complete";
+export const GAMBIT_TOOL_END = "gambit_end";
+export const BUILTIN_TOOL_NAME_SET = new Set([
+    GAMBIT_TOOL_INIT,
+    GAMBIT_TOOL_RESPOND,
+    GAMBIT_TOOL_COMPLETE,
+    GAMBIT_TOOL_END,
+]);
+// Default delay for busy/idle handler triggers.
+export const DEFAULT_STATUS_DELAY_MS = 800;

package/esm/src/definitions.d.ts

@@ -0,0 +1,11 @@
+import type { CardDefinition, DeckDefinition } from "./types.js";
+import type { z } from "zod";
+export declare function defineDeck<InputSchema extends z.ZodTypeAny, OutputSchema extends z.ZodTypeAny | undefined = undefined>(def: Omit<DeckDefinition<z.infer<InputSchema>>, "kind" | "inputSchema" | "outputSchema"> & {
+    inputSchema: InputSchema;
+    outputSchema?: OutputSchema;
+}): DeckDefinition<z.infer<InputSchema>>;
+export declare function defineDeck(def: Omit<DeckDefinition, "kind">): DeckDefinition;
+export declare function defineCard(def: Omit<CardDefinition, "kind">): CardDefinition;
+export declare function isDeckDefinition(value: unknown): value is DeckDefinition;
+export declare function isCardDefinition(value: unknown): value is CardDefinition;
+//# sourceMappingURL=definitions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/src/definitions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjE,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,wBAAgB,UAAU,CACxB,WAAW,SAAS,CAAC,CAAC,UAAU,EAChC,YAAY,SAAS,CAAC,CAAC,UAAU,GAAG,SAAS,GAAG,SAAS,EAEzD,GAAG,EACC,IAAI,CACJ,cAAc,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,EACpC,MAAM,GAAG,aAAa,GAAG,cAAc,CACxC,GACC;IACA,WAAW,EAAE,WAAW,CAAC;IACzB,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B,GACF,cAAc,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC;AACxC,wBAAgB,UAAU,CACxB,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,GAChC,cAAc,CAAC;AAOlB,wBAAgB,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,GAAG,cAAc,CAE5E;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAKxE;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAKxE"}

package/esm/src/definitions.js

@@ -0,0 +1,14 @@
+export function defineDeck(def) {
+    return { kind: "gambit.deck", ...def };
+}
+export function defineCard(def) {
+    return { kind: "gambit.card", ...def };
+}
+export function isDeckDefinition(value) {
+    return Boolean(value && typeof value === "object" &&
+        value.kind === "gambit.deck");
+}
+export function isCardDefinition(value) {
+    return Boolean(value && typeof value === "object" &&
+        value.kind === "gambit.card");
+}

package/esm/src/loader.d.ts

@@ -0,0 +1,4 @@
+import type { LoadedCard, LoadedDeck } from "./types.js";
+export declare function loadCard(cardPath: string, parentPath?: string, stack?: Array<string>): Promise<LoadedCard>;
+export declare function loadDeck(deckPath: string, parentPath?: string): Promise<LoadedDeck>;
+//# sourceMappingURL=loader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/src/loader.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAKV,UAAU,EACV,UAAU,EAEX,MAAM,YAAY,CAAC;AAsHpB,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,EACnB,KAAK,GAAE,KAAK,CAAC,MAAM,CAAM,GACxB,OAAO,CAAC,UAAU,CAAC,CAKrB;AAED,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,UAAU,CAAC,CA6HrB"}

package/esm/src/loader.js

@@ -0,0 +1,179 @@
+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 { mergeZodObjects } from "./schema.js";
+import { isMarkdownFile, loadMarkdownCard, loadMarkdownDeck, } from "./markdown.js";
+const logger = console;
+function toFileUrl(p) {
+    const abs = path.resolve(p);
+    return path.toFileUrl(abs).href;
+}
+function normalizeActionDecks(actions, basePath) {
+    if (!actions)
+        return [];
+    return actions.map((a) => ({
+        ...a,
+        path: basePath ? path.resolve(path.dirname(basePath), a.path) : a.path,
+    }));
+}
+function normalizeCompanionDecks(decks, basePath) {
+    if (!decks)
+        return [];
+    return decks.map((deck) => ({
+        ...deck,
+        path: basePath
+            ? path.resolve(path.dirname(basePath), deck.path)
+            : deck.path,
+    }));
+}
+function checkReserved(action) {
+    if (action.name.startsWith(RESERVED_TOOL_PREFIX) &&
+        !BUILTIN_TOOL_NAME_SET.has(action.name)) {
+        throw new Error(`Action name ${action.name} is reserved (prefix ${RESERVED_TOOL_PREFIX})`);
+    }
+    if (!TOOL_NAME_PATTERN.test(action.name) ||
+        action.name.length > MAX_TOOL_NAME_LENGTH) {
+        throw new Error(`Action name ${action.name} must match ${TOOL_NAME_PATTERN} and be <= ${MAX_TOOL_NAME_LENGTH} characters`);
+    }
+}
+async function loadCardInternal(cardPath, parentPath, stack = []) {
+    const resolved = parentPath
+        ? path.resolve(path.dirname(parentPath), cardPath)
+        : path.resolve(cardPath);
+    if (stack.includes(resolved)) {
+        throw new Error(`Card/embed cycle detected: ${[...stack, resolved].join(" -> ")}`);
+    }
+    const mod = await import(toFileUrl(resolved));
+    const card = mod.default;
+    if (!isCardDefinition(card)) {
+        throw new Error(`Card at ${resolved} did not export a valid card definition`);
+    }
+    if (card.handlers) {
+        throw new Error(`Card at ${resolved} cannot declare handlers (deck-only)`);
+    }
+    const cardLabel = card.label;
+    const actionDecks = normalizeActionDecks(card.actionDecks ?? card.actions, resolved);
+    if (!card.actionDecks && card.actions?.length) {
+        logger.warn(`[gambit] card at ${resolved} uses deprecated "actions"; rename to "actionDecks"`);
+    }
+    const testDecks = normalizeCompanionDecks(card.testDecks, resolved);
+    const graderDecks = normalizeCompanionDecks(card.graderDecks, resolved);
+    actionDecks.forEach(checkReserved);
+    const { label: _l, ...rest } = card;
+    return {
+        ...rest,
+        label: cardLabel,
+        actionDecks,
+        actions: actionDecks,
+        testDecks,
+        graderDecks,
+        path: resolved,
+        cards: [],
+    };
+}
+export async function loadCard(cardPath, parentPath, stack = []) {
+    if (isMarkdownFile(cardPath)) {
+        return await loadMarkdownCard(cardPath, parentPath, stack);
+    }
+    return await loadCardInternal(cardPath, parentPath, stack);
+}
+export async function loadDeck(deckPath, parentPath) {
+    if (isMarkdownFile(deckPath)) {
+        return await loadMarkdownDeck(deckPath, parentPath);
+    }
+    const resolved = parentPath
+        ? path.resolve(path.dirname(parentPath), deckPath)
+        : path.resolve(deckPath);
+    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`);
+    }
+    const deckLabel = deck.label;
+    const cards = [];
+    const mergedActions = {};
+    const allCards = flattenCards(cards);
+    for (const card of allCards) {
+        for (const action of card.actionDecks ?? []) {
+            checkReserved(action);
+            mergedActions[action.name] = action;
+        }
+    }
+    const deckActionDecks = deck.actionDecks ?? deck.actions;
+    if (!deck.actionDecks && deck.actions?.length) {
+        logger.warn(`[gambit] deck at ${resolved} uses deprecated "actions"; rename to "actionDecks"`);
+    }
+    for (const action of normalizeActionDecks(deckActionDecks, resolved)) {
+        checkReserved(action);
+        mergedActions[action.name] = action;
+    }
+    const actionDecks = Object.values(mergedActions);
+    let inputSchema = deck.inputSchema;
+    let outputSchema = deck.outputSchema;
+    for (const card of allCards) {
+        inputSchema = mergeZodObjects(inputSchema, card.inputFragment);
+        outputSchema = mergeZodObjects(outputSchema, card.outputFragment);
+    }
+    const executor = typeof deck.run === "function"
+        ? deck.run
+        : typeof deck.execute === "function"
+            ? deck.execute
+            : undefined;
+    const normalizeHandler = (cfg, kind) => {
+        if (!cfg)
+            return undefined;
+        const repeatMs = cfg.repeatMs ?? cfg.intervalMs;
+        if (cfg.intervalMs !== undefined && cfg.repeatMs === undefined) {
+            logger.warn(`[gambit] handlers.${kind}.intervalMs is deprecated; use repeatMs (${resolved})`);
+        }
+        return {
+            ...cfg,
+            repeatMs,
+            path: path.resolve(path.dirname(resolved), cfg.path),
+        };
+    };
+    const intervalAlias = deck.handlers?.onInterval;
+    const onBusy = normalizeHandler(deck.handlers?.onBusy ?? intervalAlias, intervalAlias ? "onInterval" : "onBusy");
+    if (!deck.handlers?.onBusy && intervalAlias) {
+        logger.warn(`[gambit] handlers.onInterval is deprecated; use handlers.onBusy (${resolved})`);
+    }
+    const onIdle = normalizeHandler(deck.handlers?.onIdle, "onIdle");
+    const handlers = deck.handlers
+        ? {
+            onError: deck.handlers.onError
+                ? {
+                    ...deck.handlers.onError,
+                    path: path.resolve(path.dirname(resolved), deck.handlers.onError.path),
+                }
+                : undefined,
+            onBusy,
+            onIdle,
+        }
+        : undefined;
+    const { label: _l, ...rest } = deck;
+    return {
+        ...rest,
+        label: deckLabel,
+        path: resolved,
+        cards: allCards,
+        actionDecks,
+        actions: actionDecks,
+        testDecks: normalizeCompanionDecks(deck.testDecks, resolved),
+        graderDecks: normalizeCompanionDecks(deck.graderDecks, resolved),
+        inputSchema,
+        outputSchema,
+        executor,
+        handlers,
+        respond: deck.respond,
+    };
+}
+function flattenCards(cards) {
+    const flat = [];
+    for (const card of cards) {
+        flat.push(card);
+        const nested = card.cards ?? [];
+        if (nested.length)
+            flat.push(...flattenCards(nested));
+    }
+    return flat;
+}

package/esm/src/markdown.d.ts

@@ -0,0 +1,5 @@
+import type { LoadedCard, LoadedDeck } from "./types.js";
+export declare function loadMarkdownCard(filePath: string, parentPath?: string, stack?: Array<string>): Promise<LoadedCard>;
+export declare function loadMarkdownDeck(filePath: string, parentPath?: string): Promise<LoadedDeck>;
+export declare function isMarkdownFile(filePath: string): boolean;
+//# sourceMappingURL=markdown.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/src/markdown.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAIV,UAAU,EACV,UAAU,EAEX,MAAM,YAAY,CAAC;AA8IpB,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,EACnB,KAAK,GAAE,KAAK,CAAC,MAAM,CAAM,GACxB,OAAO,CAAC,UAAU,CAAC,CA4FrB;AAED,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,UAAU,CAAC,CA8KrB;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAExD"}

package/esm/src/markdown.js

@@ -0,0 +1,307 @@
+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 { isCardDefinition } from "./definitions.js";
+import { loadCard } from "./loader.js";
+import { mergeZodObjects } from "./schema.js";
+const logger = console;
+const RESPOND_MARKER = "gambit://respond";
+const INIT_MARKER = "gambit://init";
+const END_MARKER = "gambit://end";
+const INIT_TEXT = `
+You will automatically receive a \`${GAMBIT_TOOL_INIT}\` 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}\`.
+`.trim();
+const END_TEXT = `
+If the entire workflow is finished and no further user turns should be sent, call the \`${GAMBIT_TOOL_END}\` tool with optional \`message\` and \`payload\` fields to explicitly end the session.
+`.trim();
+function toFileUrl(p) {
+    const abs = path.resolve(p);
+    return path.toFileUrl(abs).href;
+}
+async function maybeLoadSchema(schemaPath, basePath) {
+    if (!schemaPath || typeof schemaPath !== "string")
+        return undefined;
+    const resolved = path.resolve(path.dirname(basePath), schemaPath);
+    const mod = await import(toFileUrl(resolved));
+    return mod.default;
+}
+function normalizeDeckRefs(refs, basePath) {
+    if (!Array.isArray(refs))
+        return [];
+    return refs
+        .filter((a) => a && typeof a === "object")
+        .map((a) => {
+        const rec = a;
+        const p = String(rec.path ?? "").trim();
+        if (!p) {
+            throw new Error("Deck reference must include a path");
+        }
+        const normalized = { ...rec };
+        normalized.path = 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;
+        return normalized;
+    });
+}
+function mergeDeckRefs(...lists) {
+    const merged = new Map();
+    for (const list of lists) {
+        for (const entry of list) {
+            if (!entry?.path)
+                continue;
+            if (!merged.has(entry.path)) {
+                merged.set(entry.path, entry);
+            }
+        }
+    }
+    return Array.from(merged.values());
+}
+function normalizeActionDecks(entries, basePath) {
+    return normalizeDeckRefs(entries, basePath).map((entry) => {
+        const name = "name" in entry ? String(entry.name ?? "").trim() : "";
+        if (!name) {
+            throw new Error(`Action deck must include a name (${basePath})`);
+        }
+        return { ...entry, name };
+    });
+}
+async function expandEmbedsInBody(args) {
+    const { body, resolvedPath, stack } = args;
+    const regex = /!\[[^\]]*\]\(([^)]+)\)/g;
+    const embeds = [];
+    let respond = false;
+    let initHint = false;
+    let endHint = false;
+    let out = "";
+    let lastIndex = 0;
+    for (const match of body.matchAll(regex)) {
+        const matchIndex = match.index ?? 0;
+        const target = match[1];
+        out += body.slice(lastIndex, matchIndex);
+        if (target === RESPOND_MARKER) {
+            respond = true;
+            out += RESPOND_TEXT;
+        }
+        else if (target === INIT_MARKER) {
+            initHint = true;
+            out += INIT_TEXT;
+        }
+        else if (target === END_MARKER) {
+            endHint = true;
+            out += END_TEXT;
+        }
+        else {
+            const card = await loadCard(target, resolvedPath, stack);
+            embeds.push(card);
+            if (card.body)
+                out += card.body;
+        }
+        lastIndex = matchIndex + match[0].length;
+    }
+    out += body.slice(lastIndex);
+    return { body: out, embeds, respond, initHint, endHint };
+}
+export async function loadMarkdownCard(filePath, parentPath, stack = []) {
+    const resolved = parentPath
+        ? path.resolve(path.dirname(parentPath), filePath)
+        : path.resolve(filePath);
+    if (stack.includes(resolved)) {
+        throw new Error(`Card/embed cycle detected: ${[...stack, resolved].join(" -> ")}`);
+    }
+    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 candidate = attrs;
+    if (isCardDefinition(candidate)) {
+        // treat attrs as ts-shaped card
+    }
+    if (candidate.handlers) {
+        throw new Error(`Card at ${resolved} cannot declare handlers (deck-only)`);
+    }
+    const hasNewActionField = attrs.actionDecks;
+    const legacyActions = attrs.actions;
+    const actionDecks = normalizeActionDecks(hasNewActionField ?? legacyActions, resolved);
+    if (!hasNewActionField && legacyActions) {
+        logger.warn(`[gambit] card at ${resolved} uses deprecated "actions"; rename to "actionDecks"`);
+    }
+    actionDecks.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`);
+        }
+        if (!TOOL_NAME_PATTERN.test(a.name) || a.name.length > MAX_TOOL_NAME_LENGTH) {
+            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 replaced = await expandEmbedsInBody({
+        body,
+        resolvedPath: resolved,
+        stack: nextStack,
+    });
+    const cleanedBody = replaced.body;
+    const embeddedCards = replaced.embeds;
+    return {
+        kind: "gambit.card",
+        path: resolved,
+        body: cleanedBody.trim(),
+        allowEnd: replaced.endHint,
+        actionDecks,
+        actions: actionDecks,
+        testDecks: normalizeDeckRefs(attrs.testDecks, resolved),
+        graderDecks: normalizeDeckRefs(attrs.graderDecks, resolved),
+        cards: embeddedCards,
+        inputFragment,
+        outputFragment,
+        respond: replaced.respond,
+    };
+}
+export async function loadMarkdownDeck(filePath, parentPath) {
+    const resolved = 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 deckAttrs = attrs;
+    const deckMeta = (deckAttrs.deck ?? deckAttrs);
+    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"`);
+    }
+    actionDecks.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`);
+        }
+        if (!TOOL_NAME_PATTERN.test(a.name) || a.name.length > MAX_TOOL_NAME_LENGTH) {
+            throw new Error(`Action name ${a.name} must match ${TOOL_NAME_PATTERN} and be <= ${MAX_TOOL_NAME_LENGTH} characters`);
+        }
+    });
+    const replaced = await expandEmbedsInBody({
+        body,
+        resolvedPath: resolved,
+        stack: [resolved],
+    });
+    const cards = replaced.embeds;
+    const inputSchema = await maybeLoadSchema(deckMeta.inputSchema, resolved);
+    const outputSchema = await maybeLoadSchema(deckMeta.outputSchema, resolved);
+    const allCards = flattenCards(cards);
+    const cleanedBody = replaced.body;
+    const allowEnd = Boolean(deckMeta.allowEnd) ||
+        replaced.endHint ||
+        allCards.some((c) => c.allowEnd);
+    const mergedActions = {};
+    for (const card of allCards) {
+        for (const action of card.actionDecks ?? []) {
+            mergedActions[action.name] = action;
+        }
+    }
+    for (const action of actionDecks) {
+        mergedActions[action.name] = action;
+    }
+    let mergedInputSchema = inputSchema;
+    let mergedOutputSchema = outputSchema;
+    for (const card of allCards) {
+        mergedInputSchema = mergeZodObjects(mergedInputSchema, card.inputFragment);
+        mergedOutputSchema = mergeZodObjects(mergedOutputSchema, card.outputFragment);
+    }
+    const normalizeHandler = (cfg, kind) => {
+        if (!cfg)
+            return undefined;
+        const repeatMs = cfg.repeatMs ?? cfg.intervalMs;
+        if (cfg.intervalMs !== undefined && cfg.repeatMs === undefined) {
+            logger.warn(`[gambit] handlers.${kind}.intervalMs is deprecated; use repeatMs (${resolved})`);
+        }
+        return {
+            ...cfg,
+            repeatMs,
+            path: path.resolve(path.dirname(resolved), cfg.path),
+        };
+    };
+    const intervalAlias = deckMeta.handlers?.onInterval;
+    const onBusy = normalizeHandler(deckMeta.handlers?.onBusy ?? intervalAlias, intervalAlias ? "onInterval" : "onBusy");
+    if (!deckMeta.handlers?.onBusy && intervalAlias) {
+        logger.warn(`[gambit] handlers.onInterval is deprecated; use handlers.onBusy (${resolved})`);
+    }
+    const onIdle = normalizeHandler(deckMeta.handlers?.onIdle, "onIdle");
+    const handlers = deckMeta.handlers
+        ? {
+            onError: deckMeta.handlers.onError
+                ? {
+                    ...deckMeta.handlers.onError,
+                    path: path.resolve(path.dirname(resolved), deckMeta.handlers.onError.path),
+                }
+                : undefined,
+            onBusy,
+            onIdle,
+        }
+        : undefined;
+    const mergedActionDecks = Object.values(mergedActions);
+    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 ?? []);
+    return {
+        kind: "gambit.deck",
+        path: resolved,
+        body: cleanedBody.trim(),
+        allowEnd,
+        actionDecks: mergedActionDecks,
+        actions: mergedActionDecks,
+        testDecks: mergeDeckRefs(rootTestDecks, embeddedTestDecks),
+        graderDecks: mergeDeckRefs(rootGraderDecks, embeddedGraderDecks),
+        cards: allCards,
+        label: deckMeta.label,
+        modelParams: deckMeta.modelParams,
+        guardrails: deckMeta.guardrails,
+        inputSchema: mergedInputSchema,
+        outputSchema: mergedOutputSchema,
+        handlers,
+        respond: replaced.respond || allCards.some((c) => c.respond),
+        inlineEmbeds: true,
+    };
+}
+export function isMarkdownFile(filePath) {
+    return filePath.endsWith(".md");
+}
+function flattenCards(cards) {
+    const flat = [];
+    for (const card of cards) {
+        flat.push(card);
+        const nested = card.cards ?? [];
+        if (nested.length)
+            flat.push(...flattenCards(nested));
+    }
+    return flat;
+}

package/esm/src/openai_compat.d.ts

@@ -0,0 +1,63 @@
+import type { Guardrails, ModelMessage, ModelProvider, ToolDefinition } from "./types.js";
+export declare const logger: Console;
+export type ChatCompletionsRequest = {
+    model: string;
+    messages: Array<{
+        role: "system" | "user" | "assistant" | "tool";
+        content: string | null | Array<string | {
+            text?: string;
+            type?: string;
+        }>;
+        name?: string;
+        tool_call_id?: string;
+        tool_calls?: ModelMessage["tool_calls"];
+    }>;
+    tools?: Array<ToolDefinition>;
+    stream?: boolean;
+    temperature?: number;
+    top_p?: number;
+    frequency_penalty?: number;
+    presence_penalty?: number;
+    max_tokens?: number;
+    [key: string]: unknown;
+};
+export type ChatCompletionsResponse = {
+    id: string;
+    object: "chat.completion";
+    created: number;
+    model: string;
+    choices: Array<{
+        index: number;
+        message: ModelMessage;
+        finish_reason: "stop" | "tool_calls" | "length";
+        logprobs: null;
+    }>;
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+    /**
+     * Non-OpenAI extension field containing the full transcript and metadata.
+     * Most clients will ignore unknown fields.
+     */
+    gambit?: {
+        deckPath: string;
+        messages: Array<ModelMessage>;
+        runId: string;
+    };
+};
+export declare function chatCompletionsWithDeck(args: {
+    deckPath: string;
+    request: ChatCompletionsRequest;
+    modelProvider: ModelProvider;
+    /**
+     * When true (default), Gambit will execute tool calls that match deck actions.
+     * Any other tool calls are returned to the caller as normal OpenAI tool calls.
+     */
+    executeDeckTools?: boolean;
+    guardrails?: Partial<Guardrails>;
+    defaultModel?: string;
+    onStreamText?: (chunk: string) => void;
+}): Promise<ChatCompletionsResponse>;
+//# sourceMappingURL=openai_compat.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"openai_compat.d.ts","sourceRoot":"","sources":["../../src/src/openai_compat.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,UAAU,EAEV,YAAY,EACZ,aAAa,EACb,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,MAAM,SAAU,CAAC;AAO9B,MAAM,MAAM,sBAAsB,GAAG;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,KAAK,CAAC;QACd,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;QAC/C,OAAO,EACH,MAAM,GACN,IAAI,GACJ,KAAK,CAAC,MAAM,GAAG;YAAE,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACrD,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,UAAU,CAAC,EAAE,YAAY,CAAC,YAAY,CAAC,CAAC;KACzC,CAAC,CAAC;IACH,KAAK,CAAC,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IAC9B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,iBAAiB,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,KAAK,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,YAAY,CAAC;QACtB,aAAa,EAAE,MAAM,GAAG,YAAY,GAAG,QAAQ,CAAC;QAChD,QAAQ,EAAE,IAAI,CAAC;KAChB,CAAC,CAAC;IACH,KAAK,CAAC,EAAE;QACN,aAAa,EAAE,MAAM,CAAC;QACtB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF;;;OAGG;IACH,MAAM,CAAC,EAAE;QACP,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;QAC9B,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;CACH,CAAC;AAoKF,wBAAsB,uBAAuB,CAAC,IAAI,EAAE;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,sBAAsB,CAAC;IAChC,aAAa,EAAE,aAAa,CAAC;IAC7B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,UAAU,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IACjC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACxC,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAsJnC"}