libfx 0.0.14-dev.1534.g6afa7c33dac5 → 0.0.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/node.cjs CHANGED
@@ -441,7 +441,13 @@ function foldSessionLog(entries, { now = 0, alive = () => null } = {}) {
441
441
  }
442
442
  }
443
443
  for (const input of inputs) {
444
- if (input.type !== "cancel" || consumed.has(input.messageId))
444
+ if (consumed.has(input.messageId))
445
+ continue;
446
+ if (input.type === "resume") {
447
+ consume(input.messageId);
448
+ continue;
449
+ }
450
+ if (input.type !== "cancel")
445
451
  continue;
446
452
  const live = typeof input.target === "string" ? !consumed.has(input.target) || openTurn?.id === input.target : openTurn !== null && input.cursor > openTurn.at;
447
453
  if (!live)
@@ -720,6 +726,7 @@ function noAgentNamed(name) {
720
726
  return Object.assign(new Error(`no libfx agent named ${JSON.stringify(name)} runs in this process; the queue delivers this again`), { code: "FX_NO_AGENT", agent: name });
721
727
  }
722
728
  var agentsByName = globalThis[Symbol.for("libfx.durableAgents")] ??= new Map;
729
+ var openMember = (member) => member.open().catch(() => null);
723
730
  async function agentNamed(name, matches) {
724
731
  const group = agentsByName.get(name);
725
732
  if (!group)
@@ -730,26 +737,63 @@ async function agentNamed(name, matches) {
730
737
  const member = members[(first + index) % members.length];
731
738
  if (!matches(await member.durability()))
732
739
  continue;
733
- const created = await member.open();
734
- if (typeof created.deliverHere === "function")
740
+ const created = await openMember(member);
741
+ if (typeof created?.deliverHere === "function")
735
742
  return created;
736
743
  }
737
744
  return null;
738
745
  }
739
746
  var agentSharing = (name, durability) => agentNamed(name, (other) => other === durability);
740
- var agentOnRoute = async (name, durability) => await agentSharing(name, durability) ?? agentNamed(name, (other) => other !== durability && other.name === durability.name && typeof other.world === "function" && other.create === undefined);
747
+ var worldStore = (durability) => durability?.store ?? durability?.name;
748
+ var storeOf = (durability) => typeof durability?.create === "function" ? durability : `world:${worldStore(durability)}`;
749
+ var agentOnStore = (name, store) => agentNamed(name, (other) => typeof other.world === "function" && other.create === undefined && worldStore(other) === store);
741
750
  function wakeHandler() {
742
751
  return async (request) => {
743
752
  for (const group of agentsByName.values()) {
744
753
  for (const member of group.members) {
745
- const created = await member.open();
746
- if (created.viaRoute === true)
754
+ const created = await openMember(member);
755
+ if (created?.viaRoute === true)
747
756
  return created.queueHandler(request);
748
757
  }
749
758
  }
750
759
  return new Response("no libfx agent in this process takes queue deliveries from a route", { status: 503 });
751
760
  };
752
761
  }
762
+ var nameInUse = (name) => Object.assign(new Error(`an agent named ${JSON.stringify(name)} with another configuration already runs on this store in this process; give each configuration its own name, or each store its own \`store\``), { code: "FX_AGENT_NAME_IN_USE", agent: name });
763
+ function definitionOf(options) {
764
+ const { onEvent: _onEvent, ...definition } = options;
765
+ return definition;
766
+ }
767
+ function sameDefinition(a, b, depth = 0) {
768
+ if (Object.is(a, b))
769
+ return true;
770
+ if (depth > 32 || a === null || b === null || typeof a !== "object" || typeof b !== "object")
771
+ return false;
772
+ if (ArrayBuffer.isView(a) || ArrayBuffer.isView(b)) {
773
+ if (!ArrayBuffer.isView(a) || !ArrayBuffer.isView(b) || a.byteLength !== b.byteLength)
774
+ return false;
775
+ const left = new Uint8Array(a.buffer, a.byteOffset, a.byteLength);
776
+ const right = new Uint8Array(b.buffer, b.byteOffset, b.byteLength);
777
+ for (let index = 0;index < left.length; index += 1)
778
+ if (left[index] !== right[index])
779
+ return false;
780
+ return true;
781
+ }
782
+ const plain = (value) => Array.isArray(value) || Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null;
783
+ if (!plain(a) || !plain(b) || Array.isArray(a) !== Array.isArray(b))
784
+ return false;
785
+ const keys = Object.keys(a);
786
+ if (keys.length !== Object.keys(b).length)
787
+ return false;
788
+ return keys.every((key) => Object.hasOwn(b, key) && sameDefinition(a[key], b[key], depth + 1));
789
+ }
790
+ var sameStore = (a, b) => a.store === b.store || a.defaults !== null && a.defaults === b.defaults;
791
+ function claimName(name, member) {
792
+ for (const other of agentsByName.get(name)?.members ?? []) {
793
+ if (other !== member && sameStore(other, member) && !sameDefinition(other.definition, member.definition))
794
+ throw nameInUse(name);
795
+ }
796
+ }
753
797
  function createWorldBackend(world, durability) {
754
798
  const { name, reserveMs, pollMs, leaseMs, alive, holderInfo, livenessKnown = false, queueLeases = false, runInRequest = queueLeases, waitUntil, queueDurable = false, maxDurationMs, owned = true } = durability;
755
799
  const spec = world.specVersion === undefined ? {} : { specVersion: world.specVersion };
@@ -781,15 +825,17 @@ function createWorldBackend(world, durability) {
781
825
  throw new Error("libfx asks the queue to deliver this message again");
782
826
  return Number.isFinite(result?.timeoutSeconds) ? { timeoutSeconds: result.timeoutSeconds } : undefined;
783
827
  };
828
+ const store = worldStore(durability);
784
829
  const queueHandler = world.createQueueHandler(queuePrefix, async (message, meta) => {
785
830
  const named = agentOf(message?.input);
786
- const agent = await agentOnRoute(named, durability);
831
+ const agent = await agentOnStore(named, typeof message?.input?.store === "string" ? message.input.store : store);
787
832
  if (!agent)
788
833
  throw noAgentNamed(named);
789
834
  return agent.deliverHere(message, meta);
790
835
  });
791
836
  const backend = {
792
837
  name,
838
+ store,
793
839
  livenessKnown,
794
840
  queueLeases,
795
841
  runInRequest: queueLeases && runInRequest,
@@ -1145,6 +1191,33 @@ function uiWriter(log, onError, epoch) {
1145
1191
  var runOf = (input) => ({ context: input?.context ?? null, settings: input?.settings ?? null });
1146
1192
  var errorSummary = (error) => ({ name: error?.name ?? "Error", message: String(error?.message ?? error), ...error?.code ? { code: error.code } : {} });
1147
1193
  var isFenced = (error) => error?.code === "FX_FENCED";
1194
+ var messageTypes = new Set(["prompt", "steer", "cancel", "resume"]);
1195
+ function queuedMessage(message, store) {
1196
+ return {
1197
+ type: message.type,
1198
+ messageId: message.messageId,
1199
+ sessionId: message.sessionId,
1200
+ agent: typeof message.agent === "string" ? message.agent : defaultAgentName,
1201
+ ...typeof store === "string" ? { store } : {}
1202
+ };
1203
+ }
1204
+ function deliveredMessage(backend, delivered) {
1205
+ if (!delivered || typeof delivered !== "object" || !messageTypes.has(delivered.type))
1206
+ return null;
1207
+ if (!validId(delivered.messageId) || !backend.validSessionId(delivered.sessionId))
1208
+ return null;
1209
+ if (delivered.agent !== undefined && typeof delivered.agent !== "string")
1210
+ return null;
1211
+ return queuedMessage(delivered);
1212
+ }
1213
+ var knownMessage = (state, message) => state.inputKeys.has(`${message.type}:${message.messageId}`) || state.consumed.has(message.messageId);
1214
+ var maxInputBytes = 8 * 1024 * 1024;
1215
+ var jsonBytes = (value) => value === undefined ? 0 : encoder.encode(JSON.stringify(value)).byteLength;
1216
+ var jsonSnapshot = (value) => {
1217
+ const text = JSON.stringify(value);
1218
+ return text === undefined ? undefined : JSON.parse(text);
1219
+ };
1220
+ var inputTooLarge = (bytes) => Object.assign(new RangeError(`a durable input with its context and settings is ${bytes} bytes; the most is ${maxInputBytes}`), { code: "FX_INPUT_TOO_LARGE", bytes, limit: maxInputBytes });
1148
1221
  function messageEntries(state, message) {
1149
1222
  const entries = [];
1150
1223
  const named = typeof message.agent === "string" ? { agent: message.agent } : {};
@@ -1153,7 +1226,7 @@ function messageEntries(state, message) {
1153
1226
  }
1154
1227
  const key = `${message.type}:${message.messageId}`;
1155
1228
  const known = state.inputKeys.has(key) || state.consumed.has(message.messageId) || idInUse(state, message);
1156
- if ((message.type === "prompt" || message.type === "steer" || message.type === "cancel") && !known) {
1229
+ if (messageTypes.has(message.type) && !known) {
1157
1230
  entries.push({
1158
1231
  k: "input",
1159
1232
  key,
@@ -1230,13 +1303,17 @@ class SessionWorker {
1230
1303
  }
1231
1304
  async consume(message, delivery = null) {
1232
1305
  const log = await this.backend.session(this.sessionId);
1233
- await this.backend.refreshDeadline?.();
1234
- const deadline = this.backend.deadline() ?? (this.backend.maxDurationMs === null ? null : Date.now() + this.backend.maxDurationMs);
1235
1306
  let entries = await log.read();
1236
1307
  let state = this.fold(entries, delivery);
1308
+ if (!knownMessage(state, message)) {
1309
+ this.agent.emit("session.refused", { sessionId: this.sessionId, messageId: message.messageId, reason: "unknown message" });
1310
+ return;
1311
+ }
1312
+ await this.backend.refreshDeadline?.();
1313
+ const deadline = this.backend.deadline() ?? (this.backend.maxDurationMs === null ? null : Date.now() + this.backend.maxDurationMs);
1237
1314
  const owner = state.agent ?? agentOf(message);
1238
1315
  if (owner !== this.agent.name) {
1239
- await this.backend.queue.send({ ...message, agent: owner }, {
1316
+ await this.backend.queue.send(queuedMessage({ ...message, agent: owner }, this.backend.store), {
1240
1317
  idempotencyKey: `${message.sessionId}:${message.type}:${message.messageId}:to:${owner}`
1241
1318
  });
1242
1319
  this.agent.emit("session.forwarded", { sessionId: this.sessionId, agent: owner });
@@ -1248,19 +1325,6 @@ class SessionWorker {
1248
1325
  if (early) {
1249
1326
  outcome = await this.claim(log, state, deadline, early, delivery);
1250
1327
  } else {
1251
- let wrote;
1252
- try {
1253
- wrote = await recordMessage(log, state, message);
1254
- } catch (error) {
1255
- if (error?.code !== "FX_MESSAGE_ID_IN_USE")
1256
- throw error;
1257
- this.agent.emit("session.error", { sessionId: this.sessionId, error: errorSummary(error) });
1258
- return;
1259
- }
1260
- if (wrote > 0) {
1261
- entries = await log.read();
1262
- state = this.fold(entries, delivery);
1263
- }
1264
1328
  if (this.running)
1265
1329
  return { timeoutSeconds: runningBackstopSeconds };
1266
1330
  if (!state.hasWork) {
@@ -1628,7 +1692,7 @@ class SessionWorker {
1628
1692
  }
1629
1693
  }
1630
1694
  async drive(log, harness, turn, messageId, state, ui) {
1631
- const applied = new Set;
1695
+ const applied = new Set(state.inputKeys);
1632
1696
  let since = String(state.maxCursor);
1633
1697
  let polling = false;
1634
1698
  let again = false;
@@ -1641,6 +1705,8 @@ class SessionWorker {
1641
1705
  Promise.resolve().then(() => turn.endForSteer?.()).catch(() => {});
1642
1706
  };
1643
1707
  const steerTurn = (steer) => {
1708
+ if (steer.messageId === messageId)
1709
+ return;
1644
1710
  if (!joinable(steer.input))
1645
1711
  endTurn();
1646
1712
  else if (!ending)
@@ -1972,7 +2038,7 @@ function turnView({ messageId, resumeRequest = null, start }) {
1972
2038
  }
1973
2039
  };
1974
2040
  }
1975
- function createDurableAgentFactory({ harness, defaultDurability, name = "createAgent", label = "agent" }) {
2041
+ function createDurableAgentFactory({ harness, defaultDurability, defaultShared = false, name = "createAgent", label = "agent" }) {
1976
2042
  return function createDurableAgent(options = {}) {
1977
2043
  if (!options || typeof options !== "object" || Array.isArray(options)) {
1978
2044
  throw new TypeError(`${name}() options must be an object`);
@@ -2019,16 +2085,34 @@ function createDurableAgentFactory({ harness, defaultDurability, name = "createA
2019
2085
  return Promise.reject(new Error(`${label} is closed`));
2020
2086
  backendPromise ??= (async () => {
2021
2087
  const chosen = await durabilityOf();
2088
+ if (member.store !== storeOf(chosen)) {
2089
+ member.store = storeOf(chosen);
2090
+ try {
2091
+ claimName(agentName, member);
2092
+ } catch (error) {
2093
+ leaveGroup(agentsByName, agentName, registered, member);
2094
+ throw error;
2095
+ }
2096
+ }
2022
2097
  chosenDurability = chosen;
2023
2098
  const created = await createBackend(chosen);
2024
2099
  await created.start?.();
2025
- unlisten = created.listen((message, meta) => receive(created, message, deliveryOf(meta)), agentName);
2100
+ unlisten = created.listen((delivered, meta) => {
2101
+ const message = deliveredMessage(created, delivered);
2102
+ if (!message) {
2103
+ emit("session.refused", { reason: "malformed message" });
2104
+ return;
2105
+ }
2106
+ return receive(created, message, deliveryOf(meta));
2107
+ }, agentName);
2026
2108
  return created;
2027
2109
  })();
2028
2110
  return backendPromise;
2029
2111
  };
2030
2112
  const durabilityOf = () => durabilityPromise ??= durability ? Promise.resolve(durability) : defaultDurability();
2031
- const member = { open: backend, durability: durabilityOf };
2113
+ const unresolved = defaultShared ? defaultDurability : Symbol("default store");
2114
+ const member = { open: backend, durability: durabilityOf, definition: definitionOf(harnessOptions), store: durability ? storeOf(durability) : unresolved, defaults: durability ? null : unresolved };
2115
+ claimName(agentName, member);
2032
2116
  const registered = joinGroup(agentsByName, agentName, member);
2033
2117
  const receive = (created, message, delivery, { inRequest = false } = {}) => {
2034
2118
  let worker = workers.get(message.sessionId);
@@ -2063,15 +2147,19 @@ function createDurableAgentFactory({ harness, defaultDurability, name = "createA
2063
2147
  const openSession = (requestedId, sessionOptions = {}) => {
2064
2148
  if (requestedId !== undefined && !validId(requestedId))
2065
2149
  throw new TypeError(`session id must be ${idRule}`);
2066
- const context = sessionOptions?.context;
2067
- if (context !== undefined) {
2068
- try {
2069
- JSON.stringify(context);
2070
- } catch {
2071
- throw new TypeError("session context must be JSON");
2072
- }
2150
+ let context;
2151
+ try {
2152
+ context = jsonSnapshot(sessionOptions?.context);
2153
+ } catch {
2154
+ throw new TypeError("session context must be JSON");
2073
2155
  }
2074
- const settings = plugged.settings?.(sessionOptions ?? {});
2156
+ const settings = jsonSnapshot(plugged.settings?.(sessionOptions ?? {}));
2157
+ const carried = jsonBytes(context) + jsonBytes(settings);
2158
+ const admit = (input) => {
2159
+ const bytes = jsonBytes(input) + carried;
2160
+ if (bytes > maxInputBytes)
2161
+ throw inputTooLarge(bytes);
2162
+ };
2075
2163
  let id = requestedId ?? null;
2076
2164
  let seeded = seed === undefined || requestedId !== undefined;
2077
2165
  const resolved = backend().then((created) => {
@@ -2089,25 +2177,24 @@ function createDurableAgentFactory({ harness, defaultDurability, name = "createA
2089
2177
  ...settings === undefined ? {} : { settings }
2090
2178
  };
2091
2179
  const full = { ...message, ...extra, agent: agentName, sessionId };
2092
- if (!created.queueDurable) {
2093
- const log = await created.session(sessionId);
2094
- await recordMessage(log, foldSessionLog(await log.read()), full);
2095
- }
2180
+ const log = await created.session(sessionId);
2181
+ await recordMessage(log, foldSessionLog(await log.read()), full);
2182
+ const queued = queuedMessage(full, created.store);
2096
2183
  const idempotencyKey = `${sessionId}:${message.type}:${message.messageId}`;
2097
2184
  if (inRequest && created.runInRequest) {
2098
2185
  await created.refreshDeadline?.();
2099
2186
  const deadline = deliveryDeadline(created);
2100
2187
  if (deadline !== null) {
2101
2188
  const delaySeconds = Math.ceil(Math.max(0, deadline - Date.now()) / 1000) + inlineBackstopMarginSeconds;
2102
- const { messageId: backstop } = await created.queue.send(full, { idempotencyKey, delaySeconds }) ?? {};
2189
+ const { messageId: backstop } = await created.queue.send(queued, { idempotencyKey, delaySeconds }) ?? {};
2103
2190
  seeded = true;
2104
2191
  const delivery = backstop ? { messageId: backstop, attempt: 0 } : null;
2105
- const work = receive(created, full, delivery, { inRequest: true }).then(() => {}, () => {});
2192
+ const work = receive(created, queued, delivery, { inRequest: true }).then(() => {}, () => {});
2106
2193
  created.waitUntil?.(work);
2107
2194
  return;
2108
2195
  }
2109
2196
  }
2110
- await created.queue.send(full, { idempotencyKey });
2197
+ await created.queue.send(queued, { idempotencyKey });
2111
2198
  seeded = true;
2112
2199
  };
2113
2200
  const startTurn = (type, messageId, input, retried = false, aborted = false) => {
@@ -2181,6 +2268,7 @@ function createDurableAgentFactory({ harness, defaultDurability, name = "createA
2181
2268
  if (Array.isArray(input) && input.some((block) => block?.type === "image" && block.data !== undefined && typeof block.data !== "string")) {
2182
2269
  throw new TypeError("a durable prompt carries image data as a base64 string");
2183
2270
  }
2271
+ admit(input);
2184
2272
  const signal = promptOptions.signal;
2185
2273
  if (signal !== undefined && typeof signal?.addEventListener !== "function")
2186
2274
  throw new TypeError("prompt signal must be an AbortSignal");
@@ -2284,6 +2372,7 @@ function createDurableAgentFactory({ harness, defaultDurability, name = "createA
2284
2372
  const messageId = steerOptions.messageId ?? newId("str");
2285
2373
  if (!validId(messageId))
2286
2374
  throw new TypeError(`messageId must be ${idRule}`);
2375
+ admit(input);
2287
2376
  await send({ type: "steer", messageId, input });
2288
2377
  return { messageId };
2289
2378
  },
@@ -2321,7 +2410,11 @@ function createDurableAgentFactory({ harness, defaultDurability, name = "createA
2321
2410
  settled: async (sessionId) => {
2322
2411
  await workers.get(sessionId)?.settled?.();
2323
2412
  },
2324
- deliver: async (message, delivery) => receive(await backend(), message, delivery),
2413
+ deliver: async (delivered, delivery) => {
2414
+ const created = await backend();
2415
+ const message = deliveredMessage(created, delivered);
2416
+ return message ? receive(created, message, delivery) : undefined;
2417
+ },
2325
2418
  liveWorkers: () => workers.size,
2326
2419
  openLog: async (sessionId) => (await backend()).session(sessionId),
2327
2420
  lastLease: async (sessionId) => {
@@ -2821,6 +2914,165 @@ var grokSubscription = {
2821
2914
  }
2822
2915
  };
2823
2916
 
2917
+ // sdk/tool-observation.js
2918
+ function toolObservation(scope, callId, hooks, emit, signal) {
2919
+ const report = (error) => {
2920
+ try {
2921
+ Promise.resolve(hooks.onError?.(error)).catch(() => {});
2922
+ } catch {}
2923
+ };
2924
+ let next = 0;
2925
+ const id = () => `host:${scope.executionId}:${callId}:${++next}`;
2926
+ const publish = (type, data, content = {}) => emit({
2927
+ ...scope,
2928
+ type,
2929
+ data,
2930
+ timestamp: Date.now(),
2931
+ contentCaptured: hooks.captureContent === true,
2932
+ contentTruncated: content.truncated === true
2933
+ });
2934
+ const capture = () => {
2935
+ let remaining = 64 * 1024;
2936
+ return {
2937
+ truncated: false,
2938
+ text(value) {
2939
+ if (hooks.captureContent !== true || value == null)
2940
+ return;
2941
+ value = String(value);
2942
+ let prefix = value.slice(0, remaining);
2943
+ if (prefix.length && /[\uD800-\uDBFF]/.test(prefix.at(-1)))
2944
+ prefix = prefix.slice(0, -1);
2945
+ const bytes = new TextEncoder().encode(prefix);
2946
+ let end = Math.min(bytes.length, remaining);
2947
+ while (end > 0 && end < bytes.length && (bytes[end] & 192) === 128)
2948
+ end--;
2949
+ remaining -= end;
2950
+ this.truncated ||= prefix.length < value.length || end < bytes.length;
2951
+ return new TextDecoder().decode(bytes.subarray(0, end));
2952
+ }
2953
+ };
2954
+ };
2955
+ function terminal(end) {
2956
+ let ended = false;
2957
+ const finish = (...args) => {
2958
+ if (ended)
2959
+ return;
2960
+ ended = true;
2961
+ signal.removeEventListener("abort", abort);
2962
+ try {
2963
+ end(...args);
2964
+ } catch (error) {
2965
+ report(error);
2966
+ }
2967
+ };
2968
+ const abort = () => finish("cancelled", undefined);
2969
+ signal.addEventListener("abort", abort, { once: true });
2970
+ if (signal.aborted)
2971
+ abort();
2972
+ return finish;
2973
+ }
2974
+ return {
2975
+ async wait(request, run) {
2976
+ if (!request || !["approval", "question", "mcp_form", "mcp_url"].includes(request.kind) || typeof run !== "function")
2977
+ throw new TypeError("wait needs an input request and an effect");
2978
+ if (signal.aborted)
2979
+ return run();
2980
+ const requestId = id();
2981
+ const content = capture();
2982
+ content.truncated ||= (request.questions?.length ?? 0) > 128 || (request.questions ?? []).slice(0, 128).some((question) => (question.options?.length ?? 0) > 128);
2983
+ publish("wait.start", {
2984
+ requestId,
2985
+ kind: request.kind,
2986
+ callId,
2987
+ externalId: request.externalId ?? null,
2988
+ server: request.server ?? null,
2989
+ schemaJson: content.text(request.schemaJson),
2990
+ prompt: content.text(request.prompt),
2991
+ questionCount: request.questions?.length ?? 0,
2992
+ ...hooks.captureContent === true ? {
2993
+ questions: (request.questions ?? []).slice(0, 128).map((question) => ({
2994
+ question: content.text(question.question),
2995
+ options: (question.options ?? []).slice(0, 128).map((option) => ({
2996
+ label: content.text(option.label),
2997
+ description: content.text(option.description)
2998
+ }))
2999
+ }))
3000
+ } : {}
3001
+ }, content);
3002
+ const finish = terminal((outcome, result, error) => {
3003
+ const content = capture();
3004
+ content.truncated ||= (result?.answers?.length ?? 0) > 128;
3005
+ publish("wait.end", {
3006
+ requestId,
3007
+ outcome,
3008
+ error: error?.name ?? null,
3009
+ ...hooks.captureContent === true ? {
3010
+ answers: (result?.answers ?? []).slice(0, 128).map((answer) => content.text(answer))
3011
+ } : {}
3012
+ }, content);
3013
+ });
3014
+ try {
3015
+ const result = await run();
3016
+ let outcome = "accepted";
3017
+ try {
3018
+ outcome = result?.outcome ?? outcome;
3019
+ } catch (error) {
3020
+ report(error);
3021
+ }
3022
+ finish(outcome, result);
3023
+ return result;
3024
+ } catch (error) {
3025
+ finish(signal.aborted || error?.name === "AbortError" ? "cancelled" : error?.name === "TimeoutError" ? "timed_out" : "failed", undefined, error);
3026
+ throw error;
3027
+ }
3028
+ },
3029
+ async mcp(identity, run) {
3030
+ if (signal.aborted)
3031
+ return run({ correlationId: identity.correlationId });
3032
+ const operationId = id();
3033
+ publish("mcp.start", {
3034
+ operationId,
3035
+ callId,
3036
+ server: identity.server ?? null,
3037
+ tool: identity.tool,
3038
+ transport: null
3039
+ });
3040
+ if (identity.correlationId !== undefined)
3041
+ publish("mcp.request", {
3042
+ operationId,
3043
+ requestId: identity.correlationId,
3044
+ requestIdKind: "correlation"
3045
+ });
3046
+ const finish = terminal((status, error) => publish("mcp.end", { operationId, status, error: error?.name ?? null }));
3047
+ try {
3048
+ const result = await run({ correlationId: identity.correlationId });
3049
+ let status = "unknown";
3050
+ try {
3051
+ status = result?.isError ? "failure" : "success";
3052
+ } catch (error) {
3053
+ report(error);
3054
+ }
3055
+ finish(status);
3056
+ return result;
3057
+ } catch (error) {
3058
+ finish(signal.aborted || error?.name === "AbortError" ? "cancelled" : "failure", error);
3059
+ throw error;
3060
+ }
3061
+ },
3062
+ childHooks() {
3063
+ return {
3064
+ ...hooks,
3065
+ parent: {
3066
+ rootSessionId: scope.rootSessionId,
3067
+ sessionId: scope.sessionId,
3068
+ turnId: scope.turnId,
3069
+ callId
3070
+ }
3071
+ };
3072
+ }
3073
+ };
3074
+ }
3075
+
2824
3076
  // sdk/fx-sdk.js
2825
3077
  var subscriptionProviders = new Set(["codex", "grok"]);
2826
3078
  var encoder4 = new TextEncoder;
@@ -2947,6 +3199,28 @@ function normalizeAgentOptions(value) {
2947
3199
  throw new TypeError("createFxEngine() options must be an object");
2948
3200
  }
2949
3201
  const options = { ...value };
3202
+ if (options.hooks !== undefined) {
3203
+ const hooks = options.hooks;
3204
+ if (!hooks || typeof hooks !== "object" || Array.isArray(hooks) || typeof hooks.onEvent !== "function") {
3205
+ throw new TypeError("hooks must be an object with onEvent()");
3206
+ }
3207
+ if (hooks.onError !== undefined && typeof hooks.onError !== "function")
3208
+ throw new TypeError("hooks.onError must be a function");
3209
+ if (hooks.captureContent !== undefined && typeof hooks.captureContent !== "boolean")
3210
+ throw new TypeError("hooks.captureContent must be a boolean");
3211
+ options.hooks = {
3212
+ captureContent: hooks.captureContent === true,
3213
+ onEvent: hooks.onEvent.bind(hooks),
3214
+ ...hooks.onError === undefined ? {} : { onError: hooks.onError.bind(hooks) },
3215
+ ...hooks.parent === undefined ? {} : { parent: { ...hooks.parent } }
3216
+ };
3217
+ if (options.hooks.parent !== undefined) {
3218
+ for (const name of ["rootSessionId", "sessionId", "turnId", "callId"]) {
3219
+ if (typeof options.hooks.parent[name] !== "string" || options.hooks.parent[name].length === 0 || options.hooks.parent[name].length > 1024)
3220
+ throw new TypeError(`hooks.parent.${name} must be a bounded identity`);
3221
+ }
3222
+ }
3223
+ }
2950
3224
  if (Object.hasOwn(options, "env")) {
2951
3225
  throw new TypeError("createFxEngine() does not accept env; pass apiKey and model directly");
2952
3226
  }
@@ -5152,6 +5426,58 @@ async function createFxEngine(options = {}) {
5152
5426
  const pending = new Map;
5153
5427
  let nextId = 1;
5154
5428
  let sessionId = null;
5429
+ const hookScopes = new Map;
5430
+ const hookError = (error) => {
5431
+ try {
5432
+ Promise.resolve(options.hooks?.onError?.(error)).catch(() => {});
5433
+ } catch {}
5434
+ };
5435
+ const hook = (event) => {
5436
+ if (!options.hooks)
5437
+ return;
5438
+ if (options.hooks.parent)
5439
+ event = {
5440
+ ...event,
5441
+ rootSessionId: options.hooks.parent.rootSessionId,
5442
+ ...event.sessionId === sessionId && event.parentSessionId == null ? {
5443
+ parentSessionId: options.hooks.parent.sessionId,
5444
+ parentTurnId: options.hooks.parent.turnId,
5445
+ parentCallId: options.hooks.parent.callId
5446
+ } : {}
5447
+ };
5448
+ if (event.type === "tool.start") {
5449
+ const { data, type, ...scope } = event;
5450
+ hookScopes.set(`${event.sessionId}:${data.call.callId}`, scope);
5451
+ } else if (event.type === "tool.end")
5452
+ hookScopes.delete(`${event.sessionId}:${event.data.call.callId}`);
5453
+ else if (event.type === "turn.end") {
5454
+ for (const [key, scope] of hookScopes)
5455
+ if (scope.executionId === event.executionId)
5456
+ hookScopes.delete(key);
5457
+ } else if (event.type === "journal.error" && event.data.fenced)
5458
+ hookScopes.clear();
5459
+ try {
5460
+ Promise.resolve(options.hooks.onEvent(event)).catch(hookError);
5461
+ } catch (error) {
5462
+ hookError(error);
5463
+ }
5464
+ };
5465
+ const journalHook = (type, data) => hook({
5466
+ version: 1,
5467
+ type,
5468
+ sessionId,
5469
+ rootSessionId: sessionId,
5470
+ parentSessionId: null,
5471
+ sourceSessionId: null,
5472
+ workId: null,
5473
+ turnId: null,
5474
+ executionId: null,
5475
+ stepIndex: 0,
5476
+ timestamp: Date.now(),
5477
+ contentCaptured: false,
5478
+ contentTruncated: false,
5479
+ data
5480
+ });
5155
5481
  let activeTurn = null;
5156
5482
  let closing = false;
5157
5483
  let coreExitError = null;
@@ -5177,6 +5503,7 @@ async function createFxEngine(options = {}) {
5177
5503
  if (Number.isSafeInteger(lastSeq))
5178
5504
  appendedSeq = lastSeq;
5179
5505
  bytesSinceCheckpoint += data.byteLength;
5506
+ journalHook("journal.commit", { cursor: result.cursor, firstSeq: Number.isSafeInteger(events[0]?.seq) ? events[0].seq : null, lastSeq: Number.isSafeInteger(lastSeq) ? lastSeq : null, eventCount: events.length });
5180
5507
  });
5181
5508
  appendTail = appended;
5182
5509
  return appended;
@@ -5298,6 +5625,7 @@ async function createFxEngine(options = {}) {
5298
5625
  return;
5299
5626
  journalFailure = journalAppendError(error);
5300
5627
  emit("journal.error", { error: error instanceof Error ? error.name : "Error" });
5628
+ journalHook("journal.error", { error: error instanceof Error ? error.name : "Error", fenced: error?.code === "FX_FENCED" || error?.cause?.code === "FX_FENCED" });
5301
5629
  rejectInputWaiters([...inputWaiters.keys()], journalFailure);
5302
5630
  activeTurn?.cancel();
5303
5631
  }).finally(() => {
@@ -5433,7 +5761,9 @@ async function createFxEngine(options = {}) {
5433
5761
  };
5434
5762
  const executeHostTool = async (name, input, requestedSessionId, toolCallId) => {
5435
5763
  const execute = hostTools.executors.get(name);
5436
- const turn = requestedSessionId === undefined || requestedSessionId === sessionId ? activeTurn : null;
5764
+ const issuerSessionId = requestedSessionId ?? sessionId;
5765
+ const scope = hookScopes.get(`${issuerSessionId}:${toolCallId}`);
5766
+ const turn = issuerSessionId === sessionId ? activeTurn : null;
5437
5767
  if (!isCurrentTurn(turn))
5438
5768
  return { content: "", isError: true, cancelled: true };
5439
5769
  const controller = new AbortController;
@@ -5455,7 +5785,8 @@ async function createFxEngine(options = {}) {
5455
5785
  return execute(input, {
5456
5786
  signal: controller.signal,
5457
5787
  executionId: String(toolCallId ?? ""),
5458
- sessionId,
5788
+ sessionId: issuerSessionId,
5789
+ ...options.hooks && scope ? { observation: toolObservation(scope, String(toolCallId), options.hooks, hook, controller.signal) } : {},
5459
5790
  ...options.toolContext === undefined ? {} : { context: options.toolContext }
5460
5791
  });
5461
5792
  });
@@ -5576,12 +5907,13 @@ async function createFxEngine(options = {}) {
5576
5907
  });
5577
5908
  const fx = {
5578
5909
  ...followUp ? { inputId: followUp.id, inputAccepted: followUp.accepted } : {},
5579
- ...journal && turnId ? { turnId } : {},
5910
+ ...(journal || options.hooks) && turnId ? { turnId } : {},
5580
5911
  ...stopAt
5581
5912
  };
5582
5913
  return request("session/prompt", { sessionId, prompt, ...Object.keys(fx).length ? { _meta: { fx } } : {} });
5583
5914
  };
5584
5915
  runtime.exited.then((code) => {
5916
+ hookScopes.clear();
5585
5917
  closing = true;
5586
5918
  if (journal)
5587
5919
  closeJournal().catch(() => {});
@@ -5594,6 +5926,14 @@ async function createFxEngine(options = {}) {
5594
5926
  emit("runtime.exit", { code });
5595
5927
  });
5596
5928
  runtime.setLineHandler((message, size) => {
5929
+ if (message.method === "libfx/hook") {
5930
+ if (message.params?.rootSessionId === sessionId && message.params?.version === 1) {
5931
+ if (message.params.type === "turn.end" && handedOff)
5932
+ message.params.data.handoff = true;
5933
+ hook(message.params);
5934
+ }
5935
+ return;
5936
+ }
5597
5937
  emit("acp.receive", { message });
5598
5938
  if (message.method === "libfx/journal_append") {
5599
5939
  if (journal && message.params?.sessionId === sessionId) {
@@ -5673,8 +6013,13 @@ async function createFxEngine(options = {}) {
5673
6013
  });
5674
6014
  const loaded = persistence ? await loadPersistence(persistence) : null;
5675
6015
  const requestedSessionId = options.sessionId ?? null;
5676
- const sessionResult = await request("libfx/new", requestedSessionId === null ? {} : { sessionId: requestedSessionId });
6016
+ const sessionResult = await request("libfx/new", {
6017
+ ...requestedSessionId === null ? {} : { sessionId: requestedSessionId },
6018
+ ...options.hooks ? { hooks: { captureContent: options.hooks.captureContent === true } } : {}
6019
+ });
5677
6020
  sessionId = sessionResult.sessionId;
6021
+ if (options.hooks && sessionResult?._meta?.fx?.hooksVersion !== 1)
6022
+ throw new Error("Semantic hooks require a matching libfx core with hooks version 1");
5678
6023
  if (initialCheckpoint) {
5679
6024
  const [checkpointAttachment] = attachBytes([initialCheckpoint]);
5680
6025
  const restored = await request("libfx/restore", { sessionId, checkpointAttachment }).catch((error) => {
@@ -5721,6 +6066,7 @@ async function createFxEngine(options = {}) {
5721
6066
  followUps.push({ id: held.id, text: held.text, accepted: true, held: true });
5722
6067
  }
5723
6068
  emit("journal.open", { events: events.length, checkpoint: checkpoint !== null, turns: opened?.turns, resumable });
6069
+ journalHook("journal.restore", { cursor: loaded.head, lastSeq: loaded.lastSeq, resumable, openTurnId, lastTurnId });
5724
6070
  }
5725
6071
  } catch (error) {
5726
6072
  closing = true;
@@ -5862,6 +6208,7 @@ async function createFxEngine(options = {}) {
5862
6208
  return run;
5863
6209
  },
5864
6210
  async close() {
6211
+ hookScopes.clear();
5865
6212
  if (closing) {
5866
6213
  await runtime.exited;
5867
6214
  if (journal)
@@ -7244,6 +7591,7 @@ var createFxAgent = createDurableAgentFactory({
7244
7591
  name: "createFxAgent",
7245
7592
  label: "fx agent",
7246
7593
  defaultDurability: environmentDurability,
7594
+ defaultShared: true,
7247
7595
  harness: fxHarness({
7248
7596
  createEngine: createFxEngine2,
7249
7597
  defaultApiKey: async (durability) => process.env.AI_GATEWAY_API_KEY || await Promise.resolve(durability?.gatewayKey?.()).catch(() => {