sync(bfmono): docs(gambit): retire synthetic respond/end guidance and align deck authoring surfaces (+19 more) (bfmono@2d14cdf2b)

This PR is an automated gambitmono sync of bfmono Gambit packages.

- Source: `packages/gambit/`
- Core: `packages/gambit/packages/gambit-core/`
- bfmono rev: 2d14cdf2b

Changes:
- 498708844 docs(gambit): retire synthetic respond/end guidance and align deck authoring surfaces
- 35ad1d5b5 feat(gambit-core): add OpenResponses convergence runtime, extensions, and async action semantics
- b2d78cfb3 chore(gambit): cut 0.8.5-rc.9
- a0029f933 revert(gambit-ci): restore shell-based nix develop in ci-gambit-core
- 1b2930064 fix(gambit-ci): create nix profile parent dir in ci-gambit-core
- 168538d09 chore(gambit): cut 0.8.5-rc.8
- 9f2dd2186 Switch ci-gambit-core to run nix develop via step commands with a profile instead of custom shell overrides. This avoids both workflow-parse failures and literal  path resolution failures.
- bd91e87f1 chore(gambit): cut 0.8.5-rc.7
- 63a27a8a4 fix(gambit-ci): stop using github.workspace in shell field
- e923eabdd chore(gambit): cut 0.8.5-rc.6
- b6f5d2c1f feat(gambit): add workbench composer chip and chat flow updates
- 9ebc474b8 fix(gambit): invalidate build deck label cache on frontmatter changes
- 04f032d28 feat(simulator-ui): use icon remove action for error context chip
- 71a94654b fix(gambit): validate explicit deck path and stabilize stop test
- 77fa7f139 refactor(gambit-simulator-ui): replace placeholders with reusable callout
- d90d57c08 feat(gambit-simulator-ui): send scenario run errors to workbench chat
- dc7d93a08 refactor(gambit): Fix left drawer
- bdad96a86 chore(repo): pin jsx-runtime imports to react 19.2.4
- 0c787f96d chore(gambit): cut 0.8.5-rc.5 and pin React to 19.2.4
- 0fdcdf864 fix(gambit): unblock npm dnt build for 0.8.5-rc.4

Do not edit this repo directly; make changes in bfmono and re-run the sync.

Author: bft-codebot

README.md

@@ -327,10 +327,11 @@ Run it:
 npx @bolt-foundry/gambit run ./agent_with_time.deck.md --context '"hello"' --stream
 ```
 
-### Respond flow demo (non-root decks + grading)
+### Legacy respond-flow demo (historical compatibility)
 
-Need a turnkey scenario that hits personas → init → non-root `gambit_respond`
-payloads → graders? Use the example in `packages/gambit/examples/respond_flow/`.
+`packages/gambit/examples/respond_flow/` is kept as a legacy compatibility
+example for historical transcript/grader behavior. New decks should return
+schema-valid assistant output directly instead of calling `gambit_respond`.
 
 ```
 cd packages/gambit
@@ -342,10 +343,10 @@ Then:
 1. Open `http://localhost:8000/test`, pick the **Escalation persona**, and run
    it. Leave the “Use scenario deck input for init” toggle on to see persona
    data seed the init form automatically.
-2. Switch to the Debug tab to inspect the session—the child deck emits a
-   `gambit_respond` payload that now shows up as a structured assistant turn.
-3. Head to the Calibrate tab and run the **Respond payload grader** to exercise
-   grading on the non-root respond output.
+2. Switch to the Debug tab to inspect the session; this scenario still emits
+   legacy `gambit_respond` payloads for compatibility testing.
+3. Head to the Calibrate tab and run the **Respond payload grader** to validate
+   historical non-root respond-output handling.
 
 ## Deno
 

docs/external/concepts/runtime.md

@@ -21,17 +21,14 @@ safe/observable.
 - `gambit_context`: sent once when `--context` (formerly `--init`) is provided;
   payload is the raw input. Useful for assistant-first flows so the model can
   read input without a user turn. `gambit_init` remains as a deprecated alias.
-- `gambit_respond`: enable with the `gambit://snippets/respond.md` marker in
-  Markdown (or `respond: true` in TypeScript decks). Required for LLM decks that
-  should finish with a structured envelope
-  `{ payload, status?, message?, code?, meta? }`.
-- `gambit_complete`: emitted automatically for child completions and handled
-  errors so the parent can see
+- `gambit_respond` / `gambit_end`: removed from runtime defaults. Do not add
+  `gambit://snippets/respond.md`, `gambit://snippets/end.md`, `respond: true`,
+  or `allowEnd: true` in new decks. Return normal assistant output that matches
+  `responseSchema`; model status/code/meta fields directly in that schema when
+  needed.
+- Child action results are returned through the action tool result payload.
+  Handled errors use the same envelope shape:
   `{ runId, actionCallId, source, status?, payload?, message?, code?, meta? }`.
-- `gambit_end`: enable with `![end](gambit://snippets/end.md)` in Markdown (or
-  `allowEnd: true` in TypeScript decks). Calling it returns a sentinel
-  `{ __gambitEnd: true, payload?, status?, message?, code?, meta? }` so
-  CLI/scenario loops stop reinjecting the closing assistant turn.
 
 ## State and turn order
 
@@ -54,8 +51,8 @@ safe/observable.
   repeats if `repeatMs` is set. Input mirrors busy with `kind:"idle"` and no
   `childInput`.
 - Error (`handlers.onError`): wraps child errors; should return
-  `{ payload?, status?, message?, code?, meta? }` which becomes a
-  `gambit_complete` envelope. If the handler itself fails, the runtime still
+  `{ payload?, status?, message?, code?, meta? }` which becomes the structured
+  action tool result envelope. If the handler itself fails, the runtime still
   returns a structured error envelope.
 - Handler failures are swallowed so they never crash the main run.
 

docs/external/examples/handlers_md.md

@@ -3,8 +3,8 @@
 What it shows
 
 - Busy/idle/error handlers authored in Markdown decks, paired with TS actions.
-- Using `gambit://snippets/respond.md` in an error handler to force structured
-  completion.
+- Returning structured, schema-valid handler outputs without synthetic respond
+  tools.
 
 Key files
 
@@ -22,9 +22,10 @@ Why it’s structured this way
 - Markdown handlers keep prompts readable while still validating IO via schemas.
 - `onBusy` uses `repeatMs` to stream periodic status messages; `onIdle` fires
   after inactivity.
-- `onError` returns a fixed envelope via `gambit_respond`, ensuring the parent
-  sees a consistent `{status, code, message, meta, payload}` even when children
-  fail.
+- `onError` returns a fixed structured object that matches `responseSchema`,
+  ensuring the parent sees a consistent
+  `{status, code, message, meta,
+  payload}` shape even when children fail.
 
 How to run
 

docs/external/examples/handlers_ts.md

@@ -3,8 +3,8 @@
 What it shows
 
 - Busy/idle/error handlers written in TypeScript with explicit Zod schemas.
-- Demonstrates handled errors producing `gambit_complete` envelopes and status
-  streaming.
+- Demonstrates handled errors producing structured action tool-result envelopes
+  and status streaming.
 
 Key files
 

docs/external/examples/internal_monolog.md

@@ -5,9 +5,8 @@ without tool calls) before completing its work.
 
 - `internal_monolog_parent.deck.md`: root deck that calls the child tool and
   relays its answer.
-- `monolog_child.deck.md`: LLM child with the `gambit://snippets/respond.md`
-  marker that first thinks aloud (monolog), then calls a compute action, then
-  responds.
+- `monolog_child.deck.md`: LLM child that first thinks aloud (monolog), then
+  calls a compute action, then returns schema-valid assistant output.
 - `lookup_fact.deck.ts`: simple compute action the child calls.
 
 Run in the debug UI to see monolog traces:
@@ -21,5 +20,5 @@ Send a question (e.g., "What is Rust?"). In the Traces & Tools panel you’ll se
 - `model.result` from the child showing a content-only assistant turn (monolog).
 - A `monolog` trace entry (emitted because the child is non-root and spoke
   without tool calls).
-- Subsequent tool call/result for `lookup_fact`, then the final respond
-  envelope.
+- Subsequent tool call/result for `lookup_fact`, then final schema-valid
+  assistant output.

docs/external/examples/policy_support_bot.md

@@ -12,8 +12,8 @@ Key ideas:
    manual confidence scores (no external vector store required).
 2. **Policy-aware orchestration** – `policy_support_bot.deck.md` embeds persona,
    grounding, and refusal snippets, calls `search_faq`, enforces citation
-   formatting, and uses `gambit://snippets/respond.md` with a schema so the
-   UI/CLI always receives structured envelopes.
+   formatting, and returns schema-valid structured output so the UI/CLI always
+   receives consistent envelopes.
 3. **Tests + demos** – `tests/faq_dataset.test.ts` guards the FAQ knowledge base
    (category headings, IDs, entry counts), while `demo-script.md` lists prompts
    for grounded answers, refusals, and edge cases that you can replay in the

docs/external/guides/authoring.md

@@ -142,12 +142,11 @@ deno run -A packages/gambit/scripts/migrate-schema-terms.ts <repo-root>
 - `gambit_context`: injected automatically when `--context` (formerly `--init`)
   is provided; carries the raw input as the first tool result. `gambit_init`
   remains as a deprecated alias.
-- `gambit_respond`: enable by inserting the
-  `![respond](gambit://snippets/respond.md)` marker in Markdown decks (or
-  `respond: true` in TypeScript). Required for LLM decks finish via a structured
-  envelope: `{ status?, payload, message?, code?, meta? }`.
-- `gambit_complete`: emitted by child actions and handled errors to wrap their
-  results for the parent.
+- `gambit_respond` / `gambit_end`: removed from runtime defaults. Do not add
+  `gambit://snippets/respond.md`, `gambit://snippets/end.md`, `respond: true`,
+  or `allowEnd: true` in new decks.
+- Child action and handled-error metadata (`status`, `code`, `meta`, `payload`)
+  are returned via the action tool result payload envelope.
 - Optional handlers (deck-only): `handlers.onBusy`, `handlers.onIdle`,
   `handlers.onError` point to other decks. Inputs are structured (see
   `../reference/handlers.md`); errors inside handlers are swallowed.
@@ -157,9 +156,9 @@ deno run -A packages/gambit/scripts/migrate-schema-terms.ts <repo-root>
 - In Markdown, use image syntax to embed snippets:
   `![behavior](./cards/behavior.card.md)`. Local snippet files often still live
   under `cards/` with a `.card.md` suffix for legacy compatibility. Special
-  markers: `gambit://snippets/context.md` hints init tool,
-  `gambit://snippets/respond.md` injects respond instructions, and
-  `gambit://snippets/end.md` enables the `gambit_end` hang-up tool.
+  markers: `gambit://snippets/context.md` hints init tool, while
+  `gambit://snippets/respond.md` and `gambit://snippets/end.md` are legacy
+  migration markers and should not be used for new deck behavior.
 - Snippets can also be TS files exported with `defineCard`. They may contain
   action/scenario/grader deck references and schema fragments, but no handlers.
 

docs/external/reference/handlers.md

@@ -65,8 +65,8 @@ Notes:
     childInput?: Record<string, unknown>,
   }
   ```
-  Return `{ message?, code?, status?, meta?, payload? }` to populate a
-  `gambit_complete` envelope.
+  Return `{ message?, code?, status?, meta?, payload? }` to populate the
+  structured action tool result envelope.
 
 ## Outputs and streaming
 

examples/dev/intermediate-child-delta/README.md

@@ -0,0 +1,58 @@
+# Intermediate Child Delta Demo
+
+This demo is designed to exercise canonical intermediate child output-item
+semantics (Project 08 delta path).
+
+## Files
+
+- `child_progress.deck.ts`: compute child deck emitting intermediate
+  `gambit:action_progress` items via `ctx.emitOutputItem(...)`.
+- `parent_compute_harness.deck.ts`: compute parent deck that calls the child via
+  `ctx.spawnAndWait(...)`.
+- `md_llm_parent/PROMPT.md`: markdown parent LLM deck that calls markdown child
+  action deck.
+- `md_llm_child/PROMPT.md`: markdown child LLM deck (with
+  `schemas/input.zod.ts`, `schemas/output.zod.ts`, and
+  `schemas/progress.zod.ts`) that emits `gambit:action_progress` via
+  `gambit_emit_output_item`.
+
+## Run (CLI)
+
+From `packages/gambit`:
+
+```bash
+deno run -A src/cli.ts run \
+  examples/dev/intermediate-child-delta/parent_compute_harness.deck.ts \
+  --context '"exercise delta path"' \
+  --trace /tmp/intermediate-child-delta.trace.jsonl \
+  --no-worker-sandbox
+```
+
+Inspect canonical child response events:
+
+```bash
+rg '"type":"response\.(created|output_item.added|output_item.done|completed|failed)"' \
+  /tmp/intermediate-child-delta.trace.jsonl
+```
+
+## Run Markdown LLM -> Action(LLM)
+
+From `packages/gambit`:
+
+```bash
+deno run -A src/cli.ts run \
+  examples/dev/intermediate-child-delta/md_llm_parent/PROMPT.md \
+  --context '"exercise llm action deltas"' \
+  --responses \
+  --stream \
+  --model openai/gpt-4o-mini \
+  --trace /tmp/llm-to-llm-openai-md-clean.trace.jsonl \
+  --no-worker-sandbox
+```
+
+Inspect child deck trace records:
+
+```bash
+rg 'md_llm_child/PROMPT.md|gambit_emit_output_item|response\.output_item\.(added|done)|response\.created|response\.completed' \
+  /tmp/llm-to-llm-openai-md-clean.trace.jsonl
+```

examples/dev/intermediate-child-delta/child_progress.deck.ts

@@ -0,0 +1,42 @@
+import { defineDeck } from "../../../mod.ts";
+import { z } from "zod";
+
+export default defineDeck({
+  contextSchema: z.object({
+    task: z.string().default("unspecified-task"),
+  }),
+  responseSchema: z.object({
+    done: z.boolean(),
+    task: z.string(),
+  }),
+  responseItemExtensions: [
+    {
+      type: "gambit:action_progress",
+      dataSchema: z.object({
+        step: z.string(),
+        percent: z.number(),
+      }),
+      description: "Intermediate child progress updates",
+    },
+  ],
+  async run(ctx) {
+    await ctx.emitOutputItem({
+      type: "gambit:action_progress",
+      data: { step: "start", percent: 10 },
+    });
+    await new Promise((resolve) => setTimeout(resolve, 15));
+    await ctx.emitOutputItem({
+      type: "gambit:action_progress",
+      data: { step: "middle", percent: 60 },
+    });
+    await new Promise((resolve) => setTimeout(resolve, 15));
+    await ctx.emitOutputItem({
+      type: "gambit:action_progress",
+      data: { step: "finalizing", percent: 90 },
+    });
+    return {
+      done: true,
+      task: ctx.input.task,
+    };
+  },
+});