@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.1

package/dist/packages/provenance.js

@@ -0,0 +1,147 @@
+import { readCapped } from "./npm.js";
+/** The predicate type of an SLSA v1 provenance statement. */
+export const SLSA_PROVENANCE_V1 = "https://slsa.dev/provenance/v1";
+/** Attestation answers are a few KB; anything far larger is not one. */
+const MAX_ATTESTATION_BYTES = 1024 * 1024;
+/** Provenance must not hold up an import: a slow registry gives "not checked". */
+export const PROVENANCE_TIMEOUT_MS = 15_000;
+const NPM_NAME_RE = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
+const SEMVER_RE = /^[0-9A-Za-z.+-]{1,256}$/;
+const COMMIT_RE = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/;
+const notChecked = (reason) => ({ checked: false, reason });
+const errMsg = (e) => (e instanceof Error ? e.message : String(e));
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const str = (v) => typeof v === "string" && v.length > 0 && v.length <= 2048 ? v : undefined;
+/** The hex sha512 of a `sha512-<base64>` integrity (undefined for anything else). */
+function sha512Hex(integrity) {
+    for (const part of integrity.trim().split(/\s+/)) {
+        const m = /^sha512-([A-Za-z0-9+/]+={0,2})$/.exec(part);
+        if (m) {
+            const b = Buffer.from(m[1], "base64");
+            if (b.length === 64)
+                return b.toString("hex");
+        }
+    }
+    return undefined;
+}
+/**
+ * Reads the SLSA provenance of `name@version` from the configured registry. `integrity` (the
+ * tarball's `sha512-…`, when known) must be among the statement's subject digests, so a statement
+ * about another tarball is not shown. Never throws (an aborted `signal` included).
+ */
+export async function fetchProvenance(cfg, name, version, signal, opts = {}) {
+    if (!NPM_NAME_RE.test(name) || name.length > 214 || !SEMVER_RE.test(version)) {
+        return notChecked("not a valid npm package name and version");
+    }
+    let body;
+    try {
+        const registry = new URL(cfg.registry.endsWith("/") ? cfg.registry : `${cfg.registry}/`);
+        // the npm client's escaping: a scoped name's `/` is %2f
+        const url = new URL(`-/npm/v1/attestations/${name.replace("/", "%2f")}@${encodeURIComponent(version)}`, registry);
+        const res = await fetch(url, {
+            headers: {
+                accept: "application/json",
+                ...(cfg.token !== undefined && { authorization: `Bearer ${cfg.token}` }),
+            },
+            redirect: "manual",
+            signal,
+        });
+        if (res.status === 404) {
+            await res.body?.cancel().catch(() => { });
+            return notChecked("the registry has no provenance for this version");
+        }
+        if (!res.ok) {
+            await res.body?.cancel().catch(() => { });
+            return notChecked(`the registry answered HTTP ${res.status} for the attestations`);
+        }
+        const raw = await readCapped(res, MAX_ATTESTATION_BYTES, () => new Error("the attestations are too large"));
+        body = JSON.parse(raw.toString("utf8"));
+    }
+    catch (e) {
+        if (signal.aborted)
+            return notChecked("the registry did not answer in time");
+        return notChecked(`cannot read the attestations: ${errMsg(e)}`);
+    }
+    try {
+        return parseAttestations(body, opts.integrity);
+    }
+    catch (e) {
+        return notChecked(`cannot read the attestations: ${errMsg(e)}`);
+    }
+}
+/**
+ * Parses an attestations answer (`{ attestations: [{ predicateType, bundle: { dsseEnvelope } }] }`).
+ * Exported for tests.
+ */
+export function parseAttestations(body, integrity) {
+    if (!isObject(body) || !Array.isArray(body.attestations)) {
+        return notChecked("the attestations answer is not in the npm format");
+    }
+    const att = body.attestations.find((a) => isObject(a) && a.predicateType === SLSA_PROVENANCE_V1);
+    if (!att)
+        return notChecked("the registry has no SLSA provenance for this version");
+    const env = isObject(att.bundle) ? att.bundle.dsseEnvelope : undefined;
+    if (!isObject(env) || typeof env.payload !== "string") {
+        return notChecked("the provenance has no DSSE envelope");
+    }
+    if (env.payloadType !== "application/vnd.in-toto+json") {
+        return notChecked("the provenance is not an in-toto statement");
+    }
+    let stmt;
+    try {
+        stmt = JSON.parse(Buffer.from(env.payload, "base64").toString("utf8"));
+    }
+    catch {
+        return notChecked("the provenance statement is not valid JSON");
+    }
+    if (!isObject(stmt) || stmt.predicateType !== SLSA_PROVENANCE_V1 || !isObject(stmt.predicate)) {
+        return notChecked("the provenance statement is not SLSA provenance v1");
+    }
+    if (integrity !== undefined) {
+        const want = sha512Hex(integrity);
+        const subjects = Array.isArray(stmt.subject) ? stmt.subject : [];
+        const matches = subjects.some((s) => isObject(s) && isObject(s.digest) && s.digest.sha512 === want);
+        if (want === undefined || !matches) {
+            return notChecked("the provenance is about another tarball than the one downloaded");
+        }
+    }
+    const def = stmt.predicate.buildDefinition;
+    if (!isObject(def))
+        return notChecked("the provenance has no build definition");
+    const workflow = isObject(def.externalParameters) ? def.externalParameters.workflow : undefined;
+    const repository = isObject(workflow) ? str(workflow.repository) : undefined;
+    const path = isObject(workflow) ? str(workflow.path) : undefined;
+    const deps = Array.isArray(def.resolvedDependencies) ? def.resolvedDependencies : [];
+    const first = deps[0];
+    const commit = isObject(first) && isObject(first.digest) ? str(first.digest.gitCommit) : undefined;
+    const buildType = str(def.buildType);
+    if (repository === undefined)
+        return notChecked("the provenance names no repository");
+    if (path === undefined)
+        return notChecked("the provenance names no workflow");
+    if (commit === undefined || !COMMIT_RE.test(commit)) {
+        return notChecked("the provenance names no git commit");
+    }
+    if (buildType === undefined)
+        return notChecked("the provenance names no build type");
+    return { checked: true, repository, commit, workflow: path, buildType };
+}
+/** A repository URL compared case-insensitively, without `git+`, `.git` and a trailing `/`. */
+function repoKey(url) {
+    const s = url
+        .trim()
+        .replace(/^git\+/, "")
+        .replace(/\/+$/, "")
+        .replace(/\.git$/, "");
+    try {
+        const u = new URL(s);
+        return `${u.host}${u.pathname}`.toLowerCase().replace(/\/+$/, "");
+    }
+    catch {
+        return s.toLowerCase();
+    }
+}
+/** Two repository URLs name the same repository (scheme, `git+`, `.git`, case ignored). */
+export function sameRepository(a, b) {
+    return repoKey(a) === repoKey(b);
+}

package/dist/packages/tgz.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Unpacking a package tgz (npm pack layout, every entry under `package/`) and reading its
+ * `package.json`, shared by the plugin package reader (`catalog/plugin-package.ts`) and the
+ * extension package reader (`extensions/package.ts`). The tgz is always hostile input:
+ *
+ * - at most `maxBytes` compressed (the caller passes `packages.maxBytes`); `zlib.gunzip`'s
+ *   `maxOutputLength` caps the **actual** unpacked bytes ({@link PACKAGE_TGZ_LIMITS}.maxUnpackedBytes),
+ *   stopping decompression bombs. The package and its content are handled in memory.
+ * - the tar is parsed with tar-stream (3.2.2, pinned): in memory only, never the file system (unlike
+ *   node-tar's extract, with its history of path traversal / symlink CVEs), header checksums checked,
+ *   pax / GNU long names handled; it only hands over raw headers and every decision is made here.
+ * - only regular files and directories: symlinks, hard links, devices, fifos are refused; at most
+ *   {@link PACKAGE_TGZ_LIMITS}.maxEntries entries; paths under `package/` and safe (plugin-sdk
+ *   `isSafePackagePath`: no `..`, `.`, empty segments, backslashes, control characters, drive
+ *   letters), deduplicated case-insensitively (they would overwrite each other on a case-insensitive
+ *   file system); no `node_modules/`, `*.node`, `binding.gyp`.
+ * - `package.json` at most {@link PACKAGE_TGZ_LIMITS}.maxPackageJsonBytes, strict UTF-8 +
+ *   `JSON.parse`.
+ *
+ * Problems throw {@link PackageTgzError}; each reader maps it to its own error.
+ */
+/** Limits on unpacking and on `package.json`. */
+export declare const PACKAGE_TGZ_LIMITS: {
+    /** Total unpacked tar bytes. */
+    readonly maxUnpackedBytes: number;
+    /** Tar entries (directories included). */
+    readonly maxEntries: 5000;
+    /** Bytes of `package.json`. */
+    readonly maxPackageJsonBytes: number;
+};
+/**
+ * The host's zod version (a plugin package's `peerDependencies.zod` must be satisfied by it: the
+ * plugin uses this zod when loaded). Resolved from the kernel's own dependencies, the same package
+ * `syncPackage` links for extensions.
+ */
+export declare const HOST_ZOD_VERSION: string;
+/** The message for a tgz in the pre-0.1.0 format (follows the package's name). */
+export declare const LEGACY_FORMAT_MESSAGE = "uses the pre-0.1.0 package format (capybara section / app.yaml); repack it as a plugin with .capybara-plugin/plugin.json (pnpm pack-plugin)";
+/** `./skills/x` → `skills/x` (manifest paths start with `./`). */
+export declare const packagePath: (p: string) => string;
+/** A tgz or `package.json` problem; `issues` lists them (English, shown to the admin). */
+export declare class PackageTgzError extends Error {
+    readonly issues: string[];
+    constructor(issues: string[]);
+}
+/** Unpack limits: `maxBytes` is `packages.maxBytes`; the rest default to {@link PACKAGE_TGZ_LIMITS}. */
+export interface PackageTgzLimits {
+    maxBytes: number;
+    maxUnpackedBytes?: number;
+    maxEntries?: number;
+}
+/** A file in the tgz (path relative to the package root, `package/` removed). */
+export interface PackageFile {
+    path: string;
+    data: Buffer;
+}
+/**
+ * Unpacks a tgz by the rules in the file header, without looking at the content. Invalid ->
+ * {@link PackageTgzError}.
+ */
+export declare function unpackPackageTgz(bytes: Uint8Array, limits: PackageTgzLimits): Promise<PackageFile[]>;
+/**
+ * Reads the package's `package.json`: it must exist, be at most
+ * {@link PACKAGE_TGZ_LIMITS}.maxPackageJsonBytes and strict UTF-8 JSON. Invalid ->
+ * {@link PackageTgzError}. Returns the parse result (shape not validated).
+ */
+export declare function parsePackageJsonFile(file: {
+    data: Uint8Array;
+} | undefined): unknown;
+/**
+ * Packs files (paths relative to the package root) as an npm-pack style tgz under `package/`,
+ * deterministically: sorted paths, mode 0644, mtime 0, so the same files always give the same bytes
+ * (and the same package store key). Used for a git plugin with an extension, whose extension is
+ * stored and installed as a package like any other. The result is read back with the tgz rules.
+ */
+export declare function packPackageTgz(files: ReadonlyMap<string, Uint8Array>): Promise<Uint8Array>;

package/dist/packages/tgz.js

@@ -0,0 +1,225 @@
+import { createRequire } from "node:module";
+import { promisify } from "node:util";
+import { gunzip, gzip } from "node:zlib";
+import { isSafePackagePath } from "@capybara-hq/plugin-sdk";
+import { extract as tarExtract, pack as tarPack } from "tar-stream";
+/**
+ * Unpacking a package tgz (npm pack layout, every entry under `package/`) and reading its
+ * `package.json`, shared by the plugin package reader (`catalog/plugin-package.ts`) and the
+ * extension package reader (`extensions/package.ts`). The tgz is always hostile input:
+ *
+ * - at most `maxBytes` compressed (the caller passes `packages.maxBytes`); `zlib.gunzip`'s
+ *   `maxOutputLength` caps the **actual** unpacked bytes ({@link PACKAGE_TGZ_LIMITS}.maxUnpackedBytes),
+ *   stopping decompression bombs. The package and its content are handled in memory.
+ * - the tar is parsed with tar-stream (3.2.2, pinned): in memory only, never the file system (unlike
+ *   node-tar's extract, with its history of path traversal / symlink CVEs), header checksums checked,
+ *   pax / GNU long names handled; it only hands over raw headers and every decision is made here.
+ * - only regular files and directories: symlinks, hard links, devices, fifos are refused; at most
+ *   {@link PACKAGE_TGZ_LIMITS}.maxEntries entries; paths under `package/` and safe (plugin-sdk
+ *   `isSafePackagePath`: no `..`, `.`, empty segments, backslashes, control characters, drive
+ *   letters), deduplicated case-insensitively (they would overwrite each other on a case-insensitive
+ *   file system); no `node_modules/`, `*.node`, `binding.gyp`.
+ * - `package.json` at most {@link PACKAGE_TGZ_LIMITS}.maxPackageJsonBytes, strict UTF-8 +
+ *   `JSON.parse`.
+ *
+ * Problems throw {@link PackageTgzError}; each reader maps it to its own error.
+ */
+/** Limits on unpacking and on `package.json`. */
+export const PACKAGE_TGZ_LIMITS = {
+    /** Total unpacked tar bytes. */
+    maxUnpackedBytes: 256 * 1024 * 1024,
+    /** Tar entries (directories included). */
+    maxEntries: 5000,
+    /** Bytes of `package.json`. */
+    maxPackageJsonBytes: 1024 * 1024,
+};
+/**
+ * The host's zod version (a plugin package's `peerDependencies.zod` must be satisfied by it: the
+ * plugin uses this zod when loaded). Resolved from the kernel's own dependencies, the same package
+ * `syncPackage` links for extensions.
+ */
+export const HOST_ZOD_VERSION = createRequire(import.meta.url)("zod/package.json").version;
+/** The message for a tgz in the pre-0.1.0 format (follows the package's name). */
+export const LEGACY_FORMAT_MESSAGE = "uses the pre-0.1.0 package format (capybara section / app.yaml); repack it as a plugin with .capybara-plugin/plugin.json (pnpm pack-plugin)";
+/** `./skills/x` → `skills/x` (manifest paths start with `./`). */
+export const packagePath = (p) => p.replace(/^\.\//, "").replace(/\/+$/, "");
+/** A tgz or `package.json` problem; `issues` lists them (English, shown to the admin). */
+export class PackageTgzError extends Error {
+    issues;
+    constructor(issues) {
+        super(issues[0] ?? "unknown problem");
+        this.name = "PackageTgzError";
+        this.issues = issues;
+    }
+}
+/** The npm pack prefix of every entry. */
+const PREFIX = "package/";
+const fail = (issue) => {
+    throw new PackageTgzError([issue]);
+};
+const errMsg = (e) => (e instanceof Error ? e.message : String(e));
+const isForbiddenFile = (path) => {
+    const segs = path.split("/");
+    if (segs.includes("node_modules"))
+        return `${path}: node_modules/ is not allowed`;
+    const base = segs[segs.length - 1];
+    if (base === "binding.gyp")
+        return `${path}: binding.gyp is not allowed (native addons)`;
+    if (base.endsWith(".node"))
+        return `${path}: native addon (.node) files are not allowed`;
+    return undefined;
+};
+/** Decompresses and parses the tar and returns the files in it (with `package/` removed from paths). Anything non-conforming -> {@link PackageTgzError}. */
+async function unpack(bytes, opts) {
+    if (bytes.byteLength > opts.maxBytes) {
+        fail(`the package is larger than ${opts.maxBytes} bytes`);
+    }
+    let tarBuf;
+    try {
+        tarBuf = await promisify(gunzip)(Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength), {
+            maxOutputLength: opts.maxUnpackedBytes,
+        });
+    }
+    catch (e) {
+        if (e.code === "ERR_BUFFER_TOO_LARGE" || e instanceof RangeError) {
+            throw new PackageTgzError([
+                `the package is larger than ${opts.maxUnpackedBytes} bytes unpacked`,
+            ]);
+        }
+        throw new PackageTgzError(["the file is not a gzip-compressed tar archive"]);
+    }
+    const files = [];
+    const seen = new Set();
+    const dirs = new Set();
+    let entries = 0;
+    const ex = tarExtract();
+    ex.end(tarBuf);
+    try {
+        for await (const entry of ex) {
+            const h = entry.header;
+            entries++;
+            if (entries > opts.maxEntries)
+                fail(`the package has more than ${opts.maxEntries} entries`);
+            const raw = String(h.name);
+            const type = h.type;
+            if (type !== "file" && type !== "directory") {
+                entry.resume();
+                fail(`${raw}: ${type ?? "unknown"} entries are not allowed (only regular files)`);
+            }
+            const name = type === "directory" && raw.endsWith("/") ? raw.slice(0, -1) : raw;
+            if (!name.startsWith(PREFIX) && name !== PREFIX.slice(0, -1)) {
+                entry.resume();
+                fail(`${raw}: every entry must be under package/`);
+            }
+            const rel = name.slice(PREFIX.length);
+            if (type === "directory") {
+                entry.resume();
+                if (rel !== "" && !isSafePackagePath(rel))
+                    fail(`${raw}: unsafe path`);
+                continue;
+            }
+            if (!isSafePackagePath(rel)) {
+                entry.resume();
+                fail(`${raw}: unsafe path`);
+            }
+            const forbidden = isForbiddenFile(rel);
+            if (forbidden) {
+                entry.resume();
+                fail(forbidden);
+            }
+            const key = rel.toLowerCase();
+            if (seen.has(key) || dirs.has(key)) {
+                entry.resume();
+                fail(`${raw}: duplicate path (paths are compared case-insensitively)`);
+            }
+            seen.add(key);
+            const segs = key.split("/");
+            for (let i = 1; i < segs.length; i++) {
+                const d = segs.slice(0, i).join("/");
+                if (seen.has(d))
+                    fail(`${raw}: path conflicts with file "${d}"`);
+                dirs.add(d);
+            }
+            const chunks = [];
+            for await (const c of entry)
+                chunks.push(c);
+            // One chunk is used as is (no copy); only several are concatenated
+            files.push({
+                path: rel,
+                data: chunks.length === 1 ? chunks[0] : Buffer.concat(chunks),
+            });
+        }
+    }
+    catch (e) {
+        ex.destroy();
+        if (e instanceof PackageTgzError)
+            throw e;
+        fail(`the tar archive is malformed: ${errMsg(e)}`);
+    }
+    return files;
+}
+const utf8 = (path, data) => {
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(data);
+    }
+    catch {
+        return fail(`${path} is not valid UTF-8 text`);
+    }
+};
+/**
+ * Unpacks a tgz by the rules in the file header, without looking at the content. Invalid ->
+ * {@link PackageTgzError}.
+ */
+export function unpackPackageTgz(bytes, limits) {
+    return unpack(bytes, {
+        maxBytes: limits.maxBytes,
+        maxUnpackedBytes: limits.maxUnpackedBytes ?? PACKAGE_TGZ_LIMITS.maxUnpackedBytes,
+        maxEntries: limits.maxEntries ?? PACKAGE_TGZ_LIMITS.maxEntries,
+    });
+}
+/**
+ * Reads the package's `package.json`: it must exist, be at most
+ * {@link PACKAGE_TGZ_LIMITS}.maxPackageJsonBytes and strict UTF-8 JSON. Invalid ->
+ * {@link PackageTgzError}. Returns the parse result (shape not validated).
+ */
+export function parsePackageJsonFile(file) {
+    if (!file)
+        return fail("package.json not found in the package");
+    if (file.data.byteLength > PACKAGE_TGZ_LIMITS.maxPackageJsonBytes) {
+        fail(`package.json is larger than ${PACKAGE_TGZ_LIMITS.maxPackageJsonBytes} bytes`);
+    }
+    const text = utf8("package.json", file.data);
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return fail("package.json is not valid JSON");
+    }
+}
+/**
+ * Packs files (paths relative to the package root) as an npm-pack style tgz under `package/`,
+ * deterministically: sorted paths, mode 0644, mtime 0, so the same files always give the same bytes
+ * (and the same package store key). Used for a git plugin with an extension, whose extension is
+ * stored and installed as a package like any other. The result is read back with the tgz rules.
+ */
+export async function packPackageTgz(files) {
+    const p = tarPack();
+    const chunks = [];
+    const done = (async () => {
+        for await (const c of p)
+            chunks.push(c);
+    })();
+    for (const path of [...files.keys()].sort()) {
+        const data = Buffer.from(files.get(path));
+        await new Promise((resolve, reject) => p.entry({
+            name: `${PREFIX}${path}`,
+            type: "file",
+            mode: 0o644,
+            mtime: new Date(0),
+            size: data.length,
+        }, data, (err) => (err ? reject(err) : resolve())));
+    }
+    p.finalize();
+    await done;
+    return new Uint8Array(await promisify(gzip)(Buffer.concat(chunks)));
+}

package/dist/runtime/abort.d.ts

@@ -0,0 +1,32 @@
+import type { ExtensionContext } from "@capybara-hq/plugin-sdk";
+import type { Redis } from "ioredis";
+/** 中止广播的内核 bus 主题。 */
+export declare const RUN_ABORT_TOPIC = "run.abort";
+/**
+ * Why the kernel stops a run, when it is not a plain stop: `wait_timeout`, a sub-agent stopped by
+ * its parent's sub-agents wait timeout. Written to `run_aborted.detail`.
+ */
+export type RunAbortDetail = "wait_timeout";
+/** Who stopped a run, and why when the kernel did. */
+export interface RunAbortBy {
+    byAccountId: string | null;
+    detail?: RunAbortDetail;
+}
+/**
+ * 跨副本中止（spec 4.3「中止信号经 Redis 广播」）：`request` 先写标记键再广播；
+ * `watch` 先订阅、再检查一次标记键，订阅之前发出的中止也不会丢。
+ */
+export declare class RunAbort {
+    private readonly redis;
+    private readonly bus;
+    constructor(redis: Redis, bus: ExtensionContext["bus"]);
+    request(runId: string, byAccountId: string | null, detail?: RunAbortDetail): Promise<void>;
+    /**
+     * Whether a stop of this run was requested (reads the marker key): who asked (and why, when the
+     * kernel did), or null. For the moments without a subscriber (a run that just suspended and is
+     * about to become `waiting`), to pick up a stop that arrived meanwhile.
+     */
+    requested(runId: string): Promise<RunAbortBy | null>;
+    /** Subscribes to stops of one run; `onAbort` is called at most once. Returns the unsubscribe. */
+    watch(runId: string, onAbort: (byAccountId: string | null, detail?: RunAbortDetail) => void): Promise<() => Promise<void>>;
+}

package/dist/runtime/abort.js

@@ -0,0 +1,71 @@
+/** 中止广播的内核 bus 主题。 */
+export const RUN_ABORT_TOPIC = "run.abort";
+/** 中止标记的保留时长（秒）。 */
+const ABORT_TTL_SECONDS = 3600;
+const abortKey = (runId) => `capk:run-abort:${runId}`;
+const detailOf = (v) => v === "wait_timeout" ? { detail: v } : {};
+const parseStored = (stored) => {
+    const m = JSON.parse(stored);
+    return {
+        byAccountId: typeof m.byAccountId === "string" ? m.byAccountId : null,
+        ...detailOf(m.detail),
+    };
+};
+/**
+ * 跨副本中止（spec 4.3「中止信号经 Redis 广播」）：`request` 先写标记键再广播；
+ * `watch` 先订阅、再检查一次标记键，订阅之前发出的中止也不会丢。
+ */
+export class RunAbort {
+    redis;
+    bus;
+    constructor(redis, bus) {
+        this.redis = redis;
+        this.bus = bus;
+    }
+    async request(runId, byAccountId, detail) {
+        const by = { byAccountId, ...(detail !== undefined && { detail }) };
+        await this.redis.set(abortKey(runId), JSON.stringify(by), "EX", ABORT_TTL_SECONDS);
+        const msg = { runId, ...by };
+        await this.bus.publish(RUN_ABORT_TOPIC, msg);
+    }
+    /**
+     * Whether a stop of this run was requested (reads the marker key): who asked (and why, when the
+     * kernel did), or null. For the moments without a subscriber (a run that just suspended and is
+     * about to become `waiting`), to pick up a stop that arrived meanwhile.
+     */
+    async requested(runId) {
+        const stored = await this.redis.get(abortKey(runId));
+        if (stored === null)
+            return null;
+        return parseStored(stored);
+    }
+    /** Subscribes to stops of one run; `onAbort` is called at most once. Returns the unsubscribe. */
+    async watch(runId, onAbort) {
+        let fired = false;
+        const fire = (by) => {
+            if (fired)
+                return;
+            fired = true;
+            onAbort(by.byAccountId, by.detail);
+        };
+        const unsubscribe = await this.bus.subscribe(RUN_ABORT_TOPIC, (payload) => {
+            const m = payload;
+            if (m?.runId === runId) {
+                fire({
+                    byAccountId: typeof m.byAccountId === "string" ? m.byAccountId : null,
+                    ...detailOf(m.detail),
+                });
+            }
+        });
+        try {
+            const stored = await this.redis.get(abortKey(runId));
+            if (stored !== null)
+                fire(parseStored(stored));
+        }
+        catch (err) {
+            await unsubscribe();
+            throw err;
+        }
+        return unsubscribe;
+    }
+}

package/dist/runtime/checkpointer.d.ts

@@ -0,0 +1,32 @@
+import type { RunnableConfig } from "@langchain/core/runnables";
+import { BaseCheckpointSaver, type ChannelVersions, type Checkpoint, type CheckpointListOptions, type CheckpointMetadata, type CheckpointTuple, type PendingWrite } from "@langchain/langgraph-checkpoint";
+import type { KernelDb } from "../db/kernel-schema.js";
+/**
+ * LangGraph checkpoint saver，存在内核 schema 的 `lg_checkpoints` / `lg_checkpoint_writes` 里（0007_checkpoints.sql）。
+ *
+ * - 每个 checkpoint 存整份（含全部 channel_values），不按 channel 增量存，所以 {@link pruneToLatest}
+ *   之后最新一份仍能独立还原。不要配合实验性的 `DeltaChannel` 使用：它依赖父链上的 writes 还原状态。
+ * - thread_id 约定为 runId。
+ * - 所有状态都在 PG 里，不持有进程内状态，任意副本都能续跑。
+ */
+export declare class KyselyCheckpointSaver extends BaseCheckpointSaver {
+    private readonly db;
+    constructor(db: KernelDb);
+    getTuple(config: RunnableConfig): Promise<CheckpointTuple | undefined>;
+    list(config: RunnableConfig, options?: CheckpointListOptions): AsyncGenerator<CheckpointTuple>;
+    put(config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata, _newVersions: ChannelVersions): Promise<RunnableConfig>;
+    putWrites(config: RunnableConfig, writes: PendingWrite[], taskId: string, taskPath?: string): Promise<void>;
+    deleteThread(threadId: string): Promise<void>;
+    /**
+     * 一轮运行结束后调用：根命名空间（`checkpoint_ns = ''`）下只保留最新一个 checkpoint 及其 writes，
+     * 更早的 checkpoint 与它们的 writes 删除。只删 checkpoint_id **小于**最新的（按字节序）：
+     * 读出最新与删除之间并发写入的更新 checkpoint 不会被误删（R20）。返回删除的 checkpoint 条数。其他命名空间（子图）不动。
+     * 保留下来的 checkpoint 的 parent_checkpoint_id 原样保留（父 checkpoint 已不存在）。
+     */
+    pruneToLatest(threadId: string): Promise<number>;
+    private toTuple;
+    /** 某个 checkpoint 的 writes，按 `writesSortKey`（task_path, task_id, idx）排序。 */
+    private loadWrites;
+    /** v < 4 的旧 checkpoint：把父 checkpoint 上的 TASKS writes 迁成本 checkpoint 的 TASKS channel（同 MemorySaver）。 */
+    private migratePendingSends;
+}