@bolt-foundry/gambit 0.6.2 → 0.6.4

package/README.md

@@ -1,94 +1,167 @@
-# Gambit (draft README)
+# Gambit
 
-This package is developed in Bolt Foundry’s monorepo and synced into gambitmono
-(`github.com/bolt-foundry/gambit`). For now, gambitmono is a strict sync target
-(please do not land direct changes there).
+Gambit helps you build reliable LLM workflows by composing small, typed “decks”\
+with clear inputs/outputs and guardrails. Run decks locally, stream traces, and\
+debug with a built-in UI.
 
-CI runs `.github/workflows/gambit-mirror.yml` on every `main` push that touches
-this package, using `scripts/sync-gambit-mirror.sh` to open and auto-merge a PR
-from the `bft-codebot` fork into gambitmono.
+## Quickstart
 
-Gambit helps developers build the most accurate LLM apps by making it simple to
-provide exactly the right amount of context at the right time.
+Requirements: Deno 2.2+ and `OPENROUTER_API_KEY` (set `OPENROUTER_BASE_URL` if\
+you proxy OpenRouter-style APIs).
+
+Run the CLI directly from JSR (no install):
+
+```
+export OPENROUTER_API_KEY=...
+deno run -A jsr:@bolt-foundry/gambit/cli init
+```
+
+Downloads example files and sets environment variables.
+
+Run an example in the terminal (`repl`):
+
+```
+deno run -A jsr:@bolt-foundry/gambit/cli repl examples/hello.deck.md
+```
+
+This example just says "hello" and repeats your message back to you.
+
+Run an example in the browser (`serve`):
+
+```
+deno run -A jsr:@bolt-foundry/gambit/cli serve examples/hello.deck.md
+open http://localhost:8000/debug
+```
+
+---
 
 ## Status quo
 
-- Most teams wire one long prompt to several tools and hope the model routes
+- Most teams wire one long prompt to several tools and hope the model routes\
   correctly.
-- Context often arrives as a single giant fetch or RAG blob, so costs climb and
+- Context often arrives as a single giant fetch or RAG blob, so costs climb and\
   hallucinations slip in.
-- Input/outputs are rarely typed, which makes orchestration brittle and hard to
+- Input/outputs are rarely typed, which makes orchestration brittle and hard to\
   test offline.
-- Debugging leans on provider logs instead of local traces, so reproducing
+- Debugging leans on provider logs instead of local traces, so reproducing\
   failures is slow.
 
 ## Our vision
 
-- Treat each step as a small deck with explicit inputs/outputs and guardrails;
+- Treat each step as a small deck with explicit inputs/outputs and guardrails;\
   model calls are just one kind of action.
-- Mix LLM and compute tasks interchangeably and effortlessly inside the same
+- Mix LLM and compute tasks interchangeably and effortlessly inside the same\
   deck tree.
-- Feed models only what they need per step; inject references and cards instead
+- Feed models only what they need per step; inject references and cards instead\
   of dumping every document.
-- Keep orchestration logic local and testable; run decks offline with
+- Keep orchestration logic local and testable; run decks offline with\
   predictable traces.
-- Ship with built-in observability (streaming, REPL, debug UI) so debugging
+- Ship with built-in observability (streaming, REPL, debug UI) so debugging\
   feels like regular software, not guesswork.
 
-## 5-minute quickstart
+---
 
-Requirements: Deno 2.2+ and `OPENROUTER_API_KEY` (set `OPENROUTER_BASE_URL` if
-you proxy OpenRouter-style APIs).
+## Using the CLI
 
-Run the CLI directly from JSR (no install):
+Use the CLI to run decks locally, stream output, and capture traces/state.
 
-```sh
-export OPENROUTER_API_KEY=...
-deno run -A jsr:@bolt-foundry/gambit/cli --help
+Install the CLI:
+
+```
+deno install -A -n gambit jsr:@bolt-foundry/gambit/cli
 ```
 
-Run a packaged example without cloning:
+Run a deck once:
 
-```sh
-export OPENROUTER_API_KEY=...
-deno run -A jsr:@bolt-foundry/gambit/cli run --example hello_world.deck.md --init '"hi"'
+```
+gambit run <deck> --init <json|string> --message <json|string>
 ```
 
-Run the built-in assistant (from a clone of this repo):
+Drop into a REPL (streams by default):
 
-```sh
-export OPENROUTER_API_KEY=...
-deno run -A src/cli.ts run src/decks/gambit-assistant.deck.md --init '"hi"' --stream
+```
+gambit repl <deck>
+```
+
+Run a persona against a root deck (test bot):
+
+```
+gambit test-bot <root-deck> --test-deck <persona-deck>
 ```
 
-Talk to it in a REPL (default deck is `src/decks/gambit-assistant.deck.md`):
+Grade a saved session:
 
-```sh
-deno run -A src/cli.ts repl --message '"hello"' --stream --verbose
+```
+gambit grade <grader-deck> --state <file>
 ```
 
-Open the debug UI:
+Start the Debug UI server:
 
-```sh
-deno run -A src/cli.ts serve src/decks/gambit-assistant.deck.md --port 8000
-open http://localhost:8000/debug
 ```
+gambit serve <deck> --port 8000
+```
+
+Tracing and state: 
+
+`--trace <file>` for JSONL traces\
+`--verbose` to print events\
+`--state <file>` to persist a session.
+
+## Using the Simulator
+
+The simulator is the local Debug UI that streams runs and renders traces.
 
-Install the CLI once (uses the published JSR package):
+Install the CLI:
 
-```sh
+```
 deno install -A -n gambit jsr:@bolt-foundry/gambit/cli
-gambit run path/to/root.deck.ts --init '"hi"'
 ```
 
-If you run from a remote URL (e.g., `jsr:@bolt-foundry/gambit/cli`), pass an
-explicit deck path; the default REPL deck only exists in a local checkout.
+Start it:
+
+```
+gambit serve <deck> --port 8000
+```
+
+Then open:
+
+```
+http://localhost:8000/
+```
+
+It also serves:
+
+```
+http://localhost:8000/test-bot
+http://localhost:8000/calibrate
+```
+
+The Debug UI shows transcript lanes plus a trace/tools feed. If the deck has an\
+`inputSchema`, the UI renders a schema-driven form with defaults and a raw JSON\
+tab. Local-first state is stored under `.gambit/` (sessions, traces, notes).
+
+## Using the Library
+
+Use the library when you want TypeScript decks/cards or custom compute steps.
+
+Import the helpers from JSR:
+
+```
+import { defineDeck, defineCard } from "jsr:@bolt-foundry/gambit";
+```
+
+Define `inputSchema`/`outputSchema` with Zod to validate IO, and implement\
+`run`/`execute` for compute decks. To call a child deck from code, use\
+`ctx.spawnAndWait({ path, input })`. Emit structured trace events with\
+`ctx.log(...)`.
+
+---
 
 ## Author your first deck
 
-Minimal Markdown deck (model-powered):
+### Minimal Markdown deck (model-powered):
 
-```md
+```
 +++
 label = "hello_world"
 
@@ -102,13 +175,13 @@ You are a concise assistant. Greet the user and echo the input.
 
 Run it:
 
-```sh
+```
 deno run -A src/cli.ts run ./hello_world.deck.md --init '"Gambit"' --stream
 ```
 
-Compute deck in TypeScript (no model call):
+### Compute deck in TypeScript (no model call):
 
-```ts
+```
 // echo.deck.ts
 import { defineDeck } from "jsr:@bolt-foundry/gambit";
 import { z } from "zod";
@@ -125,19 +198,20 @@ export default defineDeck({
 
 Run it:
 
-```sh
+```
 deno run -A src/cli.ts run ./echo.deck.ts --init '{"text":"ping"}'
 ```
 
-Deck with a child action (calls a TypeScript tool):
+### Deck with a child action (calls a TypeScript tool):
 
-```md
+```
 +++
 label = "agent_with_time"
 modelParams = { model = "openai/gpt-4o-mini", temperature = 0 }
-actionDecks = [
-  { name = "get_time", path = "./get_time.deck.ts", description = "Return the current ISO timestamp." },
-]
+[[actionDecks]]
+name = "get_time"
+path = "./get_time.deck.ts"
+description = "Return the current ISO timestamp."
 +++
 
 A tiny agent that calls get_time, then replies with the timestamp and the input.
@@ -145,7 +219,7 @@ A tiny agent that calls get_time, then replies with the timestamp and the input.
 
 And the child action:
 
-```ts
+```
 // get_time.deck.ts
 import { defineDeck } from "jsr:@bolt-foundry/gambit";
 import { z } from "zod";
@@ -159,78 +233,3 @@ export default defineDeck({
   },
 });
 ```
-
-## Repo highlights
-
-- CLI entry: `src/cli.ts`; runtime: `src/runtime.ts`; definitions: `mod.ts`.
-- Examples: `examples/hello_world.deck.md`,
-  `examples/agent_with_multi_actions/`.
-- Debug UI assets: `src/server.ts` (built-in UI now renders schema-driven init
-  forms beneath the user message box with a raw JSON tab, reconnect button, and
-  a trace-formatting hook).
-- Tests/lint/format: `deno task test`, `deno task lint`, `deno task fmt`;
-  compile binary: `deno task compile`.
-- Docs index: `docs/README.md`; authoring guide: `docs/authoring.md`; prompting
-  notes: `docs/hourglass.md`; changelog: `CHANGELOG.md`.
-
-## Docs
-
-- Authoring decks/cards: `docs/authoring.md`
-- Runtime/guardrails: `docs/runtime.md`
-- CLI, REPL, debug UI: `docs/cli.md`
-- Examples guide: `docs/examples.md`
-- OpenAI Chat Completions compatibility: `docs/openai-compat.md`
-
-## OpenAI Chat Completions compatibility
-
-If you already construct OpenAI Chat Completions-style requests, you can use
-Gambit as a drop-in-ish wrapper that applies a deck prompt and can execute only
-deck-defined tools (action decks).
-
-```ts
-import {
-  chatCompletionsWithDeck,
-  createOpenRouterProvider,
-} from "jsr:@bolt-foundry/gambit";
-
-const provider = createOpenRouterProvider({
-  apiKey: Deno.env.get("OPENROUTER_API_KEY")!,
-});
-
-const resp = await chatCompletionsWithDeck({
-  deckPath: "./path/to/root.deck.md",
-  modelProvider: provider,
-  request: {
-    model: "openai/gpt-4o-mini",
-    messages: [{ role: "user", content: "hello" }],
-  },
-});
-
-console.log(resp.choices[0].message);
-```
-
-## Handlers (error/busy/idle)
-
-- Decks may declare `handlers` with `onError`, `onBusy`, and `onIdle`.
-  `onInterval` is still accepted but deprecated (alias for `onBusy`).
-- Busy handler input:
-  `{kind:"busy", source:{deckPath, actionName}, trigger:{reason:"timeout", elapsedMs}, childInput}`
-  plus `delayMs`/`repeatMs` knobs.
-- Idle handler input:
-  `{kind:"idle", source:{deckPath}, trigger:{reason:"idle_timeout", elapsedMs}}`
-  with `delayMs` (and optional `repeatMs` if provided).
-- Error handler input: `{kind:"error", source, error:{message}, childInput}` and
-  should return an envelope `{message?, code?, status?, meta?, payload?}`.
-- Example implementations live under `examples/handlers_ts` and
-  `examples/handlers_md`.
-- Debug UI streams handler output in a “status” lane (busy/idle) separate from
-  assistant turns.
-
-## Next steps
-
-- Swap `modelParams.model` or pass `--model`/`--model-force` to test other
-  providers.
-- Add `actionDecks` to a deck and call child decks; use `spawnAndWait` inside
-  compute decks.
-- Use `--stream` and `--verbose` while iterating; pass `--trace <file>` to
-  capture JSONL traces.

package/bin/gambit.cjs

@@ -7,10 +7,21 @@ const os = require("os");
 const https = require("https");
 const http = require("http");
 const crypto = require("crypto");
+const zlib = require("zlib");
+const { pipeline } = require("stream/promises");
 const { spawnSync } = require("child_process");
 
 const MAX_REDIRECTS = 5;
 
+const fileExists = async (filePath) => {
+  try {
+    await fs.promises.access(filePath, fs.constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
 const readJson = (filePath) => {
   const raw = fs.readFileSync(filePath, "utf8");
   return JSON.parse(raw);
@@ -88,6 +99,17 @@ const downloadFile = async (url, dest) => {
   await fs.promises.rename(tmpDest, dest);
 };
 
+const gunzipFile = async (source, dest) => {
+  const tmpDest = `${dest}.tmp-${process.pid}`;
+  await fs.promises.mkdir(path.dirname(dest), { recursive: true });
+  await pipeline(
+    fs.createReadStream(source),
+    zlib.createGunzip(),
+    fs.createWriteStream(tmpDest, { mode: 0o755 }),
+  );
+  await fs.promises.rename(tmpDest, dest);
+};
+
 const fetchText = async (url) => {
   const res = await request(url);
   const chunks = [];
@@ -139,6 +161,9 @@ const verifyChecksum = async (checksumUrl, assetName, filePath) => {
 
 const main = async () => {
   const version = getPackageVersion();
+  if (!process.env.GAMBIT_VERSION) {
+    process.env.GAMBIT_VERSION = version;
+  }
   const assetName = process.env.GAMBIT_BINARY_NAME || getPlatformAsset();
   if (!assetName) {
     console.error(
@@ -149,38 +174,87 @@ const main = async () => {
 
   const baseUrl = process.env.GAMBIT_BINARY_BASE_URL ||
     `https://github.com/bolt-foundry/gambit/releases/download/v${version}`;
-  const binaryUrl = process.env.GAMBIT_BINARY_URL || `${baseUrl}/${assetName}`;
+  const binaryUrl = process.env.GAMBIT_BINARY_URL ||
+    `${baseUrl}/${assetName}.gz`;
   const checksumUrl = process.env.GAMBIT_BINARY_CHECKSUM_URL ||
     `${baseUrl}/SHA256SUMS`;
+  const downloadName = (() => {
+    try {
+      return path.posix.basename(new URL(binaryUrl).pathname);
+    } catch {
+      return path.posix.basename(binaryUrl);
+    }
+  })();
+  const expectsGzip = downloadName.endsWith(".gz");
 
   const cacheDir = getCacheDir(version);
   const binPath = path.join(cacheDir, assetName);
+  const archivePath = expectsGzip ? `${binPath}.gz` : binPath;
   const ensureBinary = async () => {
-    if (fs.existsSync(binPath)) {
+    const hasBin = await fileExists(binPath);
+    const hasArchive = await fileExists(archivePath);
+    if (!hasBin && expectsGzip && hasArchive) {
       try {
-        await verifyChecksum(checksumUrl, assetName, binPath);
+        await verifyChecksum(checksumUrl, downloadName, archivePath);
+        await gunzipFile(archivePath, binPath);
         return;
       } catch (err) {
-        console.warn(
-          `Cached binary failed checksum; deleting and re-downloading.`,
-        );
         try {
-          await fs.promises.unlink(binPath);
+          await fs.promises.unlink(archivePath);
         } catch {
           // ignore
         }
       }
     }
+    if (hasBin) {
+      if (expectsGzip && !hasArchive) {
+        console.warn(`Cached binary missing archive; re-downloading.`);
+      } else {
+        try {
+          await verifyChecksum(checksumUrl, downloadName, archivePath);
+          if (expectsGzip) {
+            await gunzipFile(archivePath, binPath);
+          }
+          return;
+        } catch (err) {
+          console.warn(
+            `Cached binary failed checksum; deleting and re-downloading.`,
+          );
+          try {
+            await fs.promises.unlink(binPath);
+          } catch {
+            // ignore
+          }
+          if (expectsGzip) {
+            try {
+              await fs.promises.unlink(archivePath);
+            } catch {
+              // ignore
+            }
+          }
+        }
+      }
+    }
     console.log(`Downloading ${binaryUrl}...`);
-    await downloadFile(binaryUrl, binPath);
+    await downloadFile(binaryUrl, archivePath);
     try {
-      await verifyChecksum(checksumUrl, assetName, binPath);
+      await verifyChecksum(checksumUrl, downloadName, archivePath);
+      if (expectsGzip) {
+        await gunzipFile(archivePath, binPath);
+      }
     } catch (err) {
       try {
-        await fs.promises.unlink(binPath);
+        await fs.promises.unlink(archivePath);
       } catch {
         // ignore
       }
+      if (expectsGzip) {
+        try {
+          await fs.promises.unlink(binPath);
+        } catch {
+          // ignore
+        }
+      }
       throw err;
     }
   };