@@ -112,6 +112,14 @@ export default defineCard({
112112});
113113```
114114
115+ For built-in Gambit schemas in TypeScript/compute decks, use canonical module
116+ subpaths:
117+
118+ ```
119+ import contextSchema from "@bolt-foundry/gambit-core/schemas/scenarios/plain_chat_input_optional.zod.ts";
120+ import responseSchema from "@bolt-foundry/gambit-core/schemas/scenarios/plain_chat_output.zod.ts";
121+ ```
122+
115123## Running decks programmatically
116124
117125The runtime loads the deck (Markdown or TS) and steps through each pass. Provide
@@ -145,14 +153,33 @@ When the deck defines `run`/`execute`, the runtime hands you an
145153[ ` ExecutionContext ` ] ( src/types.ts ) with:
146154
147155- ` ctx.input ` : validated input (narrowable when you type the schema).
148- - ` ctx.spawnAndWait({ path, input }) ` : call another deck and await the result.
156+ - ` ctx.initialUserMessage ` : current turn user message when provided by caller.
157+ - ` ctx.getSessionMeta(key) ` : read persisted run/session metadata.
158+ - ` ctx.setSessionMeta(key, value) ` : persist metadata for later turns.
159+ - ` ctx.appendMessage({ role, content }) ` : append chat transcript messages from
160+ execute decks.
161+ - ` ctx.spawnAndWait({ path, input, initialUserMessage? }) ` : call another deck
162+ and await the result; user message is inherited by default unless overridden.
149163- ` ctx.return(payload) ` : respond early without running guards again.
150164- ` ctx.fail({ message, code?, details? }) ` : aborts the run (throws).
151165- ` ctx.log(...) ` : emit structured trace entries for observability.
152166
153167Pass ` guardrails ` , ` initialUserMessage ` , ` modelOverride ` , and
154168` allowRootStringInput ` to ` runDeck ` when scripting custom runtimes.
155169
170+ ### Worker sandbox behavior in ` runDeck `
171+
172+ ` gambit-core ` keeps worker sandboxing opt-in:
173+
174+ - ` runDeck ` enables worker sandboxing only when ` workerSandbox: true ` is passed.
175+ - You can also opt in via ` GAMBIT_DECK_WORKER_SANDBOX=1 ` (or ` true ` / ` yes ` ).
176+ - If neither is set, ` runDeck ` executes without worker sandboxing by default.
177+
178+ Why this is opt-in: ` @bolt-foundry/gambit-core ` is intended to run in multiple
179+ hosts (Node, Bun, Deno). Worker sandboxing relies on Deno-specific worker
180+ permission controls, so host apps must opt in when they run in an environment
181+ that supports it.
182+
156183## Loading Markdown decks and cards
157184
158185Markdown files use front matter for metadata, with the body becoming the prompt.
0 commit comments