@tangle-network/cli-agent-registry 0.0.0-stage → 0.14.0

package/dist/session-contract-BC75JdnA.d.mts

@@ -0,0 +1,131 @@
+//#region src/session-contract.d.ts
+/**
+ * The harness session contract: what every registered harness promises about
+ * its native session, so one capture path and one reader cover all of them.
+ *
+ * A harness always persists a native session. Its store sits at a declared
+ * place under the execution's private runtime HOME, the sidecar knows the
+ * session id for each execution before the turn's evidence is needed, and the
+ * served model, usage and ending error can be read back from what it wrote.
+ * A harness that cannot promise this cannot be registered.
+ *
+ * Data and pure functions only: this module is imported by the Worker-safe
+ * `/specs` entry, so it must not import Node built-ins.
+ *
+ * The format ids and store shape mirror `@tangle-network/harness-sessions`,
+ * which owns the readers. Where that package is installed, the registry test
+ * fails when the two lists of format ids drift.
+ */
+declare const SESSION_FORMAT_IDS: readonly ["claude-code.projects-jsonl", "codex.rollout-jsonl", "opencode.sqlite", "pi.session-jsonl", "kimi.session-dir", "factory.session-jsonl", "gemini.chat-json", "amp.thread-json", "forge.sqlite", "hermes.state-sqlite", "prime.session-jsonl", "openclaw.session-jsonl", "sidecar.message-json", "sidecar.session-json"];
+type SessionFormatId = (typeof SESSION_FORMAT_IDS)[number];
+interface NativeSessionStore {
+  /**
+   * Relative to the execution's private runtime HOME. Normalized, with no
+   * `..`; never absolute and never in the workspace.
+   */
+  root: string;
+  /** Globs under root that hold one session. `{id}` is the native session id. */
+  files: readonly string[];
+  /** How the harness writes. This decides how a copy is taken while it runs. */
+  write: "jsonl-append" | "json-rewrite" | "sqlite-wal";
+  /** True when one store holds every session in the HOME (opencode.db). Readers select by id. */
+  shared: boolean;
+  format: SessionFormatId;
+}
+type NativeSessionIdentity = /** The sidecar mints the id and records it before it spawns the CLI. */{
+  kind: "pre-minted";
+  args: readonly string[];
+} /** The id comes from an API call that precedes the first prompt. */ | {
+  kind: "api-created";
+  call: "opencode POST /session" | "acp session/new" | "codex thread/start" | "amp threads new";
+}
+/**
+ * Only for a CLI that cannot accept an id: the id is the first event's.
+ * Past the deadline the attempt fails with `native_session_id_unobserved`.
+ */
+| {
+  kind: "first-event";
+  event: string;
+  deadlineMs: number;
+};
+interface HarnessSessionEvidence {
+  servedModel: "provider-response" | "session-record" | "turn-context";
+  usage: "per-response" | "cumulative" | "session-total";
+  endingError: "session-record" | "none";
+}
+interface HarnessSessionContract {
+  version: 1;
+  stores: readonly [NativeSessionStore, ...NativeSessionStore[]];
+  identity: NativeSessionIdentity;
+  resume: {
+    kind: "args";
+    args: readonly string[];
+  } | {
+    kind: "api";
+  };
+  /**
+   * Argv tokens that disable or redirect persistence. Refused in config
+   * extraFlags, in profile flags and in the built argv. A token also matches
+   * its `--flag=value` form.
+   */
+  forbiddenArgs: readonly string[];
+  /**
+   * Env names, and flags such as `--session-dir`, that move the store, each
+   * mapped to the only path it may take, relative to the runtime HOME.
+   */
+  storeEnv: Readonly<Record<string, string>>;
+  evidence: HarnessSessionEvidence;
+  /** The pinned CLI version (infra/nix) that the conformance receipt covers. */
+  cliVersion: string;
+}
+type HarnessSessionContractErrorCode = "harness_session_contract_missing" | "harness_session_persistence_disabled" | "harness_conformance_missing" | "native_session_id_unobserved";
+declare class HarnessSessionContractError extends Error {
+  readonly code: HarnessSessionContractErrorCode;
+  constructor(code: HarnessSessionContractErrorCode, message: string);
+}
+/** Replace `{id}` in each token. */
+declare function substituteNativeSessionId(tokens: readonly string[], nativeSessionId: string): string[];
+/** The forbidden tokens present in `argv`, in argv order. */
+declare function forbiddenArgViolations(contract: Pick<HarnessSessionContract, "forbiddenArgs">, argv: readonly string[]): string[];
+/**
+ * Refuse flags that disable persistence. Called on configured flags before a
+ * turn can start, and on the built argv before spawn.
+ */
+declare function assertFlagsHonourSessionContract(harness: string, contract: Pick<HarnessSessionContract, "forbiddenArgs">, flags: readonly string[], source: string): void;
+/**
+ * Check the argv the adapter built: no forbidden token, and, for a
+ * pre-minted identity on a new session, the identity args carrying the
+ * minted id.
+ */
+declare function assertArgvHonoursSessionContract(harness: string, contract: HarnessSessionContract, argv: readonly string[], session: {
+  mintedId?: string;
+}): void;
+/** Normalize a POSIX path; `..` that escapes the start is kept as a leading `..`. */
+declare function normalizePosixPath(path: string): string;
+/**
+ * Refuse a store location the contract does not declare. Each env value (or
+ * flag value, for keys that start with `--`) must resolve to exactly
+ * HOME/<declared path>; relative flag values resolve against `cwd`.
+ */
+declare function assertStoreLocationHonoursSessionContract(harness: string, contract: Pick<HarnessSessionContract, "storeEnv">, input: {
+  runtimeHome: string;
+  cwd: string;
+  env?: Readonly<Record<string, string | undefined>>;
+  argv?: readonly string[];
+}): void;
+/**
+ * A matcher for one store glob. `**` matches any number of path segments
+ * (including none), `*` matches within one segment, and `{id}` is the native
+ * session id (any id when omitted).
+ */
+declare function compileSessionStoreGlob(glob: string, nativeSessionId?: string): RegExp;
+/**
+ * The declared store that holds `pathFromHome` for this session, or
+ * undefined. A shared store's files belong to every session.
+ */
+declare function sessionStoreForPath(contract: Pick<HarnessSessionContract, "stores">, pathFromHome: string, nativeSessionId: string): NativeSessionStore | undefined;
+/** Structural checks every declared contract must pass. */
+declare function sessionContractProblems(contract: HarnessSessionContract): string[];
+//#endregion
+export { substituteNativeSessionId as _, NativeSessionIdentity as a, SessionFormatId as c, assertStoreLocationHonoursSessionContract as d, compileSessionStoreGlob as f, sessionStoreForPath as g, sessionContractProblems as h, HarnessSessionEvidence as i, assertArgvHonoursSessionContract as l, normalizePosixPath as m, HarnessSessionContractError as n, NativeSessionStore as o, forbiddenArgViolations as p, HarnessSessionContractErrorCode as r, SESSION_FORMAT_IDS as s, HarnessSessionContract as t, assertFlagsHonourSessionContract as u };
+//# sourceMappingURL=session-contract-BC75JdnA.d.mts.map

package/dist/session-contract.d.mts

@@ -0,0 +1,2 @@
+import { _ as substituteNativeSessionId, a as NativeSessionIdentity, c as SessionFormatId, d as assertStoreLocationHonoursSessionContract, f as compileSessionStoreGlob, g as sessionStoreForPath, h as sessionContractProblems, i as HarnessSessionEvidence, l as assertArgvHonoursSessionContract, m as normalizePosixPath, n as HarnessSessionContractError, o as NativeSessionStore, p as forbiddenArgViolations, r as HarnessSessionContractErrorCode, s as SESSION_FORMAT_IDS, t as HarnessSessionContract, u as assertFlagsHonourSessionContract } from "./session-contract-BC75JdnA.mjs";
+export { HarnessSessionContract, HarnessSessionContractError, HarnessSessionContractErrorCode, HarnessSessionEvidence, NativeSessionIdentity, NativeSessionStore, SESSION_FORMAT_IDS, SessionFormatId, assertArgvHonoursSessionContract, assertFlagsHonourSessionContract, assertStoreLocationHonoursSessionContract, compileSessionStoreGlob, forbiddenArgViolations, normalizePosixPath, sessionContractProblems, sessionStoreForPath, substituteNativeSessionId };

package/dist/session-contract.mjs

@@ -0,0 +1,190 @@
+//#region src/session-contract.ts
+/**
+* The harness session contract: what every registered harness promises about
+* its native session, so one capture path and one reader cover all of them.
+*
+* A harness always persists a native session. Its store sits at a declared
+* place under the execution's private runtime HOME, the sidecar knows the
+* session id for each execution before the turn's evidence is needed, and the
+* served model, usage and ending error can be read back from what it wrote.
+* A harness that cannot promise this cannot be registered.
+*
+* Data and pure functions only: this module is imported by the Worker-safe
+* `/specs` entry, so it must not import Node built-ins.
+*
+* The format ids and store shape mirror `@tangle-network/harness-sessions`,
+* which owns the readers. Where that package is installed, the registry test
+* fails when the two lists of format ids drift.
+*/
+const SESSION_FORMAT_IDS = [
+	"claude-code.projects-jsonl",
+	"codex.rollout-jsonl",
+	"opencode.sqlite",
+	"pi.session-jsonl",
+	"kimi.session-dir",
+	"factory.session-jsonl",
+	"gemini.chat-json",
+	"amp.thread-json",
+	"forge.sqlite",
+	"hermes.state-sqlite",
+	"prime.session-jsonl",
+	"openclaw.session-jsonl",
+	"sidecar.message-json",
+	"sidecar.session-json"
+];
+var HarnessSessionContractError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(`${code}: ${message}`);
+		this.name = "HarnessSessionContractError";
+		this.code = code;
+	}
+};
+/** Replace `{id}` in each token. */
+function substituteNativeSessionId(tokens, nativeSessionId) {
+	return tokens.map((token) => token.split("{id}").join(nativeSessionId));
+}
+function matchesForbidden(token, forbidden) {
+	return token === forbidden || token.startsWith(`${forbidden}=`);
+}
+/** The forbidden tokens present in `argv`, in argv order. */
+function forbiddenArgViolations(contract, argv) {
+	return argv.filter((token) => contract.forbiddenArgs.some((forbidden) => matchesForbidden(token, forbidden)));
+}
+function indexOfSequence(haystack, needle) {
+	if (needle.length === 0) return 0;
+	for (let index = 0; index + needle.length <= haystack.length; index++) if (needle.every((token, offset) => haystack[index + offset] === token)) return index;
+	return -1;
+}
+/**
+* Refuse flags that disable persistence. Called on configured flags before a
+* turn can start, and on the built argv before spawn.
+*/
+function assertFlagsHonourSessionContract(harness, contract, flags, source) {
+	const violations = forbiddenArgViolations(contract, flags);
+	if (violations.length > 0) throw new HarnessSessionContractError("harness_session_persistence_disabled", `${harness} ${source} carries ${violations.join(", ")}, which disables or redirects its native session`);
+}
+/**
+* Check the argv the adapter built: no forbidden token, and, for a
+* pre-minted identity on a new session, the identity args carrying the
+* minted id.
+*/
+function assertArgvHonoursSessionContract(harness, contract, argv, session) {
+	assertFlagsHonourSessionContract(harness, contract, argv, "argv");
+	if (session.mintedId === void 0) return;
+	if (contract.identity.kind !== "pre-minted") throw new HarnessSessionContractError("harness_session_persistence_disabled", `${harness} was given a minted session id but its identity is ${contract.identity.kind}`);
+	if (indexOfSequence(argv, substituteNativeSessionId(contract.identity.args, session.mintedId)) < 0) throw new HarnessSessionContractError("harness_session_persistence_disabled", `${harness} argv does not carry its pre-minted session id (${contract.identity.args.join(" ")})`);
+}
+/** Normalize a POSIX path; `..` that escapes the start is kept as a leading `..`. */
+function normalizePosixPath(path) {
+	const absolute = path.startsWith("/");
+	const parts = [];
+	for (const part of path.split("/")) {
+		if (part === "" || part === ".") continue;
+		if (part === "..") {
+			if (parts.length > 0 && parts[parts.length - 1] !== "..") parts.pop();
+			else if (!absolute) parts.push("..");
+			continue;
+		}
+		parts.push(part);
+	}
+	const joined = parts.join("/");
+	return absolute ? `/${joined}` : joined || ".";
+}
+function resolvePosix(base, value) {
+	return normalizePosixPath(value.startsWith("/") ? value : `${base.replace(/\/+$/u, "")}/${value}`);
+}
+/**
+* Refuse a store location the contract does not declare. Each env value (or
+* flag value, for keys that start with `--`) must resolve to exactly
+* HOME/<declared path>; relative flag values resolve against `cwd`.
+*/
+function assertStoreLocationHonoursSessionContract(harness, contract, input) {
+	const home = normalizePosixPath(input.runtimeHome);
+	const violations = [];
+	for (const [name, declared] of Object.entries(contract.storeEnv)) {
+		const expected = resolvePosix(home, declared);
+		const values = [];
+		if (name.startsWith("--")) {
+			const argv = input.argv ?? [];
+			for (let index = 0; index < argv.length; index++) {
+				const token = argv[index];
+				if (token === name && index + 1 < argv.length) values.push(argv[index + 1]);
+				else if (token.startsWith(`${name}=`)) values.push(token.slice(name.length + 1));
+			}
+		} else {
+			const value = input.env?.[name];
+			if (value !== void 0 && value !== "") values.push(value);
+		}
+		for (const value of values) if (resolvePosix(input.cwd, value) !== expected) violations.push(`${name}=${value} (declared ${expected})`);
+	}
+	if (violations.length > 0) throw new HarnessSessionContractError("harness_session_persistence_disabled", `${harness} moves its native session store outside the declared location: ${violations.join("; ")}`);
+}
+function escapeRegExp(text) {
+	return text.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+/**
+* A matcher for one store glob. `**` matches any number of path segments
+* (including none), `*` matches within one segment, and `{id}` is the native
+* session id (any id when omitted).
+*/
+function compileSessionStoreGlob(glob, nativeSessionId) {
+	let pattern = "";
+	for (let index = 0; index < glob.length;) if (glob.startsWith("**/", index)) {
+		pattern += "(?:[^/]+/)*";
+		index += 3;
+	} else if (glob.startsWith("**", index)) {
+		pattern += ".*";
+		index += 2;
+	} else if (glob.startsWith("{id}", index)) {
+		pattern += nativeSessionId === void 0 ? "[^/]+" : escapeRegExp(nativeSessionId);
+		index += 4;
+	} else if (glob[index] === "*") {
+		pattern += "[^/]*";
+		index += 1;
+	} else {
+		pattern += escapeRegExp(glob[index]);
+		index += 1;
+	}
+	return new RegExp(`^${pattern}$`, "u");
+}
+/**
+* The declared store that holds `pathFromHome` for this session, or
+* undefined. A shared store's files belong to every session.
+*/
+function sessionStoreForPath(contract, pathFromHome, nativeSessionId) {
+	const path = normalizePosixPath(pathFromHome);
+	for (const store of contract.stores) {
+		const root = normalizePosixPath(store.root);
+		if (!path.startsWith(`${root}/`)) continue;
+		const rest = path.slice(root.length + 1);
+		const id = store.shared ? void 0 : nativeSessionId;
+		if (store.files.some((glob) => compileSessionStoreGlob(glob, id).test(rest))) return store;
+	}
+}
+/** Structural checks every declared contract must pass. */
+function sessionContractProblems(contract) {
+	const problems = [];
+	if (contract.version !== 1) problems.push("version must be 1");
+	if (!contract.cliVersion.trim()) problems.push("cliVersion is empty");
+	for (const store of contract.stores) {
+		const root = normalizePosixPath(store.root);
+		if (store.root.startsWith("/") || root.startsWith("..") || root === ".") problems.push(`store root ${store.root} is not a relative path under HOME`);
+		if (root !== store.root) problems.push(`store root ${store.root} is not normalized`);
+		if (!SESSION_FORMAT_IDS.includes(store.format)) problems.push(`store format ${store.format} is unknown`);
+		if (store.files.length === 0) problems.push(`store ${store.root} declares no files`);
+		if (!store.shared && !store.files.every((glob) => glob.includes("{id}"))) problems.push(`store ${store.root} is per-session but a glob lacks {id}`);
+	}
+	if (contract.identity.kind === "pre-minted" && !contract.identity.args.some((token) => token.includes("{id}"))) problems.push("pre-minted identity args lack {id}");
+	if (contract.resume.kind === "args" && !contract.resume.args.some((token) => token.includes("{id}"))) problems.push("resume args lack {id}");
+	if (contract.identity.kind === "first-event" && !(contract.identity.deadlineMs > 0)) problems.push("first-event identity needs a positive deadline");
+	for (const [name, declared] of Object.entries(contract.storeEnv)) {
+		const normalized = normalizePosixPath(declared);
+		if (declared.startsWith("/") || normalized.startsWith("..")) problems.push(`storeEnv ${name} must name a path under HOME`);
+	}
+	return problems;
+}
+//#endregion
+export { HarnessSessionContractError, SESSION_FORMAT_IDS, assertArgvHonoursSessionContract, assertFlagsHonourSessionContract, assertStoreLocationHonoursSessionContract, compileSessionStoreGlob, forbiddenArgViolations, normalizePosixPath, sessionContractProblems, sessionStoreForPath, substituteNativeSessionId };
+
+//# sourceMappingURL=session-contract.mjs.map