@oakgreencc/cambium 0.0.7 → 0.0.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +86 -10
- package/package.json +15 -2
- package/src/cli.mjs +18 -3
- package/src/config.mjs +4 -0
- package/src/graph/advance.mjs +2 -2
- package/src/graph/langgraph.mjs +200 -0
- package/src/graph-engine.mjs +289 -0
- package/src/graphs/task.mjs +587 -0
- package/src/issue-state.mjs +46 -0
- package/src/tick.mjs +97 -76
package/README.md
CHANGED
|
@@ -19,15 +19,16 @@ cambium status
|
|
|
19
19
|
|
|
20
20
|
## Commands
|
|
21
21
|
|
|
22
|
-
| Command
|
|
23
|
-
|
|
|
24
|
-
| `cambium start [--once]`
|
|
25
|
-
| `cambium status [--json]`
|
|
26
|
-
| `cambium pause`
|
|
27
|
-
| `cambium drain`
|
|
28
|
-
| `cambium resume`
|
|
29
|
-
| `cambium run task --issue <n> [--repo <owner/name>]`
|
|
30
|
-
| `cambium
|
|
22
|
+
| Command | What |
|
|
23
|
+
| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
24
|
+
| `cambium start [--once]` | Foreground daemon, one tick every `tickSeconds`. SIGTERM/SIGINT stop it after the current tick; workers keep running and are re-adopted on restart. One daemon per database. |
|
|
25
|
+
| `cambium status [--json]` | Mode, last tick, queue counts, workers, failed steps. Exit 1 when there is no heartbeat or it is older than 3 ticks. |
|
|
26
|
+
| `cambium pause` | Read and heartbeat only: no transitions, no starts. Running workers are left alone. |
|
|
27
|
+
| `cambium drain` | Reconcile, watch and sweep as usual; start nothing new. |
|
|
28
|
+
| `cambium resume` | Back to `running`. |
|
|
29
|
+
| `cambium run task --issue <n> [--repo <owner/name>]` | Claim one open `q:task` issue, run its worker in the foreground, then make the same transition the daemon would. |
|
|
30
|
+
| `cambium run <graph> --issue <n> [--repo <owner/name>] [--follow]` | `engine: "graph"` only (`task` is the one graph today). Advance one issue through the graph runtime in the foreground: a `q:task` issue without a lease starts with a foreground worker; anything else resumes where its marker rests. Stops at the first wait that is not ready; `--follow` re-reads and polls every `tickSeconds` until the graph ends. |
|
|
31
|
+
| `cambium install [--dry-run]` | Write the launchd agent (`KeepAlive`, `RunAtLoad`) for `start --config <this config>`; `--dry-run` prints it. It does not call `launchctl`; it prints the command. |
|
|
31
32
|
|
|
32
33
|
Every command takes `--config <file>`; the default is `$CAMBIUM_CONFIG`, then `~/.cambium/config.json`.
|
|
33
34
|
|
|
@@ -91,6 +92,7 @@ One JSON file. Everything but `repos` is optional; these are the defaults:
|
|
|
91
92
|
```json
|
|
92
93
|
{
|
|
93
94
|
"host": "<os.hostname()>",
|
|
95
|
+
"engine": "legacy",
|
|
94
96
|
"tickSeconds": 30,
|
|
95
97
|
"stepTimeoutSeconds": 20,
|
|
96
98
|
"repos": [{ "slug": "oakgreencc/monorepo", "path": "~/OGCC/monorepo", "baseBranch": "main" }],
|
|
@@ -115,6 +117,7 @@ One JSON file. Everything but `repos` is optional; these are the defaults:
|
|
|
115
117
|
|
|
116
118
|
- `repos[].path` is a local clone; worktrees are added from it and `graft` runs in it.
|
|
117
119
|
- `graft.app` is the App cambium acts as (`GRAFT_APP` for its own `graft` calls); `worker.graftApp` the one workers act as. Neither leaks into the other.
|
|
120
|
+
- `engine` picks how the Task phase runs: `"legacy"` (the stage tick, the default) or `"graph"` (the [`task` graph](#the-task-graph)). Both make the same moves; see [The task graph](#the-task-graph).
|
|
118
121
|
- Setting `paths.home` moves every default path under it.
|
|
119
122
|
- `release.time` is host-local `HH:MM`.
|
|
120
123
|
|
|
@@ -218,9 +221,62 @@ Written at the end of every tick to `paths.heartbeat` (default `~/.cambium/state
|
|
|
218
221
|
|
|
219
222
|
The mode lives in the SQLite file (`paths.db`, table `control`), so `cambium status --json` returns `{ "mode", "heartbeat" }` even when the daemon is down. The daemon's own log is `<paths.logs>/cambium.log` (one `.1` kept); launchd's stderr goes to `<paths.logs>/cambium.launchd.err.log`.
|
|
220
223
|
|
|
224
|
+
## The task graph
|
|
225
|
+
|
|
226
|
+
With `"engine": "graph"` the tick's Task-phase steps (Reconcile, Watch, Sweep, Schedule) drive the `task` graph (`src/graphs/task.mjs`) instead of the stage tick in `src/tick.mjs`. The default stays `"legacy"`; flipping it and deleting the legacy path is a follow-up.
|
|
227
|
+
|
|
228
|
+
```mermaid
|
|
229
|
+
flowchart TD
|
|
230
|
+
start_(["q:task"])
|
|
231
|
+
n0["start-worker"]
|
|
232
|
+
n1{{"worker-running"}}
|
|
233
|
+
n2{{"ci-running"}}
|
|
234
|
+
n3{{"merge-queue"}}
|
|
235
|
+
n4["close-out"]
|
|
236
|
+
n5["requeue"]
|
|
237
|
+
n6["to-human"]
|
|
238
|
+
end_(("end"))
|
|
239
|
+
start_ --> n0
|
|
240
|
+
n0 -->|"started"| n1
|
|
241
|
+
n0 -->|"budgetSpent"| n6
|
|
242
|
+
n0 --> n5
|
|
243
|
+
n1 -->|"issueGone"| end_
|
|
244
|
+
n1 -->|"submitted"| n2
|
|
245
|
+
n1 --> n5
|
|
246
|
+
n2 -->|"merged"| n4
|
|
247
|
+
n2 -->|"inMergeQueue"| n3
|
|
248
|
+
n2 -->|"stalled"| n6
|
|
249
|
+
n2 --> n5
|
|
250
|
+
n3 -->|"merged"| n4
|
|
251
|
+
n3 -->|"stalled"| n6
|
|
252
|
+
n3 --> n5
|
|
253
|
+
n5 -->|"attemptsLeft"| n0
|
|
254
|
+
n5 --> n6
|
|
255
|
+
n4 --> end_
|
|
256
|
+
n6 --> end_
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
Generated by `toMermaid(task)`; a test keeps this copy current. Boxes are step nodes, hexagons are waits.
|
|
260
|
+
|
|
261
|
+
| Node | Kind | Queue label | Holds `running` |
|
|
262
|
+
| ---------------- | ---- | ----------- | --------------- |
|
|
263
|
+
| `start-worker` | step | `q:task` | no |
|
|
264
|
+
| `worker-running` | wait | `q:task` | yes |
|
|
265
|
+
| `ci-running` | wait | none | no |
|
|
266
|
+
| `merge-queue` | wait | none | no |
|
|
267
|
+
| `close-out` | step | none | no |
|
|
268
|
+
| `requeue` | step | `q:task` | no |
|
|
269
|
+
| `to-human` | step | `q:human` | no |
|
|
270
|
+
|
|
271
|
+
- **Labels are a projection.** Each node declares its queue label and whether it holds `running`. When an issue lands on a node, the marker is written first, then the labels come from `move()` (`labels.mjs`) with that declaration.
|
|
272
|
+
- **Where a turn starts.** Reconcile polls `worker-running` for every tracked worker. Watch polls `ci-running` / `merge-queue` for agent PRs whose issue is in no queue; a merged PR goes to `close-out` wherever the issue is, as in the stage tick. Sweep sends a stale `running` lease to its node's `recover` (default: `requeue`). Schedule is the gate on the entry node: caps and priority pick the issues, each starts at `start-worker`.
|
|
273
|
+
- **Where a turn stops.** At a wait that is not ready, on entering a wait (it is polled next tick; `merge-queue` is polled on entry, so a stall is caught in the same pass), on reaching `start-worker` again (only Schedule admits it), or at the end.
|
|
274
|
+
- **Markers.** The graph writes marker v2 without `stage`: `node` is where the issue rests. `merge-queue` is the stage tick's `submitted` with `queued: true`, and a stage-era marker in that state resumes at `merge-queue`. A marker whose node the current graph version no longer has restarts at `start-worker` with a `graph-changed` history entry.
|
|
275
|
+
- **Same moves.** Every scenario in `test/tick.test.mjs` runs on both engines; the test compares their GitHub calls in order (markers semantically, not by rendered text), worker starts with their prompts, kills, teardowns and logs.
|
|
276
|
+
|
|
221
277
|
## Graph module (preview)
|
|
222
278
|
|
|
223
|
-
`@oakgreencc/cambium/graph` is the start of typed workflows: nodes with schemas, edges as data, and a loop that advances a position through them.
|
|
279
|
+
`@oakgreencc/cambium/graph` is the start of typed workflows: nodes with schemas, edges as data, and a loop that advances a position through them. The Task phase runs on it with `engine: "graph"` ([The task graph](#the-task-graph)).
|
|
224
280
|
|
|
225
281
|
```js
|
|
226
282
|
import { z } from 'zod'
|
|
@@ -260,6 +316,26 @@ const { transitions, reason, node, input } = await advance(g, { node: 'open-pr',
|
|
|
260
316
|
- **`toMermaid(graph)`** renders a flowchart: boxes for steps, hexagons for waits, conditional edges labelled with `when`'s function name.
|
|
261
317
|
- **`opts.instrument(visit, step)`** (optional) wraps each node visit: `visit` is `{ node, kind: 'node' | 'wait', input }`; `step(extraCtx?)` runs the node (or poll) and picks the edge, returning the transition, or `null` for a wait that is not ready, and throws on a node error. `extraCtx` is merged into that node's `ctx`. Return what `step` returned. Without it, `advance` behaves exactly as before. [`advanceHooks`](#tracing) is the tracing implementation.
|
|
262
318
|
|
|
319
|
+
### LangGraph interop
|
|
320
|
+
|
|
321
|
+
`@oakgreencc/cambium/graph/langgraph` converts graphs to and from [LangGraph](https://docs.langchain.com/oss/javascript/langgraph/overview). LangGraph is not a cambium dependency: install `@langchain/langgraph` and `@langchain/core` yourself (an optional peer dependency). The module does not import LangGraph at load time; `toLangGraph` imports it when called, or takes the module as `{ langgraph }`.
|
|
322
|
+
|
|
323
|
+
```js
|
|
324
|
+
import { Command, MemorySaver } from '@langchain/langgraph'
|
|
325
|
+
import { fromLangGraph, pollWait, toLangGraph } from '@oakgreencc/cambium/graph/langgraph'
|
|
326
|
+
|
|
327
|
+
const app = (await toLangGraph(g)).compile({ checkpointer: new MemorySaver() })
|
|
328
|
+
const config = { configurable: { thread_id: 'owner/repo#42' }, context: ctx }
|
|
329
|
+
let out = await app.invoke({ subject, last: { issue: 7 } }, config)
|
|
330
|
+
const waiting = out.__interrupt__?.[0]?.value // { waiting: 'ci', input: { pr: 1 } }
|
|
331
|
+
const polled = await pollWait(g, waiting, ctx)
|
|
332
|
+
if (polled.ready) out = await app.invoke(new Command({ resume: polled.output }), config)
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
- **`toLangGraph(graph, { langgraph }?)`** resolves to an uncompiled `StateGraph` over `{ subject, last, outputs }`: `last` is the next node's input, `outputs` each node's latest output by name, and `subject` what edges see (it is checkpointed, so keep it serializable). Nodes get the run's `context` (plus `signal`) as `ctx`. Each node is `addNode(name, fn, { input })`, its input schema being the node's own on `last`; `fn` validates, runs, picks the edge and applies its `map`, so `last` is already the next input. A wait calls `interrupt({ waiting, input })`; resume it with the ready poll's `output` (`pollWait` runs the poll; a not-ready poll never reaches LangGraph). Edges are `addConditionalEdges`, trying `when` in order; `END` is LangGraph's `END`. Errors are `GraphNodeError`s.
|
|
336
|
+
- **`fromLangGraph(compiled, { name, input, output })`** is a `defineNode` whose `run` invokes the compiled graph with the validated input as its input state and validates the final state against `output`. An imported graph cannot wait: `interrupt()` inside it fails the node with an error saying so.
|
|
337
|
+
- Not carried over: `entry.queue`, `version` and the task graph's per-node declarations (`queue`, `running`, `enter`, `pollOnEntry`, `recover`), which belong to cambium's runtime; a driver applies them around the interrupts, as the differential test in `test/langgraph.test.mjs` does.
|
|
338
|
+
|
|
263
339
|
## Tracing
|
|
264
340
|
|
|
265
341
|
`src/tracing.mjs` is OpenTelemetry for cambium, configured only by the standard `OTEL_*` variables with `service.name=cambium`. It reuses mycelium's `createTracing` (same packages, same on/off rule): **on only when `OTEL_EXPORTER_OTLP_ENDPOINT` or `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` is set**, unless `OTEL_SDK_DISABLED=true` or `OTEL_TRACES_EXPORTER=none`; otherwise nothing is imported and every call is a no-op. Metrics follow the same rule for their signal (`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`, `OTEL_METRICS_EXPORTER`). With an endpoint but no collector, shutdown can take ~8 s; set `OTEL_EXPORTER_OTLP_TIMEOUT=2000` for the daemon.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@oakgreencc/cambium",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.9",
|
|
4
4
|
"description": "The scheduler daemon: reads the q:* queues from GitHub every tick, runs headless claude workers in their own worktrees up to a cap, and makes every queue transition itself.",
|
|
5
5
|
"license": "AGPL-3.0-only",
|
|
6
6
|
"type": "module",
|
|
@@ -26,6 +26,7 @@
|
|
|
26
26
|
},
|
|
27
27
|
"exports": {
|
|
28
28
|
"./graph": "./src/graph/index.mjs",
|
|
29
|
+
"./graph/langgraph": "./src/graph/langgraph.mjs",
|
|
29
30
|
"./package.json": "./package.json"
|
|
30
31
|
},
|
|
31
32
|
"files": [
|
|
@@ -50,7 +51,19 @@
|
|
|
50
51
|
"@opentelemetry/sdk-metrics": "^3.1.1",
|
|
51
52
|
"@opentelemetry/sdk-trace": "^3.1.1",
|
|
52
53
|
"zod": "^4.6.7",
|
|
53
|
-
"@oakgreencc/mycelium": "0.0.
|
|
54
|
+
"@oakgreencc/mycelium": "0.0.6"
|
|
55
|
+
},
|
|
56
|
+
"devDependencies": {
|
|
57
|
+
"@langchain/core": "^1.4.1",
|
|
58
|
+
"@langchain/langgraph": "^1.7.5"
|
|
59
|
+
},
|
|
60
|
+
"peerDependencies": {
|
|
61
|
+
"@langchain/langgraph": "^1.7.5"
|
|
62
|
+
},
|
|
63
|
+
"peerDependenciesMeta": {
|
|
64
|
+
"@langchain/langgraph": {
|
|
65
|
+
"optional": true
|
|
66
|
+
}
|
|
54
67
|
},
|
|
55
68
|
"scripts": {
|
|
56
69
|
"lint": "biome check .",
|
package/src/cli.mjs
CHANGED
|
@@ -13,6 +13,7 @@ import { acquireLock, readHeartbeat, realDeps, runDaemon } from './daemon.mjs'
|
|
|
13
13
|
import { plist, plistPath } from './launchd.mjs'
|
|
14
14
|
import { openStore } from './store.mjs'
|
|
15
15
|
import { finish, newCtx, startTask } from './tick.mjs'
|
|
16
|
+
import { runIssue } from './graph-engine.mjs'
|
|
16
17
|
|
|
17
18
|
export const VERSION = '0.0.0'
|
|
18
19
|
|
|
@@ -25,6 +26,9 @@ export const HELP = `cambium ${VERSION} — the scheduler daemon
|
|
|
25
26
|
cambium drain reconcile and watch, start no new workers
|
|
26
27
|
cambium run task --issue <n> [--repo <owner/name>]
|
|
27
28
|
claim one q:task issue, run its worker in the foreground, transition
|
|
29
|
+
cambium run <graph> --issue <n> [--repo <owner/name>] [--follow]
|
|
30
|
+
engine "graph": advance the issue in the foreground to the first wait
|
|
31
|
+
that is not ready; --follow keeps polling until the graph ends
|
|
28
32
|
cambium install [--dry-run] write the launchd agent (KeepAlive); --dry-run prints it
|
|
29
33
|
|
|
30
34
|
Common: --config <file> (default $CAMBIUM_CONFIG, then ~/.cambium/config.json)`
|
|
@@ -45,6 +49,7 @@ const has = (argv, name) => argv.includes(name)
|
|
|
45
49
|
* deps?: (config: import('./config.mjs').Config) => import('./tick.mjs').Deps,
|
|
46
50
|
* signal?: AbortSignal,
|
|
47
51
|
* now?: () => number,
|
|
52
|
+
* sleep?: (ms: number) => Promise<void>,
|
|
48
53
|
* }} IO
|
|
49
54
|
*/
|
|
50
55
|
|
|
@@ -141,15 +146,21 @@ function status(config, io, json) {
|
|
|
141
146
|
|
|
142
147
|
/**
|
|
143
148
|
* `run task --issue N`: one Task phase in the foreground, with the daemon's
|
|
144
|
-
* claim and transitions, so the daemon sees the same state afterwards.
|
|
149
|
+
* claim and transitions, so the daemon sees the same state afterwards. On
|
|
150
|
+
* `engine: "graph"`, `run <graph> --issue N [--follow]` runs the graph runtime
|
|
151
|
+
* in the foreground instead (graph-engine.mjs `runIssue`).
|
|
145
152
|
*
|
|
146
153
|
* @param {import('./config.mjs').Config} config @param {string[]} argv @param {IO} io
|
|
147
154
|
* @param {(config: import('./config.mjs').Config) => import('./tick.mjs').Deps} depsFor
|
|
148
155
|
*/
|
|
149
156
|
async function runOne(config, argv, io, depsFor) {
|
|
150
157
|
const n = Number(flag(argv, '--issue'))
|
|
151
|
-
|
|
152
|
-
|
|
158
|
+
const graph = argv[0]
|
|
159
|
+
if (!graph || graph.startsWith('-') || !Number.isInteger(n) || n <= 0)
|
|
160
|
+
return fail(io, 'usage: cambium run <graph> --issue <n> [--repo <owner/name>] [--follow]')
|
|
161
|
+
const follow = has(argv, '--follow')
|
|
162
|
+
if (config.engine === 'legacy' && (graph !== 'task' || follow))
|
|
163
|
+
return fail(io, `engine "legacy" runs only \`run task --issue <n>\`; set "engine": "graph" for graphs and --follow`)
|
|
153
164
|
const slug = flag(argv, '--repo') ?? (config.repos.length === 1 ? config.repos[0].slug : undefined)
|
|
154
165
|
if (!slug || !config.repos.some((r) => r.slug === slug))
|
|
155
166
|
return fail(
|
|
@@ -157,6 +168,10 @@ async function runOne(config, argv, io, depsFor) {
|
|
|
157
168
|
`--repo must name one of the configured repos: ${config.repos.map((r) => r.slug).join(', ') || '(none)'}`,
|
|
158
169
|
)
|
|
159
170
|
const deps = depsFor(config)
|
|
171
|
+
if (config.engine === 'graph') {
|
|
172
|
+
const r = await runIssue(deps, { graph, slug, number: n, follow, out: io.out, sleep: io.sleep, signal: io.signal })
|
|
173
|
+
return r.ok ? 0 : fail(io, /** @type {string} */ (r.error))
|
|
174
|
+
}
|
|
160
175
|
if (deps.store.worker(slug, n)) return fail(io, `${slug}#${n} already has a tracked worker`)
|
|
161
176
|
const snap = await deps.github.read(slug)
|
|
162
177
|
const issue = snap.issues.get(n)
|
package/src/config.mjs
CHANGED
|
@@ -12,6 +12,7 @@ import { join, resolve } from 'node:path'
|
|
|
12
12
|
* @typedef {{ cap: number, wallClockMinutes: number, maxTurns: number, maxAttempts: number }} PhaseCaps
|
|
13
13
|
* @typedef {{
|
|
14
14
|
* host: string,
|
|
15
|
+
* engine: 'legacy' | 'graph',
|
|
15
16
|
* tickSeconds: number,
|
|
16
17
|
* stepTimeoutSeconds: number,
|
|
17
18
|
* repos: Repo[],
|
|
@@ -32,6 +33,7 @@ export const DEFAULT_HOME = join(homedir(), '.cambium')
|
|
|
32
33
|
export function defaults(home = DEFAULT_HOME) {
|
|
33
34
|
return {
|
|
34
35
|
host: hostname(),
|
|
36
|
+
engine: 'legacy',
|
|
35
37
|
tickSeconds: 30,
|
|
36
38
|
stepTimeoutSeconds: 20,
|
|
37
39
|
repos: [],
|
|
@@ -86,6 +88,8 @@ export function resolveConfig(raw = {}) {
|
|
|
86
88
|
if (!r.path) throw new Error(`config: repo ${r.slug} needs "path" (a local clone)`)
|
|
87
89
|
return { slug: r.slug, path: untilde(r.path), baseBranch: r.baseBranch ?? 'main' }
|
|
88
90
|
})
|
|
91
|
+
if (config.engine !== 'legacy' && config.engine !== 'graph')
|
|
92
|
+
throw new Error(`config: engine must be "legacy" or "graph", got ${JSON.stringify(config.engine)}`)
|
|
89
93
|
if (!/^\d{2}:\d{2}$/.test(config.release.time)) throw new Error(`config: release.time must be HH:MM`)
|
|
90
94
|
return config
|
|
91
95
|
}
|
package/src/graph/advance.mjs
CHANGED
|
@@ -16,7 +16,7 @@ import { check, END, GraphNodeError } from './define.mjs'
|
|
|
16
16
|
*/
|
|
17
17
|
|
|
18
18
|
/** @param {unknown} err @param {string} node @param {'run' | 'poll' | 'edge'} phase */
|
|
19
|
-
const asNodeError = (err, node, phase) =>
|
|
19
|
+
export const asNodeError = (err, node, phase) =>
|
|
20
20
|
err instanceof GraphNodeError
|
|
21
21
|
? err
|
|
22
22
|
: new GraphNodeError(node, phase, String(/** @type {any} */ (err)?.message ?? err), { cause: err })
|
|
@@ -94,7 +94,7 @@ export async function advance(graph, at, ctx = {}, opts = {}) {
|
|
|
94
94
|
* The first edge out of `from` whose `when` matches `output`; a node with no outgoing edges goes to END.
|
|
95
95
|
* @param {import('./define.mjs').Graph} graph @param {string} from @param {unknown} output @param {unknown} subject
|
|
96
96
|
*/
|
|
97
|
-
function pick(graph, from, output, subject) {
|
|
97
|
+
export function pick(graph, from, output, subject) {
|
|
98
98
|
let any = false
|
|
99
99
|
for (const [i, [f, to, when, map]] of graph.edges.entries()) {
|
|
100
100
|
if (f !== from) continue
|
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
// @ts-check
|
|
2
|
+
/**
|
|
3
|
+
* `@oakgreencc/cambium/graph/langgraph`: LangGraph interop for cambium graphs.
|
|
4
|
+
*
|
|
5
|
+
* LangGraph is not a dependency of cambium: install `@langchain/langgraph` (and its peer `@langchain/core`)
|
|
6
|
+
* yourself to use this module. Nothing here imports it at load time; {@link toLangGraph} imports it when called,
|
|
7
|
+
* unless you pass the module in as `{ langgraph }`.
|
|
8
|
+
*
|
|
9
|
+
* - Export, {@link toLangGraph}: a cambium graph as an uncompiled `StateGraph` whose state is
|
|
10
|
+
* `{ subject, last, outputs }`. A wait node calls `interrupt({ waiting, input })`; resume it with what its
|
|
11
|
+
* `poll` returned as `output` ({@link pollWait} runs the poll for you).
|
|
12
|
+
* - Import, {@link fromLangGraph}: a compiled LangGraph graph as one cambium step node.
|
|
13
|
+
*/
|
|
14
|
+
import { randomUUID } from 'node:crypto'
|
|
15
|
+
import { asNodeError, pick } from './advance.mjs'
|
|
16
|
+
import { check, defineNode, END, GraphNodeError } from './define.mjs'
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* @typedef {import('./define.mjs').Graph} Graph
|
|
20
|
+
* @typedef {import('./define.mjs').StandardSchema} StandardSchema
|
|
21
|
+
* @typedef {{ subject: unknown, last: unknown, outputs: Record<string, unknown> }} State
|
|
22
|
+
* `last` is the input of the node about to run: the previous node's output, through its edge's `map`.
|
|
23
|
+
* `outputs` holds each node's latest output, by node name.
|
|
24
|
+
* @typedef {{ waiting: string, input: unknown }} Waiting The value a wait node passes to `interrupt()`.
|
|
25
|
+
* @typedef {typeof import('@langchain/langgraph')} LangGraphModule
|
|
26
|
+
*/
|
|
27
|
+
|
|
28
|
+
/** @param {LangGraphModule | undefined} injected @returns {Promise<LangGraphModule>} */
|
|
29
|
+
async function load(injected) {
|
|
30
|
+
if (injected) return injected
|
|
31
|
+
try {
|
|
32
|
+
return await import('@langchain/langgraph')
|
|
33
|
+
} catch (err) {
|
|
34
|
+
throw new Error('toLangGraph needs @langchain/langgraph (and @langchain/core): install them alongside cambium', {
|
|
35
|
+
cause: err,
|
|
36
|
+
})
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* The ctx a node gets: LangGraph's run `context` (`invoke(input, { context })`), with the run's `signal`.
|
|
42
|
+
* @param {any} config @returns {Record<string, unknown>}
|
|
43
|
+
*/
|
|
44
|
+
const ctxOf = (config) => {
|
|
45
|
+
const ctx = config?.context ?? {}
|
|
46
|
+
return { ...ctx, signal: config?.signal ?? ctx.signal }
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* `graph` as an uncompiled LangGraph `StateGraph`. Compile it with a checkpointer when the graph has waits.
|
|
51
|
+
*
|
|
52
|
+
* - State: `{ subject, last, outputs }`. Start a run with `{ subject, last: <entry input> }`; `subject` is what
|
|
53
|
+
* edge `when`/`map` see (cambium's advance passes `ctx.subject`), so it is checkpointed and must be serializable.
|
|
54
|
+
* - Nodes get `{ ...context, signal }` as ctx, where `context` is the run's `invoke(…, { context })`.
|
|
55
|
+
* - A step node validates `last`, runs, validates its output, picks its edge as advance does, and writes
|
|
56
|
+
* `outputs[name]` and `last` (the chosen edge's `map` is applied here: a LangGraph router cannot write state).
|
|
57
|
+
* - A wait node validates `last` and calls `interrupt({ waiting: name, input })`; the resume value is the
|
|
58
|
+
* ready poll's `output`, validated against the wait's output schema. Not-ready polls never reach LangGraph:
|
|
59
|
+
* poll outside ({@link pollWait}) and resume only when ready.
|
|
60
|
+
* - Edges: `addConditionalEdges(from, router)`, the router trying `when` in order on `outputs[from]`; a node with
|
|
61
|
+
* no outgoing edges goes to LangGraph's END. Errors are thrown as cambium's `GraphNodeError`.
|
|
62
|
+
*
|
|
63
|
+
* @param {Graph} graph
|
|
64
|
+
* @param {{ langgraph?: LangGraphModule }} [opts] the `@langchain/langgraph` module, instead of importing it
|
|
65
|
+
*/
|
|
66
|
+
export async function toLangGraph(graph, opts = {}) {
|
|
67
|
+
const lg = await load(opts.langgraph)
|
|
68
|
+
const { Annotation, StateGraph, START, interrupt } = lg
|
|
69
|
+
const LG_END = lg.END
|
|
70
|
+
const State = Annotation.Root({
|
|
71
|
+
subject: Annotation(),
|
|
72
|
+
last: Annotation(),
|
|
73
|
+
outputs: Annotation({
|
|
74
|
+
reducer: (/** @type {Record<string, unknown>} */ a, /** @type {Record<string, unknown>} */ b) => ({ ...a, ...b }),
|
|
75
|
+
default: () => ({}),
|
|
76
|
+
}),
|
|
77
|
+
})
|
|
78
|
+
const sg = new StateGraph(State)
|
|
79
|
+
const Any = {
|
|
80
|
+
'~standard': { version: 1, vendor: 'cambium', validate: (/** @type {unknown} */ value) => ({ value }) },
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
for (const node of graph.nodes) {
|
|
84
|
+
const { name } = node
|
|
85
|
+
/** @param {unknown} output @param {unknown} subject */
|
|
86
|
+
const settle = (output, subject) => {
|
|
87
|
+
let next
|
|
88
|
+
try {
|
|
89
|
+
;({ next } = pick(graph, name, output, subject))
|
|
90
|
+
} catch (err) {
|
|
91
|
+
throw asNodeError(err, name, 'edge')
|
|
92
|
+
}
|
|
93
|
+
return { last: next, outputs: { [name]: output } }
|
|
94
|
+
}
|
|
95
|
+
/** @param {State} state @param {any} config */
|
|
96
|
+
const fn =
|
|
97
|
+
node.kind === 'wait'
|
|
98
|
+
? async (state) => {
|
|
99
|
+
const input = await check(node.input, state.last, name, 'input')
|
|
100
|
+
const resumed = interrupt(/** @type {Waiting} */ ({ waiting: name, input }))
|
|
101
|
+
return settle(await check(node.output, resumed, name, 'output'), state.subject)
|
|
102
|
+
}
|
|
103
|
+
: async (state, config) => {
|
|
104
|
+
const input = await check(node.input, state.last, name, 'input')
|
|
105
|
+
let out
|
|
106
|
+
try {
|
|
107
|
+
out = await node.run(input, ctxOf(config))
|
|
108
|
+
} catch (err) {
|
|
109
|
+
throw asNodeError(err, name, 'run')
|
|
110
|
+
}
|
|
111
|
+
return settle(await check(node.output, out, name, 'output'), state.subject)
|
|
112
|
+
}
|
|
113
|
+
sg.addNode(name, fn, { input: new lg.StateSchema({ subject: Any, last: node.input }) })
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
sg.addEdge(START, /** @type {any} */ (graph.entry.node))
|
|
117
|
+
/** @type {Map<string, import('./define.mjs').Edge[]>} */
|
|
118
|
+
const out = new Map()
|
|
119
|
+
for (const e of graph.edges) out.set(e[0], [...(out.get(e[0]) ?? []), e])
|
|
120
|
+
const target = (/** @type {string} */ to) => (to === END ? LG_END : to)
|
|
121
|
+
for (const node of graph.nodes) {
|
|
122
|
+
const edges = out.get(node.name)
|
|
123
|
+
if (!edges) {
|
|
124
|
+
sg.addEdge(/** @type {any} */ (node.name), LG_END)
|
|
125
|
+
continue
|
|
126
|
+
}
|
|
127
|
+
const ends = [...new Set(edges.map(([, to]) => target(to)))]
|
|
128
|
+
/** @param {State} state */
|
|
129
|
+
const router = (state) => {
|
|
130
|
+
const o = state.outputs[node.name]
|
|
131
|
+
for (const [, to, when] of edges) if (!when || when(o, state.subject)) return target(to)
|
|
132
|
+
throw new GraphNodeError(node.name, 'edge', 'no edge matched the output')
|
|
133
|
+
}
|
|
134
|
+
sg.addConditionalEdges(/** @type {any} */ (node.name), router, /** @type {any} */ (ends))
|
|
135
|
+
}
|
|
136
|
+
return sg
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/**
|
|
140
|
+
* Poll the wait a LangGraph run is interrupted at: `{ ready: true, output }` means resume with
|
|
141
|
+
* `new Command({ resume: output })`; `{ ready: false }` means leave the thread where it is.
|
|
142
|
+
* @param {Graph} graph @param {Waiting} waiting the interrupt's value @param {Record<string, unknown>} [ctx]
|
|
143
|
+
* @returns {Promise<import('./define.mjs').PollResult>}
|
|
144
|
+
*/
|
|
145
|
+
export async function pollWait(graph, waiting, ctx = {}) {
|
|
146
|
+
const node = graph.nodes.find((n) => n.name === waiting?.waiting)
|
|
147
|
+
if (node?.kind !== 'wait') throw new Error(`graph "${graph.name}" has no wait node "${waiting?.waiting}"`)
|
|
148
|
+
const input = await check(node.input, waiting.input, node.name, 'input')
|
|
149
|
+
let polled
|
|
150
|
+
try {
|
|
151
|
+
polled = await node.poll(input, ctx)
|
|
152
|
+
} catch (err) {
|
|
153
|
+
throw asNodeError(err, node.name, 'poll')
|
|
154
|
+
}
|
|
155
|
+
if (typeof polled?.ready !== 'boolean')
|
|
156
|
+
throw new GraphNodeError(node.name, 'poll', 'poll must return { ready: false } or { ready: true, output }')
|
|
157
|
+
return polled
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
/** @param {unknown} err */
|
|
161
|
+
const isInterrupt = (err) =>
|
|
162
|
+
/** @type {any} */ (err)?.name === 'GraphInterrupt' ||
|
|
163
|
+
/** @type {any} */ (err)?.lc_error_code === 'MISSING_CHECKPOINTER'
|
|
164
|
+
|
|
165
|
+
/**
|
|
166
|
+
* A compiled LangGraph graph as one cambium step node: `run` invokes it with the node's validated input as the
|
|
167
|
+
* graph's input state (passing ctx's `signal`), and its final state is validated against `output`.
|
|
168
|
+
*
|
|
169
|
+
* An imported graph cannot wait: an `interrupt()` inside it fails the node with an error saying so (with or
|
|
170
|
+
* without a checkpointer). Its own nodes stay opaque; they are closures over its state.
|
|
171
|
+
*
|
|
172
|
+
* @param {{ invoke: (input: any, config?: any) => Promise<any> }} compiled
|
|
173
|
+
* @param {{ name: string, input: StandardSchema, output: StandardSchema }} def
|
|
174
|
+
*/
|
|
175
|
+
export function fromLangGraph(compiled, { name, input, output }) {
|
|
176
|
+
if (typeof compiled?.invoke !== 'function') throw new Error(`fromLangGraph "${name}": expected a compiled graph`)
|
|
177
|
+
const interrupted = () =>
|
|
178
|
+
new Error(
|
|
179
|
+
`imported LangGraph graph "${name}" called interrupt(); cambium runs imported graphs to completion and cannot resume them, so model the wait as a cambium wait node instead`,
|
|
180
|
+
)
|
|
181
|
+
return defineNode({
|
|
182
|
+
name,
|
|
183
|
+
input,
|
|
184
|
+
output,
|
|
185
|
+
run: async (value, ctx) => {
|
|
186
|
+
let result
|
|
187
|
+
try {
|
|
188
|
+
result = await compiled.invoke(value, {
|
|
189
|
+
signal: ctx?.signal,
|
|
190
|
+
configurable: { thread_id: `cambium:${name}:${randomUUID()}` },
|
|
191
|
+
})
|
|
192
|
+
} catch (err) {
|
|
193
|
+
if (isInterrupt(err)) throw interrupted()
|
|
194
|
+
throw err
|
|
195
|
+
}
|
|
196
|
+
if (Array.isArray(result?.__interrupt__) && result.__interrupt__.length) throw interrupted()
|
|
197
|
+
return result
|
|
198
|
+
},
|
|
199
|
+
})
|
|
200
|
+
}
|