@yolk-sdk/codemode 0.1.0-canary.100

package/dist/output.mjs

@@ -0,0 +1,184 @@
+import { ImagePart, TextPart, inlineBase64AttachmentSource } from "@yolk-sdk/agent/protocol";
+//#region src/output.ts
+const isHighSurrogate = (code) => code >= 55296 && code <= 56319;
+const isLowSurrogate = (code) => code >= 56320 && code <= 57343;
+const headCut = (text, length) => length > 0 && length < text.length && isHighSurrogate(text.charCodeAt(length - 1)) ? length - 1 : length;
+const tailCut = (text, start) => start > 0 && start < text.length && isLowSurrogate(text.charCodeAt(start)) ? start + 1 : start;
+const textLength = (segments) => segments.reduce((total, segment) => total + (segment.type === "text" ? segment.text.length : 0), 0);
+const omissionMarker = (characters, images) => `\n\n[… ${characters} characters${images > 0 ? ` and ${images} image${images === 1 ? "" : "s"}` : ""} omitted …]\n\n`;
+const markerReserve = 80;
+/**
+* Keeps at most about `maxChars` characters of text: the head and the tail of the segments, with an
+* omission marker in between. Images inside the omitted middle are dropped and counted.
+*/
+const boundCodeModeSegments = (segments, maxChars) => {
+	const total = textLength(segments);
+	if (total <= maxChars) return segments;
+	const budget = Math.max(0, maxChars - markerReserve);
+	let headBudget = Math.ceil(budget / 2);
+	let tailBudget = budget - headBudget;
+	const head = [];
+	let headIndex = 0;
+	let headPartial = 0;
+	for (; headIndex < segments.length && headBudget > 0; headIndex++) {
+		const segment = segments[headIndex];
+		if (segment === void 0) break;
+		if (segment.type === "image") {
+			head.push(segment);
+			continue;
+		}
+		if (segment.text.length <= headBudget) {
+			head.push(segment);
+			headBudget -= segment.text.length;
+			continue;
+		}
+		headPartial = headCut(segment.text, headBudget);
+		head.push({
+			type: "text",
+			text: segment.text.slice(0, headPartial)
+		});
+		headBudget = 0;
+		break;
+	}
+	const tail = [];
+	let tailIndex = segments.length - 1;
+	let tailStart;
+	for (; tailIndex >= headIndex && tailBudget > 0; tailIndex--) {
+		const segment = segments[tailIndex];
+		if (segment === void 0) break;
+		if (segment.type === "image") {
+			if (tailIndex === headIndex) break;
+			tail.unshift(segment);
+			continue;
+		}
+		const available = tailIndex === headIndex ? segment.text.length - headPartial : segment.text.length;
+		if (available <= tailBudget && tailIndex !== headIndex) {
+			tail.unshift(segment);
+			tailBudget -= available;
+			continue;
+		}
+		tailStart = tailCut(segment.text, segment.text.length - Math.min(available, tailBudget));
+		tail.unshift({
+			type: "text",
+			text: segment.text.slice(tailStart)
+		});
+		tailBudget = 0;
+		break;
+	}
+	const keptText = textLength(head) + textLength(tail);
+	const keptImages = [...head, ...tail].filter((segment) => segment.type === "image").length;
+	const allImages = segments.filter((segment) => segment.type === "image").length;
+	return [
+		...head,
+		{
+			type: "text",
+			text: omissionMarker(total - keptText, allImages - keptImages)
+		},
+		...tail
+	];
+};
+const mergeText = (segments) => segments.reduce((merged, segment) => {
+	const last = merged.at(-1);
+	if (segment.type === "text" && last?.type === "text") merged[merged.length - 1] = {
+		type: "text",
+		text: last.text + segment.text
+	};
+	else if (segment.type === "image" || segment.text.length > 0) merged.push(segment);
+	return merged;
+}, []);
+/** Agent `Content`: a plain string without images, ordered text and image parts otherwise. */
+const codeModeSegmentsContent = (segments) => {
+	const merged = mergeText(segments);
+	if (merged.every((segment) => segment.type === "text")) return merged.map((segment) => segment.type === "text" ? segment.text : "").join("");
+	return merged.map((segment) => segment.type === "text" ? TextPart.make({ text: segment.text }) : ImagePart.make({
+		source: inlineBase64AttachmentSource(segment.data),
+		mimeType: segment.mimeType
+	}));
+};
+const statusOrder = [
+	"ok",
+	"error",
+	"cancelled"
+];
+/** `name: 2 ok, 1 error; other: 1 cancelled`, by first appearance. */
+const summarizeCodeModeCalls = (calls) => {
+	if (calls.length === 0) return "none";
+	const byName = /* @__PURE__ */ new Map();
+	for (const call of calls) {
+		const counts = byName.get(call.name) ?? /* @__PURE__ */ new Map();
+		counts.set(call.status, (counts.get(call.status) ?? 0) + 1);
+		byName.set(call.name, counts);
+	}
+	return [...byName].map(([name, counts]) => `${name}: ${statusOrder.flatMap((status) => {
+		const count = counts.get(status);
+		return count === void 0 ? [] : [`${count} ${status}`];
+	}).join(", ")}`).join("; ");
+};
+const stackFrames = (stack) => stack === void 0 ? [] : stack.split("\n").filter((line) => /^\s+at\s/.test(line) || /^\s*\S+:\d+/.test(line));
+const encodeValue = (value) => {
+	try {
+		return JSON.stringify(value) ?? "undefined";
+	} catch {
+		return "[unserializable value]";
+	}
+};
+/** Default cap of images kept in one result. */
+const defaultCodeModeMaxImages = 8;
+/** Default cap of base64 image data kept in one result, in characters (4 MiB). */
+const defaultCodeModeMaxImageBytes = 4 * 1024 * 1024;
+const imageOmissionNote = (dropped, maxImages, maxImageBytes) => `\n\n[… ${dropped} image${dropped === 1 ? "" : "s"} omitted: a result keeps at most ${maxImages} images and ${maxImageBytes} characters of base64 image data …]`;
+/**
+* Model-visible segments of one execution: a `Script completed` / `Script failed` header with the
+* wall time, the output in order, the JSON return value (omitted when undefined), and for failures
+* the error and the tool calls already made. Images are kept in order while they fit `maxImages`
+* (default 8) and `maxImageBytes` of base64 in total (default 4 MiB); an image that would exceed
+* either is dropped and counted in an omission note after the output. The result is then bounded
+* by `maxChars` with a head-and-tail cut, which also drops images in the omitted middle.
+*/
+const codeModeResultSegments = (input) => {
+	const { result } = input;
+	const maxImages = Math.max(0, Math.floor(input.maxImages ?? 8));
+	const maxImageBytes = Math.max(0, Math.floor(input.maxImageBytes ?? 4194304));
+	const ms = Math.round(input.wallTimeMs);
+	const segments = [];
+	const text = (value) => {
+		segments.push({
+			type: "text",
+			text: value
+		});
+	};
+	text(result.ok ? `Script completed in ${ms} ms.` : `Script failed after ${ms} ms.`);
+	if (result.output.length > 0) {
+		text("\n\nOutput:\n");
+		let keptImages = 0;
+		let keptImageBytes = 0;
+		let droppedImages = 0;
+		result.output.forEach((item, index) => {
+			const previous = result.output[index - 1];
+			if (item.type === "text") text(previous?.type === "text" ? `\n${item.text}` : item.text);
+			else if (keptImages < maxImages && keptImageBytes + item.data.length <= maxImageBytes) {
+				keptImages++;
+				keptImageBytes += item.data.length;
+				segments.push(item);
+			} else droppedImages++;
+		});
+		if (droppedImages > 0) text(imageOmissionNote(droppedImages, maxImages, maxImageBytes));
+	}
+	if (result.ok && result.value !== void 0) text(`\n\nReturn value:\n${encodeValue(result.value)}`);
+	if (!result.ok) {
+		const error = result.error ?? {
+			kind: "sandbox",
+			message: "The script failed without an error."
+		};
+		text(`\n\nScript error: ${error.kind}: ${error.message}`);
+		const frames = stackFrames(error.stack);
+		if (frames.length > 0) text(`\n${frames.join("\n")}`);
+		text(`\n\nTool calls made before the failure (they are not undone): ${summarizeCodeModeCalls(input.calls)}.`);
+	}
+	if (result.ok && result.output.length === 0 && result.value === void 0) text(" No output and no return value.");
+	return boundCodeModeSegments(mergeText(segments), input.maxChars);
+};
+//#endregion
+export { boundCodeModeSegments, codeModeResultSegments, codeModeSegmentsContent, defaultCodeModeMaxImageBytes, defaultCodeModeMaxImages, summarizeCodeModeCalls };
+
+//# sourceMappingURL=output.mjs.map

package/dist/output.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.mjs","names":[],"sources":["../src/output.ts"],"sourcesContent":["import {\n  ImagePart,\n  inlineBase64AttachmentSource,\n  TextPart,\n  type Content,\n  type NestedToolCallStatus\n} from '@yolk-sdk/agent/protocol'\nimport type { CodeModeExecutionResult, CodeModeOutputItem } from './executor.ts'\n\n/** Text or image piece of the model-visible result, in order. */\nexport type CodeModeResultSegment = CodeModeOutputItem\n\nconst isHighSurrogate = (code: number) => code >= 0xd800 && code <= 0xdbff\n\nconst isLowSurrogate = (code: number) => code >= 0xdc00 && code <= 0xdfff\n\n// Cut points never split a surrogate pair.\nconst headCut = (text: string, length: number) =>\n  length > 0 && length < text.length && isHighSurrogate(text.charCodeAt(length - 1))\n    ? length - 1\n    : length\n\nconst tailCut = (text: string, start: number) =>\n  start > 0 && start < text.length && isLowSurrogate(text.charCodeAt(start)) ? start + 1 : start\n\nconst textLength = (segments: ReadonlyArray<CodeModeResultSegment>) =>\n  segments.reduce(\n    (total, segment) => total + (segment.type === 'text' ? segment.text.length : 0),\n    0\n  )\n\nconst omissionMarker = (characters: number, images: number) =>\n  `\\n\\n[… ${characters} characters${images > 0 ? ` and ${images} image${images === 1 ? '' : 's'}` : ''} omitted …]\\n\\n`\n\nconst markerReserve = 80\n\n/**\n * Keeps at most about `maxChars` characters of text: the head and the tail of the segments, with an\n * omission marker in between. Images inside the omitted middle are dropped and counted.\n */\nexport const boundCodeModeSegments = (\n  segments: ReadonlyArray<CodeModeResultSegment>,\n  maxChars: number\n): ReadonlyArray<CodeModeResultSegment> => {\n  const total = textLength(segments)\n\n  if (total <= maxChars) return segments\n\n  const budget = Math.max(0, maxChars - markerReserve)\n  let headBudget = Math.ceil(budget / 2)\n  let tailBudget = budget - headBudget\n\n  const head: Array<CodeModeResultSegment> = []\n  let headIndex = 0\n  let headPartial = 0\n\n  for (; headIndex < segments.length && headBudget > 0; headIndex++) {\n    const segment = segments[headIndex]\n\n    if (segment === undefined) break\n\n    if (segment.type === 'image') {\n      head.push(segment)\n      continue\n    }\n\n    if (segment.text.length <= headBudget) {\n      head.push(segment)\n      headBudget -= segment.text.length\n      continue\n    }\n\n    headPartial = headCut(segment.text, headBudget)\n    head.push({ type: 'text', text: segment.text.slice(0, headPartial) })\n    headBudget = 0\n    break\n  }\n\n  const tail: Array<CodeModeResultSegment> = []\n  let tailIndex = segments.length - 1\n  let tailStart: number | undefined\n\n  for (; tailIndex >= headIndex && tailBudget > 0; tailIndex--) {\n    const segment = segments[tailIndex]\n\n    if (segment === undefined) break\n\n    if (segment.type === 'image') {\n      if (tailIndex === headIndex) break\n      tail.unshift(segment)\n      continue\n    }\n\n    const available =\n      tailIndex === headIndex ? segment.text.length - headPartial : segment.text.length\n\n    if (available <= tailBudget && tailIndex !== headIndex) {\n      tail.unshift(segment)\n      tailBudget -= available\n      continue\n    }\n\n    tailStart = tailCut(segment.text, segment.text.length - Math.min(available, tailBudget))\n    tail.unshift({ type: 'text', text: segment.text.slice(tailStart) })\n    tailBudget = 0\n    break\n  }\n\n  const keptText = textLength(head) + textLength(tail)\n  const keptImages = [...head, ...tail].filter(segment => segment.type === 'image').length\n  const allImages = segments.filter(segment => segment.type === 'image').length\n\n  return [\n    ...head,\n    { type: 'text', text: omissionMarker(total - keptText, allImages - keptImages) },\n    ...tail\n  ]\n}\n\nconst mergeText = (segments: ReadonlyArray<CodeModeResultSegment>) =>\n  segments.reduce<Array<CodeModeResultSegment>>((merged, segment) => {\n    const last = merged.at(-1)\n\n    if (segment.type === 'text' && last?.type === 'text') {\n      merged[merged.length - 1] = { type: 'text', text: last.text + segment.text }\n    } else if (segment.type === 'image' || segment.text.length > 0) {\n      merged.push(segment)\n    }\n\n    return merged\n  }, [])\n\n/** Agent `Content`: a plain string without images, ordered text and image parts otherwise. */\nexport const codeModeSegmentsContent = (\n  segments: ReadonlyArray<CodeModeResultSegment>\n): Content => {\n  const merged = mergeText(segments)\n\n  if (merged.every(segment => segment.type === 'text')) {\n    return merged.map(segment => (segment.type === 'text' ? segment.text : '')).join('')\n  }\n\n  return merged.map(segment =>\n    segment.type === 'text'\n      ? TextPart.make({ text: segment.text })\n      : ImagePart.make({\n          source: inlineBase64AttachmentSource(segment.data),\n          mimeType: segment.mimeType\n        })\n  )\n}\n\nexport type CodeModeCallSummary = {\n  readonly name: string\n  readonly status: NestedToolCallStatus\n}\n\nconst statusOrder: ReadonlyArray<NestedToolCallStatus> = ['ok', 'error', 'cancelled']\n\n/** `name: 2 ok, 1 error; other: 1 cancelled`, by first appearance. */\nexport const summarizeCodeModeCalls = (calls: ReadonlyArray<CodeModeCallSummary>): string => {\n  if (calls.length === 0) return 'none'\n\n  const byName = new Map<string, Map<NestedToolCallStatus, number>>()\n\n  for (const call of calls) {\n    const counts = byName.get(call.name) ?? new Map<NestedToolCallStatus, number>()\n\n    counts.set(call.status, (counts.get(call.status) ?? 0) + 1)\n    byName.set(call.name, counts)\n  }\n\n  return [...byName]\n    .map(\n      ([name, counts]) =>\n        `${name}: ${statusOrder\n          .flatMap(status => {\n            const count = counts.get(status)\n\n            return count === undefined ? [] : [`${count} ${status}`]\n          })\n          .join(', ')}`\n    )\n    .join('; ')\n}\n\nconst stackFrames = (stack: string | undefined) =>\n  stack === undefined\n    ? []\n    : stack.split('\\n').filter(line => /^\\s+at\\s/.test(line) || /^\\s*\\S+:\\d+/.test(line))\n\nconst encodeValue = (value: unknown): string => {\n  try {\n    return JSON.stringify(value) ?? 'undefined'\n  } catch {\n    return '[unserializable value]'\n  }\n}\n\n/** Default cap of images kept in one result. */\nexport const defaultCodeModeMaxImages = 8\n\n/** Default cap of base64 image data kept in one result, in characters (4 MiB). */\nexport const defaultCodeModeMaxImageBytes = 4 * 1024 * 1024\n\nconst imageOmissionNote = (dropped: number, maxImages: number, maxImageBytes: number) =>\n  `\\n\\n[… ${dropped} image${dropped === 1 ? '' : 's'} omitted: a result keeps at most ${maxImages} images and ${maxImageBytes} characters of base64 image data …]`\n\n/**\n * Model-visible segments of one execution: a `Script completed` / `Script failed` header with the\n * wall time, the output in order, the JSON return value (omitted when undefined), and for failures\n * the error and the tool calls already made. Images are kept in order while they fit `maxImages`\n * (default 8) and `maxImageBytes` of base64 in total (default 4 MiB); an image that would exceed\n * either is dropped and counted in an omission note after the output. The result is then bounded\n * by `maxChars` with a head-and-tail cut, which also drops images in the omitted middle.\n */\nexport const codeModeResultSegments = (input: {\n  readonly result: CodeModeExecutionResult\n  readonly wallTimeMs: number\n  readonly calls: ReadonlyArray<CodeModeCallSummary>\n  readonly maxChars: number\n  readonly maxImages?: number\n  readonly maxImageBytes?: number\n}): ReadonlyArray<CodeModeResultSegment> => {\n  const { result } = input\n  const maxImages = Math.max(0, Math.floor(input.maxImages ?? defaultCodeModeMaxImages))\n  const maxImageBytes = Math.max(0, Math.floor(input.maxImageBytes ?? defaultCodeModeMaxImageBytes))\n  const ms = Math.round(input.wallTimeMs)\n  const segments: Array<CodeModeResultSegment> = []\n\n  const text = (value: string) => {\n    segments.push({ type: 'text', text: value })\n  }\n\n  text(result.ok ? `Script completed in ${ms} ms.` : `Script failed after ${ms} ms.`)\n\n  if (result.output.length > 0) {\n    text('\\n\\nOutput:\\n')\n\n    let keptImages = 0\n    let keptImageBytes = 0\n    let droppedImages = 0\n\n    result.output.forEach((item, index) => {\n      const previous = result.output[index - 1]\n\n      if (item.type === 'text') {\n        text(previous?.type === 'text' ? `\\n${item.text}` : item.text)\n      } else if (keptImages < maxImages && keptImageBytes + item.data.length <= maxImageBytes) {\n        keptImages++\n        keptImageBytes += item.data.length\n        segments.push(item)\n      } else {\n        droppedImages++\n      }\n    })\n\n    if (droppedImages > 0) text(imageOmissionNote(droppedImages, maxImages, maxImageBytes))\n  }\n\n  if (result.ok && result.value !== undefined) {\n    text(`\\n\\nReturn value:\\n${encodeValue(result.value)}`)\n  }\n\n  if (!result.ok) {\n    const error = result.error ?? {\n      kind: 'sandbox',\n      message: 'The script failed without an error.'\n    }\n\n    text(`\\n\\nScript error: ${error.kind}: ${error.message}`)\n\n    const frames = stackFrames(error.stack)\n\n    if (frames.length > 0) text(`\\n${frames.join('\\n')}`)\n\n    text(\n      `\\n\\nTool calls made before the failure (they are not undone): ${summarizeCodeModeCalls(input.calls)}.`\n    )\n  }\n\n  if (result.ok && result.output.length === 0 && result.value === undefined) {\n    text(' No output and no return value.')\n  }\n\n  return boundCodeModeSegments(mergeText(segments), input.maxChars)\n}\n"],"mappings":";;AAYA,MAAM,mBAAmB,SAAiB,QAAQ,SAAU,QAAQ;AAEpE,MAAM,kBAAkB,SAAiB,QAAQ,SAAU,QAAQ;AAGnE,MAAM,WAAW,MAAc,WAC7B,SAAS,KAAK,SAAS,KAAK,UAAU,gBAAgB,KAAK,WAAW,SAAS,CAAC,CAAC,IAC7E,SAAS,IACT;AAEN,MAAM,WAAW,MAAc,UAC7B,QAAQ,KAAK,QAAQ,KAAK,UAAU,eAAe,KAAK,WAAW,KAAK,CAAC,IAAI,QAAQ,IAAI;AAE3F,MAAM,cAAc,aAClB,SAAS,QACN,OAAO,YAAY,SAAS,QAAQ,SAAS,SAAS,QAAQ,KAAK,SAAS,IAC7E,CACF;AAEF,MAAM,kBAAkB,YAAoB,WAC1C,UAAU,WAAW,aAAa,SAAS,IAAI,QAAQ,OAAO,QAAQ,WAAW,IAAI,KAAK,QAAQ,GAAG;AAEvG,MAAM,gBAAgB;;;;;AAMtB,MAAa,yBACX,UACA,aACyC;CACzC,MAAM,QAAQ,WAAW,QAAQ;CAEjC,IAAI,SAAS,UAAU,OAAO;CAE9B,MAAM,SAAS,KAAK,IAAI,GAAG,WAAW,aAAa;CACnD,IAAI,aAAa,KAAK,KAAK,SAAS,CAAC;CACrC,IAAI,aAAa,SAAS;CAE1B,MAAM,OAAqC,CAAC;CAC5C,IAAI,YAAY;CAChB,IAAI,cAAc;CAElB,OAAO,YAAY,SAAS,UAAU,aAAa,GAAG,aAAa;EACjE,MAAM,UAAU,SAAS;EAEzB,IAAI,YAAY,KAAA,GAAW;EAE3B,IAAI,QAAQ,SAAS,SAAS;GAC5B,KAAK,KAAK,OAAO;GACjB;EACF;EAEA,IAAI,QAAQ,KAAK,UAAU,YAAY;GACrC,KAAK,KAAK,OAAO;GACjB,cAAc,QAAQ,KAAK;GAC3B;EACF;EAEA,cAAc,QAAQ,QAAQ,MAAM,UAAU;EAC9C,KAAK,KAAK;GAAE,MAAM;GAAQ,MAAM,QAAQ,KAAK,MAAM,GAAG,WAAW;EAAE,CAAC;EACpE,aAAa;EACb;CACF;CAEA,MAAM,OAAqC,CAAC;CAC5C,IAAI,YAAY,SAAS,SAAS;CAClC,IAAI;CAEJ,OAAO,aAAa,aAAa,aAAa,GAAG,aAAa;EAC5D,MAAM,UAAU,SAAS;EAEzB,IAAI,YAAY,KAAA,GAAW;EAE3B,IAAI,QAAQ,SAAS,SAAS;GAC5B,IAAI,cAAc,WAAW;GAC7B,KAAK,QAAQ,OAAO;GACpB;EACF;EAEA,MAAM,YACJ,cAAc,YAAY,QAAQ,KAAK,SAAS,cAAc,QAAQ,KAAK;EAE7E,IAAI,aAAa,cAAc,cAAc,WAAW;GACtD,KAAK,QAAQ,OAAO;GACpB,cAAc;GACd;EACF;EAEA,YAAY,QAAQ,QAAQ,MAAM,QAAQ,KAAK,SAAS,KAAK,IAAI,WAAW,UAAU,CAAC;EACvF,KAAK,QAAQ;GAAE,MAAM;GAAQ,MAAM,QAAQ,KAAK,MAAM,SAAS;EAAE,CAAC;EAClE,aAAa;EACb;CACF;CAEA,MAAM,WAAW,WAAW,IAAI,IAAI,WAAW,IAAI;CACnD,MAAM,aAAa,CAAC,GAAG,MAAM,GAAG,IAAI,EAAE,QAAO,YAAW,QAAQ,SAAS,OAAO,EAAE;CAClF,MAAM,YAAY,SAAS,QAAO,YAAW,QAAQ,SAAS,OAAO,EAAE;CAEvE,OAAO;EACL,GAAG;EACH;GAAE,MAAM;GAAQ,MAAM,eAAe,QAAQ,UAAU,YAAY,UAAU;EAAE;EAC/E,GAAG;CACL;AACF;AAEA,MAAM,aAAa,aACjB,SAAS,QAAsC,QAAQ,YAAY;CACjE,MAAM,OAAO,OAAO,GAAG,EAAE;CAEzB,IAAI,QAAQ,SAAS,UAAU,MAAM,SAAS,QAC5C,OAAO,OAAO,SAAS,KAAK;EAAE,MAAM;EAAQ,MAAM,KAAK,OAAO,QAAQ;CAAK;MACtE,IAAI,QAAQ,SAAS,WAAW,QAAQ,KAAK,SAAS,GAC3D,OAAO,KAAK,OAAO;CAGrB,OAAO;AACT,GAAG,CAAC,CAAC;;AAGP,MAAa,2BACX,aACY;CACZ,MAAM,SAAS,UAAU,QAAQ;CAEjC,IAAI,OAAO,OAAM,YAAW,QAAQ,SAAS,MAAM,GACjD,OAAO,OAAO,KAAI,YAAY,QAAQ,SAAS,SAAS,QAAQ,OAAO,EAAG,EAAE,KAAK,EAAE;CAGrF,OAAO,OAAO,KAAI,YAChB,QAAQ,SAAS,SACb,SAAS,KAAK,EAAE,MAAM,QAAQ,KAAK,CAAC,IACpC,UAAU,KAAK;EACb,QAAQ,6BAA6B,QAAQ,IAAI;EACjD,UAAU,QAAQ;CACpB,CAAC,CACP;AACF;AAOA,MAAM,cAAmD;CAAC;CAAM;CAAS;AAAW;;AAGpF,MAAa,0BAA0B,UAAsD;CAC3F,IAAI,MAAM,WAAW,GAAG,OAAO;CAE/B,MAAM,yBAAS,IAAI,IAA+C;CAElE,KAAK,MAAM,QAAQ,OAAO;EACxB,MAAM,SAAS,OAAO,IAAI,KAAK,IAAI,qBAAK,IAAI,IAAkC;EAE9E,OAAO,IAAI,KAAK,SAAS,OAAO,IAAI,KAAK,MAAM,KAAK,KAAK,CAAC;EAC1D,OAAO,IAAI,KAAK,MAAM,MAAM;CAC9B;CAEA,OAAO,CAAC,GAAG,MAAM,EACd,KACE,CAAC,MAAM,YACN,GAAG,KAAK,IAAI,YACT,SAAQ,WAAU;EACjB,MAAM,QAAQ,OAAO,IAAI,MAAM;EAE/B,OAAO,UAAU,KAAA,IAAY,CAAC,IAAI,CAAC,GAAG,MAAM,GAAG,QAAQ;CACzD,CAAC,EACA,KAAK,IAAI,GAChB,EACC,KAAK,IAAI;AACd;AAEA,MAAM,eAAe,UACnB,UAAU,KAAA,IACN,CAAC,IACD,MAAM,MAAM,IAAI,EAAE,QAAO,SAAQ,WAAW,KAAK,IAAI,KAAK,cAAc,KAAK,IAAI,CAAC;AAExF,MAAM,eAAe,UAA2B;CAC9C,IAAI;EACF,OAAO,KAAK,UAAU,KAAK,KAAK;CAClC,QAAQ;EACN,OAAO;CACT;AACF;;AAGA,MAAa,2BAA2B;;AAGxC,MAAa,+BAA+B,IAAI,OAAO;AAEvD,MAAM,qBAAqB,SAAiB,WAAmB,kBAC7D,UAAU,QAAQ,QAAQ,YAAY,IAAI,KAAK,IAAI,mCAAmC,UAAU,cAAc,cAAc;;;;;;;;;AAU9H,MAAa,0BAA0B,UAOK;CAC1C,MAAM,EAAE,WAAW;CACnB,MAAM,YAAY,KAAK,IAAI,GAAG,KAAK,MAAM,MAAM,aAAA,CAAqC,CAAC;CACrF,MAAM,gBAAgB,KAAK,IAAI,GAAG,KAAK,MAAM,MAAM,iBAAA,OAA6C,CAAC;CACjG,MAAM,KAAK,KAAK,MAAM,MAAM,UAAU;CACtC,MAAM,WAAyC,CAAC;CAEhD,MAAM,QAAQ,UAAkB;EAC9B,SAAS,KAAK;GAAE,MAAM;GAAQ,MAAM;EAAM,CAAC;CAC7C;CAEA,KAAK,OAAO,KAAK,uBAAuB,GAAG,QAAQ,uBAAuB,GAAG,KAAK;CAElF,IAAI,OAAO,OAAO,SAAS,GAAG;EAC5B,KAAK,eAAe;EAEpB,IAAI,aAAa;EACjB,IAAI,iBAAiB;EACrB,IAAI,gBAAgB;EAEpB,OAAO,OAAO,SAAS,MAAM,UAAU;GACrC,MAAM,WAAW,OAAO,OAAO,QAAQ;GAEvC,IAAI,KAAK,SAAS,QAChB,KAAK,UAAU,SAAS,SAAS,KAAK,KAAK,SAAS,KAAK,IAAI;QACxD,IAAI,aAAa,aAAa,iBAAiB,KAAK,KAAK,UAAU,eAAe;IACvF;IACA,kBAAkB,KAAK,KAAK;IAC5B,SAAS,KAAK,IAAI;GACpB,OACE;EAEJ,CAAC;EAED,IAAI,gBAAgB,GAAG,KAAK,kBAAkB,eAAe,WAAW,aAAa,CAAC;CACxF;CAEA,IAAI,OAAO,MAAM,OAAO,UAAU,KAAA,GAChC,KAAK,sBAAsB,YAAY,OAAO,KAAK,GAAG;CAGxD,IAAI,CAAC,OAAO,IAAI;EACd,MAAM,QAAQ,OAAO,SAAS;GAC5B,MAAM;GACN,SAAS;EACX;EAEA,KAAK,qBAAqB,MAAM,KAAK,IAAI,MAAM,SAAS;EAExD,MAAM,SAAS,YAAY,MAAM,KAAK;EAEtC,IAAI,OAAO,SAAS,GAAG,KAAK,KAAK,OAAO,KAAK,IAAI,GAAG;EAEpD,KACE,iEAAiE,uBAAuB,MAAM,KAAK,EAAE,EACvG;CACF;CAEA,IAAI,OAAO,MAAM,OAAO,OAAO,WAAW,KAAK,OAAO,UAAU,KAAA,GAC9D,KAAK,iCAAiC;CAGxC,OAAO,sBAAsB,UAAU,QAAQ,GAAG,MAAM,QAAQ;AAClE"}

package/dist/search.d.mts

@@ -0,0 +1,23 @@
+import { CodeModeCatalogTool } from "./catalog.mjs";
+
+//#region src/search.d.ts
+/** Default number of `searchTools` results. */
+declare const defaultCodeModeSearchLimit = 8;
+/** Lowercase word tokens; splits on non-alphanumerics and camelCase boundaries. */
+declare const codeModeSearchTokens: (text: string) => ReadonlyArray<string>;
+type CodeModeSearchOptions = {
+  readonly limit?: number;
+  readonly namespace?: string;
+};
+type CodeModeSearchHit = {
+  /** The identifier scripts call as `tools.<name>(args)`. */readonly name: string;
+  readonly description: string;
+};
+/**
+ * BM25 over each tool's identifier, raw name, description, namespace, and namespace description. Ties keep catalog order.
+ * A query without words lists the (namespace-filtered) tools in catalog order.
+ */
+declare const searchCodeModeTools: (catalog: ReadonlyArray<CodeModeCatalogTool>, query: string, options?: CodeModeSearchOptions) => ReadonlyArray<CodeModeSearchHit>;
+//#endregion
+export { CodeModeSearchHit, CodeModeSearchOptions, codeModeSearchTokens, defaultCodeModeSearchLimit, searchCodeModeTools };
+//# sourceMappingURL=search.d.mts.map

package/dist/search.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.mts","names":[],"sources":["../src/search.ts"],"mappings":";;;;cAGa,0BAAA;AAAb;AAAA,cAOa,oBAAA,GAAwB,IAAA,aAAe,aAAa;AAAA,KAiCrD,qBAAA;EAAA,SACD,KAAA;EAAA,SACA,SAAS;AAAA;AAAA,KAGR,iBAAA;sEAED,IAAA;EAAA,SACA,WAAW;AAAA;;;;AANF;cAaP,mBAAA,GACX,OAAA,EAAS,aAAA,CAAc,mBAAA,GACvB,KAAA,UACA,OAAA,GAAS,qBAAA,KACR,aAAA,CAAc,iBAAA"}

package/dist/search.mjs

@@ -0,0 +1,58 @@
+//#region src/search.ts
+/** Default number of `searchTools` results. */
+const defaultCodeModeSearchLimit = 8;
+const k1 = 1.2;
+const b = .75;
+/** Lowercase word tokens; splits on non-alphanumerics and camelCase boundaries. */
+const codeModeSearchTokens = (text) => text.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase().split(/[^a-z0-9]+/).filter((token) => token.length > 0);
+const indexTool = (tool) => {
+	const tokens = codeModeSearchTokens([
+		tool.identifier,
+		tool.name,
+		tool.description,
+		tool.namespace,
+		tool.namespaceDescription ?? ""
+	].join(" "));
+	const frequencies = /* @__PURE__ */ new Map();
+	for (const token of tokens) frequencies.set(token, (frequencies.get(token) ?? 0) + 1);
+	return {
+		tool,
+		frequencies,
+		length: tokens.length
+	};
+};
+/**
+* BM25 over each tool's identifier, raw name, description, namespace, and namespace description. Ties keep catalog order.
+* A query without words lists the (namespace-filtered) tools in catalog order.
+*/
+const searchCodeModeTools = (catalog, query, options = {}) => {
+	const limit = Math.max(0, Math.floor(options.limit ?? 8));
+	const documents = (options.namespace === void 0 ? catalog : catalog.filter((tool) => tool.namespace === options.namespace)).map(indexTool);
+	const terms = [...new Set(codeModeSearchTokens(query))];
+	const hit = (tool) => ({
+		name: tool.identifier,
+		description: tool.description
+	});
+	if (terms.length === 0) return documents.slice(0, limit).map((document) => hit(document.tool));
+	const averageLength = documents.reduce((total, document) => total + document.length, 0) / Math.max(1, documents.length);
+	const inverse = new Map(terms.map((term) => {
+		const containing = documents.filter((document) => document.frequencies.has(term)).length;
+		return [term, Math.log(1 + (documents.length - containing + .5) / (containing + .5))];
+	}));
+	return documents.map((document, index) => {
+		return {
+			document,
+			index,
+			score: terms.reduce((total, term) => {
+				const frequency = document.frequencies.get(term) ?? 0;
+				if (frequency === 0) return total;
+				const norm = k1 * (1 - b + b * document.length / Math.max(1, averageLength));
+				return total + (inverse.get(term) ?? 0) * frequency * (k1 + 1) / (frequency + norm);
+			}, 0)
+		};
+	}).filter((entry) => entry.score > 0).sort((left, right) => right.score - left.score || left.index - right.index).slice(0, limit).map((entry) => hit(entry.document.tool));
+};
+//#endregion
+export { codeModeSearchTokens, defaultCodeModeSearchLimit, searchCodeModeTools };
+
+//# sourceMappingURL=search.mjs.map

package/dist/search.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.mjs","names":[],"sources":["../src/search.ts"],"sourcesContent":["import type { CodeModeCatalogTool } from './catalog.ts'\n\n/** Default number of `searchTools` results. */\nexport const defaultCodeModeSearchLimit = 8\n\nconst k1 = 1.2\n\nconst b = 0.75\n\n/** Lowercase word tokens; splits on non-alphanumerics and camelCase boundaries. */\nexport const codeModeSearchTokens = (text: string): ReadonlyArray<string> =>\n  text\n    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')\n    .toLowerCase()\n    .split(/[^a-z0-9]+/)\n    .filter(token => token.length > 0)\n\ntype IndexedTool = {\n  readonly tool: CodeModeCatalogTool\n  readonly frequencies: ReadonlyMap<string, number>\n  readonly length: number\n}\n\nconst indexTool = (tool: CodeModeCatalogTool): IndexedTool => {\n  const tokens = codeModeSearchTokens(\n    [\n      tool.identifier,\n      tool.name,\n      tool.description,\n      tool.namespace,\n      tool.namespaceDescription ?? ''\n    ].join(' ')\n  )\n\n  const frequencies = new Map<string, number>()\n\n  for (const token of tokens) {\n    frequencies.set(token, (frequencies.get(token) ?? 0) + 1)\n  }\n\n  return { tool, frequencies, length: tokens.length }\n}\n\nexport type CodeModeSearchOptions = {\n  readonly limit?: number\n  readonly namespace?: string\n}\n\nexport type CodeModeSearchHit = {\n  /** The identifier scripts call as `tools.<name>(args)`. */\n  readonly name: string\n  readonly description: string\n}\n\n/**\n * BM25 over each tool's identifier, raw name, description, namespace, and namespace description. Ties keep catalog order.\n * A query without words lists the (namespace-filtered) tools in catalog order.\n */\nexport const searchCodeModeTools = (\n  catalog: ReadonlyArray<CodeModeCatalogTool>,\n  query: string,\n  options: CodeModeSearchOptions = {}\n): ReadonlyArray<CodeModeSearchHit> => {\n  const limit = Math.max(0, Math.floor(options.limit ?? defaultCodeModeSearchLimit))\n\n  const scoped =\n    options.namespace === undefined\n      ? catalog\n      : catalog.filter(tool => tool.namespace === options.namespace)\n\n  const documents = scoped.map(indexTool)\n  const terms = [...new Set(codeModeSearchTokens(query))]\n\n  const hit = (tool: CodeModeCatalogTool): CodeModeSearchHit => ({\n    name: tool.identifier,\n    description: tool.description\n  })\n\n  if (terms.length === 0) {\n    return documents.slice(0, limit).map(document => hit(document.tool))\n  }\n\n  const averageLength =\n    documents.reduce((total, document) => total + document.length, 0) /\n    Math.max(1, documents.length)\n\n  const inverse = new Map(\n    terms.map((term): readonly [string, number] => {\n      const containing = documents.filter(document => document.frequencies.has(term)).length\n\n      return [term, Math.log(1 + (documents.length - containing + 0.5) / (containing + 0.5))]\n    })\n  )\n\n  return documents\n    .map((document, index) => {\n      const score = terms.reduce((total, term) => {\n        const frequency = document.frequencies.get(term) ?? 0\n\n        if (frequency === 0) return total\n\n        const norm = k1 * (1 - b + (b * document.length) / Math.max(1, averageLength))\n\n        return total + ((inverse.get(term) ?? 0) * frequency * (k1 + 1)) / (frequency + norm)\n      }, 0)\n\n      return { document, index, score }\n    })\n    .filter(entry => entry.score > 0)\n    .sort((left, right) => right.score - left.score || left.index - right.index)\n    .slice(0, limit)\n    .map(entry => hit(entry.document.tool))\n}\n"],"mappings":";;AAGA,MAAa,6BAA6B;AAE1C,MAAM,KAAK;AAEX,MAAM,IAAI;;AAGV,MAAa,wBAAwB,SACnC,KACG,QAAQ,sBAAsB,OAAO,EACrC,YAAY,EACZ,MAAM,YAAY,EAClB,QAAO,UAAS,MAAM,SAAS,CAAC;AAQrC,MAAM,aAAa,SAA2C;CAC5D,MAAM,SAAS,qBACb;EACE,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK,wBAAwB;CAC/B,EAAE,KAAK,GAAG,CACZ;CAEA,MAAM,8BAAc,IAAI,IAAoB;CAE5C,KAAK,MAAM,SAAS,QAClB,YAAY,IAAI,QAAQ,YAAY,IAAI,KAAK,KAAK,KAAK,CAAC;CAG1D,OAAO;EAAE;EAAM;EAAa,QAAQ,OAAO;CAAO;AACpD;;;;;AAiBA,MAAa,uBACX,SACA,OACA,UAAiC,CAAC,MACG;CACrC,MAAM,QAAQ,KAAK,IAAI,GAAG,KAAK,MAAM,QAAQ,SAAA,CAAmC,CAAC;CAOjF,MAAM,aAJJ,QAAQ,cAAc,KAAA,IAClB,UACA,QAAQ,QAAO,SAAQ,KAAK,cAAc,QAAQ,SAAS,GAExC,IAAI,SAAS;CACtC,MAAM,QAAQ,CAAC,GAAG,IAAI,IAAI,qBAAqB,KAAK,CAAC,CAAC;CAEtD,MAAM,OAAO,UAAkD;EAC7D,MAAM,KAAK;EACX,aAAa,KAAK;CACpB;CAEA,IAAI,MAAM,WAAW,GACnB,OAAO,UAAU,MAAM,GAAG,KAAK,EAAE,KAAI,aAAY,IAAI,SAAS,IAAI,CAAC;CAGrE,MAAM,gBACJ,UAAU,QAAQ,OAAO,aAAa,QAAQ,SAAS,QAAQ,CAAC,IAChE,KAAK,IAAI,GAAG,UAAU,MAAM;CAE9B,MAAM,UAAU,IAAI,IAClB,MAAM,KAAK,SAAoC;EAC7C,MAAM,aAAa,UAAU,QAAO,aAAY,SAAS,YAAY,IAAI,IAAI,CAAC,EAAE;EAEhF,OAAO,CAAC,MAAM,KAAK,IAAI,KAAK,UAAU,SAAS,aAAa,OAAQ,aAAa,GAAI,CAAC;CACxF,CAAC,CACH;CAEA,OAAO,UACJ,KAAK,UAAU,UAAU;EAWxB,OAAO;GAAE;GAAU;GAAO,OAVZ,MAAM,QAAQ,OAAO,SAAS;IAC1C,MAAM,YAAY,SAAS,YAAY,IAAI,IAAI,KAAK;IAEpD,IAAI,cAAc,GAAG,OAAO;IAE5B,MAAM,OAAO,MAAM,IAAI,IAAK,IAAI,SAAS,SAAU,KAAK,IAAI,GAAG,aAAa;IAE5E,OAAO,SAAU,QAAQ,IAAI,IAAI,KAAK,KAAK,aAAa,KAAK,MAAO,YAAY;GAClF,GAAG,CAE2B;EAAE;CAClC,CAAC,EACA,QAAO,UAAS,MAAM,QAAQ,CAAC,EAC/B,MAAM,MAAM,UAAU,MAAM,QAAQ,KAAK,SAAS,KAAK,QAAQ,MAAM,KAAK,EAC1E,MAAM,GAAG,KAAK,EACd,KAAI,UAAS,IAAI,MAAM,SAAS,IAAI,CAAC;AAC1C"}

package/dist/store.d.mts

@@ -0,0 +1,77 @@
+import { CodeModeStore, CodeModeStoreWrites } from "./executor.mjs";
+
+//#region src/store.d.ts
+/** `structuredContent` of a code mode `ToolResult`. `storeWrites` is present only for successful
+ * scripts that changed the store.
+ */
+type CodeModeStructuredContent = {
+  readonly codemode: {
+    readonly ok: boolean;
+    readonly storeWrites?: CodeModeStoreWrites; /** Set on the result of a re-executed call whose earlier execution was abandoned. */
+    readonly interrupted?: true; /** With `interrupted`: the abandoned execution's ledgered nested calls. */
+    readonly interruptedCalls?: CodeModeInterruptedCalls;
+    /** With `interrupted`, instead of `interruptedCalls`: the nested calls could not be listed
+     * (the ledger's `list` failed), so any of them may have been applied.
+     */
+    readonly interruptedCallsUnavailable?: true;
+  };
+};
+/** What an abandoned execution's ledgered nested call is known to have done: `applied` (recorded
+ * a result), `failed` (recorded a `ToolError` or an `isError` result), or `unknown` (started, no
+ * recorded outcome, so it may have been applied).
+ */
+type CodeModeInterruptedCallStatus = 'applied' | 'failed' | 'unknown';
+/** One ledgered nested call of an abandoned execution. `key` is its ledger key
+ * (`<toolCallId>/<seq>`); `args` is compact JSON, cut with a trailing `…` (then no longer JSON).
+ */
+type CodeModeInterruptedCall = {
+  readonly key: string;
+  readonly toolName: string;
+  readonly args: string;
+  readonly status: CodeModeInterruptedCallStatus;
+};
+/**
+ * `structuredContent.codemode.interruptedCalls`: plain JSON, in sequence order, bounded like
+ * `nestedCalls` (at most `limits.maxNestedCalls` calls; arguments within 8 KiB per call and
+ * 32 KiB in total). `complete: false` means calls were dropped or arguments cut, here or already
+ * in the ledger entry (`ToolLedgerEntry.argsTruncated`); `counts` covers every ledgered nested
+ * call, dropped ones included. Calls the ledger policy skips (by default read-only calls) never
+ * appear.
+ */
+type CodeModeInterruptedCalls = {
+  readonly calls: ReadonlyArray<CodeModeInterruptedCall>;
+  readonly complete: boolean;
+  readonly counts: {
+    readonly applied: number;
+    readonly failed: number;
+    readonly unknown: number;
+  };
+};
+/** Largest stored value: characters of JSON (256 KiB), as the pi engine counts them. */
+declare const maxCodeModeStoreValueChars: number;
+/** Largest store: characters of keys plus JSON values (1 MiB), as the pi engine counts them. */
+declare const maxCodeModeStoreTotalChars: number;
+/** One prior tool result with the name of the tool that produced it. */
+type CodeModeToolResultEntry = {
+  readonly toolName: string;
+  readonly result: {
+    readonly structuredContent?: unknown;
+  };
+};
+/**
+ * Rebuilds the code mode store from prior tool results, oldest first: applies the `storeWrites` of
+ * each successful script of the code mode tool named `toolName` (default `codemode`) in order.
+ * Results of other tools (even when their `structuredContent` looks like a code mode result),
+ * failed scripts, and malformed contents are skipped. Transcript `ToolResultMessage`s carry no tool
+ * name; pair each with the name of its assistant tool call.
+ *
+ * The rebuilt store keeps the engine bounds: a write whose JSON value exceeds 256 Ki characters, or
+ * that would grow the store beyond 1 Mi characters (keys plus JSON values), is dropped and the key
+ * keeps its previous value. Deletions always apply. Pass the value from `loadStore`.
+ */
+declare const codeModeStoreFromToolResults: (entries: ReadonlyArray<CodeModeToolResultEntry>, options?: {
+  readonly toolName?: string;
+}) => CodeModeStore;
+//#endregion
+export { CodeModeInterruptedCall, CodeModeInterruptedCallStatus, CodeModeInterruptedCalls, CodeModeStructuredContent, CodeModeToolResultEntry, codeModeStoreFromToolResults, maxCodeModeStoreTotalChars, maxCodeModeStoreValueChars };
+//# sourceMappingURL=store.d.mts.map

package/dist/store.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.mts","names":[],"sources":["../src/store.ts"],"mappings":";;;;;AAQA;KAAY,yBAAA;EAAA,SACD,QAAA;IAAA,SACE,EAAA;IAAA,SACA,WAAA,GAAc,mBAAA,EADd;IAAA,SAGA,WAAA,SAFc;IAAA,SAId,gBAAA,GAAmB,wBAAwB;IAA3C;;;IAAA,SAIA,2BAAA;EAAA;AAAA;;;;AAQ4B;KAA7B,6BAAA;;;;KAKA,uBAAA;EAAA,SACD,GAAA;EAAA,SACA,QAAA;EAAA,SACA,IAAA;EAAA,SACA,MAAA,EAAQ,6BAA6B;AAAA;AAAA;AAWhD;;;;;;;AAXgD,KAWpC,wBAAA;EAAA,SACD,KAAA,EAAO,aAAa,CAAC,uBAAA;EAAA,SACrB,QAAA;EAAA,SACA,MAAA;IAAA,SACE,OAAA;IAAA,SACA,MAAA;IAAA,SACA,OAAA;EAAA;AAAA;;cAmBA,0BAAA;AAAuC;AAAA,cAGvC,0BAAA;;KAGD,uBAAA;EAAA,SACD,QAAA;EAAA,SACA,MAAA;IAAA,SAAmB,iBAAA;EAAA;AAAA;;;;;;AAAiB;AAc/C;;;;;cAAa,4BAAA,GACX,OAAA,EAAS,aAAA,CAAc,uBAAA,GACvB,OAAA;EAAA,SAAoB,QAAA;AAAA,MACnB,aAAA"}

package/dist/store.mjs

@@ -0,0 +1,61 @@
+import "./tool.mjs";
+import { Option } from "effect";
+import * as Schema from "effect/Schema";
+//#region src/store.ts
+const StoreWritesSchema = Schema.Struct({
+	set: Schema.Record(Schema.String, Schema.Json),
+	delete: Schema.Array(Schema.String)
+});
+const CodeModeStructuredContentSchema = Schema.Struct({ codemode: Schema.Struct({
+	ok: Schema.Boolean,
+	storeWrites: Schema.optionalKey(StoreWritesSchema)
+}) });
+const decodeStructuredContent = Schema.decodeUnknownOption(CodeModeStructuredContentSchema);
+/** Largest stored value: characters of JSON (256 KiB), as the pi engine counts them. */
+const maxCodeModeStoreValueChars = 256 * 1024;
+/** Largest store: characters of keys plus JSON values (1 MiB), as the pi engine counts them. */
+const maxCodeModeStoreTotalChars = 1024 * 1024;
+/**
+* Rebuilds the code mode store from prior tool results, oldest first: applies the `storeWrites` of
+* each successful script of the code mode tool named `toolName` (default `codemode`) in order.
+* Results of other tools (even when their `structuredContent` looks like a code mode result),
+* failed scripts, and malformed contents are skipped. Transcript `ToolResultMessage`s carry no tool
+* name; pair each with the name of its assistant tool call.
+*
+* The rebuilt store keeps the engine bounds: a write whose JSON value exceeds 256 Ki characters, or
+* that would grow the store beyond 1 Mi characters (keys plus JSON values), is dropped and the key
+* keeps its previous value. Deletions always apply. Pass the value from `loadStore`.
+*/
+const codeModeStoreFromToolResults = (entries, options = {}) => {
+	const toolName = options.toolName ?? "codemode";
+	const store = /* @__PURE__ */ new Map();
+	let total = 0;
+	for (const entry of entries) {
+		if (entry.toolName !== toolName) continue;
+		const content = decodeStructuredContent(entry.result.structuredContent);
+		if (Option.isNone(content) || !content.value.codemode.ok) continue;
+		const writes = content.value.codemode.storeWrites;
+		if (writes === void 0) continue;
+		for (const key of writes.delete) {
+			total -= store.get(key)?.chars ?? 0;
+			store.delete(key);
+		}
+		for (const [key, value] of Object.entries(writes.set)) {
+			const json = JSON.stringify(value);
+			if (json.length > 262144) continue;
+			const chars = key.length + json.length;
+			const next = total - (store.get(key)?.chars ?? 0) + chars;
+			if (next > 1048576) continue;
+			store.set(key, {
+				value,
+				chars
+			});
+			total = next;
+		}
+	}
+	return Object.fromEntries([...store].map(([key, stored]) => [key, stored.value]));
+};
+//#endregion
+export { codeModeStoreFromToolResults, maxCodeModeStoreTotalChars, maxCodeModeStoreValueChars };
+
+//# sourceMappingURL=store.mjs.map

package/dist/store.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.mjs","names":[],"sources":["../src/store.ts"],"sourcesContent":["import { Option } from 'effect'\nimport * as Schema from 'effect/Schema'\nimport type { CodeModeStore, CodeModeStoreWrites } from './executor.ts'\nimport { codeModeToolName } from './tool.ts'\n\n/** `structuredContent` of a code mode `ToolResult`. `storeWrites` is present only for successful\n * scripts that changed the store.\n */\nexport type CodeModeStructuredContent = {\n  readonly codemode: {\n    readonly ok: boolean\n    readonly storeWrites?: CodeModeStoreWrites\n    /** Set on the result of a re-executed call whose earlier execution was abandoned. */\n    readonly interrupted?: true\n    /** With `interrupted`: the abandoned execution's ledgered nested calls. */\n    readonly interruptedCalls?: CodeModeInterruptedCalls\n    /** With `interrupted`, instead of `interruptedCalls`: the nested calls could not be listed\n     * (the ledger's `list` failed), so any of them may have been applied.\n     */\n    readonly interruptedCallsUnavailable?: true\n  }\n}\n\n/** What an abandoned execution's ledgered nested call is known to have done: `applied` (recorded\n * a result), `failed` (recorded a `ToolError` or an `isError` result), or `unknown` (started, no\n * recorded outcome, so it may have been applied).\n */\nexport type CodeModeInterruptedCallStatus = 'applied' | 'failed' | 'unknown'\n\n/** One ledgered nested call of an abandoned execution. `key` is its ledger key\n * (`<toolCallId>/<seq>`); `args` is compact JSON, cut with a trailing `…` (then no longer JSON).\n */\nexport type CodeModeInterruptedCall = {\n  readonly key: string\n  readonly toolName: string\n  readonly args: string\n  readonly status: CodeModeInterruptedCallStatus\n}\n\n/**\n * `structuredContent.codemode.interruptedCalls`: plain JSON, in sequence order, bounded like\n * `nestedCalls` (at most `limits.maxNestedCalls` calls; arguments within 8 KiB per call and\n * 32 KiB in total). `complete: false` means calls were dropped or arguments cut, here or already\n * in the ledger entry (`ToolLedgerEntry.argsTruncated`); `counts` covers every ledgered nested\n * call, dropped ones included. Calls the ledger policy skips (by default read-only calls) never\n * appear.\n */\nexport type CodeModeInterruptedCalls = {\n  readonly calls: ReadonlyArray<CodeModeInterruptedCall>\n  readonly complete: boolean\n  readonly counts: {\n    readonly applied: number\n    readonly failed: number\n    readonly unknown: number\n  }\n}\n\nconst StoreWritesSchema = Schema.Struct({\n  set: Schema.Record(Schema.String, Schema.Json),\n  delete: Schema.Array(Schema.String)\n})\n\nconst CodeModeStructuredContentSchema = Schema.Struct({\n  codemode: Schema.Struct({\n    ok: Schema.Boolean,\n    storeWrites: Schema.optionalKey(StoreWritesSchema)\n  })\n})\n\nconst decodeStructuredContent = Schema.decodeUnknownOption(CodeModeStructuredContentSchema)\n\n/** Largest stored value: characters of JSON (256 KiB), as the pi engine counts them. */\nexport const maxCodeModeStoreValueChars = 256 * 1024\n\n/** Largest store: characters of keys plus JSON values (1 MiB), as the pi engine counts them. */\nexport const maxCodeModeStoreTotalChars = 1024 * 1024\n\n/** One prior tool result with the name of the tool that produced it. */\nexport type CodeModeToolResultEntry = {\n  readonly toolName: string\n  readonly result: { readonly structuredContent?: unknown }\n}\n\n/**\n * Rebuilds the code mode store from prior tool results, oldest first: applies the `storeWrites` of\n * each successful script of the code mode tool named `toolName` (default `codemode`) in order.\n * Results of other tools (even when their `structuredContent` looks like a code mode result),\n * failed scripts, and malformed contents are skipped. Transcript `ToolResultMessage`s carry no tool\n * name; pair each with the name of its assistant tool call.\n *\n * The rebuilt store keeps the engine bounds: a write whose JSON value exceeds 256 Ki characters, or\n * that would grow the store beyond 1 Mi characters (keys plus JSON values), is dropped and the key\n * keeps its previous value. Deletions always apply. Pass the value from `loadStore`.\n */\nexport const codeModeStoreFromToolResults = (\n  entries: ReadonlyArray<CodeModeToolResultEntry>,\n  options: { readonly toolName?: string } = {}\n): CodeModeStore => {\n  const toolName = options.toolName ?? codeModeToolName\n  const store = new Map<string, { readonly value: Schema.Json; readonly chars: number }>()\n  let total = 0\n\n  for (const entry of entries) {\n    if (entry.toolName !== toolName) continue\n\n    const content = decodeStructuredContent(entry.result.structuredContent)\n\n    if (Option.isNone(content) || !content.value.codemode.ok) continue\n\n    const writes = content.value.codemode.storeWrites\n\n    if (writes === undefined) continue\n\n    for (const key of writes.delete) {\n      total -= store.get(key)?.chars ?? 0\n      store.delete(key)\n    }\n\n    for (const [key, value] of Object.entries(writes.set)) {\n      const json = JSON.stringify(value)\n\n      if (json.length > maxCodeModeStoreValueChars) continue\n\n      const chars = key.length + json.length\n      const next = total - (store.get(key)?.chars ?? 0) + chars\n\n      if (next > maxCodeModeStoreTotalChars) continue\n\n      store.set(key, { value, chars })\n      total = next\n    }\n  }\n\n  return Object.fromEntries([...store].map(([key, stored]) => [key, stored.value]))\n}\n"],"mappings":";;;;AAyDA,MAAM,oBAAoB,OAAO,OAAO;CACtC,KAAK,OAAO,OAAO,OAAO,QAAQ,OAAO,IAAI;CAC7C,QAAQ,OAAO,MAAM,OAAO,MAAM;AACpC,CAAC;AAED,MAAM,kCAAkC,OAAO,OAAO,EACpD,UAAU,OAAO,OAAO;CACtB,IAAI,OAAO;CACX,aAAa,OAAO,YAAY,iBAAiB;AACnD,CAAC,EACH,CAAC;AAED,MAAM,0BAA0B,OAAO,oBAAoB,+BAA+B;;AAG1F,MAAa,6BAA6B,MAAM;;AAGhD,MAAa,6BAA6B,OAAO;;;;;;;;;;;;AAmBjD,MAAa,gCACX,SACA,UAA0C,CAAC,MACzB;CAClB,MAAM,WAAW,QAAQ,YAAA;CACzB,MAAM,wBAAQ,IAAI,IAAqE;CACvF,IAAI,QAAQ;CAEZ,KAAK,MAAM,SAAS,SAAS;EAC3B,IAAI,MAAM,aAAa,UAAU;EAEjC,MAAM,UAAU,wBAAwB,MAAM,OAAO,iBAAiB;EAEtE,IAAI,OAAO,OAAO,OAAO,KAAK,CAAC,QAAQ,MAAM,SAAS,IAAI;EAE1D,MAAM,SAAS,QAAQ,MAAM,SAAS;EAEtC,IAAI,WAAW,KAAA,GAAW;EAE1B,KAAK,MAAM,OAAO,OAAO,QAAQ;GAC/B,SAAS,MAAM,IAAI,GAAG,GAAG,SAAS;GAClC,MAAM,OAAO,GAAG;EAClB;EAEA,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,OAAO,GAAG,GAAG;GACrD,MAAM,OAAO,KAAK,UAAU,KAAK;GAEjC,IAAI,KAAK,SAAA,QAAqC;GAE9C,MAAM,QAAQ,IAAI,SAAS,KAAK;GAChC,MAAM,OAAO,SAAS,MAAM,IAAI,GAAG,GAAG,SAAS,KAAK;GAEpD,IAAI,OAAA,SAAmC;GAEvC,MAAM,IAAI,KAAK;IAAE;IAAO;GAAM,CAAC;GAC/B,QAAQ;EACV;CACF;CAEA,OAAO,OAAO,YAAY,CAAC,GAAG,KAAK,EAAE,KAAK,CAAC,KAAK,YAAY,CAAC,KAAK,OAAO,KAAK,CAAC,CAAC;AAClF"}

package/dist/tool.d.mts

@@ -0,0 +1,103 @@
+import { CodeModeExecutor, CodeModeStore } from "./executor.mjs";
+import { Effect } from "effect";
+import { ToolCall, ToolResult } from "@yolk-sdk/agent/protocol";
+import { ToolRegistration } from "@yolk-sdk/agent/tools";
+import { ToolError } from "@yolk-sdk/agent/loop";
+
+//#region src/tool.d.ts
+/** Default name of the code mode tool. */
+declare const codeModeToolName = "codemode";
+/** Host-owned limits of one script. */
+type CodeModeLimits = {
+  /** Overall deadline including nested calls. Default 120000 (clamped by `deadline`). */readonly timeoutMs?: number; /** VM heap cap. Default 64 MiB. */
+  readonly memoryLimitBytes?: number;
+  /** Nested tool calls per script; further calls reject with an Error. Default 256. The
+   * `nestedCalls` record keeps up to this many calls, at most `nestedToolCallMaxRecordedCalls`
+   * (4096) whatever the limit (argument byte budgets still apply).
+   */
+  readonly maxNestedCalls?: number; /** Model-visible result characters, cut head and tail with an omission marker. Default 40000. */
+  readonly maxOutputChars?: number; /** Images kept in the result, in order; later images are dropped with a note. Default 8. */
+  readonly maxImages?: number;
+  /** Base64 characters of images kept in the result in total; an image that would exceed it is
+   * dropped with a note. Default 4 MiB.
+   */
+  readonly maxImageBytes?: number;
+};
+declare const defaultCodeModeLimits: {
+  readonly timeoutMs: 120000;
+  readonly memoryLimitBytes: number;
+  readonly maxNestedCalls: 256;
+  readonly maxOutputChars: 40000;
+  readonly maxImages: 8;
+  readonly maxImageBytes: number;
+};
+/** Kept between a host deadline and the script deadline, for result handling. */
+declare const codeModeDeadlineMarginMs = 5000;
+/** A deadline never clamps a script below this timeout. */
+declare const codeModeMinimumTimeoutMs = 1000;
+type MakeCodeModeToolOptions<Context> = {
+  readonly executor: CodeModeExecutor; /** Default `codemode`. */
+  readonly name?: string; /** Estimated tokens (four characters each) for listing nested tools. Default 3000. */
+  readonly inlineBudget?: number;
+  readonly limits?: CodeModeLimits;
+  /**
+   * Epoch milliseconds by which the tool call must end, for example the remaining function budget
+   * of a Workflow step. The script timeout is clamped to it minus 5 s, but never below 1 s.
+   */
+  readonly deadline?: (context: Context) => number | undefined;
+  /**
+   * The store scripts read with `load(key)`, usually rebuilt from the transcript with
+   * `codeModeStoreFromToolResults`. Without it every script starts with an empty store.
+   */
+  readonly loadStore?: (context: Context) => Effect.Effect<CodeModeStore, ToolError>;
+  /**
+   * Runs before each nested call executes, with the nested call (id `<toolCallId>/<seq>`) and the
+   * host context. A failure rejects that call in the script with the message and records it as an
+   * `error` without executing it. Host decorators around the `ToolExecutor` (outside
+   * `ResolvedToolSet.execute`) never see nested calls: put per-call run-authority checks here or in
+   * registration-level wrappers.
+   */
+  readonly beforeNestedCall?: (input: {
+    readonly call: ToolCall;
+    readonly context: Context;
+  }) => Effect.Effect<void, string>;
+  /**
+   * Runs after each nested call that `beforeNestedCall` admitted, with its outcome: `success` (a
+   * result without `isError`), `failure` (an error result or an unexpected failure), or
+   * `interrupted` (cancelled, for example still running when the script ended). `durationMs`
+   * covers the execution; `result` is present when the call produced one. Calls rejected by
+   * `beforeNestedCall` or the call limit never ran and are not reported. The script waits for the
+   * hook before it sees the call settle. A failing hook (a failure, a defect, or a synchronous
+   * throw) is logged and never changes the call's result.
+   */
+  readonly afterNestedCall?: (input: CodeModeAfterNestedCallInput<Context>) => Effect.Effect<void>;
+};
+/** Outcome of a nested call for `afterNestedCall`. */
+type CodeModeNestedCallOutcome = 'success' | 'failure' | 'interrupted';
+type CodeModeAfterNestedCallInput<Context> = {
+  readonly call: ToolCall;
+  readonly outcome: CodeModeNestedCallOutcome;
+  readonly durationMs: number;
+  readonly context: Context;
+  readonly result?: ToolResult;
+};
+/**
+ * The code mode tool: one registration (default name `codemode`, input `{ code }`) whose scripts
+ * call the other code-mode-callable tools of the same `resolveTools` resolution. Nested calls run
+ * through the resolved execute path with the same host context (input decoding, enablement,
+ * registration wrappers), get ids `<toolCallId>/<seq>`, and are recorded on the result's
+ * `nestedCalls`. The resolved description lists the callable tools (see
+ * `renderCodeModeDescription`).
+ *
+ * Access is `write`: scripts can call any write tool the resolution exposes to code mode; each
+ * nested call keeps its own access metadata and host wrappers.
+ *
+ * With a tool ledger (`resolveTools(..., { ledger })`) the code mode call itself is ledgered, so a
+ * re-executed call never runs its script again: a completed call returns its stored result, an
+ * in-flight one is awaited, and an abandoned one returns an interrupted result listing its
+ * ledgered nested calls. Nested write calls are ledgered under `<toolCallId>/<seq>`.
+ */
+declare const makeCodeModeTool: <Context>(options: MakeCodeModeToolOptions<Context>) => ToolRegistration<Context>;
+//#endregion
+export { CodeModeAfterNestedCallInput, CodeModeLimits, CodeModeNestedCallOutcome, MakeCodeModeToolOptions, codeModeDeadlineMarginMs, codeModeMinimumTimeoutMs, codeModeToolName, defaultCodeModeLimits, makeCodeModeTool };
+//# sourceMappingURL=tool.d.mts.map

package/dist/tool.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.mts","names":[],"sources":["../src/tool.ts"],"mappings":";;;;;;;;cAsEa,gBAAA;AAAb;AAAA,KAGY,cAAA;kGAED,SAAA,WALkB;EAAA,SAOlB,gBAAA;EAJe;;;;EAAA,SASf,cAAA;EAAA,SAEA,cAAA,WAEA;EAAA,SAAA,SAAA;EAIa;AAAA;AAGxB;EAHwB,SAAb,aAAA;AAAA;AAAA,cAGE,qBAAA;EAAA;;;;;;;;cAUA,wBAAA;;cAGA,wBAAA;AAAA,KAED,uBAAA;EAAA,SACD,QAAA,EAAU,gBAAA,EAHR;EAAA,SAKF,IAAA;WAEA,YAAA;EAAA,SACA,MAAA,GAAS,cAAA;EANR;;;;EAAA,SAWD,QAAA,IAAY,OAAA,EAAS,OAAA;EAAA;;;;EAAA,SAKrB,SAAA,IAAa,OAAA,EAAS,OAAA,KAAY,MAAA,CAAO,MAAA,CAAO,aAAA,EAAe,SAAA;EASvD;;;;;;;EAAA,SADR,gBAAA,IAAoB,KAAA;IAAA,SAClB,IAAA,EAAM,QAAA;IAAA,SACN,OAAA,EAAS,OAAA;EAAA,MACd,MAAA,CAAO,MAAA;EAxBJ;;;;;;;;;EAAA,SAkCA,eAAA,IAAmB,KAAA,EAAO,4BAAA,CAA6B,OAAA,MAAa,MAAA,CAAO,MAAA;AAAA;;KAI1E,yBAAA;AAAA,KAEA,4BAAA;EAAA,SACD,IAAA,EAAM,QAAA;EAAA,SACN,OAAA,EAAS,yBAAA;EAAA,SACT,UAAA;EAAA,SACA,OAAA,EAAS,OAAA;EAAA,SACT,MAAA,GAAS,UAAA;AAAA;;;;;;;;;;AAXwE;AAI5F;;;;AAAqC;AAErC;cAskBa,gBAAA,YACX,OAAA,EAAS,uBAAA,CAAwB,OAAA,MAChC,gBAAA,CAAiB,OAAA"}