libfx 0.0.14-dev.1534.g6afa7c33dac5 → 0.0.14

package/fx-sdk.js

@@ -4,6 +4,7 @@ import { customProviderDefinition, customProviderSpec } from "./custom-provider.
 import { grokSubscription } from "./grok.js";
 import { createSubscriptionAuthorizer, credentialMemory } from "./subscription.js";
 import { loadModule } from "./wasm-module.js";
+import { toolObservation } from "./tool-observation.js";
 
 // Providers that run on a user's plan, authorized by the host's credentials.
 const subscriptionProviders = new Set(["codex", "grok"]);
@@ -150,6 +151,25 @@ export function normalizeAgentOptions(value) {
     throw new TypeError("createFxEngine() options must be an object");
   }
   const options = { ...value };
+  if (options.hooks !== undefined) {
+    const hooks = options.hooks;
+    if (!hooks || typeof hooks !== "object" || Array.isArray(hooks) || typeof hooks.onEvent !== "function") {
+      throw new TypeError("hooks must be an object with onEvent()");
+    }
+    if (hooks.onError !== undefined && typeof hooks.onError !== "function") throw new TypeError("hooks.onError must be a function");
+    if (hooks.captureContent !== undefined && typeof hooks.captureContent !== "boolean") throw new TypeError("hooks.captureContent must be a boolean");
+    options.hooks = {
+      captureContent: hooks.captureContent === true,
+      onEvent: hooks.onEvent.bind(hooks),
+      ...(hooks.onError === undefined ? {} : { onError: hooks.onError.bind(hooks) }),
+      ...(hooks.parent === undefined ? {} : { parent: { ...hooks.parent } }),
+    };
+    if (options.hooks.parent !== undefined) {
+      for (const name of ["rootSessionId", "sessionId", "turnId", "callId"]) {
+        if (typeof options.hooks.parent[name] !== "string" || options.hooks.parent[name].length === 0 || options.hooks.parent[name].length > 1024) throw new TypeError(`hooks.parent.${name} must be a bounded identity`);
+      }
+    }
+  }
   if (Object.hasOwn(options, "env")) {
     throw new TypeError("createFxEngine() does not accept env; pass apiKey and model directly");
   }
@@ -409,6 +429,7 @@ function checkpointSeq(bytes) {
 
 // Reads what `persistence.load()` returns: the latest checkpoint, if any, and
 // the records after it, as the events the core folds after that checkpoint.
+// Modeled in `tests/tla/durable/SnapshotTail.tla`.
 async function loadPersistence(persistence) {
   const loaded = await persistence.load();
   if (!loaded || typeof loaded !== "object") {
@@ -2067,7 +2088,10 @@ function toolSchemaHash(descriptors) {
 }
 
 // `tools` is an array of descriptors, or an object of descriptors keyed by
-// name.
+// name. What `idempotent` and `writes` mean after a crash and for calls that
+// run together is modeled in `tests/tla/durable/ToolReplay.tla`, whose
+// `replay: "safe"` is an idempotent tool that does not write, and in
+// `tests/tla/durable/ParallelBatch.tla`.
 function normalizeHostTools(value) {
   if (value === undefined) return { descriptors: [], executors: new Map() };
   let entries;
@@ -2245,6 +2269,33 @@ export async function createFxEngine(options = {}) {
   const pending = new Map();
   let nextId = 1;
   let sessionId = null;
+  const hookScopes = new Map();
+  // Observation never participates in effects, journal barriers, or retries.
+  // Contain both throws and rejected promises, including an error handler's.
+  const hookError = (error) => {
+    try { Promise.resolve(options.hooks?.onError?.(error)).catch(() => {}); } catch {}
+  };
+  const hook = (event) => {
+    if (!options.hooks) return;
+    if (options.hooks.parent) event = {
+      ...event, rootSessionId: options.hooks.parent.rootSessionId,
+      ...(event.sessionId === sessionId && event.parentSessionId == null ? {
+        parentSessionId: options.hooks.parent.sessionId, parentTurnId: options.hooks.parent.turnId, parentCallId: options.hooks.parent.callId,
+      } : {}),
+    };
+    if (event.type === "tool.start") {
+      const { data, type, ...scope } = event;
+      hookScopes.set(`${event.sessionId}:${data.call.callId}`, scope);
+    } else if (event.type === "tool.end") hookScopes.delete(`${event.sessionId}:${event.data.call.callId}`);
+    else if (event.type === "turn.end") {
+      for (const [key, scope] of hookScopes) if (scope.executionId === event.executionId) hookScopes.delete(key);
+    } else if (event.type === "journal.error" && event.data.fenced) hookScopes.clear();
+    try { Promise.resolve(options.hooks.onEvent(event)).catch(hookError); } catch (error) { hookError(error); }
+  };
+  const journalHook = (type, data) => hook({
+    version: 1, type, sessionId, rootSessionId: sessionId, parentSessionId: null, sourceSessionId: null, workId: null, turnId: null, executionId: null, stepIndex: 0,
+    timestamp: Date.now(), contentCaptured: false, contentTruncated: false, data,
+  });
   let activeTurn = null;
   let closing = false;
   let coreExitError = null;
@@ -2267,6 +2318,8 @@ export async function createFxEngine(options = {}) {
   let appendTail = Promise.resolve();
   // One per agent, so a store can tell a repeated write from another writer's.
   const writerId = crypto.randomUUID();
+  // Pipelined appends and barriers are modeled in `tests/tla/durable/Journal.tla`,
+  // and two processes appending to one log in `tests/tla/durable/Fencing.tla`.
   const journal = persistence && {
     append(events, barrier) {
       const data = encodeJournalRecord(events);
@@ -2279,6 +2332,7 @@ export async function createFxEngine(options = {}) {
         journalHead = result.cursor;
         if (Number.isSafeInteger(lastSeq)) appendedSeq = lastSeq;
         bytesSinceCheckpoint += data.byteLength;
+        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 });
       });
       // A failed append fails every later one: they would not continue it.
       appendTail = appended;
@@ -2306,7 +2360,8 @@ export async function createFxEngine(options = {}) {
   };
   // Continues the open turn: the calls it left running run again or are
   // answered as possibly run, and each answered one ends for the turn's
-  // viewers as it does for the model.
+  // viewers as it does for the model. Modeled in
+  // `tests/tla/durable/Resumption.tla`.
   const resumeOpenTurn = (promptOptions) => {
     const { rerun, answered } = settleAmbiguous(promptOptions.onAmbiguous);
     return normalizeTurn(startTurn(null, { ...promptOptions, [resumeTurn]: true, [rerunCallIds]: rerun }), answered);
@@ -2343,7 +2398,8 @@ export async function createFxEngine(options = {}) {
   let handedOff = false;
   const handedOffError = () => new Error("this agent handed its session off; open it again to continue");
   // Input events (`accepted:<id>`, `withdrawn:<id>`) once stored, and the
-  // steer and withdraw calls waiting for them.
+  // steer and withdraw calls waiting for them, which resolve only then
+  // (`tests/tla/durable/Inbox.tla`).
   const durableInputs = new Set();
   const inputWaiters = new Map();
   const waitForInput = (key) => {
@@ -2422,6 +2478,7 @@ export async function createFxEngine(options = {}) {
       if (journalFailure) return;
       journalFailure = journalAppendError(error);
       emit("journal.error", { error: error instanceof Error ? error.name : "Error" });
+      journalHook("journal.error", { error: error instanceof Error ? error.name : "Error", fenced: error?.code === "FX_FENCED" || error?.cause?.code === "FX_FENCED" });
       rejectInputWaiters([...inputWaiters.keys()], journalFailure);
       // Nothing the turn does from here can be saved, and after a fence the
       // session has another owner: stop the turn and its effects now.
@@ -2560,7 +2617,10 @@ export async function createFxEngine(options = {}) {
   };
   const executeHostTool = async (name, input, requestedSessionId, toolCallId) => {
     const execute = hostTools.executors.get(name);
-    const turn = requestedSessionId === undefined || requestedSessionId === sessionId
+    const issuerSessionId = requestedSessionId ?? sessionId;
+    const scope = hookScopes.get(`${issuerSessionId}:${toolCallId}`);
+    // Hook metadata is not authority to execute a foreign session's tool.
+    const turn = issuerSessionId === sessionId
       ? activeTurn
       : null;
     if (!isCurrentTurn(turn)) return { content: "", isError: true, cancelled: true };
@@ -2581,7 +2641,8 @@ export async function createFxEngine(options = {}) {
         return execute(input, {
           signal: controller.signal,
           executionId: String(toolCallId ?? ""),
-          sessionId,
+          sessionId: issuerSessionId,
+          ...(options.hooks && scope ? { observation: toolObservation(scope, String(toolCallId), options.hooks, hook, controller.signal) } : {}),
           ...(options.toolContext === undefined ? {} : { context: options.toolContext }),
         });
       });
@@ -2695,12 +2756,13 @@ export async function createFxEngine(options = {}) {
     // when the host could not. A journaled turn's first progress records its id.
     const fx = {
       ...(followUp ? { inputId: followUp.id, inputAccepted: followUp.accepted } : {}),
-      ...(journal && turnId ? { turnId } : {}),
+      ...((journal || options.hooks) && turnId ? { turnId } : {}),
       ...stopAt,
     };
     return request("session/prompt", { sessionId, prompt, ...(Object.keys(fx).length ? { _meta: { fx } } : {}) });
   };
   runtime.exited.then((code) => {
+    hookScopes.clear();
     closing = true;
     // An agent whose core exited writes nothing more.
     if (journal) void closeJournal().catch(() => {});
@@ -2712,6 +2774,13 @@ export async function createFxEngine(options = {}) {
     emit("runtime.exit", { code });
   });
   runtime.setLineHandler((message, size) => {
+    if (message.method === "libfx/hook") {
+      if (message.params?.rootSessionId === sessionId && message.params?.version === 1) {
+        if (message.params.type === "turn.end" && handedOff) message.params.data.handoff = true;
+        hook(message.params);
+      }
+      return;
+    }
     emit("acp.receive", { message });
     if (message.method === "libfx/journal_append") {
       if (journal && message.params?.sessionId === sessionId) {
@@ -2783,8 +2852,12 @@ export async function createFxEngine(options = {}) {
 
     const loaded = persistence ? await loadPersistence(persistence) : null;
     const requestedSessionId = options.sessionId ?? null;
-    const sessionResult = await request("libfx/new", requestedSessionId === null ? {} : { sessionId: requestedSessionId });
+    const sessionResult = await request("libfx/new", {
+      ...(requestedSessionId === null ? {} : { sessionId: requestedSessionId }),
+      ...(options.hooks ? { hooks: { captureContent: options.hooks.captureContent === true } } : {}),
+    });
     sessionId = sessionResult.sessionId;
+    if (options.hooks && sessionResult?._meta?.fx?.hooksVersion !== 1) throw new Error("Semantic hooks require a matching libfx core with hooks version 1");
     if (initialCheckpoint) {
       const [checkpointAttachment] = attachBytes([initialCheckpoint]);
       const restored = await request("libfx/restore", { sessionId, checkpointAttachment }).catch((error) => {
@@ -2828,6 +2901,7 @@ export async function createFxEngine(options = {}) {
         followUps.push({ id: held.id, text: held.text, accepted: true, held: true });
       }
       emit("journal.open", { events: events.length, checkpoint: checkpoint !== null, turns: opened?.turns, resumable });
+      journalHook("journal.restore", { cursor: loaded.head, lastSeq: loaded.lastSeq, resumable, openTurnId, lastTurnId });
     }
   } catch (error) {
     closing = true;
@@ -2980,6 +3054,7 @@ export async function createFxEngine(options = {}) {
       return run;
     },
     async close() {
+      hookScopes.clear();
       if (closing) {
         await runtime.exited;
         if (journal) await closeJournal();

package/mcp.js

@@ -33,6 +33,11 @@ export async function createMcpAdapter(client, options = {}) {
     throw new TypeError("MCP client must provide listTools() and callTool()");
   }
   const prefix = options.prefix ?? "";
+  if (options.propagateCorrelation !== undefined && typeof options.propagateCorrelation !== "boolean") throw new TypeError("MCP propagateCorrelation must be a boolean");
+  if (options.serverName !== undefined && (typeof options.serverName !== "string" || options.serverName.length === 0 || options.serverName.length > 256)) throw new TypeError("MCP serverName must be a bounded name");
+  let reportedName;
+  try { reportedName = client.getServerVersion?.()?.name; } catch {}
+  const serverName = options.serverName ?? (typeof reportedName === "string" && reportedName.length > 0 && reportedName.length <= 256 ? reportedName : null);
   if (typeof prefix !== "string" || !/^[A-Za-z0-9_-]*$/.test(prefix)) {
     throw new TypeError("MCP prefix must contain only letters, digits, underscore, or hyphen");
   }
@@ -70,8 +75,12 @@ export async function createMcpAdapter(client, options = {}) {
       // The server's hints are not trusted: a call is never run twice on its
       // own. A host that knows a tool is safe to repeat can set this to true.
       idempotent: false,
-      async execute(input, { signal }) {
-        const result = await client.callTool({ name: tool.name, arguments: input }, undefined, { signal });
+      async execute(input, { signal, observation }) {
+        const correlationId = options.propagateCorrelation === true ? crypto.randomUUID() : undefined;
+        // Correlation is not progress reporting: progressToken requests remote
+        // notifications and some clients replace it with their JSON-RPC ID.
+        const send = () => client.callTool({ name: tool.name, arguments: input, ...(correlationId === undefined ? {} : { _meta: { "libfx/correlationId": correlationId } }) }, undefined, { signal });
+        const result = observation ? await observation.mcp({ server: serverName, tool: tool.name, correlationId }, send) : await send();
         const text = resultText(result);
         const images = (Array.isArray(result?.content) ? result.content : []).flatMap((item) => item?.type === "image" ? [item] : item?.type === "resource" && item.resource?.mimeType?.startsWith("image/") && typeof item.resource?.blob === "string" ? [{ type: "image", mimeType: item.resource.mimeType, data: item.resource.blob }] : []).map((item) => ({
           type: "image", mimeType: item.mimeType, data: item.data,