libfx 0.0.14-dev.1534.g6afa7c33dac5 → 0.0.14

package/node.js

@@ -710,6 +710,8 @@ export const createFxAgent = createDurableAgentFactory({
   name: "createFxAgent",
   label: "fx agent",
   defaultDurability: environmentDurability,
+  // One durability per environment, so agents created without one share it.
+  defaultShared: true,
   harness: fxHarness({
     createEngine: createFxEngine,
     // An explicit key, then the durability's own credential, such as a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libfx",
-  "version": "0.0.14-dev.1534.g6afa7c33dac5",
+  "version": "0.0.14",
   "description": "Embed fx agents and terminals in JavaScript hosts",
   "type": "module",
   "repository": {

package/subscription.js

@@ -7,6 +7,8 @@
 //
 // A provider spec supplies what differs: which requests it authorizes, how its
 // credentials are checked and refreshed, and which headers carry them.
+//
+// TLA+ model: `tests/tla/sdk/ProviderAuth.tla`.
 
 const refreshSkewMs = 5 * 60 * 1000;
 const maxRememberedCredentials = 256;

package/tool-observation.js

@@ -0,0 +1,185 @@
+// Observations of host-owned effects. Helpers call the effect exactly once,
+// preserve its value/error, and never await an instrumentation callback.
+export function toolObservation(scope, callId, hooks, emit, signal) {
+  const report = (error) => {
+    try {
+      Promise.resolve(hooks.onError?.(error)).catch(() => {});
+    } catch {}
+  };
+  let next = 0;
+  const id = () => `host:${scope.executionId}:${callId}:${++next}`;
+  const publish = (type, data, content = {}) =>
+    emit({
+      ...scope,
+      type,
+      data,
+      timestamp: Date.now(),
+      contentCaptured: hooks.captureContent === true,
+      contentTruncated: content.truncated === true,
+    });
+  const capture = () => {
+    let remaining = 64 * 1024;
+    return {
+      truncated: false,
+      text(value) {
+        if (hooks.captureContent !== true || value == null) return undefined;
+        value = String(value);
+        let prefix = value.slice(0, remaining);
+        if (prefix.length && /[\uD800-\uDBFF]/.test(prefix.at(-1))) prefix = prefix.slice(0, -1);
+        const bytes = new TextEncoder().encode(prefix);
+        let end = Math.min(bytes.length, remaining);
+        while (end > 0 && end < bytes.length && (bytes[end] & 0xc0) === 0x80) end--;
+        remaining -= end;
+        this.truncated ||= prefix.length < value.length || end < bytes.length;
+        return new TextDecoder().decode(bytes.subarray(0, end));
+      },
+    };
+  };
+  function terminal(end) {
+    let ended = false;
+    const finish = (...args) => {
+      if (ended) return;
+      ended = true;
+      signal.removeEventListener("abort", abort);
+      try {
+        end(...args);
+      } catch (error) {
+        report(error);
+      }
+    };
+    const abort = () => finish("cancelled", undefined);
+    signal.addEventListener("abort", abort, { once: true });
+    if (signal.aborted) abort();
+    return finish;
+  }
+  return {
+    async wait(request, run) {
+      if (
+        !request ||
+        !["approval", "question", "mcp_form", "mcp_url"].includes(request.kind) ||
+        typeof run !== "function"
+      )
+        throw new TypeError("wait needs an input request and an effect");
+      if (signal.aborted) return run();
+      const requestId = id();
+      const content = capture();
+      content.truncated ||=
+        (request.questions?.length ?? 0) > 128 ||
+        (request.questions ?? [])
+          .slice(0, 128)
+          .some((question) => (question.options?.length ?? 0) > 128);
+      publish(
+        "wait.start",
+        {
+          requestId,
+          kind: request.kind,
+          callId,
+          externalId: request.externalId ?? null,
+          server: request.server ?? null,
+          schemaJson: content.text(request.schemaJson),
+          prompt: content.text(request.prompt),
+          questionCount: request.questions?.length ?? 0,
+          ...(hooks.captureContent === true
+            ? {
+                questions: (request.questions ?? []).slice(0, 128).map((question) => ({
+                  question: content.text(question.question),
+                  options: (question.options ?? []).slice(0, 128).map((option) => ({
+                    label: content.text(option.label),
+                    description: content.text(option.description),
+                  })),
+                })),
+              }
+            : {}),
+        },
+        content,
+      );
+      const finish = terminal((outcome, result, error) => {
+        const content = capture();
+        content.truncated ||= (result?.answers?.length ?? 0) > 128;
+        publish(
+          "wait.end",
+          {
+            requestId,
+            outcome,
+            error: error?.name ?? null,
+            ...(hooks.captureContent === true
+              ? {
+                  answers: (result?.answers ?? [])
+                    .slice(0, 128)
+                    .map((answer) => content.text(answer)),
+                }
+              : {}),
+          },
+          content,
+        );
+      });
+      try {
+        const result = await run();
+        let outcome = "accepted";
+        try {
+          outcome = result?.outcome ?? outcome;
+        } catch (error) {
+          report(error);
+        }
+        finish(outcome, result);
+        return result;
+      } catch (error) {
+        finish(
+          signal.aborted || error?.name === "AbortError"
+            ? "cancelled"
+            : error?.name === "TimeoutError"
+              ? "timed_out"
+              : "failed",
+          undefined,
+          error,
+        );
+        throw error;
+      }
+    },
+    async mcp(identity, run) {
+      if (signal.aborted) return run({ correlationId: identity.correlationId });
+      const operationId = id();
+      publish("mcp.start", {
+        operationId,
+        callId,
+        server: identity.server ?? null,
+        tool: identity.tool,
+        transport: null,
+      });
+      if (identity.correlationId !== undefined)
+        publish("mcp.request", {
+          operationId,
+          requestId: identity.correlationId,
+          requestIdKind: "correlation",
+        });
+      const finish = terminal((status, error) =>
+        publish("mcp.end", { operationId, status, error: error?.name ?? null }),
+      );
+      try {
+        const result = await run({ correlationId: identity.correlationId });
+        let status = "unknown";
+        try {
+          status = result?.isError ? "failure" : "success";
+        } catch (error) {
+          report(error);
+        }
+        finish(status);
+        return result;
+      } catch (error) {
+        finish(signal.aborted || error?.name === "AbortError" ? "cancelled" : "failure", error);
+        throw error;
+      }
+    },
+    childHooks() {
+      return {
+        ...hooks,
+        parent: {
+          rootSessionId: scope.rootSessionId,
+          sessionId: scope.sessionId,
+          turnId: scope.turnId,
+          callId,
+        },
+      };
+    },
+  };
+}

package/types/browser.d.ts

@@ -53,6 +53,10 @@ export type {
   FxGatewayProvider,
   FxGrokProvider,
   FxHostTool,
+  FxHooks,
+  FxHookEvent,
+  FxHookMessage,
+  FxHookToolCall,
   FxIdleResult,
   FxImageBlock,
   FxJsonSchema,
@@ -92,6 +96,9 @@ export type {
   FxTextBlock,
   FxTool,
   FxToolContext,
+  FxToolObservation,
+  FxWaitRequest,
+  FxWaitResponse,
   FxToolImage,
   FxToolResult,
   FxTools,

package/types/durable-world.d.ts

@@ -41,7 +41,13 @@ export type WorldSource = World | (() => World | Promise<World>);
 export type WorldOptions = {
   /** The durability's name in errors. Default `"world"`. */
   name?: string;
-  /** The queue keeps a message until a delivery acknowledges it, across crashes. When false, `prompt()` stores the prompt first. Default false. */
+  /**
+   * The store this World keeps sessions in. Queue messages name it, so one route hands each delivery to the agents on
+   * its store, and on one store an agent name belongs to one configuration. Give each customer of an app a store of its
+   * own. Default the durability's `name`.
+   */
+  store?: string;
+  /** The queue keeps a message until a delivery acknowledges it, across crashes. `prompt()` stores the prompt first either way. Default false. */
   queueDurable?: boolean;
   /** How often a waiting worker reads the session again. Default 1000. */
   pollMs?: number;

package/types/libfx.d.cts

@@ -144,6 +144,32 @@ export interface FxToolContext {
   sessionId: string;
   /** The JSON passed as `context` to the `session()` call whose prompt or steer started the turn. */
   context?: JsonValue;
+  /** Present when hooks are installed. Observe host-owned input waits and child engines. */
+  observation?: FxToolObservation;
+}
+
+export interface FxWaitRequest {
+  kind: "approval" | "question" | "mcp_form" | "mcp_url";
+  externalId?: string | number;
+  server?: string;
+  prompt?: string;
+  schemaJson?: string;
+  questions?: { question: string; options?: { label: string; description?: string }[] }[];
+}
+
+export interface FxWaitResponse<T = unknown> {
+  outcome: "accepted" | "denied" | "cancelled" | "failed" | "timed_out";
+  answers?: string[];
+  value?: T;
+}
+
+export interface FxToolObservation {
+  /** Calls the host effect once and preserves its response/error. Never makes a permission decision. */
+  wait<T>(request: FxWaitRequest, run: () => FxWaitResponse<T> | Promise<FxWaitResponse<T>>): Promise<FxWaitResponse<T>>;
+  /** Used by the MCP adapter to bind a remote call to this tool invocation. */
+  mcp<T>(identity: { server: string | null; tool: string; correlationId?: string | undefined }, run: (request: { correlationId: string | undefined }) => T | Promise<T>): Promise<T>;
+  /** Install these hooks on a host-created child engine to retain the parent tool relationship. */
+  childHooks(): FxHooks;
 }
 
 /** An image in a typed tool result: base64 `data`, or a `sourceRef` with no `data`. */
@@ -294,6 +320,8 @@ export type FxSessionEvent = FxEventBase & (
   | { type: "session.fenced"; sessionId: string; epoch: number }
   /** A message for a session of the agent `agent` reached this one, which sent it on. */
   | { type: "session.forwarded"; sessionId: string; agent: string }
+  /** A queue delivery named an input the session's log does not hold, or none at all, so it ran nothing. */
+  | { type: "session.refused"; sessionId?: string; messageId?: string; reason: "unknown message" | "malformed message" }
   /** `cutoffs`: the times in a row the deadline cut off the same step, this one included. */
   | { type: "session.deadline"; sessionId: string; epoch: number; cutoffs: number }
   | { type: "ui.error"; sessionId: string; error: string }
@@ -305,8 +333,107 @@ export type FxAgentEvent = FxEngineEvent | FxSessionEvent;
 // ---------------------------------------------------------------------------
 // Options shared by agents and engines
 
+/** Semantic observation, independent of diagnostics, UI events, permissions, and tracing libraries. */
+export interface FxHooks {
+  /** Parent of a host-created child engine. Normally supplied by `context.observation.childHooks()`. */
+  parent?: { rootSessionId: string; sessionId: string; turnId: string; callId: string };
+  /** Include bounded messages, instructions, tool arguments/results, and schemas. Default false. */
+  captureContent?: boolean;
+  /** Called in event order, but returned promises are not awaited. The host owns buffering and flushing. */
+  onEvent(event: FxHookEvent): void | Promise<void>;
+  /** Receives callback throws and rejected promises. Errors here are contained too. */
+  onError?(error: unknown): void | Promise<void>;
+}
+
+/** An authoritative model call identity, with no provider replay or credentials. */
+export interface FxHookToolCall {
+  callId: string;
+  name: string;
+  provenance: "fx_local" | "provider_executed";
+  /** Present only with content capture. May be a truncated JSON string. */
+  argumentsJson?: string | null;
+}
+
+export interface FxHookMessage {
+  role: "system" | "user" | "assistant" | "tool";
+  content?: string | null;
+  toolCallId: string | null;
+  toolName: string | null;
+  toolResultStatus: "success" | "failure" | null;
+  imageCount: number;
+  toolCalls: FxHookToolCall[];
+}
+
+interface FxHookEnvelope {
+  version: 1;
+  sessionId: string;
+  rootSessionId: string;
+  parentSessionId: string | null;
+  sourceSessionId: string | null;
+  workId: string | null;
+  parentTurnId?: string;
+  parentCallId?: string;
+  /** Stable host turn ID; null for session-scoped journal receipts. */
+  turnId: string | null;
+  /** Fresh for each execution/resume, not a trace or durable operation ID. */
+  executionId: string | null;
+  /** One-based within this execution, or 0 outside a step. */
+  stepIndex: number;
+  /** Milliseconds since the epoch, sampled at the semantic boundary. */
+  timestamp: number;
+  contentCaptured: boolean;
+  /** A content budget or collection limit omitted information. */
+  contentTruncated: boolean;
+}
+
+/** Versioned execution facts. The host chooses topology, conventions, redaction, and export. */
+export type FxHookEvent = FxHookEnvelope & (
+  | { type: "turn.start"; data: { resumed: boolean; input?: string | null } }
+  | { type: "turn.end"; data: { outcome: "completed" | "interrupted" | "failed" | "paused" | "yielded" | "cancelled" | "fenced"; error: string | null; handoff?: boolean } }
+  | { type: "step.start" | "step.end"; data: Record<string, never> }
+  | { type: "model.start"; data: {
+    /** Scoped to executionId. Retries have distinct IDs. */
+    modelCallId: number;
+    parentCallId: string | null;
+    purpose: "agent" | "compaction" | "vision" | "title" | "permission_review" | "auxiliary";
+    model: string; toolChoice: string; maxOutputTokens: number | null; messageCount: number;
+    instructions?: FxHookMessage[]; messages?: FxHookMessage[];
+    toolsJson?: string | null;
+    tools: { name: string; description?: string | null; inputSchemaJson?: string | null }[];
+  } }
+  | { type: "model.admitted" | "model.output_start"; data: { modelCallId: number } }
+  | { type: "model.end"; data: {
+    modelCallId: number; error: string | null; cancelled: boolean; output?: string | null;
+    finishReason?: string | null; generationId?: string | null; provider?: string | null;
+    usage?: { inputTokens: number | null; outputTokens: number | null; cacheReadTokens: number | null; cacheWriteTokens: number | null; reasoningTokens: number | null };
+    toolCalls?: FxHookToolCall[];
+  } }
+  | { type: "tool.start"; data: { call: FxHookToolCall; rerun: boolean } }
+  | { type: "permission.start"; data: { call: FxHookToolCall } }
+  | { type: "tool.end"; data: {
+    call: FxHookToolCall; output?: string | null; status: "success" | "failure" | "cancelled"; error: string | null;
+    usage?: { inputTokens: number; outputTokens: number; webSearchRequests: number };
+  } }
+  /** Acceptance into conversation memory, not proof of durable storage. */
+  | { type: "tool.result"; data: { call: FxHookToolCall; output?: string | null; status: "success" | "failure" } }
+  /** Permission evaluation can complete without a human prompt. */
+  | { type: "permission.end"; data: { call: FxHookToolCall; decision: "once" | "always" | "deny" | "policy_denied" | "permission_required" | null; error: string | null } }
+  | { type: "wait.start"; data: { requestId: number | string; kind: FxWaitRequest["kind"]; callId: string | null; externalId: string | number | null; server: string | null; prompt?: string | null; schemaJson?: string | null; questionCount: number; questions?: { question: string; submission?: "none" | "input" | "choice"; options: { label: string; description?: string | null }[] }[] } }
+  | { type: "wait.end"; data: { requestId: number | string; outcome: FxWaitResponse["outcome"]; error: string | null; answers?: string[] } }
+  | { type: "mcp.start"; data: { operationId: number | string; callId: string | null; server: string | null; tool: string; transport: string | null } }
+  | { type: "mcp.request"; data: { operationId: number | string; requestId: number | string; requestIdKind: "jsonrpc" | "engine" | "correlation" } }
+  | { type: "mcp.end"; data: { operationId: number | string; status: "success" | "failure" | "cancelled" | "input_required" | "unavailable" | "unknown"; error: string | null } }
+  | { type: "delegation"; data: { callId: string; childSessionId: string; workId: string; operationId: string | null; phase: "dispatched" | "completed" | "yielded" | "replayed" | "failed" | "cancelled" | "feedback_queued" | "feedback_applied" | "feedback_not_applied" } }
+  /** Emitted only after append resolves and its cursor validates. */
+  | { type: "journal.commit"; data: { cursor: string; firstSeq: number | null; lastSeq: number | null; eventCount: number } }
+  | { type: "journal.restore"; data: { cursor: string | null; lastSeq: number; resumable: boolean; openTurnId: string | null; lastTurnId: string | null } }
+  | { type: "journal.error"; data: { error: string; fenced: boolean } }
+);
+
 /** Options `createFxAgent()` and `createFxEngine()` share. */
 export interface FxSharedOptions<Event> {
+  /** Host-owned instrumentation of native and Wasm execution. Disabled by default. */
+  hooks?: FxHooks;
   /** The complete host-owned system context, up to 64 KiB of UTF-8. An array is joined with blank lines. */
   instructions?: string | readonly string[];
   tools?: FxTools;
@@ -627,7 +754,7 @@ export type FxAgentOptions = Omit<FxSharedOptions<FxAgentEvent>, "tools"> & FxMo
 
 /** Options for `agent.session()`. Each applies to the turns this session object starts. */
 export interface FxSessionOptions {
-  /** JSON every tool call of those turns receives as `context`. */
+  /** JSON every tool call of those turns receives as `context`, copied when `session()` is called. */
   context?: JsonValue;
   /** The model for those turns instead of the agent's whole model choice: a model ID, or a model object. */
   model?: string | FxModelOptions;
@@ -647,8 +774,7 @@ export interface FxPromptOptions {
 export interface FxSteerOptions {
   /**
    * The steer's id, so a retried request adds nothing. Follows the session id rule. Reusing a prompt's id rejects
-   * with `FX_MESSAGE_ID_IN_USE`; on a queue that outlives the process, the worker drops the steer and emits a
-   * `session.error` with that code instead.
+   * with `FX_MESSAGE_ID_IN_USE`.
    */
   messageId?: string;
 }

package/types/mcp.d.ts

@@ -10,7 +10,8 @@ export interface McpClient {
   /** Resolves to the tools array or `{ tools, nextCursor? }`. */
   listTools(params?: { cursor: string }): unknown;
   /** Called with the tool's original name, the model's arguments, and the turn's `signal` in `options`. */
-  callTool(params: { name: string; arguments?: unknown }, resultSchema?: unknown, options?: { signal?: AbortSignal }): unknown;
+  callTool(params: { name: string; arguments?: unknown; _meta?: { "libfx/correlationId": string } }, resultSchema?: unknown, options?: { signal?: AbortSignal }): unknown;
+  getServerVersion?(): { name?: string } | undefined;
   /** Required when `resources` is given. */
   readResource?(params: { uri: string }): unknown;
   /** Required when `prompts` is given. */
@@ -20,6 +21,10 @@ export interface McpClient {
 
 /** Options for `createMcpAdapter()`. */
 export interface McpAdapterOptions {
+  /** Local server identity for hook events. Defaults to the client's reported server name, or null. */
+  serverName?: string;
+  /** Send an opaque UUID as `_meta["libfx/correlationId"]`. Default false; doesn't request MCP progress notifications. */
+  propagateCorrelation?: boolean;
   /** Prepended to each tool name: letters, digits, `_`, or `-`. */
   prefix?: string;
   /** Resource URIs whose text becomes instructions. */

package/types/node.d.cts

@@ -62,6 +62,10 @@ export type {
   FxGatewayProvider,
   FxGrokProvider,
   FxHostTool,
+  FxHooks,
+  FxHookEvent,
+  FxHookMessage,
+  FxHookToolCall,
   FxIdleResult,
   FxImageBlock,
   FxJsonSchema,
@@ -103,6 +107,9 @@ export type {
   FxTextBlock,
   FxTool,
   FxToolContext,
+  FxToolObservation,
+  FxWaitRequest,
+  FxWaitResponse,
   FxToolImage,
   FxToolResult,
   FxTools,

package/types/wasm.d.ts

@@ -35,6 +35,10 @@ export type {
   FxGatewayProvider,
   FxGrokProvider,
   FxHostTool,
+  FxHooks,
+  FxHookEvent,
+  FxHookMessage,
+  FxHookToolCall,
   FxImageBlock,
   FxJsonSchema,
   FxKeyedTool,
@@ -62,6 +66,9 @@ export type {
   FxTextBlock,
   FxTool,
   FxToolContext,
+  FxToolObservation,
+  FxWaitRequest,
+  FxWaitResponse,
   FxToolImage,
   FxToolResult,
   FxTools,