@langchain/langgraph-sdk 1.8.5 → 1.8.6

package/dist/headless-tools.cjs

@@ -0,0 +1,114 @@
+//#region src/headless-tools.ts
+/**
+* Strip headless-tool interrupts from a user-facing interrupt list.
+*/
+function filterOutHeadlessToolInterrupts(interrupts) {
+	return interrupts.filter((interrupt) => interrupt.value == null || !isHeadlessToolInterrupt(interrupt.value));
+}
+function isHeadlessToolInterrupt(interrupt) {
+	if (typeof interrupt !== "object" || interrupt == null) return false;
+	const value = interrupt;
+	return value.type === "tool" && typeof value.toolCall === "object" && value.toolCall != null && typeof value.toolCall.name === "string";
+}
+function findHeadlessTool(tools, name) {
+	return tools.find((tool) => tool.tool.name === name);
+}
+async function executeHeadlessTool(implementation, args, onTool) {
+	const startTime = Date.now();
+	onTool?.({
+		phase: "start",
+		name: implementation.tool.name,
+		args
+	});
+	try {
+		const result = await implementation.execute(args);
+		const duration = Date.now() - startTime;
+		onTool?.({
+			phase: "success",
+			name: implementation.tool.name,
+			args,
+			result,
+			duration
+		});
+		return {
+			success: true,
+			result
+		};
+	} catch (err) {
+		const error = err instanceof Error ? err : new Error(String(err));
+		const duration = Date.now() - startTime;
+		onTool?.({
+			phase: "error",
+			name: implementation.tool.name,
+			args,
+			error,
+			duration
+		});
+		return {
+			success: false,
+			error
+		};
+	}
+}
+async function handleHeadlessToolInterrupt(interrupt, tools, onTool) {
+	const { toolCall } = interrupt;
+	const implementation = findHeadlessTool(tools, toolCall.name);
+	if (!implementation) {
+		const error = /* @__PURE__ */ new Error(`Headless tool "${toolCall.name}" is not registered. Available tools: ${tools.map((tool) => tool.tool.name).join(", ") || "none"}`);
+		onTool?.({
+			phase: "error",
+			name: toolCall.name,
+			args: toolCall.args,
+			error,
+			duration: 0
+		});
+		return {
+			toolCallId: toolCall.id,
+			value: { error: error.message }
+		};
+	}
+	const result = await executeHeadlessTool(implementation, toolCall.args, onTool);
+	if (result.success) return {
+		toolCallId: toolCall.id,
+		value: result.result
+	};
+	return {
+		toolCallId: toolCall.id,
+		value: { error: result.error.message }
+	};
+}
+function headlessToolResumeCommand(result) {
+	return { resume: result.toolCallId ? { [result.toolCallId]: result.value } : result.value };
+}
+/**
+* Execute and resume all newly seen headless-tool interrupts from a values
+* payload. Callers own `handledIds` and should clear it when the thread changes.
+*/
+function flushPendingHeadlessToolInterrupts(values, tools, handledIds, options) {
+	if (!tools?.length || !values) return;
+	const interrupts = values.__interrupt__;
+	if (!Array.isArray(interrupts) || interrupts.length === 0) return;
+	const defer = options.defer ?? ((run) => run());
+	for (const interrupt of interrupts) {
+		if (!isHeadlessToolInterrupt(interrupt.value)) continue;
+		const headlessInterrupt = interrupt.value;
+		const interruptId = interrupt.id ?? headlessInterrupt.toolCall.id ?? "";
+		if (handledIds.has(interruptId)) continue;
+		handledIds.add(interruptId);
+		defer(() => {
+			handleHeadlessToolInterrupt(headlessInterrupt, tools, options.onTool).then((result) => {
+				options.resumeSubmit(headlessToolResumeCommand(result));
+			});
+		});
+	}
+}
+//#endregion
+exports.executeHeadlessTool = executeHeadlessTool;
+exports.filterOutHeadlessToolInterrupts = filterOutHeadlessToolInterrupts;
+exports.findHeadlessTool = findHeadlessTool;
+exports.flushPendingHeadlessToolInterrupts = flushPendingHeadlessToolInterrupts;
+exports.handleHeadlessToolInterrupt = handleHeadlessToolInterrupt;
+exports.headlessToolResumeCommand = headlessToolResumeCommand;
+exports.isHeadlessToolInterrupt = isHeadlessToolInterrupt;
+
+//# sourceMappingURL=headless-tools.cjs.map

package/dist/headless-tools.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"headless-tools.cjs","names":[],"sources":["../src/headless-tools.ts"],"sourcesContent":["import type { Interrupt } from \"./schema.js\";\n\n/**\n * Represents a headless tool interrupt payload emitted by LangChain's\n * schema-only `tool({ ... })` overload.\n */\nexport interface HeadlessToolInterrupt {\n  type: \"tool\";\n  toolCall: {\n    id: string | undefined;\n    name: string;\n    args: unknown;\n  };\n}\n\n/**\n * Client-side implementation returned by `headlessTool.implement(...)`.\n */\nexport interface HeadlessToolImplementation<Args = unknown, Output = unknown> {\n  tool: {\n    name: string;\n  };\n  execute: (args: Args) => Promise<Output>;\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type AnyHeadlessToolImplementation = HeadlessToolImplementation<\n  any,\n  any\n>;\n\nexport interface ToolEvent {\n  phase: \"start\" | \"success\" | \"error\";\n  name: string;\n  args: unknown;\n  result?: unknown;\n  error?: Error;\n  duration?: number;\n}\n\nexport type OnToolCallback = (event: ToolEvent) => void;\n\n/**\n * Strip headless-tool interrupts from a user-facing interrupt list.\n */\nexport function filterOutHeadlessToolInterrupts<T extends { value?: unknown }>(\n  interrupts: readonly T[]\n): T[] {\n  return interrupts.filter(\n    (interrupt) =>\n      interrupt.value == null || !isHeadlessToolInterrupt(interrupt.value)\n  );\n}\n\nexport function isHeadlessToolInterrupt(\n  interrupt: unknown\n): interrupt is HeadlessToolInterrupt {\n  if (typeof interrupt !== \"object\" || interrupt == null) {\n    return false;\n  }\n\n  const value = interrupt as Record<string, unknown>;\n  return (\n    value.type === \"tool\" &&\n    typeof value.toolCall === \"object\" &&\n    value.toolCall != null &&\n    typeof (value.toolCall as Record<string, unknown>).name === \"string\"\n  );\n}\n\nexport function findHeadlessTool<Args = unknown, Output = unknown>(\n  tools: HeadlessToolImplementation[],\n  name: string\n): HeadlessToolImplementation<Args, Output> | undefined {\n  return tools.find((tool) => tool.tool.name === name) as\n    | HeadlessToolImplementation<Args, Output>\n    | undefined;\n}\n\nexport async function executeHeadlessTool<Args = unknown, Output = unknown>(\n  implementation: HeadlessToolImplementation<Args, Output>,\n  args: Args,\n  onTool?: OnToolCallback\n): Promise<\n  { success: true; result: Output } | { success: false; error: Error }\n> {\n  const startTime = Date.now();\n\n  onTool?.({\n    phase: \"start\",\n    name: implementation.tool.name,\n    args,\n  });\n\n  try {\n    const result = await implementation.execute(args);\n    const duration = Date.now() - startTime;\n\n    onTool?.({\n      phase: \"success\",\n      name: implementation.tool.name,\n      args,\n      result,\n      duration,\n    });\n\n    return { success: true, result };\n  } catch (err) {\n    // oxlint-disable-next-line no-instanceof/no-instanceof\n    const error = err instanceof Error ? err : new Error(String(err));\n    const duration = Date.now() - startTime;\n\n    onTool?.({\n      phase: \"error\",\n      name: implementation.tool.name,\n      args,\n      error,\n      duration,\n    });\n\n    return { success: false, error };\n  }\n}\n\nexport async function handleHeadlessToolInterrupt(\n  interrupt: HeadlessToolInterrupt,\n  tools: HeadlessToolImplementation[],\n  onTool?: OnToolCallback\n): Promise<{ toolCallId: string | undefined; value: unknown }> {\n  const { toolCall } = interrupt;\n  const implementation = findHeadlessTool(tools, toolCall.name);\n\n  if (!implementation) {\n    const error = new Error(\n      `Headless tool \"${toolCall.name}\" is not registered. ` +\n        `Available tools: ${tools.map((tool) => tool.tool.name).join(\", \") || \"none\"}`\n    );\n\n    onTool?.({\n      phase: \"error\",\n      name: toolCall.name,\n      args: toolCall.args,\n      error,\n      duration: 0,\n    });\n\n    return {\n      toolCallId: toolCall.id,\n      value: { error: error.message },\n    };\n  }\n\n  const result = await executeHeadlessTool(\n    implementation,\n    toolCall.args as never,\n    onTool\n  );\n\n  if (result.success) {\n    return {\n      toolCallId: toolCall.id,\n      value: result.result,\n    };\n  }\n\n  return {\n    toolCallId: toolCall.id,\n    value: { error: result.error.message },\n  };\n}\n\nexport function headlessToolResumeCommand(result: {\n  toolCallId: string | undefined;\n  value: unknown;\n}): { resume: unknown } {\n  return {\n    resume: result.toolCallId\n      ? { [result.toolCallId]: result.value }\n      : result.value,\n  };\n}\n\nexport interface FlushPendingHeadlessToolInterruptsOptions {\n  onTool?: OnToolCallback;\n  resumeSubmit: (command: { resume: unknown }) => void | Promise<void>;\n  defer?: (run: () => void) => void;\n}\n\n/**\n * Execute and resume all newly seen headless-tool interrupts from a values\n * payload. Callers own `handledIds` and should clear it when the thread changes.\n */\nexport function flushPendingHeadlessToolInterrupts(\n  values: Record<string, unknown> | null | undefined,\n  tools: HeadlessToolImplementation[] | undefined,\n  handledIds: Set<string>,\n  options: FlushPendingHeadlessToolInterruptsOptions\n): void {\n  if (!tools?.length || !values) return;\n\n  const interrupts = values.__interrupt__;\n  if (!Array.isArray(interrupts) || interrupts.length === 0) return;\n\n  const defer = options.defer ?? ((run) => run());\n\n  for (const interrupt of interrupts as Interrupt[]) {\n    if (!isHeadlessToolInterrupt(interrupt.value)) continue;\n    const headlessInterrupt = interrupt.value;\n\n    const interruptId = interrupt.id ?? headlessInterrupt.toolCall.id ?? \"\";\n    if (handledIds.has(interruptId)) continue;\n    handledIds.add(interruptId);\n\n    defer(() => {\n      void handleHeadlessToolInterrupt(\n        headlessInterrupt,\n        tools,\n        options.onTool\n      ).then((result) => {\n        void options.resumeSubmit(headlessToolResumeCommand(result));\n      });\n    });\n  }\n}\n"],"mappings":";;;;AA6CA,SAAgB,gCACd,YACK;AACL,QAAO,WAAW,QACf,cACC,UAAU,SAAS,QAAQ,CAAC,wBAAwB,UAAU,MAAM,CACvE;;AAGH,SAAgB,wBACd,WACoC;AACpC,KAAI,OAAO,cAAc,YAAY,aAAa,KAChD,QAAO;CAGT,MAAM,QAAQ;AACd,QACE,MAAM,SAAS,UACf,OAAO,MAAM,aAAa,YAC1B,MAAM,YAAY,QAClB,OAAQ,MAAM,SAAqC,SAAS;;AAIhE,SAAgB,iBACd,OACA,MACsD;AACtD,QAAO,MAAM,MAAM,SAAS,KAAK,KAAK,SAAS,KAAK;;AAKtD,eAAsB,oBACpB,gBACA,MACA,QAGA;CACA,MAAM,YAAY,KAAK,KAAK;AAE5B,UAAS;EACP,OAAO;EACP,MAAM,eAAe,KAAK;EAC1B;EACD,CAAC;AAEF,KAAI;EACF,MAAM,SAAS,MAAM,eAAe,QAAQ,KAAK;EACjD,MAAM,WAAW,KAAK,KAAK,GAAG;AAE9B,WAAS;GACP,OAAO;GACP,MAAM,eAAe,KAAK;GAC1B;GACA;GACA;GACD,CAAC;AAEF,SAAO;GAAE,SAAS;GAAM;GAAQ;UACzB,KAAK;EAEZ,MAAM,QAAQ,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,IAAI,CAAC;EACjE,MAAM,WAAW,KAAK,KAAK,GAAG;AAE9B,WAAS;GACP,OAAO;GACP,MAAM,eAAe,KAAK;GAC1B;GACA;GACA;GACD,CAAC;AAEF,SAAO;GAAE,SAAS;GAAO;GAAO;;;AAIpC,eAAsB,4BACpB,WACA,OACA,QAC6D;CAC7D,MAAM,EAAE,aAAa;CACrB,MAAM,iBAAiB,iBAAiB,OAAO,SAAS,KAAK;AAE7D,KAAI,CAAC,gBAAgB;EACnB,MAAM,wBAAQ,IAAI,MAChB,kBAAkB,SAAS,KAAK,wCACV,MAAM,KAAK,SAAS,KAAK,KAAK,KAAK,CAAC,KAAK,KAAK,IAAI,SACzE;AAED,WAAS;GACP,OAAO;GACP,MAAM,SAAS;GACf,MAAM,SAAS;GACf;GACA,UAAU;GACX,CAAC;AAEF,SAAO;GACL,YAAY,SAAS;GACrB,OAAO,EAAE,OAAO,MAAM,SAAS;GAChC;;CAGH,MAAM,SAAS,MAAM,oBACnB,gBACA,SAAS,MACT,OACD;AAED,KAAI,OAAO,QACT,QAAO;EACL,YAAY,SAAS;EACrB,OAAO,OAAO;EACf;AAGH,QAAO;EACL,YAAY,SAAS;EACrB,OAAO,EAAE,OAAO,OAAO,MAAM,SAAS;EACvC;;AAGH,SAAgB,0BAA0B,QAGlB;AACtB,QAAO,EACL,QAAQ,OAAO,aACX,GAAG,OAAO,aAAa,OAAO,OAAO,GACrC,OAAO,OACZ;;;;;;AAaH,SAAgB,mCACd,QACA,OACA,YACA,SACM;AACN,KAAI,CAAC,OAAO,UAAU,CAAC,OAAQ;CAE/B,MAAM,aAAa,OAAO;AAC1B,KAAI,CAAC,MAAM,QAAQ,WAAW,IAAI,WAAW,WAAW,EAAG;CAE3D,MAAM,QAAQ,QAAQ,WAAW,QAAQ,KAAK;AAE9C,MAAK,MAAM,aAAa,YAA2B;AACjD,MAAI,CAAC,wBAAwB,UAAU,MAAM,CAAE;EAC/C,MAAM,oBAAoB,UAAU;EAEpC,MAAM,cAAc,UAAU,MAAM,kBAAkB,SAAS,MAAM;AACrE,MAAI,WAAW,IAAI,YAAY,CAAE;AACjC,aAAW,IAAI,YAAY;AAE3B,cAAY;AACL,+BACH,mBACA,OACA,QAAQ,OACT,CAAC,MAAM,WAAW;AACZ,YAAQ,aAAa,0BAA0B,OAAO,CAAC;KAC5D;IACF"}

package/dist/headless-tools.d.cts

@@ -0,0 +1,72 @@
+//#region src/headless-tools.d.ts
+/**
+ * Represents a headless tool interrupt payload emitted by LangChain's
+ * schema-only `tool({ ... })` overload.
+ */
+interface HeadlessToolInterrupt {
+  type: "tool";
+  toolCall: {
+    id: string | undefined;
+    name: string;
+    args: unknown;
+  };
+}
+/**
+ * Client-side implementation returned by `headlessTool.implement(...)`.
+ */
+interface HeadlessToolImplementation<Args = unknown, Output = unknown> {
+  tool: {
+    name: string;
+  };
+  execute: (args: Args) => Promise<Output>;
+}
+type AnyHeadlessToolImplementation = HeadlessToolImplementation<any, any>;
+interface ToolEvent {
+  phase: "start" | "success" | "error";
+  name: string;
+  args: unknown;
+  result?: unknown;
+  error?: Error;
+  duration?: number;
+}
+type OnToolCallback = (event: ToolEvent) => void;
+/**
+ * Strip headless-tool interrupts from a user-facing interrupt list.
+ */
+declare function filterOutHeadlessToolInterrupts<T extends {
+  value?: unknown;
+}>(interrupts: readonly T[]): T[];
+declare function isHeadlessToolInterrupt(interrupt: unknown): interrupt is HeadlessToolInterrupt;
+declare function findHeadlessTool<Args = unknown, Output = unknown>(tools: HeadlessToolImplementation[], name: string): HeadlessToolImplementation<Args, Output> | undefined;
+declare function executeHeadlessTool<Args = unknown, Output = unknown>(implementation: HeadlessToolImplementation<Args, Output>, args: Args, onTool?: OnToolCallback): Promise<{
+  success: true;
+  result: Output;
+} | {
+  success: false;
+  error: Error;
+}>;
+declare function handleHeadlessToolInterrupt(interrupt: HeadlessToolInterrupt, tools: HeadlessToolImplementation[], onTool?: OnToolCallback): Promise<{
+  toolCallId: string | undefined;
+  value: unknown;
+}>;
+declare function headlessToolResumeCommand(result: {
+  toolCallId: string | undefined;
+  value: unknown;
+}): {
+  resume: unknown;
+};
+interface FlushPendingHeadlessToolInterruptsOptions {
+  onTool?: OnToolCallback;
+  resumeSubmit: (command: {
+    resume: unknown;
+  }) => void | Promise<void>;
+  defer?: (run: () => void) => void;
+}
+/**
+ * Execute and resume all newly seen headless-tool interrupts from a values
+ * payload. Callers own `handledIds` and should clear it when the thread changes.
+ */
+declare function flushPendingHeadlessToolInterrupts(values: Record<string, unknown> | null | undefined, tools: HeadlessToolImplementation[] | undefined, handledIds: Set<string>, options: FlushPendingHeadlessToolInterruptsOptions): void;
+//#endregion
+export { AnyHeadlessToolImplementation, FlushPendingHeadlessToolInterruptsOptions, HeadlessToolImplementation, HeadlessToolInterrupt, OnToolCallback, ToolEvent, executeHeadlessTool, filterOutHeadlessToolInterrupts, findHeadlessTool, flushPendingHeadlessToolInterrupts, handleHeadlessToolInterrupt, headlessToolResumeCommand, isHeadlessToolInterrupt };
+//# sourceMappingURL=headless-tools.d.cts.map

package/dist/headless-tools.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headless-tools.d.cts","names":[],"sources":["../src/headless-tools.ts"],"mappings":";;AAMA;;;UAAiB,qBAAA;EACf,IAAA;EACA,QAAA;IACE,EAAA;IACA,IAAA;IACA,IAAA;EAAA;AAAA;AAOJ;;;AAAA,UAAiB,0BAAA;EACf,IAAA;IACE,IAAA;EAAA;EAEF,OAAA,GAAU,IAAA,EAAM,IAAA,KAAS,OAAA,CAAQ,MAAA;AAAA;AAAA,KAIvB,6BAAA,GAAgC,0BAAA;AAAA,UAK3B,SAAA;EACf,KAAA;EACA,IAAA;EACA,IAAA;EACA,MAAA;EACA,KAAA,GAAQ,KAAA;EACR,QAAA;AAAA;AAAA,KAGU,cAAA,IAAkB,KAAA,EAAO,SAAA;AAdrC;;;AAAA,iBAmBgB,+BAAA;EAA4C,KAAA;AAAA,EAAA,CAC1D,UAAA,WAAqB,CAAA,KACpB,CAAA;AAAA,iBAOa,uBAAA,CACd,SAAA,YACC,SAAA,IAAa,qBAAA;AAAA,iBAcA,gBAAA,kCAAA,CACd,KAAA,EAAO,0BAAA,IACP,IAAA,WACC,0BAAA,CAA2B,IAAA,EAAM,MAAA;AAAA,iBAMd,mBAAA,kCAAA,CACpB,cAAA,EAAgB,0BAAA,CAA2B,IAAA,EAAM,MAAA,GACjD,IAAA,EAAM,IAAA,EACN,MAAA,GAAS,cAAA,GACR,OAAA;EACC,OAAA;EAAe,MAAA,EAAQ,MAAA;AAAA;EAAa,OAAA;EAAgB,KAAA,EAAO,KAAA;AAAA;AAAA,iBAwCzC,2BAAA,CACpB,SAAA,EAAW,qBAAA,EACX,KAAA,EAAO,0BAAA,IACP,MAAA,GAAS,cAAA,GACR,OAAA;EAAU,UAAA;EAAgC,KAAA;AAAA;AAAA,iBA2C7B,yBAAA,CAA0B,MAAA;EACxC,UAAA;EACA,KAAA;AAAA;EACI,MAAA;AAAA;AAAA,UAQW,yCAAA;EACf,MAAA,GAAS,cAAA;EACT,YAAA,GAAe,OAAA;IAAW,MAAA;EAAA,aAA6B,OAAA;EACvD,KAAA,IAAS,GAAA;AAAA;;;AAnIX;;iBA0IgB,kCAAA,CACd,MAAA,EAAQ,MAAA,sCACR,KAAA,EAAO,0BAAA,gBACP,UAAA,EAAY,GAAA,UACZ,OAAA,EAAS,yCAAA"}

package/dist/headless-tools.d.ts

@@ -0,0 +1,72 @@
+//#region src/headless-tools.d.ts
+/**
+ * Represents a headless tool interrupt payload emitted by LangChain's
+ * schema-only `tool({ ... })` overload.
+ */
+interface HeadlessToolInterrupt {
+  type: "tool";
+  toolCall: {
+    id: string | undefined;
+    name: string;
+    args: unknown;
+  };
+}
+/**
+ * Client-side implementation returned by `headlessTool.implement(...)`.
+ */
+interface HeadlessToolImplementation<Args = unknown, Output = unknown> {
+  tool: {
+    name: string;
+  };
+  execute: (args: Args) => Promise<Output>;
+}
+type AnyHeadlessToolImplementation = HeadlessToolImplementation<any, any>;
+interface ToolEvent {
+  phase: "start" | "success" | "error";
+  name: string;
+  args: unknown;
+  result?: unknown;
+  error?: Error;
+  duration?: number;
+}
+type OnToolCallback = (event: ToolEvent) => void;
+/**
+ * Strip headless-tool interrupts from a user-facing interrupt list.
+ */
+declare function filterOutHeadlessToolInterrupts<T extends {
+  value?: unknown;
+}>(interrupts: readonly T[]): T[];
+declare function isHeadlessToolInterrupt(interrupt: unknown): interrupt is HeadlessToolInterrupt;
+declare function findHeadlessTool<Args = unknown, Output = unknown>(tools: HeadlessToolImplementation[], name: string): HeadlessToolImplementation<Args, Output> | undefined;
+declare function executeHeadlessTool<Args = unknown, Output = unknown>(implementation: HeadlessToolImplementation<Args, Output>, args: Args, onTool?: OnToolCallback): Promise<{
+  success: true;
+  result: Output;
+} | {
+  success: false;
+  error: Error;
+}>;
+declare function handleHeadlessToolInterrupt(interrupt: HeadlessToolInterrupt, tools: HeadlessToolImplementation[], onTool?: OnToolCallback): Promise<{
+  toolCallId: string | undefined;
+  value: unknown;
+}>;
+declare function headlessToolResumeCommand(result: {
+  toolCallId: string | undefined;
+  value: unknown;
+}): {
+  resume: unknown;
+};
+interface FlushPendingHeadlessToolInterruptsOptions {
+  onTool?: OnToolCallback;
+  resumeSubmit: (command: {
+    resume: unknown;
+  }) => void | Promise<void>;
+  defer?: (run: () => void) => void;
+}
+/**
+ * Execute and resume all newly seen headless-tool interrupts from a values
+ * payload. Callers own `handledIds` and should clear it when the thread changes.
+ */
+declare function flushPendingHeadlessToolInterrupts(values: Record<string, unknown> | null | undefined, tools: HeadlessToolImplementation[] | undefined, handledIds: Set<string>, options: FlushPendingHeadlessToolInterruptsOptions): void;
+//#endregion
+export { AnyHeadlessToolImplementation, FlushPendingHeadlessToolInterruptsOptions, HeadlessToolImplementation, HeadlessToolInterrupt, OnToolCallback, ToolEvent, executeHeadlessTool, filterOutHeadlessToolInterrupts, findHeadlessTool, flushPendingHeadlessToolInterrupts, handleHeadlessToolInterrupt, headlessToolResumeCommand, isHeadlessToolInterrupt };
+//# sourceMappingURL=headless-tools.d.ts.map

package/dist/headless-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headless-tools.d.ts","names":[],"sources":["../src/headless-tools.ts"],"mappings":";;AAMA;;;UAAiB,qBAAA;EACf,IAAA;EACA,QAAA;IACE,EAAA;IACA,IAAA;IACA,IAAA;EAAA;AAAA;AAOJ;;;AAAA,UAAiB,0BAAA;EACf,IAAA;IACE,IAAA;EAAA;EAEF,OAAA,GAAU,IAAA,EAAM,IAAA,KAAS,OAAA,CAAQ,MAAA;AAAA;AAAA,KAIvB,6BAAA,GAAgC,0BAAA;AAAA,UAK3B,SAAA;EACf,KAAA;EACA,IAAA;EACA,IAAA;EACA,MAAA;EACA,KAAA,GAAQ,KAAA;EACR,QAAA;AAAA;AAAA,KAGU,cAAA,IAAkB,KAAA,EAAO,SAAA;AAdrC;;;AAAA,iBAmBgB,+BAAA;EAA4C,KAAA;AAAA,EAAA,CAC1D,UAAA,WAAqB,CAAA,KACpB,CAAA;AAAA,iBAOa,uBAAA,CACd,SAAA,YACC,SAAA,IAAa,qBAAA;AAAA,iBAcA,gBAAA,kCAAA,CACd,KAAA,EAAO,0BAAA,IACP,IAAA,WACC,0BAAA,CAA2B,IAAA,EAAM,MAAA;AAAA,iBAMd,mBAAA,kCAAA,CACpB,cAAA,EAAgB,0BAAA,CAA2B,IAAA,EAAM,MAAA,GACjD,IAAA,EAAM,IAAA,EACN,MAAA,GAAS,cAAA,GACR,OAAA;EACC,OAAA;EAAe,MAAA,EAAQ,MAAA;AAAA;EAAa,OAAA;EAAgB,KAAA,EAAO,KAAA;AAAA;AAAA,iBAwCzC,2BAAA,CACpB,SAAA,EAAW,qBAAA,EACX,KAAA,EAAO,0BAAA,IACP,MAAA,GAAS,cAAA,GACR,OAAA;EAAU,UAAA;EAAgC,KAAA;AAAA;AAAA,iBA2C7B,yBAAA,CAA0B,MAAA;EACxC,UAAA;EACA,KAAA;AAAA;EACI,MAAA;AAAA;AAAA,UAQW,yCAAA;EACf,MAAA,GAAS,cAAA;EACT,YAAA,GAAe,OAAA;IAAW,MAAA;EAAA,aAA6B,OAAA;EACvD,KAAA,IAAS,GAAA;AAAA;;;AAnIX;;iBA0IgB,kCAAA,CACd,MAAA,EAAQ,MAAA,sCACR,KAAA,EAAO,0BAAA,gBACP,UAAA,EAAY,GAAA,UACZ,OAAA,EAAS,yCAAA"}

package/dist/headless-tools.js

@@ -0,0 +1,108 @@
+//#region src/headless-tools.ts
+/**
+* Strip headless-tool interrupts from a user-facing interrupt list.
+*/
+function filterOutHeadlessToolInterrupts(interrupts) {
+	return interrupts.filter((interrupt) => interrupt.value == null || !isHeadlessToolInterrupt(interrupt.value));
+}
+function isHeadlessToolInterrupt(interrupt) {
+	if (typeof interrupt !== "object" || interrupt == null) return false;
+	const value = interrupt;
+	return value.type === "tool" && typeof value.toolCall === "object" && value.toolCall != null && typeof value.toolCall.name === "string";
+}
+function findHeadlessTool(tools, name) {
+	return tools.find((tool) => tool.tool.name === name);
+}
+async function executeHeadlessTool(implementation, args, onTool) {
+	const startTime = Date.now();
+	onTool?.({
+		phase: "start",
+		name: implementation.tool.name,
+		args
+	});
+	try {
+		const result = await implementation.execute(args);
+		const duration = Date.now() - startTime;
+		onTool?.({
+			phase: "success",
+			name: implementation.tool.name,
+			args,
+			result,
+			duration
+		});
+		return {
+			success: true,
+			result
+		};
+	} catch (err) {
+		const error = err instanceof Error ? err : new Error(String(err));
+		const duration = Date.now() - startTime;
+		onTool?.({
+			phase: "error",
+			name: implementation.tool.name,
+			args,
+			error,
+			duration
+		});
+		return {
+			success: false,
+			error
+		};
+	}
+}
+async function handleHeadlessToolInterrupt(interrupt, tools, onTool) {
+	const { toolCall } = interrupt;
+	const implementation = findHeadlessTool(tools, toolCall.name);
+	if (!implementation) {
+		const error = /* @__PURE__ */ new Error(`Headless tool "${toolCall.name}" is not registered. Available tools: ${tools.map((tool) => tool.tool.name).join(", ") || "none"}`);
+		onTool?.({
+			phase: "error",
+			name: toolCall.name,
+			args: toolCall.args,
+			error,
+			duration: 0
+		});
+		return {
+			toolCallId: toolCall.id,
+			value: { error: error.message }
+		};
+	}
+	const result = await executeHeadlessTool(implementation, toolCall.args, onTool);
+	if (result.success) return {
+		toolCallId: toolCall.id,
+		value: result.result
+	};
+	return {
+		toolCallId: toolCall.id,
+		value: { error: result.error.message }
+	};
+}
+function headlessToolResumeCommand(result) {
+	return { resume: result.toolCallId ? { [result.toolCallId]: result.value } : result.value };
+}
+/**
+* Execute and resume all newly seen headless-tool interrupts from a values
+* payload. Callers own `handledIds` and should clear it when the thread changes.
+*/
+function flushPendingHeadlessToolInterrupts(values, tools, handledIds, options) {
+	if (!tools?.length || !values) return;
+	const interrupts = values.__interrupt__;
+	if (!Array.isArray(interrupts) || interrupts.length === 0) return;
+	const defer = options.defer ?? ((run) => run());
+	for (const interrupt of interrupts) {
+		if (!isHeadlessToolInterrupt(interrupt.value)) continue;
+		const headlessInterrupt = interrupt.value;
+		const interruptId = interrupt.id ?? headlessInterrupt.toolCall.id ?? "";
+		if (handledIds.has(interruptId)) continue;
+		handledIds.add(interruptId);
+		defer(() => {
+			handleHeadlessToolInterrupt(headlessInterrupt, tools, options.onTool).then((result) => {
+				options.resumeSubmit(headlessToolResumeCommand(result));
+			});
+		});
+	}
+}
+//#endregion
+export { executeHeadlessTool, filterOutHeadlessToolInterrupts, findHeadlessTool, flushPendingHeadlessToolInterrupts, handleHeadlessToolInterrupt, headlessToolResumeCommand, isHeadlessToolInterrupt };
+
+//# sourceMappingURL=headless-tools.js.map

package/dist/headless-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"headless-tools.js","names":[],"sources":["../src/headless-tools.ts"],"sourcesContent":["import type { Interrupt } from \"./schema.js\";\n\n/**\n * Represents a headless tool interrupt payload emitted by LangChain's\n * schema-only `tool({ ... })` overload.\n */\nexport interface HeadlessToolInterrupt {\n  type: \"tool\";\n  toolCall: {\n    id: string | undefined;\n    name: string;\n    args: unknown;\n  };\n}\n\n/**\n * Client-side implementation returned by `headlessTool.implement(...)`.\n */\nexport interface HeadlessToolImplementation<Args = unknown, Output = unknown> {\n  tool: {\n    name: string;\n  };\n  execute: (args: Args) => Promise<Output>;\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type AnyHeadlessToolImplementation = HeadlessToolImplementation<\n  any,\n  any\n>;\n\nexport interface ToolEvent {\n  phase: \"start\" | \"success\" | \"error\";\n  name: string;\n  args: unknown;\n  result?: unknown;\n  error?: Error;\n  duration?: number;\n}\n\nexport type OnToolCallback = (event: ToolEvent) => void;\n\n/**\n * Strip headless-tool interrupts from a user-facing interrupt list.\n */\nexport function filterOutHeadlessToolInterrupts<T extends { value?: unknown }>(\n  interrupts: readonly T[]\n): T[] {\n  return interrupts.filter(\n    (interrupt) =>\n      interrupt.value == null || !isHeadlessToolInterrupt(interrupt.value)\n  );\n}\n\nexport function isHeadlessToolInterrupt(\n  interrupt: unknown\n): interrupt is HeadlessToolInterrupt {\n  if (typeof interrupt !== \"object\" || interrupt == null) {\n    return false;\n  }\n\n  const value = interrupt as Record<string, unknown>;\n  return (\n    value.type === \"tool\" &&\n    typeof value.toolCall === \"object\" &&\n    value.toolCall != null &&\n    typeof (value.toolCall as Record<string, unknown>).name === \"string\"\n  );\n}\n\nexport function findHeadlessTool<Args = unknown, Output = unknown>(\n  tools: HeadlessToolImplementation[],\n  name: string\n): HeadlessToolImplementation<Args, Output> | undefined {\n  return tools.find((tool) => tool.tool.name === name) as\n    | HeadlessToolImplementation<Args, Output>\n    | undefined;\n}\n\nexport async function executeHeadlessTool<Args = unknown, Output = unknown>(\n  implementation: HeadlessToolImplementation<Args, Output>,\n  args: Args,\n  onTool?: OnToolCallback\n): Promise<\n  { success: true; result: Output } | { success: false; error: Error }\n> {\n  const startTime = Date.now();\n\n  onTool?.({\n    phase: \"start\",\n    name: implementation.tool.name,\n    args,\n  });\n\n  try {\n    const result = await implementation.execute(args);\n    const duration = Date.now() - startTime;\n\n    onTool?.({\n      phase: \"success\",\n      name: implementation.tool.name,\n      args,\n      result,\n      duration,\n    });\n\n    return { success: true, result };\n  } catch (err) {\n    // oxlint-disable-next-line no-instanceof/no-instanceof\n    const error = err instanceof Error ? err : new Error(String(err));\n    const duration = Date.now() - startTime;\n\n    onTool?.({\n      phase: \"error\",\n      name: implementation.tool.name,\n      args,\n      error,\n      duration,\n    });\n\n    return { success: false, error };\n  }\n}\n\nexport async function handleHeadlessToolInterrupt(\n  interrupt: HeadlessToolInterrupt,\n  tools: HeadlessToolImplementation[],\n  onTool?: OnToolCallback\n): Promise<{ toolCallId: string | undefined; value: unknown }> {\n  const { toolCall } = interrupt;\n  const implementation = findHeadlessTool(tools, toolCall.name);\n\n  if (!implementation) {\n    const error = new Error(\n      `Headless tool \"${toolCall.name}\" is not registered. ` +\n        `Available tools: ${tools.map((tool) => tool.tool.name).join(\", \") || \"none\"}`\n    );\n\n    onTool?.({\n      phase: \"error\",\n      name: toolCall.name,\n      args: toolCall.args,\n      error,\n      duration: 0,\n    });\n\n    return {\n      toolCallId: toolCall.id,\n      value: { error: error.message },\n    };\n  }\n\n  const result = await executeHeadlessTool(\n    implementation,\n    toolCall.args as never,\n    onTool\n  );\n\n  if (result.success) {\n    return {\n      toolCallId: toolCall.id,\n      value: result.result,\n    };\n  }\n\n  return {\n    toolCallId: toolCall.id,\n    value: { error: result.error.message },\n  };\n}\n\nexport function headlessToolResumeCommand(result: {\n  toolCallId: string | undefined;\n  value: unknown;\n}): { resume: unknown } {\n  return {\n    resume: result.toolCallId\n      ? { [result.toolCallId]: result.value }\n      : result.value,\n  };\n}\n\nexport interface FlushPendingHeadlessToolInterruptsOptions {\n  onTool?: OnToolCallback;\n  resumeSubmit: (command: { resume: unknown }) => void | Promise<void>;\n  defer?: (run: () => void) => void;\n}\n\n/**\n * Execute and resume all newly seen headless-tool interrupts from a values\n * payload. Callers own `handledIds` and should clear it when the thread changes.\n */\nexport function flushPendingHeadlessToolInterrupts(\n  values: Record<string, unknown> | null | undefined,\n  tools: HeadlessToolImplementation[] | undefined,\n  handledIds: Set<string>,\n  options: FlushPendingHeadlessToolInterruptsOptions\n): void {\n  if (!tools?.length || !values) return;\n\n  const interrupts = values.__interrupt__;\n  if (!Array.isArray(interrupts) || interrupts.length === 0) return;\n\n  const defer = options.defer ?? ((run) => run());\n\n  for (const interrupt of interrupts as Interrupt[]) {\n    if (!isHeadlessToolInterrupt(interrupt.value)) continue;\n    const headlessInterrupt = interrupt.value;\n\n    const interruptId = interrupt.id ?? headlessInterrupt.toolCall.id ?? \"\";\n    if (handledIds.has(interruptId)) continue;\n    handledIds.add(interruptId);\n\n    defer(() => {\n      void handleHeadlessToolInterrupt(\n        headlessInterrupt,\n        tools,\n        options.onTool\n      ).then((result) => {\n        void options.resumeSubmit(headlessToolResumeCommand(result));\n      });\n    });\n  }\n}\n"],"mappings":";;;;AA6CA,SAAgB,gCACd,YACK;AACL,QAAO,WAAW,QACf,cACC,UAAU,SAAS,QAAQ,CAAC,wBAAwB,UAAU,MAAM,CACvE;;AAGH,SAAgB,wBACd,WACoC;AACpC,KAAI,OAAO,cAAc,YAAY,aAAa,KAChD,QAAO;CAGT,MAAM,QAAQ;AACd,QACE,MAAM,SAAS,UACf,OAAO,MAAM,aAAa,YAC1B,MAAM,YAAY,QAClB,OAAQ,MAAM,SAAqC,SAAS;;AAIhE,SAAgB,iBACd,OACA,MACsD;AACtD,QAAO,MAAM,MAAM,SAAS,KAAK,KAAK,SAAS,KAAK;;AAKtD,eAAsB,oBACpB,gBACA,MACA,QAGA;CACA,MAAM,YAAY,KAAK,KAAK;AAE5B,UAAS;EACP,OAAO;EACP,MAAM,eAAe,KAAK;EAC1B;EACD,CAAC;AAEF,KAAI;EACF,MAAM,SAAS,MAAM,eAAe,QAAQ,KAAK;EACjD,MAAM,WAAW,KAAK,KAAK,GAAG;AAE9B,WAAS;GACP,OAAO;GACP,MAAM,eAAe,KAAK;GAC1B;GACA;GACA;GACD,CAAC;AAEF,SAAO;GAAE,SAAS;GAAM;GAAQ;UACzB,KAAK;EAEZ,MAAM,QAAQ,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,IAAI,CAAC;EACjE,MAAM,WAAW,KAAK,KAAK,GAAG;AAE9B,WAAS;GACP,OAAO;GACP,MAAM,eAAe,KAAK;GAC1B;GACA;GACA;GACD,CAAC;AAEF,SAAO;GAAE,SAAS;GAAO;GAAO;;;AAIpC,eAAsB,4BACpB,WACA,OACA,QAC6D;CAC7D,MAAM,EAAE,aAAa;CACrB,MAAM,iBAAiB,iBAAiB,OAAO,SAAS,KAAK;AAE7D,KAAI,CAAC,gBAAgB;EACnB,MAAM,wBAAQ,IAAI,MAChB,kBAAkB,SAAS,KAAK,wCACV,MAAM,KAAK,SAAS,KAAK,KAAK,KAAK,CAAC,KAAK,KAAK,IAAI,SACzE;AAED,WAAS;GACP,OAAO;GACP,MAAM,SAAS;GACf,MAAM,SAAS;GACf;GACA,UAAU;GACX,CAAC;AAEF,SAAO;GACL,YAAY,SAAS;GACrB,OAAO,EAAE,OAAO,MAAM,SAAS;GAChC;;CAGH,MAAM,SAAS,MAAM,oBACnB,gBACA,SAAS,MACT,OACD;AAED,KAAI,OAAO,QACT,QAAO;EACL,YAAY,SAAS;EACrB,OAAO,OAAO;EACf;AAGH,QAAO;EACL,YAAY,SAAS;EACrB,OAAO,EAAE,OAAO,OAAO,MAAM,SAAS;EACvC;;AAGH,SAAgB,0BAA0B,QAGlB;AACtB,QAAO,EACL,QAAQ,OAAO,aACX,GAAG,OAAO,aAAa,OAAO,OAAO,GACrC,OAAO,OACZ;;;;;;AAaH,SAAgB,mCACd,QACA,OACA,YACA,SACM;AACN,KAAI,CAAC,OAAO,UAAU,CAAC,OAAQ;CAE/B,MAAM,aAAa,OAAO;AAC1B,KAAI,CAAC,MAAM,QAAQ,WAAW,IAAI,WAAW,WAAW,EAAG;CAE3D,MAAM,QAAQ,QAAQ,WAAW,QAAQ,KAAK;AAE9C,MAAK,MAAM,aAAa,YAA2B;AACjD,MAAI,CAAC,wBAAwB,UAAU,MAAM,CAAE;EAC/C,MAAM,oBAAoB,UAAU;EAEpC,MAAM,cAAc,UAAU,MAAM,kBAAkB,SAAS,MAAM;AACrE,MAAI,WAAW,IAAI,YAAY,CAAE;AACjC,aAAW,IAAI,YAAY;AAE3B,cAAY;AACL,+BACH,mBACA,OACA,QAAQ,OACT,CAAC,MAAM,WAAW;AACZ,YAAQ,aAAa,0BAA0B,OAAO,CAAC;KAC5D;IACF"}

package/dist/index.cjs

@@ -2,7 +2,15 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_fetch = require("./singletons/fetch.cjs");
 const require_client = require("./client.cjs");
 const require_errors = require("./ui/errors.cjs");
+const require_headless_tools = require("./headless-tools.cjs");
 exports.Client = require_client.Client;
 exports.StreamError = require_errors.StreamError;
+exports.executeHeadlessTool = require_headless_tools.executeHeadlessTool;
+exports.filterOutHeadlessToolInterrupts = require_headless_tools.filterOutHeadlessToolInterrupts;
+exports.findHeadlessTool = require_headless_tools.findHeadlessTool;
+exports.flushPendingHeadlessToolInterrupts = require_headless_tools.flushPendingHeadlessToolInterrupts;
 exports.getApiKey = require_client.getApiKey;
+exports.handleHeadlessToolInterrupt = require_headless_tools.handleHeadlessToolInterrupt;
+exports.headlessToolResumeCommand = require_headless_tools.headlessToolResumeCommand;
+exports.isHeadlessToolInterrupt = require_headless_tools.isHeadlessToolInterrupt;
 exports.overrideFetchImplementation = require_fetch.overrideFetchImplementation;

package/dist/index.d.cts

@@ -5,9 +5,10 @@ import { Command, OnConflictBehavior, RunsInvokePayload, StreamEvent } from "./t
 import { Client, ClientConfig, RequestHook, getApiKey } from "./client.cjs";
 import { overrideFetchImplementation } from "./singletons/fetch.cjs";
 import { BagTemplate } from "./types.template.cjs";
+import { AnyHeadlessToolImplementation, FlushPendingHeadlessToolInterruptsOptions, HeadlessToolImplementation, HeadlessToolInterrupt, OnToolCallback, ToolEvent, executeHeadlessTool, filterOutHeadlessToolInterrupts, findHeadlessTool, flushPendingHeadlessToolInterrupts, handleHeadlessToolInterrupt, headlessToolResumeCommand, isHeadlessToolInterrupt } from "./headless-tools.cjs";
 import { BaseStream } from "./ui/stream/base.cjs";
 import { UseAgentStream, UseAgentStreamOptions } from "./ui/stream/agent.cjs";
 import { UseDeepAgentStream, UseDeepAgentStreamOptions } from "./ui/stream/deep-agent.cjs";
 import { InferBag, InferNodeNames, InferNodeReturnTypes, InferStateType, InferSubagentStates, InferToolCalls, ResolveStreamInterface, ResolveStreamOptions } from "./ui/stream/index.cjs";
 import { StreamError } from "./ui/errors.cjs";
-export { type AIMessage, type Assistant, type AssistantBase, type AssistantGraph, type AssistantVersion, type AssistantsSearchResponse, type BagTemplate, BaseStream, type Checkpoint, Client, type ClientConfig, type Command, type Config, type Cron, type CronCreateForThreadResponse, type CronCreateResponse, type CustomStreamEvent, type DebugStreamEvent, type DefaultToolCall, type DefaultValues, type ErrorStreamEvent, type EventsStreamEvent, type FeedbackStreamEvent, type FunctionMessage, type GraphSchema, type HumanMessage, InferBag, InferNodeNames, InferNodeReturnTypes, InferStateType, InferSubagentStates, InferToolCalls, type Interrupt, type Item, type ListNamespaceResponse, type Message, type MessagesStreamEvent, type MessagesTupleStreamEvent, type Metadata, type MetadataStreamEvent, type OnConflictBehavior, type RemoveMessage, type RequestHook, ResolveStreamInterface, ResolveStreamOptions, type Run, type RunsInvokePayload, type SearchItem, type SearchItemsResponse, StreamError, type StreamEvent, type StreamMode, type SystemMessage, type Thread, type ThreadState, type ThreadStatus, type ThreadTask, type ToolCallFromTool, type ToolCallState, type ToolCallWithResult, type ToolCallsFromTools, type ToolMessage, type ToolProgress, type ToolsStreamEvent, type UpdatesStreamEvent, UseAgentStream, UseAgentStreamOptions, UseDeepAgentStream, UseDeepAgentStreamOptions, type ValuesStreamEvent, getApiKey, overrideFetchImplementation };
+export { type AIMessage, type AnyHeadlessToolImplementation, type Assistant, type AssistantBase, type AssistantGraph, type AssistantVersion, type AssistantsSearchResponse, type BagTemplate, BaseStream, type Checkpoint, Client, type ClientConfig, type Command, type Config, type Cron, type CronCreateForThreadResponse, type CronCreateResponse, type CustomStreamEvent, type DebugStreamEvent, type DefaultToolCall, type DefaultValues, type ErrorStreamEvent, type EventsStreamEvent, type FeedbackStreamEvent, type FlushPendingHeadlessToolInterruptsOptions, type FunctionMessage, type GraphSchema, type HeadlessToolImplementation, type HeadlessToolInterrupt, type HumanMessage, InferBag, InferNodeNames, InferNodeReturnTypes, InferStateType, InferSubagentStates, InferToolCalls, type Interrupt, type Item, type ListNamespaceResponse, type Message, type MessagesStreamEvent, type MessagesTupleStreamEvent, type Metadata, type MetadataStreamEvent, type OnConflictBehavior, type OnToolCallback, type RemoveMessage, type RequestHook, ResolveStreamInterface, ResolveStreamOptions, type Run, type RunsInvokePayload, type SearchItem, type SearchItemsResponse, StreamError, type StreamEvent, type StreamMode, type SystemMessage, type Thread, type ThreadState, type ThreadStatus, type ThreadTask, type ToolCallFromTool, type ToolCallState, type ToolCallWithResult, type ToolCallsFromTools, type ToolEvent, type ToolMessage, type ToolProgress, type ToolsStreamEvent, type UpdatesStreamEvent, UseAgentStream, UseAgentStreamOptions, UseDeepAgentStream, UseDeepAgentStreamOptions, type ValuesStreamEvent, executeHeadlessTool, filterOutHeadlessToolInterrupts, findHeadlessTool, flushPendingHeadlessToolInterrupts, getApiKey, handleHeadlessToolInterrupt, headlessToolResumeCommand, isHeadlessToolInterrupt, overrideFetchImplementation };

package/dist/index.d.ts

@@ -5,9 +5,10 @@ import { Command, OnConflictBehavior, RunsInvokePayload, StreamEvent } from "./t
 import { Client, ClientConfig, RequestHook, getApiKey } from "./client.js";
 import { overrideFetchImplementation } from "./singletons/fetch.js";
 import { BagTemplate } from "./types.template.js";
+import { AnyHeadlessToolImplementation, FlushPendingHeadlessToolInterruptsOptions, HeadlessToolImplementation, HeadlessToolInterrupt, OnToolCallback, ToolEvent, executeHeadlessTool, filterOutHeadlessToolInterrupts, findHeadlessTool, flushPendingHeadlessToolInterrupts, handleHeadlessToolInterrupt, headlessToolResumeCommand, isHeadlessToolInterrupt } from "./headless-tools.js";
 import { BaseStream } from "./ui/stream/base.js";
 import { UseAgentStream, UseAgentStreamOptions } from "./ui/stream/agent.js";
 import { UseDeepAgentStream, UseDeepAgentStreamOptions } from "./ui/stream/deep-agent.js";
 import { InferBag, InferNodeNames, InferNodeReturnTypes, InferStateType, InferSubagentStates, InferToolCalls, ResolveStreamInterface, ResolveStreamOptions } from "./ui/stream/index.js";
 import { StreamError } from "./ui/errors.js";
-export { type AIMessage, type Assistant, type AssistantBase, type AssistantGraph, type AssistantVersion, type AssistantsSearchResponse, type BagTemplate, BaseStream, type Checkpoint, Client, type ClientConfig, type Command, type Config, type Cron, type CronCreateForThreadResponse, type CronCreateResponse, type CustomStreamEvent, type DebugStreamEvent, type DefaultToolCall, type DefaultValues, type ErrorStreamEvent, type EventsStreamEvent, type FeedbackStreamEvent, type FunctionMessage, type GraphSchema, type HumanMessage, InferBag, InferNodeNames, InferNodeReturnTypes, InferStateType, InferSubagentStates, InferToolCalls, type Interrupt, type Item, type ListNamespaceResponse, type Message, type MessagesStreamEvent, type MessagesTupleStreamEvent, type Metadata, type MetadataStreamEvent, type OnConflictBehavior, type RemoveMessage, type RequestHook, ResolveStreamInterface, ResolveStreamOptions, type Run, type RunsInvokePayload, type SearchItem, type SearchItemsResponse, StreamError, type StreamEvent, type StreamMode, type SystemMessage, type Thread, type ThreadState, type ThreadStatus, type ThreadTask, type ToolCallFromTool, type ToolCallState, type ToolCallWithResult, type ToolCallsFromTools, type ToolMessage, type ToolProgress, type ToolsStreamEvent, type UpdatesStreamEvent, UseAgentStream, UseAgentStreamOptions, UseDeepAgentStream, UseDeepAgentStreamOptions, type ValuesStreamEvent, getApiKey, overrideFetchImplementation };
+export { type AIMessage, type AnyHeadlessToolImplementation, type Assistant, type AssistantBase, type AssistantGraph, type AssistantVersion, type AssistantsSearchResponse, type BagTemplate, BaseStream, type Checkpoint, Client, type ClientConfig, type Command, type Config, type Cron, type CronCreateForThreadResponse, type CronCreateResponse, type CustomStreamEvent, type DebugStreamEvent, type DefaultToolCall, type DefaultValues, type ErrorStreamEvent, type EventsStreamEvent, type FeedbackStreamEvent, type FlushPendingHeadlessToolInterruptsOptions, type FunctionMessage, type GraphSchema, type HeadlessToolImplementation, type HeadlessToolInterrupt, type HumanMessage, InferBag, InferNodeNames, InferNodeReturnTypes, InferStateType, InferSubagentStates, InferToolCalls, type Interrupt, type Item, type ListNamespaceResponse, type Message, type MessagesStreamEvent, type MessagesTupleStreamEvent, type Metadata, type MetadataStreamEvent, type OnConflictBehavior, type OnToolCallback, type RemoveMessage, type RequestHook, ResolveStreamInterface, ResolveStreamOptions, type Run, type RunsInvokePayload, type SearchItem, type SearchItemsResponse, StreamError, type StreamEvent, type StreamMode, type SystemMessage, type Thread, type ThreadState, type ThreadStatus, type ThreadTask, type ToolCallFromTool, type ToolCallState, type ToolCallWithResult, type ToolCallsFromTools, type ToolEvent, type ToolMessage, type ToolProgress, type ToolsStreamEvent, type UpdatesStreamEvent, UseAgentStream, UseAgentStreamOptions, UseDeepAgentStream, UseDeepAgentStreamOptions, type ValuesStreamEvent, executeHeadlessTool, filterOutHeadlessToolInterrupts, findHeadlessTool, flushPendingHeadlessToolInterrupts, getApiKey, handleHeadlessToolInterrupt, headlessToolResumeCommand, isHeadlessToolInterrupt, overrideFetchImplementation };

package/dist/index.js

@@ -1,4 +1,5 @@
 import { overrideFetchImplementation } from "./singletons/fetch.js";
 import { Client, getApiKey } from "./client.js";
 import { StreamError } from "./ui/errors.js";
-export { Client, StreamError, getApiKey, overrideFetchImplementation };
+import { executeHeadlessTool, filterOutHeadlessToolInterrupts, findHeadlessTool, flushPendingHeadlessToolInterrupts, handleHeadlessToolInterrupt, headlessToolResumeCommand, isHeadlessToolInterrupt } from "./headless-tools.js";
+export { Client, StreamError, executeHeadlessTool, filterOutHeadlessToolInterrupts, findHeadlessTool, flushPendingHeadlessToolInterrupts, getApiKey, handleHeadlessToolInterrupt, headlessToolResumeCommand, isHeadlessToolInterrupt, overrideFetchImplementation };

package/dist/react/index.cjs

@@ -1,11 +1,19 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_headless_tools = require("../headless-tools.cjs");
 const require_subagents = require("../ui/subagents.cjs");
 const require_stream_custom = require("./stream.custom.cjs");
 const require_stream = require("./stream.cjs");
 exports.FetchStreamTransport = require_stream_custom.FetchStreamTransport;
 exports.SubagentManager = require_subagents.SubagentManager;
 exports.calculateDepthFromNamespace = require_subagents.calculateDepthFromNamespace;
+exports.executeHeadlessTool = require_headless_tools.executeHeadlessTool;
 exports.extractParentIdFromNamespace = require_subagents.extractParentIdFromNamespace;
 exports.extractToolCallIdFromNamespace = require_subagents.extractToolCallIdFromNamespace;
+exports.filterOutHeadlessToolInterrupts = require_headless_tools.filterOutHeadlessToolInterrupts;
+exports.findHeadlessTool = require_headless_tools.findHeadlessTool;
+exports.flushPendingHeadlessToolInterrupts = require_headless_tools.flushPendingHeadlessToolInterrupts;
+exports.handleHeadlessToolInterrupt = require_headless_tools.handleHeadlessToolInterrupt;
+exports.headlessToolResumeCommand = require_headless_tools.headlessToolResumeCommand;
+exports.isHeadlessToolInterrupt = require_headless_tools.isHeadlessToolInterrupt;
 exports.isSubagentNamespace = require_subagents.isSubagentNamespace;
 exports.useStream = require_stream.useStream;

package/dist/react/index.d.cts

@@ -1,4 +1,5 @@
 import { DefaultToolCall, ToolCallFromTool, ToolCallState, ToolCallWithResult, ToolCallsFromTools } from "../types.messages.cjs";
+import { AnyHeadlessToolImplementation, FlushPendingHeadlessToolInterruptsOptions, HeadlessToolImplementation, HeadlessToolInterrupt, OnToolCallback, ToolEvent, executeHeadlessTool, filterOutHeadlessToolInterrupts, findHeadlessTool, flushPendingHeadlessToolInterrupts, handleHeadlessToolInterrupt, headlessToolResumeCommand, isHeadlessToolInterrupt } from "../headless-tools.cjs";
 import { AgentTypeConfigLike, BaseSubagentState, CompiledSubAgentLike, DeepAgentTypeConfigLike, DefaultSubagentStates, ExtractAgentConfig, ExtractDeepAgentConfig, ExtractSubAgentMiddleware, GetToolCallsType, InferAgentToolCalls, InferDeepAgentSubagents, InferSubagentByName, InferSubagentNames, InferSubagentState, IsAgentLike, IsDeepAgentLike, MessageMetadata, SubAgentLike, SubagentStateMap, SubagentStatus, SubagentStream, SubagentStreamInterface, SubagentToolCall, UseStreamCustomOptions, UseStreamOptions, UseStreamThread, UseStreamTransport } from "../ui/types.cjs";
 import { BaseStream } from "../ui/stream/base.cjs";
 import { UseAgentStream, UseAgentStreamOptions } from "../ui/stream/agent.cjs";
@@ -8,4 +9,4 @@ import { UseStream, UseStreamCustom } from "./types.cjs";
 import { useStream } from "./stream.cjs";
 import { FetchStreamTransport } from "./stream.custom.cjs";
 import { SubagentManager, calculateDepthFromNamespace, extractParentIdFromNamespace, extractToolCallIdFromNamespace, isSubagentNamespace } from "../ui/subagents.cjs";
-export { type AgentTypeConfigLike, type BaseStream, type BaseSubagentState, type CompiledSubAgentLike, type DeepAgentTypeConfigLike, type DefaultSubagentStates, type DefaultToolCall, type ExtractAgentConfig, type ExtractDeepAgentConfig, type ExtractSubAgentMiddleware, FetchStreamTransport, type GetToolCallsType, type InferAgentToolCalls, type InferBag, type InferDeepAgentSubagents, type InferNodeNames, type InferStateType, type InferSubagentByName, type InferSubagentNames, type InferSubagentState, type InferSubagentStates, type InferToolCalls, type IsAgentLike, type IsDeepAgentLike, type MessageMetadata, type ResolveStreamInterface, type ResolveStreamOptions, type SubAgentLike, SubagentManager, type SubagentStateMap, type SubagentStatus, type SubagentStream, type SubagentStreamInterface, type SubagentToolCall, type ToolCallFromTool, type ToolCallState, type ToolCallWithResult, type ToolCallsFromTools, type UseAgentStream, type UseAgentStreamOptions, type UseDeepAgentStream, type UseDeepAgentStreamOptions, type UseStream, type UseStreamCustom, type UseStreamCustomOptions, type UseStreamOptions, type UseStreamThread, type UseStreamTransport, calculateDepthFromNamespace, extractParentIdFromNamespace, extractToolCallIdFromNamespace, isSubagentNamespace, useStream };
+export { type AgentTypeConfigLike, type AnyHeadlessToolImplementation, type BaseStream, type BaseSubagentState, type CompiledSubAgentLike, type DeepAgentTypeConfigLike, type DefaultSubagentStates, type DefaultToolCall, type ExtractAgentConfig, type ExtractDeepAgentConfig, type ExtractSubAgentMiddleware, FetchStreamTransport, type FlushPendingHeadlessToolInterruptsOptions, type GetToolCallsType, type HeadlessToolImplementation, type HeadlessToolInterrupt, type InferAgentToolCalls, type InferBag, type InferDeepAgentSubagents, type InferNodeNames, type InferStateType, type InferSubagentByName, type InferSubagentNames, type InferSubagentState, type InferSubagentStates, type InferToolCalls, type IsAgentLike, type IsDeepAgentLike, type MessageMetadata, type OnToolCallback, type ResolveStreamInterface, type ResolveStreamOptions, type SubAgentLike, SubagentManager, type SubagentStateMap, type SubagentStatus, type SubagentStream, type SubagentStreamInterface, type SubagentToolCall, type ToolCallFromTool, type ToolCallState, type ToolCallWithResult, type ToolCallsFromTools, type ToolEvent, type UseAgentStream, type UseAgentStreamOptions, type UseDeepAgentStream, type UseDeepAgentStreamOptions, type UseStream, type UseStreamCustom, type UseStreamCustomOptions, type UseStreamOptions, type UseStreamThread, type UseStreamTransport, calculateDepthFromNamespace, executeHeadlessTool, extractParentIdFromNamespace, extractToolCallIdFromNamespace, filterOutHeadlessToolInterrupts, findHeadlessTool, flushPendingHeadlessToolInterrupts, handleHeadlessToolInterrupt, headlessToolResumeCommand, isHeadlessToolInterrupt, isSubagentNamespace, useStream };

package/dist/react/index.d.ts

@@ -1,4 +1,5 @@
 import { DefaultToolCall, ToolCallFromTool, ToolCallState, ToolCallWithResult, ToolCallsFromTools } from "../types.messages.js";
+import { AnyHeadlessToolImplementation, FlushPendingHeadlessToolInterruptsOptions, HeadlessToolImplementation, HeadlessToolInterrupt, OnToolCallback, ToolEvent, executeHeadlessTool, filterOutHeadlessToolInterrupts, findHeadlessTool, flushPendingHeadlessToolInterrupts, handleHeadlessToolInterrupt, headlessToolResumeCommand, isHeadlessToolInterrupt } from "../headless-tools.js";
 import { AgentTypeConfigLike, BaseSubagentState, CompiledSubAgentLike, DeepAgentTypeConfigLike, DefaultSubagentStates, ExtractAgentConfig, ExtractDeepAgentConfig, ExtractSubAgentMiddleware, GetToolCallsType, InferAgentToolCalls, InferDeepAgentSubagents, InferSubagentByName, InferSubagentNames, InferSubagentState, IsAgentLike, IsDeepAgentLike, MessageMetadata, SubAgentLike, SubagentStateMap, SubagentStatus, SubagentStream, SubagentStreamInterface, SubagentToolCall, UseStreamCustomOptions, UseStreamOptions, UseStreamThread, UseStreamTransport } from "../ui/types.js";
 import { BaseStream } from "../ui/stream/base.js";
 import { UseAgentStream, UseAgentStreamOptions } from "../ui/stream/agent.js";
@@ -8,4 +9,4 @@ import { UseStream, UseStreamCustom } from "./types.js";
 import { useStream } from "./stream.js";
 import { FetchStreamTransport } from "./stream.custom.js";
 import { SubagentManager, calculateDepthFromNamespace, extractParentIdFromNamespace, extractToolCallIdFromNamespace, isSubagentNamespace } from "../ui/subagents.js";
-export { type AgentTypeConfigLike, type BaseStream, type BaseSubagentState, type CompiledSubAgentLike, type DeepAgentTypeConfigLike, type DefaultSubagentStates, type DefaultToolCall, type ExtractAgentConfig, type ExtractDeepAgentConfig, type ExtractSubAgentMiddleware, FetchStreamTransport, type GetToolCallsType, type InferAgentToolCalls, type InferBag, type InferDeepAgentSubagents, type InferNodeNames, type InferStateType, type InferSubagentByName, type InferSubagentNames, type InferSubagentState, type InferSubagentStates, type InferToolCalls, type IsAgentLike, type IsDeepAgentLike, type MessageMetadata, type ResolveStreamInterface, type ResolveStreamOptions, type SubAgentLike, SubagentManager, type SubagentStateMap, type SubagentStatus, type SubagentStream, type SubagentStreamInterface, type SubagentToolCall, type ToolCallFromTool, type ToolCallState, type ToolCallWithResult, type ToolCallsFromTools, type UseAgentStream, type UseAgentStreamOptions, type UseDeepAgentStream, type UseDeepAgentStreamOptions, type UseStream, type UseStreamCustom, type UseStreamCustomOptions, type UseStreamOptions, type UseStreamThread, type UseStreamTransport, calculateDepthFromNamespace, extractParentIdFromNamespace, extractToolCallIdFromNamespace, isSubagentNamespace, useStream };
+export { type AgentTypeConfigLike, type AnyHeadlessToolImplementation, type BaseStream, type BaseSubagentState, type CompiledSubAgentLike, type DeepAgentTypeConfigLike, type DefaultSubagentStates, type DefaultToolCall, type ExtractAgentConfig, type ExtractDeepAgentConfig, type ExtractSubAgentMiddleware, FetchStreamTransport, type FlushPendingHeadlessToolInterruptsOptions, type GetToolCallsType, type HeadlessToolImplementation, type HeadlessToolInterrupt, type InferAgentToolCalls, type InferBag, type InferDeepAgentSubagents, type InferNodeNames, type InferStateType, type InferSubagentByName, type InferSubagentNames, type InferSubagentState, type InferSubagentStates, type InferToolCalls, type IsAgentLike, type IsDeepAgentLike, type MessageMetadata, type OnToolCallback, type ResolveStreamInterface, type ResolveStreamOptions, type SubAgentLike, SubagentManager, type SubagentStateMap, type SubagentStatus, type SubagentStream, type SubagentStreamInterface, type SubagentToolCall, type ToolCallFromTool, type ToolCallState, type ToolCallWithResult, type ToolCallsFromTools, type ToolEvent, type UseAgentStream, type UseAgentStreamOptions, type UseDeepAgentStream, type UseDeepAgentStreamOptions, type UseStream, type UseStreamCustom, type UseStreamCustomOptions, type UseStreamOptions, type UseStreamThread, type UseStreamTransport, calculateDepthFromNamespace, executeHeadlessTool, extractParentIdFromNamespace, extractToolCallIdFromNamespace, filterOutHeadlessToolInterrupts, findHeadlessTool, flushPendingHeadlessToolInterrupts, handleHeadlessToolInterrupt, headlessToolResumeCommand, isHeadlessToolInterrupt, isSubagentNamespace, useStream };

package/dist/react/index.js

@@ -1,4 +1,5 @@
+import { executeHeadlessTool, filterOutHeadlessToolInterrupts, findHeadlessTool, flushPendingHeadlessToolInterrupts, handleHeadlessToolInterrupt, headlessToolResumeCommand, isHeadlessToolInterrupt } from "../headless-tools.js";
 import { SubagentManager, calculateDepthFromNamespace, extractParentIdFromNamespace, extractToolCallIdFromNamespace, isSubagentNamespace } from "../ui/subagents.js";
 import { FetchStreamTransport } from "./stream.custom.js";
 import { useStream } from "./stream.js";
-export { FetchStreamTransport, SubagentManager, calculateDepthFromNamespace, extractParentIdFromNamespace, extractToolCallIdFromNamespace, isSubagentNamespace, useStream };
+export { FetchStreamTransport, SubagentManager, calculateDepthFromNamespace, executeHeadlessTool, extractParentIdFromNamespace, extractToolCallIdFromNamespace, filterOutHeadlessToolInterrupts, findHeadlessTool, flushPendingHeadlessToolInterrupts, handleHeadlessToolInterrupt, headlessToolResumeCommand, isHeadlessToolInterrupt, isSubagentNamespace, useStream };

package/dist/react/stream.custom.cjs

@@ -2,6 +2,7 @@
 require("../_virtual/_rolldown/runtime.cjs");
 const require_sse = require("../utils/sse.cjs");
 const require_stream = require("../utils/stream.cjs");
+const require_headless_tools = require("../headless-tools.cjs");
 const require_messages = require("../ui/messages.cjs");
 const require_tools = require("../utils/tools.cjs");
 const require_manager = require("../ui/manager.cjs");
@@ -125,6 +126,24 @@ function useStreamCustom(options) {
 			}
 		});
 	};
+	const handledToolsRef = (0, react.useRef)(/* @__PURE__ */ new Set());
+	(0, react.useEffect)(() => {
+		handledToolsRef.current.clear();
+	}, [threadId]);
+	(0, react.useEffect)(() => {
+		require_headless_tools.flushPendingHeadlessToolInterrupts(stream.values, options.tools, handledToolsRef.current, {
+			onTool: options.onTool,
+			defer: (run) => {
+				Promise.resolve().then(run);
+			},
+			resumeSubmit: (command) => submit(null, { command })
+		});
+	}, [
+		options.onTool,
+		options.tools,
+		stream.values,
+		submit
+	]);
 	return {
 		get values() {
 			return stream.values ?? {};
@@ -134,11 +153,7 @@ function useStreamCustom(options) {
 		stop,
 		submit,
 		get interrupts() {
-			if (stream.values != null && "__interrupt__" in stream.values && Array.isArray(stream.values.__interrupt__)) {
-				const valueInterrupts = stream.values.__interrupt__;
-				if (valueInterrupts.length === 0) return [{ when: "breakpoint" }];
-				return require_interrupts.normalizeInterruptsList(valueInterrupts);
-			}
+			if (stream.values != null && "__interrupt__" in stream.values && Array.isArray(stream.values.__interrupt__)) return require_interrupts.userFacingInterruptsFromValuesArray(stream.values.__interrupt__);
 			return [];
 		},
 		get interrupt() {