@skein-js/server-kit 0.11.3 → 0.13.0
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 +30 -2
- package/dist/chunk-JUBBCC7R.js +56 -0
- package/dist/chunk-QOHYARHD.js +237 -0
- package/dist/dev-BfYYRfEB.d.ts +46 -0
- package/dist/dev.d.ts +4 -0
- package/dist/dev.js +303 -0
- package/dist/in-memory-runtime-32UYJRVJ.js +9 -0
- package/dist/index.d.ts +325 -45
- package/dist/index.js +323 -496
- package/package.json +10 -5
package/dist/index.d.ts
CHANGED
|
@@ -1,12 +1,14 @@
|
|
|
1
|
-
import { ProtocolRuntime, Logger, ProtocolDeps, RunWorkerOptions, RunFailureReport, GraphResolver, ProtocolResponse } from '@skein-js/agent-protocol';
|
|
1
|
+
import { ProtocolRuntime, RouteBinding, Logger, ProtocolDeps, RunWorkerOptions, CronSchedulerOptions, RunFailureReport, GraphResolver, RouteMatcher, DisabledRouteGroups, ProtocolResponse } from '@skein-js/agent-protocol';
|
|
2
2
|
export { CompiledGraphFactory, DEFAULT_RUN_CONCURRENCY, DEFAULT_SHUTDOWN_GRACE_MS, GraphResolver, Logger, ProtocolDeps, ResolvedGraph, RunWorkerOptions } from '@skein-js/agent-protocol';
|
|
3
3
|
import { ModuleImporter, LanggraphJson, GraphSchemas } from '@skein-js/config';
|
|
4
4
|
import { CorsOptions } from 'cors';
|
|
5
5
|
export { CorsOptions } from 'cors';
|
|
6
|
-
import {
|
|
7
|
-
import {
|
|
8
|
-
|
|
6
|
+
import { MemoryRunEventBusOptions } from '@skein-js/storage-memory';
|
|
7
|
+
import { D as DevStateSnapshot } from './dev-BfYYRfEB.js';
|
|
8
|
+
export { a as DevStateCounts } from './dev-BfYYRfEB.js';
|
|
9
|
+
import { CompiledGraph } from '@langchain/langgraph';
|
|
9
10
|
import { ServerResponse } from 'node:http';
|
|
11
|
+
import '@skein-js/core';
|
|
10
12
|
|
|
11
13
|
interface SkeinRuntimeCommonOptions {
|
|
12
14
|
/**
|
|
@@ -58,6 +60,17 @@ interface SkeinRuntimeCommonOptions {
|
|
|
58
60
|
* longer than this, or the abort step never runs — see docs/deploy.md.
|
|
59
61
|
*/
|
|
60
62
|
worker?: RunWorkerOptions;
|
|
63
|
+
/**
|
|
64
|
+
* Tuning for the cron scheduler.
|
|
65
|
+
*
|
|
66
|
+
* `tickMs` is how often each instance looks for due crons (default `DEFAULT_CRON_TICK_MS`); omit it
|
|
67
|
+
* and skein reads `SKEIN_CRON_TICK_MS`, with the same explicit-wins-but-still-validated rule.
|
|
68
|
+
*
|
|
69
|
+
* `enabled` defaults to whether the crons route group is mounted, so `http.disable_crons` switches
|
|
70
|
+
* off the schedules as well as the endpoints. Set it explicitly to run one without the other — a
|
|
71
|
+
* worker-only instance that serves no HTTP, say.
|
|
72
|
+
*/
|
|
73
|
+
scheduler?: CronSchedulerOptions;
|
|
61
74
|
}
|
|
62
75
|
/** Either point at a `langgraph.json` (in-memory runtime) or inject a ready `ProtocolDeps`. */
|
|
63
76
|
type SkeinRuntimeOptions = SkeinRuntimeCommonOptions & ({
|
|
@@ -78,6 +91,12 @@ interface ResolvedProtocolRuntime {
|
|
|
78
91
|
runtime: ProtocolRuntime;
|
|
79
92
|
/** CORS mapped from the config's `http.cors`, or `undefined` for the injected-`deps` path. */
|
|
80
93
|
cors?: CorsOptions;
|
|
94
|
+
/**
|
|
95
|
+
* The route table to mount: the full protocol, minus any group the config's `http.disable_*` flags
|
|
96
|
+
* switched off. Always present — the injected-`deps` path has no config to read flags from, so it
|
|
97
|
+
* gets the complete table.
|
|
98
|
+
*/
|
|
99
|
+
routes: readonly RouteBinding[];
|
|
81
100
|
/**
|
|
82
101
|
* The logger the engine ended up with, after {@link SkeinRuntimeCommonOptions.logger}'s precedence
|
|
83
102
|
* chain. `undefined` means nothing logs. Adapters read this (rather than `options.logger`) for
|
|
@@ -91,6 +110,8 @@ interface ResolvedRuntimeDeps {
|
|
|
91
110
|
deps: ProtocolDeps;
|
|
92
111
|
/** CORS mapped from the config's `http.cors`, or `undefined` for the injected-`deps` path. */
|
|
93
112
|
cors?: CorsOptions;
|
|
113
|
+
/** The route table to mount — see {@link ResolvedProtocolRuntime.routes}. */
|
|
114
|
+
routes: readonly RouteBinding[];
|
|
94
115
|
/** The resolved logger — see {@link ResolvedProtocolRuntime.logger}. */
|
|
95
116
|
logger?: Logger;
|
|
96
117
|
}
|
|
@@ -160,6 +181,182 @@ declare function formatLogMeta(meta: unknown): string;
|
|
|
160
181
|
*/
|
|
161
182
|
declare function describeError(thrown: unknown): string;
|
|
162
183
|
|
|
184
|
+
/**
|
|
185
|
+
* The two bounds this resolves. `finishedIdTtlMs` and `now` are deliberately not included — the TTL
|
|
186
|
+
* matches the Redis driver's closed-marker window and is not something a deployment tunes, and the
|
|
187
|
+
* clock exists for tests.
|
|
188
|
+
*/
|
|
189
|
+
type ResolvedMemoryBusLimits = Required<Pick<MemoryRunEventBusOptions, "maxRetainedRuns" | "maxFramesPerRun">>;
|
|
190
|
+
/**
|
|
191
|
+
* Resolve the memory bus's retention bounds from explicit options, then the environment, then the
|
|
192
|
+
* defaults. Both variables are validated even when an explicit value is supplied, so a bad one can't
|
|
193
|
+
* sit unnoticed in a deployment that also passes options.
|
|
194
|
+
*
|
|
195
|
+
* `env` is injected (defaulting to `process.env`) so callers — and tests — can resolve against an
|
|
196
|
+
* environment they control.
|
|
197
|
+
*
|
|
198
|
+
* @example
|
|
199
|
+
* ```ts
|
|
200
|
+
* new MemoryRunEventBus(resolveMemoryBusLimits());
|
|
201
|
+
* ```
|
|
202
|
+
*/
|
|
203
|
+
declare function resolveMemoryBusLimits(explicit?: MemoryRunEventBusOptions, env?: NodeJS.ProcessEnv): ResolvedMemoryBusLimits;
|
|
204
|
+
|
|
205
|
+
/** Reads a file, or returns undefined when it is absent/unreadable. Injectable for tests. */
|
|
206
|
+
type FileReader = (path: string) => string | undefined;
|
|
207
|
+
/**
|
|
208
|
+
* The container's memory limit in bytes, or `undefined` when there isn't one to read — not
|
|
209
|
+
* containerized, a cgroup namespace that doesn't expose it, or an explicitly unlimited container.
|
|
210
|
+
*
|
|
211
|
+
* cgroup v2 writes the literal `max` when unbounded; v1 writes a huge sentinel (commonly
|
|
212
|
+
* `9223372036854771712`) rather than anything meaningful, so a value at or above the exabyte mark is
|
|
213
|
+
* treated as "no limit" too.
|
|
214
|
+
*/
|
|
215
|
+
declare function readContainerMemoryLimit(readFile?: FileReader): number | undefined;
|
|
216
|
+
interface HeapHeadroom {
|
|
217
|
+
/** V8's own ceiling for the old space, in bytes. */
|
|
218
|
+
heapLimitBytes: number;
|
|
219
|
+
/** The container's limit, when one could be read. */
|
|
220
|
+
containerLimitBytes: number | undefined;
|
|
221
|
+
/** A warning to log, or `undefined` when the sizing is fine (or unknowable). */
|
|
222
|
+
warning: string | undefined;
|
|
223
|
+
}
|
|
224
|
+
/**
|
|
225
|
+
* Compare V8's heap ceiling against the container's memory limit.
|
|
226
|
+
*
|
|
227
|
+
* Warns when the ceiling exceeds {@link HEAP_LIMIT_WARN_FRACTION} of the limit: at that point V8 is
|
|
228
|
+
* willing to grow into memory the container does not have, and the process dies by OOM kill rather than
|
|
229
|
+
* by a heap-out-of-memory error it could report. The remedy is `--max-old-space-size`, which is why the
|
|
230
|
+
* warning names it with a computed value rather than telling the operator to go and read something.
|
|
231
|
+
*
|
|
232
|
+
* Silent when no container limit is readable: guessing on a bare host would warn on every dev machine.
|
|
233
|
+
*/
|
|
234
|
+
declare function describeHeapHeadroom(heapLimitBytes: number, containerLimitBytes: number | undefined): HeapHeadroom;
|
|
235
|
+
/**
|
|
236
|
+
* Read both limits and report the mis-sizing, if any. Call once at boot.
|
|
237
|
+
*
|
|
238
|
+
* `heapStatistics` and `readFile` are injected so this is testable without a container and without
|
|
239
|
+
* mutating the real process's heap.
|
|
240
|
+
*/
|
|
241
|
+
declare function checkHeapHeadroom(options?: {
|
|
242
|
+
heapStatistics?: () => {
|
|
243
|
+
heap_size_limit: number;
|
|
244
|
+
};
|
|
245
|
+
readFile?: FileReader;
|
|
246
|
+
}): HeapHeadroom;
|
|
247
|
+
|
|
248
|
+
/** Percent of the heap limit at which to warn. */
|
|
249
|
+
declare const DEFAULT_HEAP_WARN_PERCENT = 85;
|
|
250
|
+
/**
|
|
251
|
+
* How far below the warn threshold usage must fall before another warning can fire.
|
|
252
|
+
*
|
|
253
|
+
* Hysteresis, not a fixed floor: a process hovering at exactly the threshold would otherwise warn, drop a
|
|
254
|
+
* megabyte, warn again, and produce the per-sample noise the latch exists to prevent. Derived from the
|
|
255
|
+
* threshold rather than hardcoded because the threshold is operator-settable — a fixed 70% band with
|
|
256
|
+
* `SKEIN_HEAP_WARN_PERCENT=60` would re-arm on the very samples that trip the warning, turning the latch
|
|
257
|
+
* into exactly the flood it exists to prevent.
|
|
258
|
+
*
|
|
259
|
+
* Wider than the GC sawtooth: measured in `node:22-slim`, a busy process swings ~12–15 points between
|
|
260
|
+
* collections, so a narrower band would warn once per cycle on a healthy instance.
|
|
261
|
+
*/
|
|
262
|
+
declare const HEAP_REARM_MARGIN_PERCENT = 15;
|
|
263
|
+
/** The default re-arm point, for docs and tests: 85% warn − 15 margin. */
|
|
264
|
+
declare const HEAP_REARM_PERCENT: number;
|
|
265
|
+
/** How often to sample. Long enough to cost nothing, short enough to catch an episode. */
|
|
266
|
+
declare const DEFAULT_HEAP_SAMPLE_MS = 30000;
|
|
267
|
+
/** Extra context gathered at warn time — whatever the host can cheaply answer. */
|
|
268
|
+
interface HeapPressureContext {
|
|
269
|
+
/** Runs executing on this instance right now. */
|
|
270
|
+
inFlightRuns?: number;
|
|
271
|
+
/** Frames the in-memory event bus is holding, when that bus is in use. */
|
|
272
|
+
bufferedFrames?: number;
|
|
273
|
+
}
|
|
274
|
+
/** Whatever the injected scheduler returns; only ever passed back to the injected clearer. */
|
|
275
|
+
type IntervalHandle = {
|
|
276
|
+
unref?: () => void;
|
|
277
|
+
};
|
|
278
|
+
interface HeapPressureMonitorOptions {
|
|
279
|
+
/** Where the warning goes. No logger → the monitor does nothing at all. */
|
|
280
|
+
logger?: Logger;
|
|
281
|
+
/** Percent of the heap limit at which to warn. `0` disables the monitor. */
|
|
282
|
+
warnPercent?: number;
|
|
283
|
+
/** Sampling interval in ms. */
|
|
284
|
+
sampleMs?: number;
|
|
285
|
+
/** Called at warn time only, so gathering context costs nothing on a healthy process. */
|
|
286
|
+
context?: () => HeapPressureContext;
|
|
287
|
+
/** Injected for tests. */
|
|
288
|
+
heapStatistics?: () => {
|
|
289
|
+
heap_size_limit: number;
|
|
290
|
+
used_heap_size: number;
|
|
291
|
+
};
|
|
292
|
+
/** Injected for tests. */
|
|
293
|
+
rss?: () => number;
|
|
294
|
+
/**
|
|
295
|
+
* Injected for tests. Typed loosely on purpose: the handle only ever travels from here to
|
|
296
|
+
* `clearInterval` below, so a real `Timeout` and a fake `{ unref }` both fit.
|
|
297
|
+
*/
|
|
298
|
+
setInterval?: (callback: () => void, ms: number) => IntervalHandle;
|
|
299
|
+
clearInterval?: (handle: IntervalHandle) => void;
|
|
300
|
+
}
|
|
301
|
+
interface HeapPressureMonitor {
|
|
302
|
+
/** Stop sampling. Idempotent. */
|
|
303
|
+
stop(): void;
|
|
304
|
+
}
|
|
305
|
+
/**
|
|
306
|
+
* Start watching heap usage. Returns a handle to stop it; call that where the run worker is stopped.
|
|
307
|
+
*
|
|
308
|
+
* The interval is `unref`'d, so it can never hold the event loop open through shutdown — an embedded
|
|
309
|
+
* host with no force-exit timer of its own would otherwise experience a clean shutdown as a hang.
|
|
310
|
+
*
|
|
311
|
+
* Off is a supported configuration: no logger, or `warnPercent: 0`, and nothing is scheduled.
|
|
312
|
+
*/
|
|
313
|
+
declare function startHeapPressureMonitor(options?: HeapPressureMonitorOptions): HeapPressureMonitor;
|
|
314
|
+
/**
|
|
315
|
+
* Resolve the monitor's tuning from the environment, following the same rule as the other knobs:
|
|
316
|
+
* explicit wins, but the environment is read *and validated* either way, so a typo fails at boot
|
|
317
|
+
* rather than sitting unnoticed in a deployment.
|
|
318
|
+
*
|
|
319
|
+
* `SKEIN_HEAP_WARN_PERCENT` accepts `0` to disable, which is why it cannot use
|
|
320
|
+
* `positiveIntegerFromEnv`.
|
|
321
|
+
*/
|
|
322
|
+
declare function resolveHeapPressureOptions(explicit?: {
|
|
323
|
+
warnPercent?: number;
|
|
324
|
+
sampleMs?: number;
|
|
325
|
+
}, env?: NodeJS.ProcessEnv): {
|
|
326
|
+
warnPercent: number;
|
|
327
|
+
sampleMs: number;
|
|
328
|
+
};
|
|
329
|
+
|
|
330
|
+
/**
|
|
331
|
+
* The one precedence chain for the page bound: an explicit `maxPageSize` store option wins, else
|
|
332
|
+
* `SKEIN_MAX_PAGE_SIZE`, else {@link DEFAULT_MAX_PAGE_SIZE}. The environment is read and validated even
|
|
333
|
+
* when `explicit` is given, so a bad value can't sit unnoticed in a deployment that also passes it.
|
|
334
|
+
*
|
|
335
|
+
* Raising this is the escape hatch for a deployment that genuinely needs bigger pages; it is a
|
|
336
|
+
* *memory* setting, not a correctness one — the wire schemas independently cap a client-supplied
|
|
337
|
+
* `limit` at {@link DEFAULT_MAX_PAGE_SIZE}, so raising it only widens what an absent limit means and
|
|
338
|
+
* what an in-process caller may ask for.
|
|
339
|
+
*
|
|
340
|
+
* `env` is injected (defaulting to `process.env`) so callers — and tests — can resolve against an
|
|
341
|
+
* environment they control.
|
|
342
|
+
*/
|
|
343
|
+
declare function resolveMaxPageSize(explicit?: number, env?: NodeJS.ProcessEnv): number;
|
|
344
|
+
|
|
345
|
+
/**
|
|
346
|
+
* The one precedence chain for the cron tick interval: an explicit `scheduler.tickMs` wins, else
|
|
347
|
+
* `SKEIN_CRON_TICK_MS`, else {@link DEFAULT_CRON_TICK_MS}. The environment is read and validated even
|
|
348
|
+
* when `explicit` is given, so a bad value cannot sit unnoticed in a deployment that also passes the
|
|
349
|
+
* option.
|
|
350
|
+
*
|
|
351
|
+
* Lowering this does not make schedules more accurate below one minute — a 5-field cron expression
|
|
352
|
+
* cannot express anything finer. Raising it trades lateness for fewer reads; the practical ceiling is
|
|
353
|
+
* one minute, past which a `* * * * *` cron visibly skips minutes.
|
|
354
|
+
*
|
|
355
|
+
* `env` is injected (defaulting to `process.env`) so callers — and tests — can resolve against an
|
|
356
|
+
* environment they control.
|
|
357
|
+
*/
|
|
358
|
+
declare function resolveCronTickMs(explicit?: number, env?: NodeJS.ProcessEnv): number;
|
|
359
|
+
|
|
163
360
|
/**
|
|
164
361
|
* The one precedence chain for background-run concurrency: an explicit value (a `worker.maxConcurrency`
|
|
165
362
|
* option, or the CLI's `--concurrency` / `-n`) wins, else `SKEIN_RUN_CONCURRENCY`, else
|
|
@@ -171,6 +368,32 @@ declare function describeError(thrown: unknown): string;
|
|
|
171
368
|
* environment they control.
|
|
172
369
|
*/
|
|
173
370
|
declare function resolveRunConcurrency(explicit?: number, env?: NodeJS.ProcessEnv): number;
|
|
371
|
+
/**
|
|
372
|
+
* A warning when the background worker can execute more runs at once than the Postgres pool has
|
|
373
|
+
* connections to serve them — or `undefined` when the two are sized sensibly.
|
|
374
|
+
*
|
|
375
|
+
* Each executing run holds a connection for its checkpoint writes, so `runConcurrency > poolMax` means
|
|
376
|
+
* runs queue on the pool rather than on the queue. That is not an error and not a deadlock, but it is
|
|
377
|
+
* invisible: throughput flattens, `PG_CONNECTION_TIMEOUT_MS` starts firing under load, and nothing in
|
|
378
|
+
* the logs points at the pool. Cheaper to say so once at boot.
|
|
379
|
+
*
|
|
380
|
+
* `poolMax` is `undefined` when `PG_POOL_MAX` is unset, in which case `pg`'s own default (10) applies —
|
|
381
|
+
* which is exactly the case worth warning about, since {@link DEFAULT_RUN_CONCURRENCY} is also 10 and a
|
|
382
|
+
* raised concurrency then silently outgrows a pool nobody chose.
|
|
383
|
+
*/
|
|
384
|
+
declare function describePoolPressure(runConcurrency: number, poolMax: number | undefined): string | undefined;
|
|
385
|
+
|
|
386
|
+
/**
|
|
387
|
+
* The one precedence chain for the run timeout: an explicit value (the CLI's `--run-timeout`, or a
|
|
388
|
+
* `runTimeoutMs` on the deps) wins, else `SKEIN_RUN_TIMEOUT_MS`, else **unset** — no timeout.
|
|
389
|
+
*
|
|
390
|
+
* The environment is read and validated even when `explicit` is given, so a typo can't sit unnoticed in
|
|
391
|
+
* a deployment that also passes the option.
|
|
392
|
+
*
|
|
393
|
+
* `env` is injected (defaulting to `process.env`) so callers — and tests — can resolve against an
|
|
394
|
+
* environment they control.
|
|
395
|
+
*/
|
|
396
|
+
declare function resolveRunTimeoutMs(explicit?: number, env?: NodeJS.ProcessEnv): number | undefined;
|
|
174
397
|
|
|
175
398
|
/**
|
|
176
399
|
* The one precedence chain for the shutdown drain window: an explicit `worker.shutdownGraceMs` wins,
|
|
@@ -186,28 +409,13 @@ declare function resolveRunConcurrency(explicit?: number, env?: NodeJS.ProcessEn
|
|
|
186
409
|
*/
|
|
187
410
|
declare function resolveShutdownGraceMs(explicit?: number, env?: NodeJS.ProcessEnv): number;
|
|
188
411
|
|
|
189
|
-
/** The checkpoint tuple `[checkpoint, metadata, parentId?]` with the blobs base64-encoded. */
|
|
190
|
-
type SerializedCheckpointTuple = [string, string, string | undefined];
|
|
191
|
-
/** `MemorySaver.storage` (thread → namespace → checkpointId → tuple) with blobs base64-encoded. */
|
|
192
|
-
type SerializedCheckpointStorage = Record<string, Record<string, Record<string, SerializedCheckpointTuple>>>;
|
|
193
|
-
/** `MemorySaver.writes` (key → taskId+idx → `[taskId, channel, blob]`) with the blob base64-encoded. */
|
|
194
|
-
type SerializedCheckpointWrites = Record<string, Record<string, [string, string, string]>>;
|
|
195
|
-
interface CheckpointerSnapshot {
|
|
196
|
-
storage: SerializedCheckpointStorage;
|
|
197
|
-
writes: SerializedCheckpointWrites;
|
|
198
|
-
}
|
|
199
|
-
/** A JSON-serializable snapshot of the whole in-memory dev runtime. */
|
|
200
|
-
interface DevStateSnapshot {
|
|
201
|
-
version: 1;
|
|
202
|
-
store: MemoryStoreSnapshot;
|
|
203
|
-
checkpoints: CheckpointerSnapshot;
|
|
204
|
-
}
|
|
205
|
-
|
|
206
412
|
interface InMemoryRuntimeConfig {
|
|
207
413
|
/** In-memory `ProtocolDeps` (store, queue, bus, checkpointer) around the config's graphs. */
|
|
208
414
|
deps: ProtocolDeps;
|
|
209
415
|
/** CORS mapped from the config's `http.cors`, or `undefined` when none is declared. */
|
|
210
416
|
cors?: CorsOptions;
|
|
417
|
+
/** The route table to mount, with any `http.disable_*` groups already removed. */
|
|
418
|
+
routes: readonly RouteBinding[];
|
|
211
419
|
}
|
|
212
420
|
/** Load `langgraph.json`, wiring fresh in-memory drivers and reading its `http.cors` for the adapter. */
|
|
213
421
|
declare function loadInMemoryRuntime(configPath: string, importModule?: ModuleImporter, staticSchemas?: Record<string, GraphSchemas>): Promise<InMemoryRuntimeConfig>;
|
|
@@ -293,29 +501,8 @@ declare function embedInMemoryGraphs(graphs: GraphResolver | Record<string, Embe
|
|
|
293
501
|
*/
|
|
294
502
|
declare const createInMemoryDeps: typeof embedInMemoryGraphs;
|
|
295
503
|
|
|
296
|
-
/**
|
|
297
|
-
|
|
298
|
-
* Returns `null` when the directory holds none of the expected files (nothing to import).
|
|
299
|
-
*/
|
|
300
|
-
declare function readLanggraphDevState(langgraphApiDir: string): Promise<DevStateSnapshot | null>;
|
|
301
|
-
/** Row/checkpoint counts in a snapshot, for CLI + log summaries. */
|
|
302
|
-
interface DevStateCounts {
|
|
303
|
-
assistants: number;
|
|
304
|
-
threads: number;
|
|
305
|
-
runs: number;
|
|
306
|
-
items: number;
|
|
307
|
-
/** Threads that carry graph checkpoint history. */
|
|
308
|
-
checkpointedThreads: number;
|
|
309
|
-
}
|
|
310
|
-
declare function describeSnapshot(snapshot: DevStateSnapshot): DevStateCounts;
|
|
311
|
-
/**
|
|
312
|
-
* Load a `DevStateSnapshot` into a live store + checkpointer — the sink for importing into a real
|
|
313
|
-
* skein deployment (e.g. Postgres). Resource rows go through the driver's `restore` (ids +
|
|
314
|
-
* timestamps preserved, `ON CONFLICT DO NOTHING` so re-runs are safe); checkpoints — graph state +
|
|
315
|
-
* full history — are copied via the public checkpointer API. Throws if the store can't bulk-restore
|
|
316
|
-
* (both first-party drivers can); a custom driver must implement `restore` to be an import target.
|
|
317
|
-
*/
|
|
318
|
-
declare function loadSnapshotIntoStore(snapshot: DevStateSnapshot, store: SkeinStore, checkpointer: BaseCheckpointSaver): Promise<void>;
|
|
504
|
+
/** The matcher for `routes`, compiled on first use and reused thereafter. */
|
|
505
|
+
declare function routeMatcherFor(routes: readonly RouteBinding[]): RouteMatcher;
|
|
319
506
|
|
|
320
507
|
/** The `http.cors` block of a langgraph.json — LangGraph's field names (snake_case). */
|
|
321
508
|
interface LanggraphCorsConfig {
|
|
@@ -331,6 +518,19 @@ interface LanggraphCorsConfig {
|
|
|
331
518
|
declare function toCorsOptions(config: LanggraphCorsConfig): CorsOptions;
|
|
332
519
|
/** Read `http.cors` from a langgraph.json `http` block, mapped to `CorsOptions`, or `undefined`. */
|
|
333
520
|
declare function corsFromHttpConfig(http: unknown): CorsOptions | undefined;
|
|
521
|
+
/**
|
|
522
|
+
* Read the `http.disable_*` route toggles from a langgraph.json `http` block.
|
|
523
|
+
*
|
|
524
|
+
* Only literal `true` disables a group: LangGraph's schema defaults each flag to `false`, and a
|
|
525
|
+
* truthy-but-not-true value (a `"false"` string from an env-substituted config) must not silently
|
|
526
|
+
* remove a resource.
|
|
527
|
+
*/
|
|
528
|
+
declare function disabledRoutesFromHttpConfig(http: unknown): DisabledRouteGroups;
|
|
529
|
+
/**
|
|
530
|
+
* The route table a server should mount given a langgraph.json `http` block — the full table when
|
|
531
|
+
* nothing is disabled (the same array, not a copy).
|
|
532
|
+
*/
|
|
533
|
+
declare function routesFromHttpConfig(http: unknown): readonly RouteBinding[];
|
|
334
534
|
|
|
335
535
|
type CorsSetting = true | CorsOptions;
|
|
336
536
|
/**
|
|
@@ -369,4 +569,84 @@ declare function sendNodeError(error: unknown, res: ServerResponse, logger?: Log
|
|
|
369
569
|
*/
|
|
370
570
|
declare function stripBasePath(pathname: string, basePath: string): string | null;
|
|
371
571
|
|
|
372
|
-
|
|
572
|
+
/**
|
|
573
|
+
* Memory values that runtimes can report honestly. Missing values are unavailable, not zero.
|
|
574
|
+
*
|
|
575
|
+
* No heap *limit* here on purpose: no runtime reports one through this seam, and an optional field
|
|
576
|
+
* nothing populates reads to a caller as "unavailable" when the truth is that
|
|
577
|
+
* `node:v8`'s `getHeapStatistics()` answers on all three (see `resolve-runtime.ts`). A field that is
|
|
578
|
+
* always undefined is how the heap-pressure monitor came to be silently disabled on Bun and Deno.
|
|
579
|
+
*/
|
|
580
|
+
interface RuntimeMemorySnapshot {
|
|
581
|
+
rssBytes?: number;
|
|
582
|
+
heapUsedBytes?: number;
|
|
583
|
+
nativeHeapBytes?: number;
|
|
584
|
+
}
|
|
585
|
+
interface RuntimeSignalSubscription {
|
|
586
|
+
dispose(): void;
|
|
587
|
+
}
|
|
588
|
+
/** The small platform seam used by runtime-neutral production launchers and diagnostics. */
|
|
589
|
+
interface RuntimeCapabilities {
|
|
590
|
+
name: "node" | "bun" | "deno";
|
|
591
|
+
version: string;
|
|
592
|
+
env: {
|
|
593
|
+
get(name: string): string | undefined;
|
|
594
|
+
set(name: string, value: string): void;
|
|
595
|
+
};
|
|
596
|
+
clock: {
|
|
597
|
+
nowEpochMs(): number;
|
|
598
|
+
nowMonotonicMs(): number;
|
|
599
|
+
};
|
|
600
|
+
memory: {
|
|
601
|
+
read(): RuntimeMemorySnapshot;
|
|
602
|
+
};
|
|
603
|
+
signals: {
|
|
604
|
+
on(signal: "SIGINT" | "SIGTERM", listener: () => void): RuntimeSignalSubscription;
|
|
605
|
+
};
|
|
606
|
+
exit(code: number): never;
|
|
607
|
+
}
|
|
608
|
+
interface ProcessLike {
|
|
609
|
+
version: string;
|
|
610
|
+
env: Record<string, string | undefined>;
|
|
611
|
+
memoryUsage(): {
|
|
612
|
+
rss: number;
|
|
613
|
+
heapUsed: number;
|
|
614
|
+
};
|
|
615
|
+
on(signal: string, listener: () => void): void;
|
|
616
|
+
off(signal: string, listener: () => void): void;
|
|
617
|
+
exit(code: number): never;
|
|
618
|
+
}
|
|
619
|
+
interface BunLike {
|
|
620
|
+
version: string;
|
|
621
|
+
env: Record<string, string | undefined>;
|
|
622
|
+
memoryUsage?(): {
|
|
623
|
+
rss?: number;
|
|
624
|
+
heapUsed?: number;
|
|
625
|
+
current?: number;
|
|
626
|
+
};
|
|
627
|
+
}
|
|
628
|
+
interface DenoLike {
|
|
629
|
+
version: {
|
|
630
|
+
deno: string;
|
|
631
|
+
};
|
|
632
|
+
env: {
|
|
633
|
+
get(name: string): string | undefined;
|
|
634
|
+
set(name: string, value: string): void;
|
|
635
|
+
};
|
|
636
|
+
memoryUsage(): {
|
|
637
|
+
rss: number;
|
|
638
|
+
heapUsed: number;
|
|
639
|
+
};
|
|
640
|
+
addSignalListener(signal: "SIGINT" | "SIGTERM", listener: () => void): void;
|
|
641
|
+
removeSignalListener(signal: "SIGINT" | "SIGTERM", listener: () => void): void;
|
|
642
|
+
exit(code: number): never;
|
|
643
|
+
}
|
|
644
|
+
type RuntimeGlobal = typeof globalThis & {
|
|
645
|
+
process?: ProcessLike;
|
|
646
|
+
Bun?: BunLike;
|
|
647
|
+
Deno?: DenoLike;
|
|
648
|
+
};
|
|
649
|
+
/** Detect Node, Bun, or Deno without importing a runtime-specific module. */
|
|
650
|
+
declare function detectRuntimeCapabilities(scope?: RuntimeGlobal): RuntimeCapabilities;
|
|
651
|
+
|
|
652
|
+
export { type ConsoleLogLevel, type ConsoleLoggerOptions, type CorsSetting, DEFAULT_HEAP_SAMPLE_MS, DEFAULT_HEAP_WARN_PERCENT, DevStateSnapshot, type EmbeddableGraph, type FileReader, HEAP_REARM_MARGIN_PERCENT, HEAP_REARM_PERCENT, type HeapHeadroom, type HeapPressureContext, type HeapPressureMonitor, type HeapPressureMonitorOptions, type InMemoryRuntimeConfig, type IntervalHandle, type LanggraphCorsConfig, type ReloadableInMemoryRuntime, type ResolvedMemoryBusLimits, type ResolvedProtocolRuntime, type ResolvedRuntimeDeps, type RuntimeCapabilities, type RuntimeMemorySnapshot, type RuntimeSignalSubscription, type SkeinRuntimeCommonOptions, type SkeinRuntimeOptions, allowedOrigin, applyNodeCors, checkHeapHeadroom, corsFromHttpConfig, corsPreflightHeaders, corsResponseHeaders, createConsoleLogger, createInMemoryDeps, describeError, describeHeapHeadroom, describePoolPressure, detectRuntimeCapabilities, disabledRoutesFromHttpConfig, embedInMemoryGraphs, formatLogMeta, graphMapToResolver, joinList, loadInMemoryRuntime, loadReloadableInMemoryRuntime, normalizeEmbeddableGraphs, readContainerMemoryLimit, resolveCronTickMs, resolveHeapPressureOptions, resolveMaxPageSize, resolveMemoryBusLimits, resolveProtocolRuntime, resolveRunConcurrency, resolveRunTimeoutMs, resolveRuntimeDeps, resolveShutdownGraceMs, routeMatcherFor, routesFromHttpConfig, runFailureIdentity, sendNodeError, sendNodePreflight, sendNodeResponse, startHeapPressureMonitor, stripBasePath, toCorsOptions };
|