@animalabs/agent-framework 0.22.2 → 0.22.4

package/src/mcpl/inbound-source.ts

@@ -0,0 +1,156 @@
+/**
+ * Where an inbound item came from, decided once at Agent Framework's
+ * ingestion boundary and stored on the message as `metadata.inboundSource`.
+ *
+ * A consumer of where an item came from reads this one value
+ * (readInboundSource) rather than re-deriving identity from the lane the
+ * item happened to arrive on, and compares conversations with
+ * conversationKey. It is frozen when the host ACCEPTS the item. A coalesced
+ * occurrence (RFC-006) carries the value stamped at its acceptance through
+ * deferral, fan-out and replay, so a later rename, reconnect or re-render
+ * never rewrites where an old item says it came from.
+ *
+ * The field is framework-owned. It is written after any adapter-supplied
+ * metadata is spread, so an adapter cannot supply or spoof it, and one a
+ * module's messages carry is dropped (adapter `origin` objects already use a
+ * free-form `source` string, which is why this is not called `source`).
+ *
+ * Facts only, no policy: whether an item is a body, an edit or a deletion
+ * stays in its tags (`chat:edited`, `chat:deleted`); `deferred` and
+ * `materialized` record what RFC-006 did with it. Nothing here is a version
+ * key: `eventId` is present only when the producer supplied one.
+ */
+
+/** The MCPL admission lane that accepted an item. Its contract decides what
+ *  an `eventId` is worth: `push/event` deduplicates by eventId, and RFC-006
+ *  coalesced admission (`coalesced: true`) guarantees stable retries and
+ *  distinct versions; a `channels/incoming` eventId outside coalescing is
+ *  adapter-supplied with no such guarantee. */
+export type InboundLane = 'channels/incoming' | 'push/event';
+
+/** An item that belongs to a registered channel. */
+export interface InboundChannelSource {
+  kind: 'channel';
+  /** The admission lane that accepted it (see InboundLane). */
+  lane: InboundLane;
+  /** Accepted through RFC-006 coalesced admission. */
+  coalesced?: true;
+  /** MCPL server (connection) id the item arrived through, as the host names it. */
+  serverId: string;
+  /** RFC-006 endpoint binding of that connection at acceptance. A recipe that
+   *  later points the same server id at a different endpoint gets a
+   *  different binding, so old items never acquire the new endpoint's identity. */
+  binding: string;
+  /** The registered canonical channel id (on the push lane: the composite id
+   *  the host derived from `origin`, never the adapter's raw platform id). */
+  channelId: string;
+  /** Thread within the channel, when the adapter supplied one. */
+  threadId?: string;
+  /** The platform message this item is (or, for an edit/delete, refers to). */
+  messageId?: string;
+  /** The producer's occurrence id, when it supplied one. */
+  eventId?: string;
+  /** The channel's human label when the host accepted the item. */
+  label?: string;
+  /** Message this one replies to, when the adapter supplied a reply edge. */
+  replyTo?: string;
+  /** Host acceptance time (epoch ms). */
+  acceptedAt: number;
+  /** The adapter's own timestamp for the item, verbatim. */
+  sourceTimestamp?: string;
+  /** RFC-006: accepted as a deferred notification (body rendered later). */
+  deferred?: true;
+  /** RFC-006: this delivery carries the materialized (rendered) body. */
+  materialized?: true;
+}
+
+/** An MCPL push that names no channel (heartbeats, timers, feature-set events). */
+export interface InboundUnscopedSource {
+  kind: 'unscoped';
+  lane: 'push/event';
+  coalesced?: true;
+  serverId: string;
+  binding: string;
+  eventId?: string;
+  acceptedAt: number;
+  sourceTimestamp?: string;
+  deferred?: true;
+  materialized?: true;
+}
+
+/** Conversational input from a non-channel surface (console, TUI, API). */
+export interface InboundSurfaceSource {
+  kind: 'surface';
+  /** The surface's name as its module reported it (e.g. `tui`, `api`). */
+  surface: string;
+  acceptedAt: number;
+}
+
+export type InboundSource = InboundChannelSource | InboundUnscopedSource | InboundSurfaceSource;
+
+/**
+ * Told once per inbound acceptance, with that acceptance's envelope: when an
+ * ordinary item reaches the framework, and when the RFC-006 coalescer admits
+ * an occurrence (deferred work included). Deliveries that reuse a frozen
+ * envelope (replay, fan-out, materialization, corrections) are not
+ * acceptances and are not reported. Observation only: the framework contains
+ * and reports a throw, which never affects delivery.
+ */
+export interface InboundAcceptanceObserver {
+  inboundAccepted(source: InboundSource): void;
+}
+
+/** Metadata key the framework stamps. */
+export const INBOUND_SOURCE_KEY = 'inboundSource';
+
+const isText = (v: unknown): v is string => typeof v === 'string' && v.length > 0;
+const optionalText = (v: unknown): boolean => v === undefined || isText(v);
+const optionalTrue = (v: unknown): boolean => v === undefined || v === true;
+
+/**
+ * Read a stored item's source back from its metadata, validating every field
+ * a consumer relies on: identity strings are non-empty strings, `acceptedAt`
+ * is a finite number, flags are exactly `true` when present, and the lane is
+ * one this version knows. Anything else (older messages, a shape this
+ * version does not recognize, a damaged import) is undefined — never a guess.
+ */
+export function readInboundSource(metadata: unknown): InboundSource | undefined {
+  if (!metadata || typeof metadata !== 'object') return undefined;
+  const raw = (metadata as Record<string, unknown>)[INBOUND_SOURCE_KEY];
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return undefined;
+  const s = raw as Record<string, unknown>;
+  if (typeof s.acceptedAt !== 'number' || !Number.isFinite(s.acceptedAt)) return undefined;
+  if (s.kind === 'surface') {
+    return isText(s.surface) ? (s as unknown as InboundSurfaceSource) : undefined;
+  }
+  const effectFlags = optionalTrue(s.coalesced) && optionalTrue(s.deferred) && optionalTrue(s.materialized);
+  if (!isText(s.serverId) || !isText(s.binding) || !effectFlags) return undefined;
+  if (!optionalText(s.eventId) || !optionalText(s.sourceTimestamp)) return undefined;
+  if (s.kind === 'channel') {
+    if (s.lane !== 'channels/incoming' && s.lane !== 'push/event') return undefined;
+    if (!isText(s.channelId)) return undefined;
+    for (const field of ['threadId', 'messageId', 'label', 'replyTo'] as const) {
+      if (!optionalText(s[field])) return undefined;
+    }
+    return s as unknown as InboundChannelSource;
+  }
+  if (s.kind === 'unscoped') {
+    return s.lane === 'push/event' ? (s as unknown as InboundUnscopedSource) : undefined;
+  }
+  return undefined;
+}
+
+/**
+ * The conversation an item belongs to, as a comparable key: server + channel
+ * + thread for a channel item, the surface for console input. Undefined for an
+ * unscoped push, which belongs to no conversation. The parts are server-chosen
+ * strings, so they are encoded as a JSON array, never joined with a separator
+ * one of them could contain: two keys are equal only for the same parts.
+ */
+export function conversationKey(source: InboundSource): string | undefined {
+  if (source.kind === 'channel') {
+    return JSON.stringify(['channel', source.serverId, source.channelId, source.threadId ?? null]);
+  }
+  if (source.kind === 'surface') return JSON.stringify(['surface', source.surface]);
+  return undefined;
+}

package/src/mcpl/index.ts

@@ -106,7 +106,7 @@ export {
 } from './errors.js';
 
 // Server connection and registry
-export { McplServerConnection } from './server-connection.js';
+export { McplServerConnection, McplRequestError } from './server-connection.js';
 export type { McplConnectionCloseInfo } from './server-connection.js';
 export type { TransportCloseInfo } from './transport.js';
 export { McplServerRegistry, type McplCapabilityQuery } from './server-registry.js';
@@ -159,6 +159,15 @@ export { InferenceRouter } from './inference-router.js';
 // Channel registry (channel lifecycle, incoming messages, synthesized tools)
 export { ChannelRegistry } from './channel-registry.js';
 
+// Inbound source envelope: where each accepted item came from, stamped once
+export { INBOUND_SOURCE_KEY, readInboundSource, conversationKey } from './inbound-source.js';
+export type {
+  InboundSource,
+  InboundChannelSource,
+  InboundUnscopedSource,
+  InboundSurfaceSource,
+} from './inbound-source.js';
+
 // Per-channel conversation routing (fork-per-channel agents)
 /** @deprecated Per-channel conversation routing is deprecated and will be removed (anima-research/agent-framework#235). */
 export { ConversationRouter, DEFAULT_CLOSURE_PROMPT } from './conversation-router.js';

package/src/mcpl/inference-router.ts

@@ -8,7 +8,14 @@
  * Spec reference: Section 11 (Server-Initiated Inference).
  */
 
-import type { Membrane, ContentBlock, NormalizedRequest } from '@animalabs/membrane';
+import type {
+  Membrane,
+  ContentBlock,
+  NormalizedRequest,
+  NormalizedResponse,
+  StopReason,
+  ToolCall,
+} from '@animalabs/membrane';
 
 import type {
   McplInferenceRequestParams,
@@ -60,6 +67,100 @@ function wildcardMatch(pattern: string, name: string): boolean {
   return true;
 }
 
+// ============================================================================
+// Results
+// ============================================================================
+
+/**
+ * The inference/request result for a completed inference, the same for both
+ * modes: the response's text, the model that served it, why it stopped, and
+ * its usage.
+ *
+ * A response MCPL can't report as a completion throws, and is answered with
+ * the error: one the provider ended with an error, one where the model wrote a
+ * tool call, since inference/request offers the model none, and one with a
+ * stop reason FinishReason has no value for (see finishReasonFor).
+ */
+function resultFrom(response: NormalizedResponse, routedModel: string): McplInferenceRequestResult {
+  // A provider can end an inference with finish_reason 'error' and no error
+  // object. membrane 0.5.87's OpenAI-style adapters fail a stream on a frame
+  // that carries one, as OpenRouter's mid-stream error does, but pass the token
+  // alone through, and membrane, having no stop reason for it, normalizes it
+  // to end_turn and keeps it as providerReason.
+  if (response.details.stop.providerReason === 'error') {
+    throw new Error("The provider ended the inference with an error (finish_reason 'error')");
+  }
+  // membrane's yielding stream lists a native tool call in toolCalls only
+  // when the stop was tool_use, so a tool_use block cut off by another stop is
+  // only in the content. membrane's complete() lists every tool_use block in
+  // toolCalls, whatever the stop.
+  const toolUses = response.content.filter((b: ContentBlock): b is ContentBlock & { type: 'tool_use' } => b.type === 'tool_use');
+  if (response.toolCalls.length > 0 || toolUses.length > 0) {
+    throw toolCallError(response.toolCalls.length > 0 ? response.toolCalls : toolUses);
+  }
+  // In XML tool mode membrane reads tool calls out of the text. Markup it
+  // reads no call from still shows in how the output ended: with a tool-call
+  // block still open (a call cut off at max_tokens, or an opening tag written
+  // in prose), or at `</function_calls>`, the stop sequence XML tool mode adds
+  // so that it can run calls (inference/request asks for no stop sequence of
+  // its own). Either way the markup is in the text.
+  if (response.details.stop.unclosedToolBlock) {
+    throw new Error("The model's output ended with a tool-call block still open, and inference/request offers no tools");
+  }
+  if (response.details.stop.triggeredSequence === '</function_calls>') {
+    throw new Error('The model wrote tool-call markup, and inference/request offers no tools');
+  }
+  return {
+    content: response.content
+      .filter((b: ContentBlock): b is ContentBlock & { type: 'text' } => b.type === 'text')
+      .map((b) => b.text)
+      .join(''),
+    // Spec §11.3: the actual model used, which can differ from the routed one
+    // where routing or fallback applies. When membrane names none, the routed
+    // model is the only one there is to report.
+    model: actualModelOf(response) ?? routedModel,
+    finishReason: finishReasonFor(response.stopReason),
+    usage: {
+      inputTokens: response.usage.inputTokens,
+      outputTokens: response.usage.outputTokens,
+    },
+  };
+}
+
+/**
+ * The model membrane says served the response, or undefined when it names
+ * none. membrane's type says it always names one, but some of its adapters
+ * pass the provider's own value through as it is, which can be empty.
+ */
+function actualModelOf(response: NormalizedResponse): string | undefined {
+  return response.details.model.actual || undefined;
+}
+
+/**
+ * MCPL's finishReason for membrane's stop reason. Spec §11.3 closes
+ * FinishReason at these three, so any other stop throws: `end_turn` for a
+ * refusal, or for a turn membrane's resumption guard ended (`no_progress`,
+ * `round_limit`), would tell the server the model had finished.
+ */
+function finishReasonFor(stopReason: StopReason): McplInferenceRequestResult['finishReason'] {
+  switch (stopReason) {
+    case 'end_turn':
+    case 'max_tokens':
+    case 'stop_sequence':
+      return stopReason;
+    default:
+      throw new Error(
+        `The inference ended with stop reason '${stopReason}', for which inference/request has no finishReason`,
+      );
+  }
+}
+
+/** The error for a model that called a tool, which inference/request doesn't offer. */
+function toolCallError(calls: Array<Pick<ToolCall, 'name'>>): Error {
+  const names = calls.map((call) => call.name).join(', ');
+  return new Error(`The model called a tool (${names}), and inference/request offers none`);
+}
+
 // ============================================================================
 // Constants
 // ============================================================================
@@ -101,9 +202,10 @@ export class InferenceRouter {
    * 1. Validate feature set
    * 2. Check loop prevention (reject if inside a hook)
    * 3. Resolve model from routing policy
-   * 4. Build membrane request and run inference
-   * 5. Optionally stream chunks
-   * 6. Return result via responder
+   * 4. Build membrane request
+   * 5. Run inference, streaming its visible text as chunks when asked
+   * 6. Answer with the result, or with the error for any ending that isn't
+   *    a completion
    */
   async handleInferenceRequest(
     serverId: string,
@@ -161,49 +263,46 @@ export class InferenceRouter {
       },
     };
 
+    // Streaming needs a way to send chunks and an id to tag them with;
+    // without either, the request is answered whole.
+    const chunkRequestId = params.stream && this.sendChunkFn ? responder.requestId : undefined;
+    const streamed = chunkRequestId != null;
+
     try {
-      // 5. Run inference
-      if (params.stream && this.sendChunkFn && responder.requestId != null) {
-        // Streaming mode
-        await this.handleStreaming(serverId, model, request, responder);
-      } else {
-        // Non-streaming mode
-        const response = await this.membrane.complete(request);
-
-        // Extract text content from response
-        const contentText = response.content
-          .filter((b: ContentBlock): b is ContentBlock & { type: 'text' } => b.type === 'text')
-          .map((b: ContentBlock & { type: 'text' }) => b.text)
-          .join('');
-
-        const result: McplInferenceRequestResult = {
-          content: contentText,
-          model,
-          finishReason: this.mapStopReason(response.stopReason),
-          usage: {
-            inputTokens: response.usage.inputTokens,
-            outputTokens: response.usage.outputTokens,
-          },
-        };
-
-        // Emit trace: inference complete
-        this.emitTraceFn({
-          type: 'mcpl:inference_complete',
-          serverId,
-          model,
-          inputTokens: result.usage.inputTokens,
-          outputTokens: result.usage.outputTokens,
-        });
-
-        responder.respond(result);
-      }
+      // 5. Run inference. Both modes end in membrane's response, and one
+      // builder makes the result from it.
+      const response = chunkRequestId != null
+        ? await this.streamResponse(serverId, request, chunkRequestId)
+        : await this.membrane.complete(request);
+
+      // 6. Answer
+      const result = resultFrom(response, model);
+      const actualModel = actualModelOf(response);
+
+      this.emitTraceFn({
+        type: 'mcpl:inference_complete',
+        serverId,
+        // The routed model, as inference_start has it. actualModel is the one
+        // the result reports, left out when membrane named none.
+        model,
+        ...(actualModel !== undefined ? { actualModel } : {}),
+        inputTokens: result.usage.inputTokens,
+        outputTokens: result.usage.outputTokens,
+        streamed,
+      });
+
+      responder.respond(result);
     } catch (err) {
-      // Emit trace: inference failed
+      // Every ending that isn't a completion lands here, in either mode:
+      // membrane's error, a stream that stopped early, a tool call, or a
+      // stop FinishReason can't name. The answer is the JSON-RPC error, never
+      // a result carrying what arrived.
       this.emitTraceFn({
         type: 'mcpl:inference_fail',
         serverId,
         model,
         error: err instanceof Error ? err.message : String(err),
+        streamed,
       });
 
       responder.respondError(
@@ -263,73 +362,49 @@ export class InferenceRouter {
   // ==========================================================================
 
   /**
-   * Handle streaming inference by sending chunks back to the server.
+   * Run the inference as a stream, sending each visible text delta to the
+   * server as an inference/chunk, and return membrane's response once the
+   * stream completes.
    *
-   * Uses membrane.streamYielding when available; falls back to non-streaming
-   * membrane.complete otherwise.
+   * Every other ending throws, so the request is answered with the error
+   * rather than with the text that arrived: membrane's `error`, an `aborted`
+   * stream, a stream that ends with no terminal event, and `tool-calls`. A
+   * stream that has yielded tool calls waits for their results until it is
+   * cancelled, and inference/request offers the model no tools. Leaving the
+   * loop by return or throw calls the stream's return(), which cancels it,
+   * so nothing keeps running once the request is answered.
    */
-  private async handleStreaming(
+  private async streamResponse(
     serverId: string,
-    model: string,
     request: NormalizedRequest,
-    responder: Responder,
-  ): Promise<void> {
-    const requestId = responder.requestId!;
-
-    // Check if streamYielding is available on the membrane instance.
-    // We use streamYielding to iterate events and forward text deltas as chunks.
+    requestId: string | number,
+  ): Promise<NormalizedResponse> {
     const stream = this.membrane.streamYielding(request);
-    let chunkIndex = 0;
-    let fullContent = '';
+    let index = 0;
 
     for await (const event of stream) {
-      if (event.type === 'tokens' && 'content' in event) {
-        const delta = (event as { type: 'tokens'; content: string }).content;
-        fullContent += delta;
-        this.sendChunkFn!(serverId, {
-          requestId,
-          index: chunkIndex++,
-          delta,
-        });
+      switch (event.type) {
+        case 'tokens':
+          // Only text membrane marks visible is sent, which leaves out
+          // thinking and tool-call markup. The result's content is the
+          // response's text blocks, which membrane parses on its own, so in
+          // XML tool mode the chunks can miss text the content holds: prose
+          // naming a tag the stream parser opens a block for, or a thinking
+          // block cut off before its close tag.
+          if (event.meta.visible) {
+            this.sendChunkFn!(serverId, { requestId, index: index++, delta: event.content });
+          }
+          break;
+        case 'tool-calls':
+          throw toolCallError(event.calls);
+        case 'complete':
+          return event.response;
+        case 'error':
+          throw event.error;
+        case 'aborted':
+          throw new Error(`The inference stopped before it finished (${event.reason})`);
       }
     }
-
-    // After streaming completes, send the final result
-    const result: McplInferenceRequestResult = {
-      content: fullContent,
-      model,
-      finishReason: 'end_turn',
-      usage: { inputTokens: 0, outputTokens: 0 },
-    };
-
-    this.emitTraceFn({
-      type: 'mcpl:inference_complete',
-      serverId,
-      model,
-      streamed: true,
-    });
-
-    responder.respond(result);
-  }
-
-  // ==========================================================================
-  // Private: Helpers
-  // ==========================================================================
-
-  /**
-   * Map membrane's stopReason string to MCPL's finishReason enum.
-   */
-  private mapStopReason(
-    stopReason: string | undefined,
-  ): 'end_turn' | 'max_tokens' | 'stop_sequence' {
-    switch (stopReason) {
-      case 'max_tokens':
-        return 'max_tokens';
-      case 'stop_sequence':
-        return 'stop_sequence';
-      case 'end_turn':
-      default:
-        return 'end_turn';
-    }
+    throw new Error('The inference stream ended without a result');
   }
 }