@graphorin/agent 0.5.0

package/dist/preferred-model/index.js

@@ -0,0 +1,141 @@
+//#region src/preferred-model/index.ts
+const TIER_ORDER = {
+	fast: 0,
+	balanced: 1,
+	smart: 2
+};
+function isModelHint(value) {
+	return value === "fast" || value === "balanced" || value === "smart";
+}
+function specToProvider(spec) {
+	if ("provider" in spec) return spec.provider;
+	return spec;
+}
+function modelIdFromSpec(spec) {
+	if ("provider" in spec) return spec.model;
+	return spec.modelId;
+}
+/**
+* Pick the highest-cost tier across the supplied per-tool hints.
+* Explicit `ModelSpec` entries are treated as the highest tier
+* (`'smart'`) for tie-breaking — the conservative-correctness rule
+* documented in DEC-169 / suggested ADR-057.
+*
+* Returns the picked hint together with the original `ModelSpec`
+* (when an explicit spec won the tie-break).
+*
+* @stable
+*/
+function pickTopTierAcrossTools(hints) {
+	let bestRank = -1;
+	let bestSpec;
+	let bestHint;
+	for (const h of hints) {
+		if (h === void 0) continue;
+		if (isModelHint(h)) {
+			const rank = TIER_ORDER[h];
+			if (rank > bestRank) {
+				bestRank = rank;
+				bestSpec = void 0;
+				bestHint = h;
+			}
+		} else {
+			const rank = TIER_ORDER.smart;
+			if (rank >= bestRank) {
+				bestRank = rank;
+				bestSpec = h;
+				bestHint = "smart";
+			}
+		}
+	}
+	if (bestHint === void 0) return void 0;
+	if (bestSpec !== void 0) return {
+		hint: bestHint,
+		spec: bestSpec
+	};
+	return { hint: bestHint };
+}
+/**
+* Walk the precedence ladder and return the resolved provider for a
+* single agent step. Pure function — no side effects.
+*
+* @stable
+*/
+function resolvePreferredModel(input) {
+	if (input.prepareStepProvider !== void 0) return {
+		resolvedProvider: input.prepareStepProvider,
+		resolvedModelId: input.prepareStepProvider.modelId,
+		source: "prepare-step"
+	};
+	const top = pickTopTierAcrossTools(input.toolPreferredModels);
+	if (top !== void 0) {
+		if (top.spec !== void 0) return {
+			resolvedProvider: specToProvider(top.spec),
+			resolvedModelId: modelIdFromSpec(top.spec),
+			source: "spec"
+		};
+		const mapped = input.modelTierMap?.[top.hint];
+		if (mapped !== void 0) return {
+			resolvedProvider: specToProvider(mapped),
+			resolvedModelId: modelIdFromSpec(mapped),
+			source: "tier-map",
+			hintApplied: top.hint
+		};
+		const agent$1 = input.agentPreferredModel;
+		if (agent$1 !== void 0) if (isModelHint(agent$1)) {
+			const agentMapped = input.modelTierMap?.[agent$1];
+			if (agentMapped !== void 0) return {
+				resolvedProvider: specToProvider(agentMapped),
+				resolvedModelId: modelIdFromSpec(agentMapped),
+				source: "agent-preferred",
+				hintApplied: agent$1,
+				fallthroughReason: "tier-not-mapped"
+			};
+		} else return {
+			resolvedProvider: specToProvider(agent$1),
+			resolvedModelId: modelIdFromSpec(agent$1),
+			source: "agent-preferred",
+			fallthroughReason: "tier-not-mapped"
+		};
+		return {
+			resolvedProvider: input.agentDefaultProvider,
+			resolvedModelId: input.agentDefaultProvider.modelId,
+			source: "fallthrough-default",
+			hintApplied: top.hint,
+			fallthroughReason: "tier-not-mapped"
+		};
+	}
+	const agent = input.agentPreferredModel;
+	if (agent !== void 0) {
+		if (isModelHint(agent)) {
+			const mapped = input.modelTierMap?.[agent];
+			if (mapped !== void 0) return {
+				resolvedProvider: specToProvider(mapped),
+				resolvedModelId: modelIdFromSpec(mapped),
+				source: "agent-preferred",
+				hintApplied: agent
+			};
+			return {
+				resolvedProvider: input.agentDefaultProvider,
+				resolvedModelId: input.agentDefaultProvider.modelId,
+				source: "fallthrough-default",
+				hintApplied: agent,
+				fallthroughReason: "tier-not-mapped"
+			};
+		}
+		return {
+			resolvedProvider: specToProvider(agent),
+			resolvedModelId: modelIdFromSpec(agent),
+			source: "agent-preferred"
+		};
+	}
+	return {
+		resolvedProvider: input.agentDefaultProvider,
+		resolvedModelId: input.agentDefaultProvider.modelId,
+		source: "fallthrough-default"
+	};
+}
+
+//#endregion
+export { pickTopTierAcrossTools, resolvePreferredModel };
+//# sourceMappingURL=index.js.map

package/dist/preferred-model/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["TIER_ORDER: Record<ModelHint, number>","bestSpec: ModelSpec | undefined","bestHint: ModelHint | undefined","agent"],"sources":["../../src/preferred-model/index.ts"],"sourcesContent":["/**\n * Per-tool / per-agent preferred-model resolution. Pure functions\n * consulted by the agent loop AFTER the model has decided which\n * tool(s) to call but BEFORE `provider.stream(...)` is invoked.\n *\n * The four-step precedence ladder (highest wins):\n *\n *   1. `prepareStep({ provider })` — the operator's explicit per-step\n *      override always wins.\n *   2. `Tool.preferredModel`        — the tool author's per-tool hint.\n *      Only the tools the model actually CALLED on the previous step\n *      are consulted (AG-15) — an advertised-but-uncalled hint never\n *      escalates the run. Multi-tool ties resolve to the highest cost\n *      tier (`'smart' > 'balanced' > 'fast'`; explicit `ModelSpec` is\n *      treated as the highest tier).\n *   3. `Agent.preferredModel?`      — the per-agent default.\n *   4. `Agent` default `provider`   — the v0.1-alpha behaviour.\n *\n * Cost-tier resolution against `Agent.modelTierMap` is documented\n * as a hint: when the requested tier is unmapped, the resolver\n * falls through to the next precedence step rather than throwing.\n *\n * @packageDocumentation\n */\n\nimport type { ModelHint, ModelSpec, Provider } from '@graphorin/core';\n\nconst TIER_ORDER: Record<ModelHint, number> = { fast: 0, balanced: 1, smart: 2 };\n\n/**\n * Result returned by {@link resolvePreferredModel}.\n *\n * @stable\n */\nexport interface PreferredModelResolution {\n  readonly resolvedProvider: Provider;\n  readonly resolvedModelId: string;\n  readonly source: 'prepare-step' | 'tier-map' | 'spec' | 'agent-preferred' | 'fallthrough-default';\n  readonly hintApplied?: ModelHint;\n  readonly fallthroughReason?:\n    | 'tier-not-mapped'\n    | 'provider-unavailable'\n    | 'override-takes-precedence';\n}\n\n/**\n * Pure inputs to {@link resolvePreferredModel}.\n *\n * @stable\n */\nexport interface ResolvePreferredModelInput {\n  readonly prepareStepProvider?: Provider;\n  readonly toolPreferredModels: ReadonlyArray<ModelHint | ModelSpec | undefined>;\n  readonly agentPreferredModel?: ModelHint | ModelSpec;\n  readonly agentDefaultProvider: Provider;\n  readonly modelTierMap?: Partial<Record<ModelHint, ModelSpec>>;\n}\n\nfunction isModelHint(value: ModelHint | ModelSpec | undefined): value is ModelHint {\n  return value === 'fast' || value === 'balanced' || value === 'smart';\n}\n\nfunction specToProvider(spec: ModelSpec): Provider {\n  if ('provider' in spec) return spec.provider as Provider;\n  return spec as Provider;\n}\n\nfunction modelIdFromSpec(spec: ModelSpec): string {\n  if ('provider' in spec) return spec.model;\n  return (spec as Provider).modelId;\n}\n\n/**\n * Pick the highest-cost tier across the supplied per-tool hints.\n * Explicit `ModelSpec` entries are treated as the highest tier\n * (`'smart'`) for tie-breaking — the conservative-correctness rule\n * documented in DEC-169 / suggested ADR-057.\n *\n * Returns the picked hint together with the original `ModelSpec`\n * (when an explicit spec won the tie-break).\n *\n * @stable\n */\nexport function pickTopTierAcrossTools(\n  hints: ReadonlyArray<ModelHint | ModelSpec | undefined>,\n): { readonly hint: ModelHint; readonly spec?: ModelSpec } | undefined {\n  let bestRank = -1;\n  let bestSpec: ModelSpec | undefined;\n  let bestHint: ModelHint | undefined;\n  for (const h of hints) {\n    if (h === undefined) continue;\n    if (isModelHint(h)) {\n      const rank = TIER_ORDER[h];\n      if (rank > bestRank) {\n        bestRank = rank;\n        bestSpec = undefined;\n        bestHint = h;\n      }\n    } else {\n      // Explicit `ModelSpec` -> treat as the highest tier.\n      const rank = TIER_ORDER.smart;\n      if (rank >= bestRank) {\n        bestRank = rank;\n        bestSpec = h;\n        bestHint = 'smart';\n      }\n    }\n  }\n  if (bestHint === undefined) return undefined;\n  if (bestSpec !== undefined) return { hint: bestHint, spec: bestSpec };\n  return { hint: bestHint };\n}\n\n/**\n * Walk the precedence ladder and return the resolved provider for a\n * single agent step. Pure function — no side effects.\n *\n * @stable\n */\nexport function resolvePreferredModel(input: ResolvePreferredModelInput): PreferredModelResolution {\n  if (input.prepareStepProvider !== undefined) {\n    return {\n      resolvedProvider: input.prepareStepProvider,\n      resolvedModelId: input.prepareStepProvider.modelId,\n      source: 'prepare-step',\n    };\n  }\n  const top = pickTopTierAcrossTools(input.toolPreferredModels);\n  if (top !== undefined) {\n    if (top.spec !== undefined) {\n      return {\n        resolvedProvider: specToProvider(top.spec),\n        resolvedModelId: modelIdFromSpec(top.spec),\n        source: 'spec',\n      };\n    }\n    const mapped = input.modelTierMap?.[top.hint];\n    if (mapped !== undefined) {\n      return {\n        resolvedProvider: specToProvider(mapped),\n        resolvedModelId: modelIdFromSpec(mapped),\n        source: 'tier-map',\n        hintApplied: top.hint,\n      };\n    }\n    // Fall through to agent-preferred / default.\n    const agent = input.agentPreferredModel;\n    if (agent !== undefined) {\n      if (isModelHint(agent)) {\n        const agentMapped = input.modelTierMap?.[agent];\n        if (agentMapped !== undefined) {\n          return {\n            resolvedProvider: specToProvider(agentMapped),\n            resolvedModelId: modelIdFromSpec(agentMapped),\n            source: 'agent-preferred',\n            hintApplied: agent,\n            fallthroughReason: 'tier-not-mapped',\n          };\n        }\n      } else {\n        return {\n          resolvedProvider: specToProvider(agent),\n          resolvedModelId: modelIdFromSpec(agent),\n          source: 'agent-preferred',\n          fallthroughReason: 'tier-not-mapped',\n        };\n      }\n    }\n    return {\n      resolvedProvider: input.agentDefaultProvider,\n      resolvedModelId: input.agentDefaultProvider.modelId,\n      source: 'fallthrough-default',\n      hintApplied: top.hint,\n      fallthroughReason: 'tier-not-mapped',\n    };\n  }\n  // No per-tool hints. Honour `Agent.preferredModel` next.\n  const agent = input.agentPreferredModel;\n  if (agent !== undefined) {\n    if (isModelHint(agent)) {\n      const mapped = input.modelTierMap?.[agent];\n      if (mapped !== undefined) {\n        return {\n          resolvedProvider: specToProvider(mapped),\n          resolvedModelId: modelIdFromSpec(mapped),\n          source: 'agent-preferred',\n          hintApplied: agent,\n        };\n      }\n      // Agent-default tier not mapped: fall through.\n      return {\n        resolvedProvider: input.agentDefaultProvider,\n        resolvedModelId: input.agentDefaultProvider.modelId,\n        source: 'fallthrough-default',\n        hintApplied: agent,\n        fallthroughReason: 'tier-not-mapped',\n      };\n    }\n    return {\n      resolvedProvider: specToProvider(agent),\n      resolvedModelId: modelIdFromSpec(agent),\n      source: 'agent-preferred',\n    };\n  }\n  return {\n    resolvedProvider: input.agentDefaultProvider,\n    resolvedModelId: input.agentDefaultProvider.modelId,\n    source: 'fallthrough-default',\n  };\n}\n"],"mappings":";AA2BA,MAAMA,aAAwC;CAAE,MAAM;CAAG,UAAU;CAAG,OAAO;CAAG;AA+BhF,SAAS,YAAY,OAA8D;AACjF,QAAO,UAAU,UAAU,UAAU,cAAc,UAAU;;AAG/D,SAAS,eAAe,MAA2B;AACjD,KAAI,cAAc,KAAM,QAAO,KAAK;AACpC,QAAO;;AAGT,SAAS,gBAAgB,MAAyB;AAChD,KAAI,cAAc,KAAM,QAAO,KAAK;AACpC,QAAQ,KAAkB;;;;;;;;;;;;;AAc5B,SAAgB,uBACd,OACqE;CACrE,IAAI,WAAW;CACf,IAAIC;CACJ,IAAIC;AACJ,MAAK,MAAM,KAAK,OAAO;AACrB,MAAI,MAAM,OAAW;AACrB,MAAI,YAAY,EAAE,EAAE;GAClB,MAAM,OAAO,WAAW;AACxB,OAAI,OAAO,UAAU;AACnB,eAAW;AACX,eAAW;AACX,eAAW;;SAER;GAEL,MAAM,OAAO,WAAW;AACxB,OAAI,QAAQ,UAAU;AACpB,eAAW;AACX,eAAW;AACX,eAAW;;;;AAIjB,KAAI,aAAa,OAAW,QAAO;AACnC,KAAI,aAAa,OAAW,QAAO;EAAE,MAAM;EAAU,MAAM;EAAU;AACrE,QAAO,EAAE,MAAM,UAAU;;;;;;;;AAS3B,SAAgB,sBAAsB,OAA6D;AACjG,KAAI,MAAM,wBAAwB,OAChC,QAAO;EACL,kBAAkB,MAAM;EACxB,iBAAiB,MAAM,oBAAoB;EAC3C,QAAQ;EACT;CAEH,MAAM,MAAM,uBAAuB,MAAM,oBAAoB;AAC7D,KAAI,QAAQ,QAAW;AACrB,MAAI,IAAI,SAAS,OACf,QAAO;GACL,kBAAkB,eAAe,IAAI,KAAK;GAC1C,iBAAiB,gBAAgB,IAAI,KAAK;GAC1C,QAAQ;GACT;EAEH,MAAM,SAAS,MAAM,eAAe,IAAI;AACxC,MAAI,WAAW,OACb,QAAO;GACL,kBAAkB,eAAe,OAAO;GACxC,iBAAiB,gBAAgB,OAAO;GACxC,QAAQ;GACR,aAAa,IAAI;GAClB;EAGH,MAAMC,UAAQ,MAAM;AACpB,MAAIA,YAAU,OACZ,KAAI,YAAYA,QAAM,EAAE;GACtB,MAAM,cAAc,MAAM,eAAeA;AACzC,OAAI,gBAAgB,OAClB,QAAO;IACL,kBAAkB,eAAe,YAAY;IAC7C,iBAAiB,gBAAgB,YAAY;IAC7C,QAAQ;IACR,aAAaA;IACb,mBAAmB;IACpB;QAGH,QAAO;GACL,kBAAkB,eAAeA,QAAM;GACvC,iBAAiB,gBAAgBA,QAAM;GACvC,QAAQ;GACR,mBAAmB;GACpB;AAGL,SAAO;GACL,kBAAkB,MAAM;GACxB,iBAAiB,MAAM,qBAAqB;GAC5C,QAAQ;GACR,aAAa,IAAI;GACjB,mBAAmB;GACpB;;CAGH,MAAM,QAAQ,MAAM;AACpB,KAAI,UAAU,QAAW;AACvB,MAAI,YAAY,MAAM,EAAE;GACtB,MAAM,SAAS,MAAM,eAAe;AACpC,OAAI,WAAW,OACb,QAAO;IACL,kBAAkB,eAAe,OAAO;IACxC,iBAAiB,gBAAgB,OAAO;IACxC,QAAQ;IACR,aAAa;IACd;AAGH,UAAO;IACL,kBAAkB,MAAM;IACxB,iBAAiB,MAAM,qBAAqB;IAC5C,QAAQ;IACR,aAAa;IACb,mBAAmB;IACpB;;AAEH,SAAO;GACL,kBAAkB,eAAe,MAAM;GACvC,iBAAiB,gBAAgB,MAAM;GACvC,QAAQ;GACT;;AAEH,QAAO;EACL,kBAAkB,MAAM;EACxB,iBAAiB,MAAM,qBAAqB;EAC5C,QAAQ;EACT"}

package/dist/progress/index.d.ts

@@ -0,0 +1,62 @@
+import { ProgressArtifactRef, Sensitivity } from "@graphorin/core";
+
+//#region src/progress/index.d.ts
+
+/**
+ * Optional configuration accepted by {@link createProgressIO}.
+ *
+ * @stable
+ */
+interface ProgressIOConfig {
+  /** Filesystem root under which `<runId>/progress/<role>.<seq>.txt` files live. */
+  readonly artifactRoot?: string;
+  /** Default `Sensitivity` applied when the caller does not override. */
+  readonly defaultSensitivity?: Sensitivity;
+  /** Optional redaction transform applied to content before write. */
+  readonly redact?: (content: string) => string;
+}
+/**
+ * Per-call options for {@link ProgressIO.write}.
+ *
+ * @stable
+ */
+interface ProgressWriteOptions {
+  readonly role?: string;
+  /** Explicit sequence number; default auto-increments per `(runId, role)`. */
+  readonly seq?: number;
+  readonly sensitivity?: Sensitivity;
+  readonly tags?: ReadonlyArray<string>;
+}
+/**
+ * Per-call options for {@link ProgressIO.read}.
+ *
+ * @stable
+ */
+interface ProgressReadOptions {
+  readonly runId?: string;
+  readonly role?: string;
+  /** Skip artifacts whose `seq <= sinceSeq`. */
+  readonly sinceSeq?: number;
+  /** Default `100`. */
+  readonly maxArtifacts?: number;
+}
+/**
+ * Public surface returned by {@link createProgressIO}. Used by the
+ * agent runtime to back `agent.progress.write / read`.
+ *
+ * @stable
+ */
+interface ProgressIO {
+  write(runId: string, content: string, options?: ProgressWriteOptions): Promise<ProgressArtifactRef>;
+  read(currentRunId: string, options?: ProgressReadOptions): Promise<ReadonlyArray<ProgressArtifactRef>>;
+  rootFor(runId: string): string;
+}
+/**
+ * Build a {@link ProgressIO} bound to a particular artifact root.
+ *
+ * @stable
+ */
+declare function createProgressIO(config?: ProgressIOConfig): ProgressIO;
+//#endregion
+export { ProgressIO, ProgressIOConfig, ProgressReadOptions, ProgressWriteOptions, createProgressIO };
+//# sourceMappingURL=index.d.ts.map

package/dist/progress/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/progress/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;UAoCiB,gBAAA;;;;gCAIe;;;;;;;;;UAUf,oBAAA;;;;yBAIQ;kBACP;;;;;;;UAQD,mBAAA;;;;;;;;;;;;;;UAeA,UAAA;kDAIH,uBACT,QAAQ;uCAGC,sBACT,QAAQ,cAAc;;;;;;;;iBAkBX,gBAAA,UAAyB,mBAAwB"}

package/dist/progress/index.js

@@ -0,0 +1,150 @@
+import { ProgressWriteError } from "../errors/index.js";
+import { createHash } from "node:crypto";
+import { mkdir, readFile, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+//#region src/progress/index.ts
+/**
+* Structured progress-artifact IO. Persists UTF-8 text artifacts
+* under `<artifactRoot>/<runId>/progress/<role>.<seqPadded>.txt`
+* via atomic-write `.tmp + rename` discipline.
+*
+* Cross-session continuity flow:
+*
+* 1. The current agent calls `agent.progress.write(content)` —
+*    runtime persists the file and queues the
+*    `agent.progress.written` event (drained into the active or
+*    next consumed stream).
+* 2. A sibling / future agent calls
+*    `agent.progress.read({ runId: priorRunId })` — runtime
+*    discovers existing files (no implicit auto-discovery; the
+*    operator must supply the `runId` cursor).
+*
+* Auto-discovery across runs is deferred to v0.2.
+*
+* @packageDocumentation
+*/
+const DEFAULT_ARTIFACT_DIR = "graphorin-progress";
+const SEQ_PAD_WIDTH = 3;
+const seqWidth = (n) => String(n).padStart(SEQ_PAD_WIDTH, "0");
+const sha256Hex = (input) => createHash("sha256").update(input, "utf8").digest("hex");
+/**
+* Build a {@link ProgressIO} bound to a particular artifact root.
+*
+* @stable
+*/
+function createProgressIO(config = {}) {
+	const root = config.artifactRoot ?? join(tmpdir(), DEFAULT_ARTIFACT_DIR);
+	const defaultSensitivity = config.defaultSensitivity ?? "internal";
+	const redact = config.redact ?? ((s) => s);
+	const seqState = /* @__PURE__ */ new Map();
+	const directoryFor = (runId) => join(root, runId, "progress");
+	const seqKey = (runId, role) => `${runId}::${role}`;
+	const ensureSeqState = async (runId, role) => {
+		const key = seqKey(runId, role);
+		let state = seqState.get(key);
+		if (state !== void 0) return state;
+		state = { next: 1 };
+		try {
+			const entries = await readdir(directoryFor(runId));
+			let max = 0;
+			const prefix = `${role}.`;
+			for (const entry of entries) {
+				if (!entry.startsWith(prefix) || !entry.endsWith(".txt")) continue;
+				const seqStr = entry.slice(prefix.length, entry.length - 4);
+				const n = Number(seqStr);
+				if (Number.isFinite(n) && n > max) max = n;
+			}
+			state.next = max + 1;
+		} catch {}
+		seqState.set(key, state);
+		return state;
+	};
+	const write = async (runId, rawContent, options = {}) => {
+		const role = options.role ?? "agent";
+		const sensitivity = options.sensitivity ?? defaultSensitivity;
+		const tags = options.tags ?? [];
+		const seqSource = await ensureSeqState(runId, role);
+		const seq = options.seq ?? seqSource.next;
+		seqSource.next = Math.max(seqSource.next, seq + 1);
+		const content = redact(rawContent);
+		const dir = directoryFor(runId);
+		const finalPath = join(dir, `${role}.${seqWidth(seq)}.txt`);
+		const tmpPath = `${finalPath}.tmp`;
+		try {
+			await mkdir(dir, { recursive: true });
+			await writeFile(tmpPath, content, { encoding: "utf8" });
+			await rename(tmpPath, finalPath);
+		} catch (cause) {
+			try {
+				await unlink(tmpPath);
+			} catch {}
+			throw new ProgressWriteError(finalPath, cause);
+		}
+		const stats = await stat(finalPath);
+		const sha256 = sha256Hex(content);
+		return {
+			path: finalPath,
+			role,
+			seq,
+			sizeBytes: stats.size,
+			sensitivity,
+			...tags.length > 0 ? { tags } : {},
+			writtenAtIso: (/* @__PURE__ */ new Date()).toISOString(),
+			sha256
+		};
+	};
+	const read = async (currentRunId, options = {}) => {
+		const runId = options.runId ?? currentRunId;
+		const max = options.maxArtifacts ?? 100;
+		const sinceSeq = options.sinceSeq ?? 0;
+		const dir = directoryFor(runId);
+		let entries;
+		try {
+			entries = await readdir(dir);
+		} catch {
+			return [];
+		}
+		const out = [];
+		const role = options.role;
+		for (const entry of entries) {
+			if (!entry.endsWith(".txt")) continue;
+			const dot = entry.indexOf(".");
+			if (dot < 0) continue;
+			const entryRole = entry.slice(0, dot);
+			const seqStr = entry.slice(dot + 1, entry.length - 4);
+			const seq = Number(seqStr);
+			if (!Number.isFinite(seq)) continue;
+			if (role !== void 0 && entryRole !== role) continue;
+			if (seq <= sinceSeq) continue;
+			const fullPath = join(dir, entry);
+			const stats = await stat(fullPath);
+			const sha256 = sha256Hex(await readFile(fullPath, { encoding: "utf8" }));
+			out.push({
+				path: fullPath,
+				role: entryRole,
+				seq,
+				sizeBytes: stats.size,
+				sensitivity: "internal",
+				writtenAtIso: stats.mtime.toISOString(),
+				sha256
+			});
+			if (out.length >= max) break;
+		}
+		out.sort((a, b) => {
+			if (a.role !== b.role) return a.role.localeCompare(b.role);
+			return a.seq - b.seq;
+		});
+		return out;
+	};
+	return {
+		write,
+		read,
+		rootFor: (runId) => directoryFor(runId)
+	};
+}
+
+//#endregion
+export { createProgressIO };
+//# sourceMappingURL=index.js.map

package/dist/progress/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["defaultSensitivity: Sensitivity","redact: (s: string) => string","entries: string[]","out: ProgressArtifactRef[]"],"sources":["../../src/progress/index.ts"],"sourcesContent":["/**\n * Structured progress-artifact IO. Persists UTF-8 text artifacts\n * under `<artifactRoot>/<runId>/progress/<role>.<seqPadded>.txt`\n * via atomic-write `.tmp + rename` discipline.\n *\n * Cross-session continuity flow:\n *\n * 1. The current agent calls `agent.progress.write(content)` —\n *    runtime persists the file and queues the\n *    `agent.progress.written` event (drained into the active or\n *    next consumed stream).\n * 2. A sibling / future agent calls\n *    `agent.progress.read({ runId: priorRunId })` — runtime\n *    discovers existing files (no implicit auto-discovery; the\n *    operator must supply the `runId` cursor).\n *\n * Auto-discovery across runs is deferred to v0.2.\n *\n * @packageDocumentation\n */\n\nimport { createHash } from 'node:crypto';\nimport { mkdir, readdir, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';\nimport { tmpdir } from 'node:os';\nimport { join } from 'node:path';\nimport type { ProgressArtifactRef, Sensitivity } from '@graphorin/core';\nimport { ProgressWriteError } from '../errors/index.js';\n\nconst DEFAULT_ARTIFACT_DIR = 'graphorin-progress';\nconst SEQ_PAD_WIDTH = 3;\n\n/**\n * Optional configuration accepted by {@link createProgressIO}.\n *\n * @stable\n */\nexport interface ProgressIOConfig {\n  /** Filesystem root under which `<runId>/progress/<role>.<seq>.txt` files live. */\n  readonly artifactRoot?: string;\n  /** Default `Sensitivity` applied when the caller does not override. */\n  readonly defaultSensitivity?: Sensitivity;\n  /** Optional redaction transform applied to content before write. */\n  readonly redact?: (content: string) => string;\n}\n\n/**\n * Per-call options for {@link ProgressIO.write}.\n *\n * @stable\n */\nexport interface ProgressWriteOptions {\n  readonly role?: string;\n  /** Explicit sequence number; default auto-increments per `(runId, role)`. */\n  readonly seq?: number;\n  readonly sensitivity?: Sensitivity;\n  readonly tags?: ReadonlyArray<string>;\n}\n\n/**\n * Per-call options for {@link ProgressIO.read}.\n *\n * @stable\n */\nexport interface ProgressReadOptions {\n  readonly runId?: string;\n  readonly role?: string;\n  /** Skip artifacts whose `seq <= sinceSeq`. */\n  readonly sinceSeq?: number;\n  /** Default `100`. */\n  readonly maxArtifacts?: number;\n}\n\n/**\n * Public surface returned by {@link createProgressIO}. Used by the\n * agent runtime to back `agent.progress.write / read`.\n *\n * @stable\n */\nexport interface ProgressIO {\n  write(\n    runId: string,\n    content: string,\n    options?: ProgressWriteOptions,\n  ): Promise<ProgressArtifactRef>;\n  read(\n    currentRunId: string,\n    options?: ProgressReadOptions,\n  ): Promise<ReadonlyArray<ProgressArtifactRef>>;\n  rootFor(runId: string): string;\n}\n\ninterface InternalSeqState {\n  next: number;\n}\n\nconst seqWidth = (n: number): string => String(n).padStart(SEQ_PAD_WIDTH, '0');\n\nconst sha256Hex = (input: string): string =>\n  createHash('sha256').update(input, 'utf8').digest('hex');\n\n/**\n * Build a {@link ProgressIO} bound to a particular artifact root.\n *\n * @stable\n */\nexport function createProgressIO(config: ProgressIOConfig = {}): ProgressIO {\n  const root = config.artifactRoot ?? join(tmpdir(), DEFAULT_ARTIFACT_DIR);\n  const defaultSensitivity: Sensitivity = config.defaultSensitivity ?? 'internal';\n  const redact: (s: string) => string = config.redact ?? ((s) => s);\n  const seqState = new Map<string, InternalSeqState>();\n\n  const directoryFor = (runId: string): string => join(root, runId, 'progress');\n\n  const seqKey = (runId: string, role: string): string => `${runId}::${role}`;\n\n  const ensureSeqState = async (runId: string, role: string): Promise<InternalSeqState> => {\n    const key = seqKey(runId, role);\n    let state = seqState.get(key);\n    if (state !== undefined) return state;\n    state = { next: 1 };\n    try {\n      const dir = directoryFor(runId);\n      const entries = await readdir(dir);\n      let max = 0;\n      const prefix = `${role}.`;\n      for (const entry of entries) {\n        if (!entry.startsWith(prefix) || !entry.endsWith('.txt')) continue;\n        const seqStr = entry.slice(prefix.length, entry.length - 4);\n        const n = Number(seqStr);\n        if (Number.isFinite(n) && n > max) max = n;\n      }\n      state.next = max + 1;\n    } catch {\n      // Directory does not exist yet — first write will create it.\n    }\n    seqState.set(key, state);\n    return state;\n  };\n\n  const write = async (\n    runId: string,\n    rawContent: string,\n    options: ProgressWriteOptions = {},\n  ): Promise<ProgressArtifactRef> => {\n    const role = options.role ?? 'agent';\n    const sensitivity = options.sensitivity ?? defaultSensitivity;\n    const tags = options.tags ?? [];\n    const seqSource = await ensureSeqState(runId, role);\n    const seq = options.seq ?? seqSource.next;\n    seqSource.next = Math.max(seqSource.next, seq + 1);\n\n    const content = redact(rawContent);\n    const dir = directoryFor(runId);\n    const filename = `${role}.${seqWidth(seq)}.txt`;\n    const finalPath = join(dir, filename);\n    const tmpPath = `${finalPath}.tmp`;\n\n    try {\n      await mkdir(dir, { recursive: true });\n      await writeFile(tmpPath, content, { encoding: 'utf8' });\n      await rename(tmpPath, finalPath);\n    } catch (cause) {\n      try {\n        await unlink(tmpPath);\n      } catch {\n        // Best-effort cleanup; the write error is the operator-facing signal.\n      }\n      throw new ProgressWriteError(finalPath, cause);\n    }\n\n    const stats = await stat(finalPath);\n    const sha256 = sha256Hex(content);\n    return {\n      path: finalPath,\n      role,\n      seq,\n      sizeBytes: stats.size,\n      sensitivity,\n      ...(tags.length > 0 ? { tags } : {}),\n      writtenAtIso: new Date().toISOString(),\n      sha256,\n    };\n  };\n\n  const read = async (\n    currentRunId: string,\n    options: ProgressReadOptions = {},\n  ): Promise<ReadonlyArray<ProgressArtifactRef>> => {\n    const runId = options.runId ?? currentRunId;\n    const max = options.maxArtifacts ?? 100;\n    const sinceSeq = options.sinceSeq ?? 0;\n    const dir = directoryFor(runId);\n    let entries: string[];\n    try {\n      entries = await readdir(dir);\n    } catch {\n      return [];\n    }\n    const out: ProgressArtifactRef[] = [];\n    const role = options.role;\n    for (const entry of entries) {\n      if (!entry.endsWith('.txt')) continue;\n      const dot = entry.indexOf('.');\n      if (dot < 0) continue;\n      const entryRole = entry.slice(0, dot);\n      const seqStr = entry.slice(dot + 1, entry.length - 4);\n      const seq = Number(seqStr);\n      if (!Number.isFinite(seq)) continue;\n      if (role !== undefined && entryRole !== role) continue;\n      if (seq <= sinceSeq) continue;\n      const fullPath = join(dir, entry);\n      const stats = await stat(fullPath);\n      const content = await readFile(fullPath, { encoding: 'utf8' });\n      const sha256 = sha256Hex(content);\n      out.push({\n        path: fullPath,\n        role: entryRole,\n        seq,\n        sizeBytes: stats.size,\n        sensitivity: 'internal',\n        writtenAtIso: stats.mtime.toISOString(),\n        sha256,\n      });\n      if (out.length >= max) break;\n    }\n    out.sort((a, b) => {\n      if (a.role !== b.role) return a.role.localeCompare(b.role);\n      return a.seq - b.seq;\n    });\n    return out;\n  };\n\n  return {\n    write,\n    read,\n    rootFor: (runId) => directoryFor(runId),\n  };\n}\n"],"mappings":"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"}

package/dist/run-state/index.d.ts

@@ -0,0 +1,152 @@
+import { CompletedToolCall, HandoffRecord, Message, RunState, RunStateUsageByModel, RunStatus, RunStep, RunTaintSummary, ToolApproval, Usage } from "@graphorin/core";
+
+//#region src/run-state/index.d.ts
+
+/**
+ * Canonical schema id for serialized {@link RunState} payloads.
+ *
+ * @stable
+ */
+declare const RUN_STATE_SCHEMA_VERSION: "graphorin-run-state/1.1";
+/**
+ * Reader-supported schema id range. Major version 1 only for v0.1.
+ *
+ * @stable
+ */
+declare const RUN_STATE_SCHEMA_MAJOR_SUPPORTED = 1;
+/**
+ * On-disk payload returned by {@link serializeRunState} and accepted
+ * by {@link deserializeRunState}. The shape is JSON-stable.
+ *
+ * @stable
+ */
+interface SerializedRunState {
+  readonly version: typeof RUN_STATE_SCHEMA_VERSION;
+  readonly id: string;
+  readonly agentId: string;
+  readonly currentAgentId: string;
+  readonly sessionId: string;
+  readonly userId?: string;
+  readonly status: RunStatus;
+  readonly steps: ReadonlyArray<RunStep>;
+  readonly messages: ReadonlyArray<Message>;
+  readonly pendingApprovals: ReadonlyArray<ToolApproval>;
+  readonly handoffs: ReadonlyArray<HandoffRecord>;
+  readonly usage: Usage;
+  readonly usageByModel?: RunStateUsageByModel;
+  /** AG-19: coarse data-flow taint summary (no untrusted text). */
+  readonly taintSummary?: RunTaintSummary;
+  /** AG-19: deferred tools promoted by `tool_search` this run. */
+  readonly promotedTools?: ReadonlyArray<string>;
+  readonly startedAt: string;
+  readonly finishedAt?: string;
+  readonly error?: {
+    readonly message: string;
+    readonly code: string;
+    readonly details?: unknown;
+  };
+}
+/**
+ * Options accepted by {@link serializeRunState}.
+ *
+ * @stable
+ */
+interface SerializeRunStateOptions {
+  /**
+   * Deep-redact secret-named keys (`apiKey`, `authorization`,
+   * `bearerToken` / `accessToken` / `refreshToken`, `password`,
+   * `secret`, …) anywhere in the snapshot — tool results and messages
+   * included — replacing their values with `'[redacted]'`. Defaults to
+   * `false` for the round-trip canonical helper; the agent runtime
+   * passes `true` when persisting through the checkpoint store
+   * (AG-23). Redaction is best-effort by key name: secrets stored
+   * under unrelated keys are not detected.
+   */
+  readonly stripTracingApiKey?: boolean;
+}
+/**
+ * Render a JSON-stable snapshot of the supplied {@link RunState}.
+ * The returned value is plain JSON (no `Map`, `Set`, `Date`, ...).
+ *
+ * @stable
+ */
+declare function serializeRunState(state: RunState, options?: SerializeRunStateOptions): SerializedRunState;
+/**
+ * Render the canonical JSON string representation of the supplied
+ * {@link RunState}. `JSON.stringify(serializeRunState(state))` —
+ * provided as a convenience.
+ *
+ * @stable
+ */
+declare function runStateToJSON(state: RunState, options?: SerializeRunStateOptions): string;
+interface DeserializeOptions {
+  /**
+   * Synthesize `usageByModel` from a v0.1-alpha state that omits
+   * the field. Defaults to `true` so callers can rehydrate older
+   * states without explicit migration.
+   */
+  readonly synthesizeUsageByModel?: boolean;
+  /**
+   * Logger callback for one-time INFO messages emitted on
+   * backwards-compat synthesis. Defaults to a no-op.
+   */
+  readonly logger?: (message: string) => void;
+}
+/**
+ * Rehydrate a {@link RunState} from the on-disk payload. Throws
+ * {@link RunStateVersionUnsupportedError} when the payload version
+ * is from a future major; throws
+ * {@link RunStateMalformedError} when the payload is structurally
+ * invalid.
+ *
+ * Backwards-compat: a payload that omits `usageByModel` is accepted
+ * and the field is synthesized from the aggregate `usage` with
+ * `attemptCount: 1` for the primary model.
+ *
+ * @stable
+ */
+declare function deserializeRunState(payload: unknown, options?: DeserializeOptions): RunState;
+/** Convenience JSON-string parser pairing with {@link runStateToJSON}. */
+declare function runStateFromJSON(serialized: string, options?: DeserializeOptions): RunState;
+/**
+ * Build a fresh, minimal {@link RunState} for a new run. Helper used
+ * by `createAgent({...})` so consumers can construct deterministic
+ * run state in tests.
+ *
+ * @stable
+ */
+declare function createInitialRunState(args: {
+  readonly id: string;
+  readonly agentId: string;
+  readonly sessionId: string;
+  readonly userId?: string;
+  readonly startedAt?: string;
+}): RunState;
+/**
+ * Append a per-model usage entry to {@link RunState.usageByModel}.
+ * Mutates the supplied state in place — used by the agent runtime's
+ * per-step retry loop. Pure callers that need an immutable update
+ * should clone the state first.
+ *
+ * @stable
+ */
+declare function addModelUsage(state: RunState, modelId: string, delta: Usage): void;
+/**
+ * Recompute the aggregate usage from `usageByModel`. Returns the
+ * sum that callers can compare against `state.usage` to verify the
+ * per-step retry loop maintained the documented invariant.
+ *
+ * @stable
+ */
+declare function aggregateUsageFromByModel(byModel: RunStateUsageByModel | undefined): Usage;
+/**
+ * The "tools used" surface of a completed run. Cheap to compute
+ * from `RunState.steps`; surfaced as a stand-alone helper for
+ * Phase 17 example apps and operator-facing dashboards.
+ *
+ * @stable
+ */
+declare function completedToolCallsFromState(state: RunState): ReadonlyArray<CompletedToolCall>;
+//#endregion
+export { RUN_STATE_SCHEMA_MAJOR_SUPPORTED, RUN_STATE_SCHEMA_VERSION, SerializeRunStateOptions, SerializedRunState, addModelUsage, aggregateUsageFromByModel, completedToolCallsFromState, createInitialRunState, deserializeRunState, runStateFromJSON, runStateToJSON, serializeRunState };
+//# sourceMappingURL=index.d.ts.map

package/dist/run-state/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/run-state/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AA4D0B,cA5Bb,wBA4Ba,EAAA,yBAAA;;;;AAe1B;AAoBA;AACS,cAzDI,gCAAA,GAyDJ,CAAA;;;;AAmFT;AAEC;AAiCD;AAoJgB,UA3TC,kBAAA,CA2T8C;EAkB/C,SAAA,OAAA,EAAA,OA5UW,wBAkVf;EAyBI,SAAA,EAAA,EAAA,MAAa;EA8Bb,SAAA,OAAA,EAAA,MAAA;EA+BA,SAAA,cAAA,EAAA,MAA2B;EAAQ,SAAA,SAAA,EAAA,MAAA;EAAyB,SAAA,MAAA,CAAA,EAAA,MAAA;EAAd,SAAA,MAAA,EAla3C,SAka2C;EAAa,SAAA,KAAA,EAjazD,aAiayD,CAja3C,OAia2C,CAAA;qBAhatD,cAAc;6BACN,cAAc;qBACtB,cAAc;kBACjB;0BACQ;;0BAEA;;2BAEC;;;;;;;;;;;;;;UAWV,wBAAA;;;;;;;;;;;;;;;;;;;iBAoBD,iBAAA,QACP,oBACE,2BACR;;;;;;;;iBAiFa,cAAA,QAAsB,oBAAoB;UAIhD,kBAAA;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+BM,mBAAA,6BAA+C,qBAA0B;;iBAoJzE,gBAAA,+BAA+C,qBAAqB;;;;;;;;iBAkBpE,qBAAA;;;;;;IAMZ;;;;;;;;;iBAyBY,aAAA,QAAqB,kCAAkC;;;;;;;;iBA8BvD,yBAAA,UAAmC,mCAAmC;;;;;;;;iBA+BtE,2BAAA,QAAmC,WAAW,cAAc"}