@aigne/agent-runtime 1.12.0-beta.5

package/dist/agent-runners/hook-channel.cjs

@@ -0,0 +1,55 @@
+const require_scratchpad_afs = require('./scratchpad-afs.cjs');
+
+//#region src/agent-runners/hook-channel.ts
+function createHookChannel() {
+	const events = [];
+	const subscribers = /* @__PURE__ */ new Set();
+	return {
+		emit(name, payload) {
+			const event = {
+				name,
+				from: payload.from,
+				to: payload.to,
+				session: payload.session,
+				ts: (/* @__PURE__ */ new Date()).toISOString()
+			};
+			if (payload.iteration !== void 0) event.iteration = payload.iteration;
+			events.push(event);
+			for (const fn of subscribers) fn(event);
+		},
+		subscribe(fn) {
+			subscribers.add(fn);
+			return () => {
+				subscribers.delete(fn);
+			};
+		},
+		drain() {
+			return [...events];
+		}
+	};
+}
+/**
+* Persist hook events to the scope-local `/scratch/hook-channel.jsonl` file.
+*
+* Phase 2 moves this off the shared `/modules/memory/runs/<session>/...`
+* tree so that team/orchestrator runs get an isolated, per-scope audit
+* trail. Best-effort writer: returns the written path on success, or null
+* when the caller has no session, no `afs.write`, or the write itself
+* fails. An empty events file is still written (and the path returned) so
+* callers don't special-case "no events".
+*/
+async function persistHookEvents(afs, session, events) {
+	if (!session || !afs.write) return null;
+	const path = `${require_scratchpad_afs.SCRATCH_SCOPE_ROOT}/hook-channel.jsonl`;
+	const content = events.length > 0 ? `${events.map((e) => JSON.stringify(e)).join("\n")}\n` : "";
+	try {
+		await afs.write(path, { content });
+		return path;
+	} catch {
+		return null;
+	}
+}
+
+//#endregion
+exports.createHookChannel = createHookChannel;
+exports.persistHookEvents = persistHookEvents;

package/dist/agent-runners/hook-channel.d.cts

@@ -0,0 +1,38 @@
+//#region src/agent-runners/hook-channel.d.ts
+interface HookEvent {
+  name: string;
+  from: string;
+  to: string;
+  iteration?: number;
+  session: string;
+  ts: string;
+}
+interface HookChannel {
+  emit(name: string, payload: {
+    from: string;
+    to: string;
+    iteration?: number;
+    session: string;
+  }): void;
+  subscribe(fn: (event: HookEvent) => void): () => void;
+  drain(): HookEvent[];
+}
+declare function createHookChannel(): HookChannel;
+/**
+ * Persist hook events to the scope-local `/scratch/hook-channel.jsonl` file.
+ *
+ * Phase 2 moves this off the shared `/modules/memory/runs/<session>/...`
+ * tree so that team/orchestrator runs get an isolated, per-scope audit
+ * trail. Best-effort writer: returns the written path on success, or null
+ * when the caller has no session, no `afs.write`, or the write itself
+ * fails. An empty events file is still written (and the path returned) so
+ * callers don't special-case "no events".
+ */
+declare function persistHookEvents(afs: {
+  write?: (path: string, payload: {
+    content: string;
+  }) => Promise<unknown>;
+}, session: string | undefined, events: HookEvent[]): Promise<string | null>;
+//#endregion
+export { HookChannel, HookEvent, createHookChannel, persistHookEvents };
+//# sourceMappingURL=hook-channel.d.cts.map

package/dist/agent-runners/hook-channel.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-channel.d.cts","names":[],"sources":["../../src/agent-runners/hook-channel.ts"],"mappings":";UAEiB,SAAA;EACf,IAAA;EACA,IAAA;EACA,EAAA;EACA,SAAA;EACA,OAAA;EACA,EAAA;AAAA;AAAA,UAGe,WAAA;EACf,IAAA,CACE,IAAA,UACA,OAAA;IAAW,IAAA;IAAc,EAAA;IAAY,SAAA;IAAoB,OAAA;EAAA;EAE3D,SAAA,CAAU,EAAA,GAAK,KAAA,EAAO,SAAA;EACtB,KAAA,IAAS,SAAA;AAAA;AAAA,iBAGK,iBAAA,CAAA,GAAqB,WAAA;;;;;;;;;;;iBA2Cf,iBAAA,CACpB,GAAA;EAAO,KAAA,IAAS,IAAA,UAAc,OAAA;IAAW,OAAA;EAAA,MAAsB,OAAA;AAAA,GAC/D,OAAA,sBACA,MAAA,EAAQ,SAAA,KACP,OAAA"}

package/dist/agent-runners/hook-channel.d.mts

@@ -0,0 +1,38 @@
+//#region src/agent-runners/hook-channel.d.ts
+interface HookEvent {
+  name: string;
+  from: string;
+  to: string;
+  iteration?: number;
+  session: string;
+  ts: string;
+}
+interface HookChannel {
+  emit(name: string, payload: {
+    from: string;
+    to: string;
+    iteration?: number;
+    session: string;
+  }): void;
+  subscribe(fn: (event: HookEvent) => void): () => void;
+  drain(): HookEvent[];
+}
+declare function createHookChannel(): HookChannel;
+/**
+ * Persist hook events to the scope-local `/scratch/hook-channel.jsonl` file.
+ *
+ * Phase 2 moves this off the shared `/modules/memory/runs/<session>/...`
+ * tree so that team/orchestrator runs get an isolated, per-scope audit
+ * trail. Best-effort writer: returns the written path on success, or null
+ * when the caller has no session, no `afs.write`, or the write itself
+ * fails. An empty events file is still written (and the path returned) so
+ * callers don't special-case "no events".
+ */
+declare function persistHookEvents(afs: {
+  write?: (path: string, payload: {
+    content: string;
+  }) => Promise<unknown>;
+}, session: string | undefined, events: HookEvent[]): Promise<string | null>;
+//#endregion
+export { HookChannel, HookEvent, createHookChannel, persistHookEvents };
+//# sourceMappingURL=hook-channel.d.mts.map

package/dist/agent-runners/hook-channel.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-channel.d.mts","names":[],"sources":["../../src/agent-runners/hook-channel.ts"],"mappings":";UAEiB,SAAA;EACf,IAAA;EACA,IAAA;EACA,EAAA;EACA,SAAA;EACA,OAAA;EACA,EAAA;AAAA;AAAA,UAGe,WAAA;EACf,IAAA,CACE,IAAA,UACA,OAAA;IAAW,IAAA;IAAc,EAAA;IAAY,SAAA;IAAoB,OAAA;EAAA;EAE3D,SAAA,CAAU,EAAA,GAAK,KAAA,EAAO,SAAA;EACtB,KAAA,IAAS,SAAA;AAAA;AAAA,iBAGK,iBAAA,CAAA,GAAqB,WAAA;;;;;;;;;;;iBA2Cf,iBAAA,CACpB,GAAA;EAAO,KAAA,IAAS,IAAA,UAAc,OAAA;IAAW,OAAA;EAAA,MAAsB,OAAA;AAAA,GAC/D,OAAA,sBACA,MAAA,EAAQ,SAAA,KACP,OAAA"}

package/dist/agent-runners/hook-channel.mjs

@@ -0,0 +1,55 @@
+import { SCRATCH_SCOPE_ROOT } from "./scratchpad-afs.mjs";
+
+//#region src/agent-runners/hook-channel.ts
+function createHookChannel() {
+	const events = [];
+	const subscribers = /* @__PURE__ */ new Set();
+	return {
+		emit(name, payload) {
+			const event = {
+				name,
+				from: payload.from,
+				to: payload.to,
+				session: payload.session,
+				ts: (/* @__PURE__ */ new Date()).toISOString()
+			};
+			if (payload.iteration !== void 0) event.iteration = payload.iteration;
+			events.push(event);
+			for (const fn of subscribers) fn(event);
+		},
+		subscribe(fn) {
+			subscribers.add(fn);
+			return () => {
+				subscribers.delete(fn);
+			};
+		},
+		drain() {
+			return [...events];
+		}
+	};
+}
+/**
+* Persist hook events to the scope-local `/scratch/hook-channel.jsonl` file.
+*
+* Phase 2 moves this off the shared `/modules/memory/runs/<session>/...`
+* tree so that team/orchestrator runs get an isolated, per-scope audit
+* trail. Best-effort writer: returns the written path on success, or null
+* when the caller has no session, no `afs.write`, or the write itself
+* fails. An empty events file is still written (and the path returned) so
+* callers don't special-case "no events".
+*/
+async function persistHookEvents(afs, session, events) {
+	if (!session || !afs.write) return null;
+	const path = `${SCRATCH_SCOPE_ROOT}/hook-channel.jsonl`;
+	const content = events.length > 0 ? `${events.map((e) => JSON.stringify(e)).join("\n")}\n` : "";
+	try {
+		await afs.write(path, { content });
+		return path;
+	} catch {
+		return null;
+	}
+}
+
+//#endregion
+export { createHookChannel, persistHookEvents };
+//# sourceMappingURL=hook-channel.mjs.map

package/dist/agent-runners/hook-channel.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-channel.mjs","names":[],"sources":["../../src/agent-runners/hook-channel.ts"],"sourcesContent":["import { SCRATCH_SCOPE_ROOT } from \"./scratchpad-afs.js\";\n\nexport interface HookEvent {\n  name: string;\n  from: string;\n  to: string;\n  iteration?: number;\n  session: string;\n  ts: string;\n}\n\nexport interface HookChannel {\n  emit(\n    name: string,\n    payload: { from: string; to: string; iteration?: number; session: string },\n  ): void;\n  subscribe(fn: (event: HookEvent) => void): () => void;\n  drain(): HookEvent[];\n}\n\nexport function createHookChannel(): HookChannel {\n  const events: HookEvent[] = [];\n  const subscribers: Set<(event: HookEvent) => void> = new Set();\n\n  return {\n    emit(name, payload) {\n      const event: HookEvent = {\n        name,\n        from: payload.from,\n        to: payload.to,\n        session: payload.session,\n        ts: new Date().toISOString(),\n      };\n      if (payload.iteration !== undefined) {\n        event.iteration = payload.iteration;\n      }\n      events.push(event);\n      for (const fn of subscribers) fn(event);\n    },\n\n    subscribe(fn) {\n      subscribers.add(fn);\n      return () => {\n        subscribers.delete(fn);\n      };\n    },\n\n    drain() {\n      return [...events];\n    },\n  };\n}\n\n/**\n * Persist hook events to the scope-local `/scratch/hook-channel.jsonl` file.\n *\n * Phase 2 moves this off the shared `/modules/memory/runs/<session>/...`\n * tree so that team/orchestrator runs get an isolated, per-scope audit\n * trail. Best-effort writer: returns the written path on success, or null\n * when the caller has no session, no `afs.write`, or the write itself\n * fails. An empty events file is still written (and the path returned) so\n * callers don't special-case \"no events\".\n */\nexport async function persistHookEvents(\n  afs: { write?: (path: string, payload: { content: string }) => Promise<unknown> },\n  session: string | undefined,\n  events: HookEvent[],\n): Promise<string | null> {\n  if (!session || !afs.write) return null;\n  const path = `${SCRATCH_SCOPE_ROOT}/hook-channel.jsonl`;\n  const content = events.length > 0 ? `${events.map((e) => JSON.stringify(e)).join(\"\\n\")}\\n` : \"\";\n  try {\n    await afs.write(path, { content });\n    return path;\n  } catch {\n    return null;\n  }\n}\n"],"mappings":";;;AAoBA,SAAgB,oBAAiC;CAC/C,MAAM,SAAsB,EAAE;CAC9B,MAAM,8BAA+C,IAAI,KAAK;AAE9D,QAAO;EACL,KAAK,MAAM,SAAS;GAClB,MAAM,QAAmB;IACvB;IACA,MAAM,QAAQ;IACd,IAAI,QAAQ;IACZ,SAAS,QAAQ;IACjB,qBAAI,IAAI,MAAM,EAAC,aAAa;IAC7B;AACD,OAAI,QAAQ,cAAc,OACxB,OAAM,YAAY,QAAQ;AAE5B,UAAO,KAAK,MAAM;AAClB,QAAK,MAAM,MAAM,YAAa,IAAG,MAAM;;EAGzC,UAAU,IAAI;AACZ,eAAY,IAAI,GAAG;AACnB,gBAAa;AACX,gBAAY,OAAO,GAAG;;;EAI1B,QAAQ;AACN,UAAO,CAAC,GAAG,OAAO;;EAErB;;;;;;;;;;;;AAaH,eAAsB,kBACpB,KACA,SACA,QACwB;AACxB,KAAI,CAAC,WAAW,CAAC,IAAI,MAAO,QAAO;CACnC,MAAM,OAAO,GAAG,mBAAmB;CACnC,MAAM,UAAU,OAAO,SAAS,IAAI,GAAG,OAAO,KAAK,MAAM,KAAK,UAAU,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,MAAM;AAC7F,KAAI;AACF,QAAM,IAAI,MAAM,MAAM,EAAE,SAAS,CAAC;AAClC,SAAO;SACD;AACN,SAAO"}

package/dist/agent-runners/hooks.cjs

@@ -0,0 +1,107 @@
+let ufo = require("ufo");
+let _aigne_afs = require("@aigne/afs");
+
+//#region src/agent-runners/hooks.ts
+const log = (0, _aigne_afs.makeNsLog)("agent-runtime");
+const MAX_HOOK_CHAIN_DEPTH = 3;
+const INTERNAL_FIELD_PREFIX = "_";
+function sanitizePayloadForHook(obj) {
+	const sanitized = {};
+	for (const [key, value] of Object.entries(obj)) if (!key.startsWith(INTERNAL_FIELD_PREFIX)) sanitized[key] = value;
+	return sanitized;
+}
+async function fireHook(afs, hookPath, payload, opts) {
+	const chainDepth = opts.chainDepth ?? 0;
+	if (chainDepth >= MAX_HOOK_CHAIN_DEPTH) {
+		log.warn(`[hooks] Chain depth ${chainDepth} >= ${MAX_HOOK_CHAIN_DEPTH}, skipping: ${hookPath}`);
+		return;
+	}
+	const cloned = structuredClone(sanitizePayloadForHook(payload));
+	const hookSession = opts.session ? `${opts.session}-hook-${Date.now()}` : void 0;
+	try {
+		await afs.exec(hookPath, {
+			...cloned,
+			session: hookSession,
+			_hook_chain_depth: chainDepth + 1
+		}, {});
+	} catch (err) {
+		log.warn(`[hooks] Hook "${hookPath}" failed: ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
+function createHookDispatcher(afs, hooks, opts) {
+	const { mountPath, blockletId, session, chainDepth = 0 } = opts;
+	const resolve = (hookRef) => {
+		if (!hookRef) return null;
+		if (hookRef.startsWith("/")) return hookRef;
+		return (0, ufo.joinURL)(mountPath, hookRef);
+	};
+	const fire = async (hookRef, payload) => {
+		const path = resolve(hookRef);
+		if (!path) return;
+		await fireHook(afs, path, payload, {
+			session,
+			chainDepth
+		});
+	};
+	return {
+		async fireOnStart(input) {
+			await fire(hooks?.onStart, {
+				event: "on_start",
+				blockletId,
+				input: sanitizePayloadForHook(input),
+				ts: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		},
+		async fireOnSuccess(result) {
+			await fire(hooks?.onSuccess, {
+				event: "on_success",
+				blockletId,
+				result,
+				ts: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		},
+		async fireOnError(error) {
+			await fire(hooks?.onError, {
+				event: "on_error",
+				blockletId,
+				error,
+				ts: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		},
+		async fireOnHandoff(from, to, iteration) {
+			await fire(hooks?.onHandoff, {
+				event: "on_handoff",
+				blockletId,
+				from,
+				to,
+				...iteration !== void 0 ? { iteration } : {},
+				ts: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		},
+		async fireOnSkillStart(skill, args) {
+			await fire(hooks?.onSkillStart, {
+				event: "on_skill_start",
+				blockletId,
+				skill,
+				args: sanitizePayloadForHook(args),
+				ts: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		},
+		async fireOnSkillEnd(skill, payload) {
+			await fire(hooks?.onSkillEnd, {
+				event: "on_skill_end",
+				blockletId,
+				skill,
+				status: payload.status,
+				...payload.result !== void 0 ? { result: payload.result } : {},
+				...payload.error !== void 0 ? { error: payload.error } : {},
+				durationMs: payload.durationMs,
+				ts: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		}
+	};
+}
+
+//#endregion
+exports.createHookDispatcher = createHookDispatcher;
+exports.fireHook = fireHook;

package/dist/agent-runners/hooks.d.cts

@@ -0,0 +1,41 @@
+import { AFSRoot } from "@aigne/afs";
+
+//#region src/agent-runners/hooks.d.ts
+interface HookConfig {
+  onStart?: string;
+  onSuccess?: string;
+  onError?: string;
+  onHandoff?: string;
+  onSkillStart?: string;
+  onSkillEnd?: string;
+}
+interface SkillEndPayload {
+  status: "ok" | "error";
+  result?: unknown;
+  error?: string;
+  durationMs: number;
+}
+declare function fireHook(afs: AFSRoot, hookPath: string, payload: Record<string, unknown>, opts: {
+  session?: string;
+  chainDepth?: number;
+}): Promise<void>;
+interface HookDispatcher {
+  fireOnStart(input: Record<string, unknown>): Promise<void>;
+  fireOnSuccess(result: unknown): Promise<void>;
+  fireOnError(error: {
+    code: string;
+    message: string;
+  }): Promise<void>;
+  fireOnHandoff(from: string, to: string, iteration?: number): Promise<void>;
+  fireOnSkillStart(skill: string, args: Record<string, unknown>): Promise<void>;
+  fireOnSkillEnd(skill: string, payload: SkillEndPayload): Promise<void>;
+}
+declare function createHookDispatcher(afs: AFSRoot, hooks: HookConfig | undefined, opts: {
+  mountPath: string;
+  blockletId: string;
+  session?: string;
+  chainDepth?: number;
+}): HookDispatcher;
+//#endregion
+export { HookConfig, HookDispatcher, SkillEndPayload, createHookDispatcher, fireHook };
+//# sourceMappingURL=hooks.d.cts.map

package/dist/agent-runners/hooks.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.cts","names":[],"sources":["../../src/agent-runners/hooks.ts"],"mappings":";;;UAMiB,UAAA;EACf,OAAA;EACA,SAAA;EACA,OAAA;EACA,SAAA;EACA,YAAA;EACA,UAAA;AAAA;AAAA,UAGe,eAAA;EACf,MAAA;EACA,MAAA;EACA,KAAA;EACA,UAAA;AAAA;AAAA,iBAiBoB,QAAA,CACpB,GAAA,EAAK,OAAA,EACL,QAAA,UACA,OAAA,EAAS,MAAA,mBACT,IAAA;EAAQ,OAAA;EAAkB,UAAA;AAAA,IACzB,OAAA;AAAA,UAwBc,cAAA;EACf,WAAA,CAAY,KAAA,EAAO,MAAA,oBAA0B,OAAA;EAC7C,aAAA,CAAc,MAAA,YAAkB,OAAA;EAChC,WAAA,CAAY,KAAA;IAAS,IAAA;IAAc,OAAA;EAAA,IAAoB,OAAA;EACvD,aAAA,CAAc,IAAA,UAAc,EAAA,UAAY,SAAA,YAAqB,OAAA;EAC7D,gBAAA,CAAiB,KAAA,UAAe,IAAA,EAAM,MAAA,oBAA0B,OAAA;EAChE,cAAA,CAAe,KAAA,UAAe,OAAA,EAAS,eAAA,GAAkB,OAAA;AAAA;AAAA,iBAG3C,oBAAA,CACd,GAAA,EAAK,OAAA,EACL,KAAA,EAAO,UAAA,cACP,IAAA;EAAQ,SAAA;EAAmB,UAAA;EAAoB,OAAA;EAAkB,UAAA;AAAA,IAChE,cAAA"}

package/dist/agent-runners/hooks.d.mts

@@ -0,0 +1,41 @@
+import { AFSRoot } from "@aigne/afs";
+
+//#region src/agent-runners/hooks.d.ts
+interface HookConfig {
+  onStart?: string;
+  onSuccess?: string;
+  onError?: string;
+  onHandoff?: string;
+  onSkillStart?: string;
+  onSkillEnd?: string;
+}
+interface SkillEndPayload {
+  status: "ok" | "error";
+  result?: unknown;
+  error?: string;
+  durationMs: number;
+}
+declare function fireHook(afs: AFSRoot, hookPath: string, payload: Record<string, unknown>, opts: {
+  session?: string;
+  chainDepth?: number;
+}): Promise<void>;
+interface HookDispatcher {
+  fireOnStart(input: Record<string, unknown>): Promise<void>;
+  fireOnSuccess(result: unknown): Promise<void>;
+  fireOnError(error: {
+    code: string;
+    message: string;
+  }): Promise<void>;
+  fireOnHandoff(from: string, to: string, iteration?: number): Promise<void>;
+  fireOnSkillStart(skill: string, args: Record<string, unknown>): Promise<void>;
+  fireOnSkillEnd(skill: string, payload: SkillEndPayload): Promise<void>;
+}
+declare function createHookDispatcher(afs: AFSRoot, hooks: HookConfig | undefined, opts: {
+  mountPath: string;
+  blockletId: string;
+  session?: string;
+  chainDepth?: number;
+}): HookDispatcher;
+//#endregion
+export { HookConfig, HookDispatcher, SkillEndPayload, createHookDispatcher, fireHook };
+//# sourceMappingURL=hooks.d.mts.map

package/dist/agent-runners/hooks.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.mts","names":[],"sources":["../../src/agent-runners/hooks.ts"],"mappings":";;;UAMiB,UAAA;EACf,OAAA;EACA,SAAA;EACA,OAAA;EACA,SAAA;EACA,YAAA;EACA,UAAA;AAAA;AAAA,UAGe,eAAA;EACf,MAAA;EACA,MAAA;EACA,KAAA;EACA,UAAA;AAAA;AAAA,iBAiBoB,QAAA,CACpB,GAAA,EAAK,OAAA,EACL,QAAA,UACA,OAAA,EAAS,MAAA,mBACT,IAAA;EAAQ,OAAA;EAAkB,UAAA;AAAA,IACzB,OAAA;AAAA,UAwBc,cAAA;EACf,WAAA,CAAY,KAAA,EAAO,MAAA,oBAA0B,OAAA;EAC7C,aAAA,CAAc,MAAA,YAAkB,OAAA;EAChC,WAAA,CAAY,KAAA;IAAS,IAAA;IAAc,OAAA;EAAA,IAAoB,OAAA;EACvD,aAAA,CAAc,IAAA,UAAc,EAAA,UAAY,SAAA,YAAqB,OAAA;EAC7D,gBAAA,CAAiB,KAAA,UAAe,IAAA,EAAM,MAAA,oBAA0B,OAAA;EAChE,cAAA,CAAe,KAAA,UAAe,OAAA,EAAS,eAAA,GAAkB,OAAA;AAAA;AAAA,iBAG3C,oBAAA,CACd,GAAA,EAAK,OAAA,EACL,KAAA,EAAO,UAAA,cACP,IAAA;EAAQ,SAAA;EAAmB,UAAA;EAAoB,OAAA;EAAkB,UAAA;AAAA,IAChE,cAAA"}

package/dist/agent-runners/hooks.mjs

@@ -0,0 +1,107 @@
+import { joinURL } from "ufo";
+import { makeNsLog } from "@aigne/afs";
+
+//#region src/agent-runners/hooks.ts
+const log = makeNsLog("agent-runtime");
+const MAX_HOOK_CHAIN_DEPTH = 3;
+const INTERNAL_FIELD_PREFIX = "_";
+function sanitizePayloadForHook(obj) {
+	const sanitized = {};
+	for (const [key, value] of Object.entries(obj)) if (!key.startsWith(INTERNAL_FIELD_PREFIX)) sanitized[key] = value;
+	return sanitized;
+}
+async function fireHook(afs, hookPath, payload, opts) {
+	const chainDepth = opts.chainDepth ?? 0;
+	if (chainDepth >= MAX_HOOK_CHAIN_DEPTH) {
+		log.warn(`[hooks] Chain depth ${chainDepth} >= ${MAX_HOOK_CHAIN_DEPTH}, skipping: ${hookPath}`);
+		return;
+	}
+	const cloned = structuredClone(sanitizePayloadForHook(payload));
+	const hookSession = opts.session ? `${opts.session}-hook-${Date.now()}` : void 0;
+	try {
+		await afs.exec(hookPath, {
+			...cloned,
+			session: hookSession,
+			_hook_chain_depth: chainDepth + 1
+		}, {});
+	} catch (err) {
+		log.warn(`[hooks] Hook "${hookPath}" failed: ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
+function createHookDispatcher(afs, hooks, opts) {
+	const { mountPath, blockletId, session, chainDepth = 0 } = opts;
+	const resolve = (hookRef) => {
+		if (!hookRef) return null;
+		if (hookRef.startsWith("/")) return hookRef;
+		return joinURL(mountPath, hookRef);
+	};
+	const fire = async (hookRef, payload) => {
+		const path = resolve(hookRef);
+		if (!path) return;
+		await fireHook(afs, path, payload, {
+			session,
+			chainDepth
+		});
+	};
+	return {
+		async fireOnStart(input) {
+			await fire(hooks?.onStart, {
+				event: "on_start",
+				blockletId,
+				input: sanitizePayloadForHook(input),
+				ts: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		},
+		async fireOnSuccess(result) {
+			await fire(hooks?.onSuccess, {
+				event: "on_success",
+				blockletId,
+				result,
+				ts: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		},
+		async fireOnError(error) {
+			await fire(hooks?.onError, {
+				event: "on_error",
+				blockletId,
+				error,
+				ts: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		},
+		async fireOnHandoff(from, to, iteration) {
+			await fire(hooks?.onHandoff, {
+				event: "on_handoff",
+				blockletId,
+				from,
+				to,
+				...iteration !== void 0 ? { iteration } : {},
+				ts: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		},
+		async fireOnSkillStart(skill, args) {
+			await fire(hooks?.onSkillStart, {
+				event: "on_skill_start",
+				blockletId,
+				skill,
+				args: sanitizePayloadForHook(args),
+				ts: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		},
+		async fireOnSkillEnd(skill, payload) {
+			await fire(hooks?.onSkillEnd, {
+				event: "on_skill_end",
+				blockletId,
+				skill,
+				status: payload.status,
+				...payload.result !== void 0 ? { result: payload.result } : {},
+				...payload.error !== void 0 ? { error: payload.error } : {},
+				durationMs: payload.durationMs,
+				ts: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		}
+	};
+}
+
+//#endregion
+export { createHookDispatcher, fireHook };
+//# sourceMappingURL=hooks.mjs.map

package/dist/agent-runners/hooks.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.mjs","names":[],"sources":["../../src/agent-runners/hooks.ts"],"sourcesContent":["import type { AFSRoot } from \"@aigne/afs\";\nimport { makeNsLog } from \"@aigne/afs\";\nimport { joinURL } from \"ufo\";\n\nconst log = makeNsLog(\"agent-runtime\");\n\nexport interface HookConfig {\n  onStart?: string;\n  onSuccess?: string;\n  onError?: string;\n  onHandoff?: string;\n  onSkillStart?: string;\n  onSkillEnd?: string;\n}\n\nexport interface SkillEndPayload {\n  status: \"ok\" | \"error\";\n  result?: unknown;\n  error?: string;\n  durationMs: number;\n}\n\nconst MAX_HOOK_CHAIN_DEPTH = 3;\n\nconst INTERNAL_FIELD_PREFIX = \"_\";\n\nfunction sanitizePayloadForHook(obj: Record<string, unknown>): Record<string, unknown> {\n  const sanitized: Record<string, unknown> = {};\n  for (const [key, value] of Object.entries(obj)) {\n    if (!key.startsWith(INTERNAL_FIELD_PREFIX)) {\n      sanitized[key] = value;\n    }\n  }\n  return sanitized;\n}\n\nexport async function fireHook(\n  afs: AFSRoot,\n  hookPath: string,\n  payload: Record<string, unknown>,\n  opts: { session?: string; chainDepth?: number },\n): Promise<void> {\n  const chainDepth = opts.chainDepth ?? 0;\n\n  if (chainDepth >= MAX_HOOK_CHAIN_DEPTH) {\n    log.warn(`[hooks] Chain depth ${chainDepth} >= ${MAX_HOOK_CHAIN_DEPTH}, skipping: ${hookPath}`);\n    return;\n  }\n\n  const cloned = structuredClone(sanitizePayloadForHook(payload));\n  const hookSession = opts.session ? `${opts.session}-hook-${Date.now()}` : undefined;\n\n  try {\n    await afs.exec!(\n      hookPath,\n      { ...cloned, session: hookSession, _hook_chain_depth: chainDepth + 1 },\n      {},\n    );\n  } catch (err) {\n    log.warn(\n      `[hooks] Hook \"${hookPath}\" failed: ${err instanceof Error ? err.message : String(err)}`,\n    );\n  }\n}\n\nexport interface HookDispatcher {\n  fireOnStart(input: Record<string, unknown>): Promise<void>;\n  fireOnSuccess(result: unknown): Promise<void>;\n  fireOnError(error: { code: string; message: string }): Promise<void>;\n  fireOnHandoff(from: string, to: string, iteration?: number): Promise<void>;\n  fireOnSkillStart(skill: string, args: Record<string, unknown>): Promise<void>;\n  fireOnSkillEnd(skill: string, payload: SkillEndPayload): Promise<void>;\n}\n\nexport function createHookDispatcher(\n  afs: AFSRoot,\n  hooks: HookConfig | undefined,\n  opts: { mountPath: string; blockletId: string; session?: string; chainDepth?: number },\n): HookDispatcher {\n  const { mountPath, blockletId, session, chainDepth = 0 } = opts;\n\n  const resolve = (hookRef: string | undefined): string | null => {\n    if (!hookRef) return null;\n    if (hookRef.startsWith(\"/\")) return hookRef;\n    return joinURL(mountPath, hookRef);\n  };\n\n  const fire = async (hookRef: string | undefined, payload: Record<string, unknown>) => {\n    const path = resolve(hookRef);\n    if (!path) return;\n    await fireHook(afs, path, payload, { session, chainDepth });\n  };\n\n  return {\n    async fireOnStart(input) {\n      await fire(hooks?.onStart, {\n        event: \"on_start\",\n        blockletId,\n        input: sanitizePayloadForHook(input),\n        ts: new Date().toISOString(),\n      });\n    },\n    async fireOnSuccess(result) {\n      await fire(hooks?.onSuccess, {\n        event: \"on_success\",\n        blockletId,\n        result: result as Record<string, unknown>,\n        ts: new Date().toISOString(),\n      });\n    },\n    async fireOnError(error) {\n      await fire(hooks?.onError, {\n        event: \"on_error\",\n        blockletId,\n        error,\n        ts: new Date().toISOString(),\n      });\n    },\n    async fireOnHandoff(from, to, iteration?) {\n      await fire(hooks?.onHandoff, {\n        event: \"on_handoff\",\n        blockletId,\n        from,\n        to,\n        ...(iteration !== undefined ? { iteration } : {}),\n        ts: new Date().toISOString(),\n      });\n    },\n    async fireOnSkillStart(skill, args) {\n      await fire(hooks?.onSkillStart, {\n        event: \"on_skill_start\",\n        blockletId,\n        skill,\n        args: sanitizePayloadForHook(args),\n        ts: new Date().toISOString(),\n      });\n    },\n    async fireOnSkillEnd(skill, payload) {\n      await fire(hooks?.onSkillEnd, {\n        event: \"on_skill_end\",\n        blockletId,\n        skill,\n        status: payload.status,\n        ...(payload.result !== undefined ? { result: payload.result } : {}),\n        ...(payload.error !== undefined ? { error: payload.error } : {}),\n        durationMs: payload.durationMs,\n        ts: new Date().toISOString(),\n      });\n    },\n  };\n}\n"],"mappings":";;;;AAIA,MAAM,MAAM,UAAU,gBAAgB;AAkBtC,MAAM,uBAAuB;AAE7B,MAAM,wBAAwB;AAE9B,SAAS,uBAAuB,KAAuD;CACrF,MAAM,YAAqC,EAAE;AAC7C,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,IAAI,CAC5C,KAAI,CAAC,IAAI,WAAW,sBAAsB,CACxC,WAAU,OAAO;AAGrB,QAAO;;AAGT,eAAsB,SACpB,KACA,UACA,SACA,MACe;CACf,MAAM,aAAa,KAAK,cAAc;AAEtC,KAAI,cAAc,sBAAsB;AACtC,MAAI,KAAK,uBAAuB,WAAW,MAAM,qBAAqB,cAAc,WAAW;AAC/F;;CAGF,MAAM,SAAS,gBAAgB,uBAAuB,QAAQ,CAAC;CAC/D,MAAM,cAAc,KAAK,UAAU,GAAG,KAAK,QAAQ,QAAQ,KAAK,KAAK,KAAK;AAE1E,KAAI;AACF,QAAM,IAAI,KACR,UACA;GAAE,GAAG;GAAQ,SAAS;GAAa,mBAAmB,aAAa;GAAG,EACtE,EAAE,CACH;UACM,KAAK;AACZ,MAAI,KACF,iBAAiB,SAAS,YAAY,eAAe,QAAQ,IAAI,UAAU,OAAO,IAAI,GACvF;;;AAaL,SAAgB,qBACd,KACA,OACA,MACgB;CAChB,MAAM,EAAE,WAAW,YAAY,SAAS,aAAa,MAAM;CAE3D,MAAM,WAAW,YAA+C;AAC9D,MAAI,CAAC,QAAS,QAAO;AACrB,MAAI,QAAQ,WAAW,IAAI,CAAE,QAAO;AACpC,SAAO,QAAQ,WAAW,QAAQ;;CAGpC,MAAM,OAAO,OAAO,SAA6B,YAAqC;EACpF,MAAM,OAAO,QAAQ,QAAQ;AAC7B,MAAI,CAAC,KAAM;AACX,QAAM,SAAS,KAAK,MAAM,SAAS;GAAE;GAAS;GAAY,CAAC;;AAG7D,QAAO;EACL,MAAM,YAAY,OAAO;AACvB,SAAM,KAAK,OAAO,SAAS;IACzB,OAAO;IACP;IACA,OAAO,uBAAuB,MAAM;IACpC,qBAAI,IAAI,MAAM,EAAC,aAAa;IAC7B,CAAC;;EAEJ,MAAM,cAAc,QAAQ;AAC1B,SAAM,KAAK,OAAO,WAAW;IAC3B,OAAO;IACP;IACQ;IACR,qBAAI,IAAI,MAAM,EAAC,aAAa;IAC7B,CAAC;;EAEJ,MAAM,YAAY,OAAO;AACvB,SAAM,KAAK,OAAO,SAAS;IACzB,OAAO;IACP;IACA;IACA,qBAAI,IAAI,MAAM,EAAC,aAAa;IAC7B,CAAC;;EAEJ,MAAM,cAAc,MAAM,IAAI,WAAY;AACxC,SAAM,KAAK,OAAO,WAAW;IAC3B,OAAO;IACP;IACA;IACA;IACA,GAAI,cAAc,SAAY,EAAE,WAAW,GAAG,EAAE;IAChD,qBAAI,IAAI,MAAM,EAAC,aAAa;IAC7B,CAAC;;EAEJ,MAAM,iBAAiB,OAAO,MAAM;AAClC,SAAM,KAAK,OAAO,cAAc;IAC9B,OAAO;IACP;IACA;IACA,MAAM,uBAAuB,KAAK;IAClC,qBAAI,IAAI,MAAM,EAAC,aAAa;IAC7B,CAAC;;EAEJ,MAAM,eAAe,OAAO,SAAS;AACnC,SAAM,KAAK,OAAO,YAAY;IAC5B,OAAO;IACP;IACA;IACA,QAAQ,QAAQ;IAChB,GAAI,QAAQ,WAAW,SAAY,EAAE,QAAQ,QAAQ,QAAQ,GAAG,EAAE;IAClE,GAAI,QAAQ,UAAU,SAAY,EAAE,OAAO,QAAQ,OAAO,GAAG,EAAE;IAC/D,YAAY,QAAQ;IACpB,qBAAI,IAAI,MAAM,EAAC,aAAa;IAC7B,CAAC;;EAEL"}