@chrok/braid 0.1.0

package/docs/resource-limits.md

@@ -0,0 +1,53 @@
+# Resource limits and deployment responsibility
+
+Braid targets small reasoning graphs. Graph size, prompt/output size, event-log
+size, and the number of simultaneous graph submissions have no hard cap in 0.1.
+The scheduler rescans the graph as work settles. Consult the
+[benchmark](benchmark.md) for measured local overhead rather than treating the
+validator's deep-graph tests as a production capacity guarantee.
+
+| Control | Core default | Pi default |
+| --- | --- | --- |
+| Active runtime-managed invocations per graph | 4 | 4 |
+| Node timeout (starts at admission) | 60 seconds | Unlimited |
+| Graph timeout (includes queueing) | 5 minutes | Unlimited |
+| Caller cancellation | `AbortSignal` | `braid_cancel` / panel `c` |
+| Worker tool loop | Decision continuation / merge Git-tool loop, bounded by deadlines | Unlimited by default; optional `maxToolRounds` and `maxToolCalls` |
+| Result preview | Full result | 50 KB / 2,000 lines, then temporary full-result file |
+| Token / monetary budget | Not enforced | Not enforced |
+
+Pi keeps unlimited timeouts for interactive background work. For bounded work,
+submit explicit `options`, for example:
+
+```json
+{ "maxConcurrency": 2, "nodeTimeoutMs": 30000, "graphTimeoutMs": 120000, "maxToolRounds": 12, "maxToolCalls": 32 }
+```
+
+The concurrency limit belongs to each graph, not to the process or provider
+account. Ten graphs with `maxConcurrency: 4` can collectively start 40 calls.
+The host should cap simultaneous submissions and validate graph dimensions and
+input sizes before admitting untrusted requests. The core's graph timer starts
+after validation; it does not bound validation CPU or input allocation.
+
+Token counts report only usage returned by runners. Missing counts, failed
+requests, or timeout-aborted calls can still incur charges. There is no hard cost
+ceiling, and adding a token counter after completion cannot prevent concurrent
+calls from overspending. Use provider account quotas, output-token limits in a
+custom runner, host admission controls, and finite deadlines where needed.
+
+All events and full results live in memory; handoff events retain output for each
+edge. Large fan-out/fan-in graphs and verbose workers increase memory and context
+use. Pi retains completed jobs for its session lifetime and full temporary result
+files until the host/user removes them. Limit the length of sessions or reload
+after exporting needed results. Reloading also cancels outstanding work.
+
+Git worktree preparation, checkpointing, tracked writes, and cleanup add disk,
+Git-process, and elapsed-time overhead. Cleanup may extend wall time beyond a
+model deadline. Automatically appended merge agents are additional model calls
+and share the graph's remaining time. Benchmark results measured outside Git do
+not include this lifecycle. Recoverable refs retain Git objects until removed.
+
+An aborted runtime slot can be reused even if an uncooperative provider continues
+working. Runners must forward `signal`; neither Braid nor JavaScript can forcibly
+stop that remote work. Workspace and tool guards are not a security sandbox. See
+[SECURITY.md](../SECURITY.md) before exposing a runner to untrusted input.

package/examples/basic.ts

@@ -0,0 +1,86 @@
+import { braid, type BraidInput, type ModelRunner } from "../src/index.js";
+import { createOpenAICompatibleRunner } from "../src/adapters/openai.js";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const input: BraidInput = {
+  goal: "Compare the benefits and risks of adopting a four-day work week.",
+  nodes: [
+    {
+      type: "decision",
+      id: "route",
+      prompt: "Choose whether this goal needs a comparison or a short answer.",
+      choices: ["compare", "brief"],
+    },
+    {
+      type: "execute",
+      id: "benefits",
+      prompt: "Explain the main potential benefits.",
+    },
+    {
+      type: "execute",
+      id: "risks",
+      prompt: "Explain the main risks and uncertainties.",
+    },
+    {
+      type: "execute",
+      id: "answer",
+      prompt: "Synthesize both perspectives into a balanced recommendation.",
+    },
+    {
+      type: "execute",
+      id: "brief",
+      prompt: "Give a concise answer to the goal.",
+    },
+  ],
+  edges: [
+    { from: "route", to: "benefits", choice: "compare" },
+    { from: "route", to: "risks", choice: "compare" },
+    { from: "benefits", to: "answer" },
+    { from: "risks", to: "answer" },
+    { from: "route", to: "brief", choice: "brief" },
+  ],
+};
+
+// Deterministic stand-in for a provider. No network calls or token estimates.
+let runner: ModelRunner = async (request) => {
+  if (request.decide) {
+    request.decide("compare");
+    return { output: "A comparison needs both benefits and risks." };
+  }
+  if (request.node.id === "benefits")
+    return { output: "A shorter week may improve work-life balance." };
+  if (request.node.id === "risks")
+    return { output: "Coverage and workload compression need evaluation." };
+  return {
+    output:
+      request.predecessors
+        .map((item) => `[${item.nodeId}] ${item.output}`)
+        .join("\n") +
+      "\nRecommendation: test a time-limited pilot with explicit success criteria.",
+  };
+};
+let defaultModel = "demo";
+
+// Live calls are opt-in: OPENAI_API_KEY=... BRAID_MODEL=... npm run demo -- --live
+if (process.argv.includes("--live")) {
+  const apiKey = process.env.OPENAI_API_KEY;
+  const model = process.env.BRAID_MODEL;
+  const baseURL = process.env.OPENAI_BASE_URL;
+  if (!apiKey || !model)
+    throw new Error("--live requires OPENAI_API_KEY and BRAID_MODEL");
+  defaultModel = model;
+  runner = createOpenAICompatibleRunner({
+    apiKey,
+    ...(baseURL ? { baseURL } : {}),
+  });
+}
+
+// This text-only demo runs outside Git and needs no repository workspaces.
+const cwd = await mkdtemp(join(tmpdir(), "braid-demo-"));
+try {
+  const result = await braid(input, { cwd, runner, defaultModel, maxConcurrency: 2 });
+  console.log(JSON.stringify(result, null, 2));
+  if (result.status === "failed") process.exitCode = 1;
+} finally { await rm(cwd, { recursive: true, force: true }); }

package/examples/code-review.ts

@@ -0,0 +1,24 @@
+import { braid, type BraidInput, type ModelRunner } from "../src/index.js";
+import { inTemporaryDirectory } from "./support.js";
+
+// Supply an actual diff as graph data. Core workers have no filesystem access.
+const diff = "- return cache[key];\n+ return cache[key] ?? await load(key);";
+const graph: BraidInput = {
+  goal: `Review this proposed cache change:\n${diff}`,
+  nodes: [
+    { type: "execute", id: "correctness", prompt: "Review cache semantics and concurrent misses." },
+    { type: "execute", id: "tests", prompt: "Identify regression cases worth testing." },
+    { type: "execute", id: "review", prompt: "Synthesize actionable findings from both reviews." },
+  ],
+  edges: [{ from: "correctness", to: "review" }, { from: "tests", to: "review" }],
+};
+const runner: ModelRunner = async ({ node, predecessors }) => ({
+  output: node.id === "correctness"
+    ? "Concurrent cache misses can call load twice. Confirm whether null is a cached value."
+    : node.id === "tests"
+      ? "Test an existing value, null, concurrent misses, and a rejected load."
+      : predecessors.map(p => `${p.nodeId}: ${p.output}`).join("\n"),
+});
+const result = await inTemporaryDirectory(cwd => braid(graph, { cwd, runner, maxConcurrency: 2 }));
+if (result.status !== "completed") throw new Error(result.error?.message);
+console.log(result.terminalOutputs.review!.output);

package/examples/custom-runner.ts

@@ -0,0 +1,28 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { braid, type ModelRunner } from "../src/index.js";
+import { inTemporaryDirectory } from "./support.js";
+
+// A deterministic adapter demonstrating the contract; replace this stand-in
+// with a fresh provider conversation and expose decide as an actual model tool.
+const runner: ModelRunner = async request => {
+  request.signal.throwIfAborted();
+  await delay(1, undefined, { signal: request.signal });
+  if (request.node.type === "decision") {
+    request.decide!("continue");
+    return { output: "Continue with the analysis.", model: "offline-example" };
+  }
+  return {
+    output: `Received direct predecessors: ${request.predecessors.map(p => p.nodeId).join(", ")}`,
+    model: "offline-example",
+  };
+};
+const result = await inTemporaryDirectory(cwd => braid({
+  goal: "Demonstrate a cancellable isolated runner.",
+  nodes: [
+    { type: "decision", id: "route", prompt: "Choose a path.", choices: ["continue", "stop"] },
+    { type: "execute", id: "answer", prompt: "List the supplied predecessor IDs." },
+  ],
+  edges: [{ from: "route", to: "answer", choice: "continue" }],
+}, { cwd, runner, nodeTimeoutMs: 1000, graphTimeoutMs: 5000 }));
+if (result.status !== "completed") throw new Error(result.error?.message);
+console.log(result.terminalOutputs.answer!.output);

package/examples/failure-handling.ts

@@ -0,0 +1,29 @@
+import assert from "node:assert/strict";
+import { braid } from "../src/index.js";
+import { inTemporaryDirectory } from "./support.js";
+
+const result = await inTemporaryDirectory(cwd => braid({
+  goal: "Retain independent findings when one provider fails.",
+  nodes: [
+    { type: "execute", id: "offline", prompt: "Summarize known local facts." },
+    { type: "execute", id: "remote", prompt: "Ask the unavailable provider." },
+    { type: "execute", id: "join", prompt: "Combine both inputs." },
+  ],
+  edges: [{ from: "offline", to: "join" }, { from: "remote", to: "join" }],
+}, {
+  cwd,
+  runner: async ({ node, predecessors }) => {
+    if (node.id === "remote") throw new Error("Demo provider unavailable");
+    if (node.id === "join") return {
+      output: predecessors.map(p => `${p.nodeId}: ${p.error ? `unavailable (${p.error.code})` : p.output}`).join("\n"),
+    };
+    return { output: "Known local facts are still available." };
+  },
+}));
+assert.equal(result.status, "failed");
+assert.equal(result.nodes.join!.status, "completed");
+assert.match(result.terminalOutputs.join!.output, /remote: unavailable \(MODEL_ERROR\)/);
+// Unconditional successors receive failed predecessors as explicit error context.
+// A recovered answer does not erase the graph's original failure status.
+console.log(`status: ${result.status}; join: ${result.nodes.join!.status}`);
+console.log(result.terminalOutputs.join!.output);

package/examples/support.ts

@@ -0,0 +1,10 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/** Text-only examples run outside Git, without worktrees or source integration. */
+export async function inTemporaryDirectory<T>(run: (cwd: string) => Promise<T>): Promise<T> {
+  const cwd = await mkdtemp(join(tmpdir(), "braid-example-"));
+  try { return await run(cwd); }
+  finally { await rm(cwd, { recursive: true, force: true }); }
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@chrok/braid",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "A small, framework-agnostic DAG runtime for isolated model invocations",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./adapters/openai": {
+      "types": "./dist/adapters/openai.d.ts",
+      "import": "./dist/adapters/openai.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "docs",
+    "examples",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "CODE_OF_CONDUCT.md",
+    "ROADMAP.md"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "check": "tsc --noEmit",
+    "test": "tsx --test test/*.test.ts",
+    "demo": "tsx examples/basic.ts",
+    "check:pi": "npm --prefix integrations/pi run check",
+    "test:pi": "npm --prefix integrations/pi test",
+    "prepack": "npm run build",
+    "build:pi": "npm --prefix integrations/pi run build",
+    "test:package": "node scripts/package-smoke.mjs",
+    "verify": "npm run check && npm test && npm run check:pi && npm run test:pi && npm run examples && npm run test:package",
+    "examples": "tsx examples/basic.ts && tsx examples/code-review.ts && tsx examples/failure-handling.ts && tsx examples/custom-runner.ts",
+    "bench": "npm run build && node --expose-gc scripts/benchmark.mjs",
+    "demo:panel": "tsx scripts/panel-demo.ts",
+    "test:pi:live": "npm run build:pi && node integrations/pi/test/live/run.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Epsirom/braid.git"
+  },
+  "homepage": "https://github.com/Epsirom/braid#readme",
+  "bugs": {
+    "url": "https://github.com/Epsirom/braid/issues"
+  },
+  "keywords": [
+    "llm",
+    "agents",
+    "dag",
+    "orchestration",
+    "typescript"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}