@springbrand/agent-runtime 0.3.0-alpha.16 → 0.3.0-alpha.18

package/src/config/harness-runtime.ts

@@ -91,8 +91,10 @@ export class HarnessRuntimeConfig {
     prepared: PreparedPiRuntime,
     pinnedDescriptor: string,
     request: {
-      readonly modelSessionId?: string;
+      readonly modelSessionId?: string | (() => string);
       readonly onGeneration?: PiGenerationLifecycleObserver;
+      readonly assertRequestAllowed?: () => void;
+      readonly onCompactionGeneration?: PiGenerationLifecycleObserver;
     } = {},
   ) {
     const { state, descriptor } = readPinnedPiRuntime(
@@ -102,6 +104,19 @@ export class HarnessRuntimeConfig {
     );
     const pinnedModel = state.snapshot.pi.model;
     let models!: MutableModels;
+    const requestStream = (observer = request.onGeneration) => {
+      const stream = withProviderBoundary(
+        this.models.streamSimple.bind(this.models), request.modelSessionId, observer,
+      );
+      return ((model, context, options) => lazyStream(model, async () => {
+        options?.signal?.throwIfAborted();
+        request.assertRequestAllowed?.();
+        const refreshed = await refreshModelGuidance(state.candidates, context);
+        options?.signal?.throwIfAborted();
+        request.assertRequestAllowed?.();
+        return stream(model, refreshed, options);
+      })) satisfies typeof stream;
+    };
     models = new Proxy(this.models, {
       get: (target, property) => {
         if (property === "getModel") {
@@ -110,21 +125,19 @@ export class HarnessRuntimeConfig {
               ? pinnedModel
               : target.getModel(provider, modelId);
         }
-        if (property === "streamSimple") {
-          const stream = withProviderBoundary(
-            target.streamSimple.bind(target),
-            request.modelSessionId,
-            request.onGeneration,
-          );
-          return ((model, context, options) => lazyStream(model, async () => {
-            options?.signal?.throwIfAborted();
-            const refreshed = await refreshModelGuidance(state.candidates, context);
-            options?.signal?.throwIfAborted();
-            return stream(model, refreshed, options);
-          })) satisfies typeof stream;
-        }
+        if (property === "streamSimple") return requestStream();
         if (property === "completeSimple") {
-          return target.completeSimple.bind(models);
+          const compactionModels = new Proxy(models, {
+            get: (base, key) => {
+              if (key === "streamSimple") return requestStream((event) => {
+                request.onGeneration?.(event);
+                request.onCompactionGeneration?.(event);
+              });
+              const value = Reflect.get(base, key, base);
+              return typeof value === "function" ? value.bind(base) : value;
+            },
+          });
+          return target.completeSimple.bind(compactionModels);
         }
         const value = Reflect.get(target, property, target);
         return typeof value === "function" ? value.bind(target) : value;

package/src/config/model-guidance.ts

@@ -1,21 +1,20 @@
-import type { Context } from "@earendil-works/pi-ai";
+import { getCurrentTools, normalizeContext, type Context, type Tool, type TranscriptContext } from "@earendil-works/pi-ai";
 import type { PiToolCandidate } from "../tools/runtime/contracts";
 
-/** Only descriptions and guidance may vary inside a pinned Submission. */
-export async function refreshModelGuidance(
-  candidates: readonly PiToolCandidate[],
-  context: Context,
-): Promise<Context> {
-  const guidance = new Map(await Promise.all(candidates
-    .filter(candidate => candidate.modelGuidance && context.tools?.some(tool => tool.name === candidate.tool.name))
-    .map(async candidate => [candidate.tool.name, await candidate.modelGuidance!()] as const)));
-  if (!guidance.size) return context;
-  return {
-    ...context,
-    systemPrompt: [context.systemPrompt, ...new Set([...guidance.values()].map(item => item.systemPrompt).filter(Boolean))].filter(Boolean).join("\n\n"),
-    tools: context.tools?.map(tool => {
-      const prompt = guidance.get(tool.name);
-      return prompt ? { ...tool, description: prompt.description } : tool;
+/** Request-only presentation; Pi remains the source of transcript and active Tool selection. */
+export async function refreshModelGuidance(candidates: readonly PiToolCandidate[], context: Context): Promise<TranscriptContext> {
+  const transcript = normalizeContext(context);
+  const active = new Set(getCurrentTools(transcript.messages).map((tool) => tool.name));
+  const byName = new Map(candidates.map((candidate) => [candidate.tool.name, candidate]));
+  const guidance = new Map(await Promise.all(candidates.filter((candidate) => active.has(candidate.tool.name) && candidate.modelGuidance)
+    .map(async (candidate) => [candidate.tool.name, await candidate.modelGuidance!()] as const)));
+  const messages = transcript.messages.map((message) => message.role !== "system" || !message.toolsAdded ? message : {
+    ...message,
+    toolsAdded: message.toolsAdded.map((tool): Tool => {
+      const candidate = byName.get(tool.name), prompt = guidance.get(tool.name);
+      return { ...tool, ...(candidate?.deferLoading ? { deferLoading: true as const } : {}), ...(prompt ? { description: prompt.description } : {}) };
     }),
-  };
+  });
+  const sections = [...new Set([...guidance.values()].flatMap((value) => value.systemPrompt ? [value.systemPrompt] : []))];
+  return normalizeContext({ messages: sections.length ? [...messages, { role: "system", content: "", sections: { "springbrand.live-services": sections.join("\n\n") }, timestamp: 1 }] : messages });
 }

package/src/config/ports.ts

@@ -1004,6 +1004,8 @@ export interface RuntimeModelEndpoint {
   >;
   /** OpenRouter upstream provider pins keyed by model ID; pinned requests never fall back. */
   openRouterProviderPins?: Readonly<Record<string, string>>;
+  /** OpenRouter provider ordering; omitted keeps OpenRouter's default routing. */
+  openRouterProviderSort?: "price" | "throughput" | "latency";
   modelMetadata?: Readonly<Record<string, RuntimeModelMetadata>>;
 }
 

package/src/conversation/harness-resume.ts

@@ -1,14 +1,14 @@
-import { HarnessClosed, type AgentLane, type LaneSnapshot, type WatchHandle } from "@earendil-works/pi-agent-core";
-import { BACKGROUND_CONTEXT } from "@earendil-works/pi-agent-core/harness/context";
-import type { OperationResultRecord } from "@earendil-works/pi-agent-core/harness/session";
+import type { AgentEventStream } from "@earendil-works/pi-durable";
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
 import type { Connection } from "agents";
-import { MessageType } from "agents/chat";
+import { MessageType, STREAM_RESUME_NONE_REASONS } from "agents/chat";
 import type { UIMessage, UIMessageChunk } from "ai";
+import type { SessionHarness, SessionRunOutcome } from "../harness/session-harness";
 import type { ConversationHistory } from "./history";
 import { HarnessStreamProjection } from "./harness-stream";
 
 interface ActiveConversation {
-  lane: AgentLane;
+  runtime: SessionHarness;
   submissionId: string;
   requestId: string;
   assistantMessageId: string;
@@ -18,271 +18,106 @@ interface ActiveConversation {
 interface ResumeConnection {
   connection: Connection;
   source: ActiveConversation;
-  ready: Promise<void>;
-  watch?: WatchHandle<LaneSnapshot>;
-  projection?: HarnessStreamProjection;
-  acknowledging: boolean;
-  replay?: Promise<void>;
-  terminal?: OperationResultRecord;
-  released?: boolean;
-  finished?: boolean;
+  watch: AgentEventStream;
+  projection: HarnessStreamProjection;
+  delivery: Promise<void>;
+  started: boolean;
 }
 
-
-/** CF's resume handshake, with its replay prefix and subsequent events sourced only from Pi. */
+/** Pi supplies the atomic snapshot and deltas; this boundary owns the CF transport handshake. */
 export class HarnessConversationBridge {
   private active?: ActiveConversation;
   private readonly connections = new Map<string, ResumeConnection>();
-
   constructor(private readonly host: {
     history: Pick<ConversationHistory, "browserMessages" | "browserSnapshot">;
     send: (connection: Connection, body: string) => void | Promise<void>;
     broadcast: (body: string, excludedConnectionIds: string[]) => void;
   }) {}
-
-  activate(lane: AgentLane, submission: Omit<ActiveConversation, "lane">): void {
-    this.active = { lane, ...submission };
+  activate(runtime: SessionHarness, submission: Omit<ActiveConversation, "runtime">): void { this.active = { runtime, ...submission }; }
+  private replayMessage(messages: UIMessage[], submissionId: string) {
+    return [...messages].reverse().find((message) => message.role === "assistant" && (message.metadata as { turnId?: string } | undefined)?.turnId === submissionId);
   }
-
-  private replayMessage(messages: UIMessage[], submissionId: string): UIMessage | undefined {
-    return messages.filter((message) => message.role === "assistant" &&
-      (message.metadata as { turnId?: string } | undefined)?.turnId === submissionId).at(-1);
-  }
-
-  private historyBeforeReplay(messages: UIMessage[], submissionId: string): UIMessage[] {
-    const target = this.replayMessage(messages, submissionId);
-    return target ? messages.filter((message) => message.id !== target.id) : messages;
-  }
-
-  /** Reads never release lifecycle state; hydration leaves the active reply to replay. */
   async messages(view: "full" | "hydration" = "full"): Promise<UIMessage[]> {
-    for (;;) {
-      const source = this.active;
-      let watch: WatchHandle<LaneSnapshot> | undefined;
-      if (source) {
-        try { watch = await source.lane.watch(BACKGROUND_CONTEXT); }
-        catch (error) {
-          if (!(error instanceof HarnessClosed)) throw error;
-        }
-      }
-      try {
-        const messages = watch
-          ? await this.host.history.browserSnapshot(watch.snapshot)
-          : await this.host.history.browserMessages();
-        if (this.active !== source) continue;
-        return view === "hydration" && source && watch?.snapshot.operation?.id === source.submissionId
-          ? this.historyBeforeReplay(messages, source.submissionId)
-          : messages;
-      } finally { watch?.unsubscribe(); }
-    }
-  }
-
-  private async send(connection: Connection, frame: unknown): Promise<void> {
-    const session = this.connections.get(connection.id);
-    try { await this.host.send(connection, JSON.stringify(frame)); }
-    catch { if (session) this.discard(session); }
-  }
-
-  private async sendHistory(connection: Connection, messages: UIMessage[]): Promise<void> {
-    await this.send(connection, { type: MessageType.CF_AGENT_CHAT_MESSAGES, messages });
-  }
-
-  private async sendIdleHistory(connection: Connection, probeId?: string): Promise<void> {
     const source = this.active;
-    const session = this.connections.get(connection.id);
-    const messages = await this.host.history.browserMessages();
-    if (this.connections.get(connection.id) !== session) return;
-    if (this.active !== source) return this.resume(connection, probeId);
-    await this.sendHistory(connection, messages);
-    if (this.connections.get(connection.id) !== session) return;
-    if (this.active !== source) return this.resume(connection, probeId);
-    await this.send(connection, { type: MessageType.CF_AGENT_STREAM_RESUME_NONE, ...(probeId ? { probeId } : {}) });
+    if (!source) return this.host.history.browserMessages();
+    const watch = await source.runtime.watch(BACKGROUND_CONTEXT);
+    try {
+      const messages = await this.host.history.browserSnapshot(watch.snapshot, source.submissionId);
+      const replay = this.replayMessage(messages, source.submissionId);
+      return view === "hydration" && watch.snapshot.run && replay ? messages.filter((message) => message.id !== replay.id) : messages;
+    } finally { await watch.stop(); }
   }
-
-  private async sendChunks(session: ResumeConnection, chunks: readonly UIMessageChunk[], replay = false): Promise<void> {
+  private send(connection: Connection, frame: unknown) { return this.host.send(connection, JSON.stringify(frame)); }
+  private async chunks(session: ResumeConnection, chunks: readonly UIMessageChunk[], replay = false) {
     for (const chunk of chunks) {
       if (this.connections.get(session.connection.id) !== session) return;
-      await this.send(session.connection, {
-        type: MessageType.CF_AGENT_USE_CHAT_RESPONSE,
-        id: session.source.requestId,
-        body: JSON.stringify(chunk), done: false,
-        ...(replay ? { replay: true, continuation: false } : {}),
-      });
+      await this.send(session.connection, { type: MessageType.CF_AGENT_USE_CHAT_RESPONSE, id: session.source.requestId, body: JSON.stringify(chunk), done: false, ...(replay ? { replay: true, continuation: false } : {}) });
     }
   }
-
   async resume(connection: Connection, probeId?: string): Promise<void> {
+    this.disconnect(connection);
     const source = this.active;
     if (!source) {
-      return this.sendIdleHistory(connection, probeId);
-    }
-    let session = this.connections.get(connection.id);
-    if (!session || session.source !== source) {
-      this.disconnect(connection);
-      session = { connection, source, ready: Promise.resolve(), acknowledging: false };
-      this.connections.set(connection.id, session);
-      const current = session;
-      current.ready = (async () => {
-        const watch = await source.lane.watch(BACKGROUND_CONTEXT);
-        if (this.connections.get(connection.id) !== current) { watch.unsubscribe(); return; }
-        current.watch = watch;
-      })();
-    }
-    try { await session.ready; }
-    catch (error) {
-      if (this.connections.get(connection.id) !== session) return;
-      this.discard(session);
-      if (this.active !== source) return this.resume(connection, probeId);
-      if (error instanceof HarnessClosed) {
-        await this.sendIdleHistory(connection, probeId);
-      }
+      await this.send(connection, { type: MessageType.CF_AGENT_CHAT_MESSAGES, messages: await this.host.history.browserMessages() });
+      await this.send(connection, { type: MessageType.CF_AGENT_STREAM_RESUME_NONE, reason: STREAM_RESUME_NONE_REASONS.IDLE, ...(probeId ? { probeId } : {}) });
       return;
     }
-    if (this.connections.get(connection.id) !== session) return;
-    if (this.active !== source) {
-      this.discard(session);
-      return this.resume(connection, probeId);
-    }
-    const snapshot = session.watch?.snapshot;
-    if (!snapshot?.operation || snapshot.operation.id !== source.submissionId) {
-      this.discard(session);
-      return this.sendIdleHistory(connection, probeId);
-    }
-    if (!session.acknowledging) {
-      const messages = await this.host.history.browserSnapshot(snapshot);
-      if (this.connections.get(connection.id) !== session) return;
-      if (this.active !== source) { this.discard(session); return this.resume(connection, probeId); }
-      await this.sendHistory(connection, this.historyBeforeReplay(messages, source.submissionId));
+    const watch = await source.runtime.watch(BACKGROUND_CONTEXT);
+    if (this.active !== source) { await watch.stop(); return this.resume(connection, probeId); }
+    if (!watch.snapshot.run) {
+      await watch.stop();
+      await this.send(connection, { type: MessageType.CF_AGENT_CHAT_MESSAGES, messages: await this.host.history.browserMessages() });
+      await this.send(connection, { type: MessageType.CF_AGENT_STREAM_RESUME_NONE, reason: STREAM_RESUME_NONE_REASONS.IDLE, ...(probeId ? { probeId } : {}) });
+      return;
     }
-    if (this.connections.get(connection.id) !== session) return;
-    if (this.active !== source) { this.discard(session); return this.resume(connection, probeId); }
-    await this.send(connection, {
-      type: MessageType.CF_AGENT_STREAM_RESUMING, id: source.requestId,
-      ...(probeId ? { probeId } : {}),
-    });
+    const messages = await this.host.history.browserSnapshot(watch.snapshot, source.submissionId);
+    const replay = this.replayMessage(messages, source.submissionId);
+    const session: ResumeConnection = { connection, source, watch, projection: new HarnessStreamProjection({ messageId: source.assistantMessageId, userMessageId: source.userMessageId, startedAt: source.createdAt, turnId: source.submissionId }), delivery: Promise.resolve(), started: false };
+    this.connections.set(connection.id, session);
+    await this.send(connection, { type: MessageType.CF_AGENT_CHAT_MESSAGES, messages: replay ? messages.filter((message) => message.id !== replay.id) : messages });
+    await this.send(connection, { type: MessageType.CF_AGENT_STREAM_RESUMING, id: source.requestId, ...(probeId ? { probeId } : {}) });
   }
-
   async acknowledge(connection: Connection, requestId: string): Promise<void> {
     const session = this.connections.get(connection.id);
-    if (!session || session.source.requestId !== requestId || session.acknowledging) return;
-    if (this.active && this.active.submissionId !== session.source.submissionId) {
-      // A queued Submission may already be live when an older offer is ACKed.
-      // End the old transport, then atomically resume the current lane view.
-      this.disconnect(connection);
-      const current = this.resume(connection);
-      await this.send(connection, { type: MessageType.CF_AGENT_USE_CHAT_RESPONSE, id: requestId, body: "", done: true });
-      await current;
-      return;
-    }
-    session.acknowledging = true;
-    session.replay = this.replay(session);
-    try {
-      await session.replay;
-      if (session.terminal) await this.finish(session, session.terminal);
-      if (session.released) this.discard(session);
-    } catch { this.discard(session); }
-  }
-
-  private async replay(session: ResumeConnection): Promise<void> {
-    const connection = session.connection;
-    const requestId = session.source.requestId;
-    await session.ready;
-    if (this.connections.get(connection.id) !== session) return;
-    if (!session.watch && this.active?.submissionId === session.source.submissionId) {
-      session.source = this.active;
-      session.released = false;
-      const watch = await this.active.lane.watch(BACKGROUND_CONTEXT);
-      if (this.connections.get(connection.id) !== session) { watch.unsubscribe(); return; }
-      session.watch = watch;
-    }
-    const watch = session.watch;
-    const messages = watch ? await this.host.history.browserSnapshot(watch.snapshot) : await this.host.history.browserMessages();
-    if (this.connections.get(connection.id) !== session) return;
-    const source = session.source;
-    const message = this.replayMessage(messages, source.submissionId) ?? {
-      id: source.assistantMessageId, role: "assistant" as const, parts: [],
-      metadata: { turnId: source.submissionId, userMessageId: source.userMessageId,
-        createdAt: source.createdAt, turnStatus: "running" },
-    };
-    const projection = new HarnessStreamProjection({
-      messageId: message.id, startedAt: source.createdAt, turnId: source.submissionId,
-      userMessageId: source.userMessageId,
-    });
-    session.projection = projection;
-    const prefix = projection.restore(message, Boolean(watch?.snapshot.operation?.streamingMessage));
-    await this.sendChunks(session, prefix, true);
-    if (this.connections.get(connection.id) !== session) return;
-    await this.send(connection, { type: MessageType.CF_AGENT_USE_CHAT_RESPONSE,
-      id: requestId, body: "", done: false, replayComplete: true });
-    if (this.connections.get(connection.id) !== session) return;
-    watch?.start(async (event) => {
-      if ("runId" in event && event.runId !== source.submissionId) return;
-      await this.sendChunks(session, projection.event(event));
-    });
+    if (!session || session.source.requestId !== requestId || session.started) return;
+    session.started = true;
+    const messages = await this.host.history.browserSnapshot(session.watch.snapshot, session.source.submissionId);
+    const replay = this.replayMessage(messages, session.source.submissionId);
+    if (replay) await this.chunks(session, session.projection.restore(replay, Boolean(session.watch.snapshot.generation?.message), session.watch.snapshot), true);
+    await this.send(session.connection, { type: MessageType.CF_AGENT_USE_CHAT_RESPONSE, id: session.source.requestId, body: "", done: false, replayComplete: true });
+    session.watch.start((events) => session.delivery = (async () => {
+      for (const event of events) {
+        if (event.type === "snapshot") {
+          await this.resume(session.connection);
+          return;
+        } else await this.chunks(session, session.projection.event(event));
+      }
+    })());
   }
-
-  private async finish(session: ResumeConnection, record: OperationResultRecord): Promise<void> {
-    if (session.finished || !session.projection) return;
-    session.finished = true;
-    await session.watch?.drain();
-    await this.sendChunks(session, session.projection.finish(record));
-    if (this.connections.get(session.connection.id) === session) {
-      await this.send(session.connection, { type: MessageType.CF_AGENT_USE_CHAT_RESPONSE,
-        id: session.source.requestId, body: "", done: true });
+  async settle(outcome: SessionRunOutcome): Promise<void> {
+    for (const session of this.connections.values()) {
+      await session.watch.stop(); await session.delivery;
+      if (session.started) {
+        await this.chunks(session, session.projection.finish(outcome));
+      }
+      await this.send(session.connection, { type: MessageType.CF_AGENT_USE_CHAT_RESPONSE, id: session.source.requestId, body: "", done: true });
     }
+    if (this.active) this.broadcastResponse({ id: this.active.requestId, body: "", done: true });
   }
-
-  /** Called only after the Host has persisted the Submission's terminal result. */
-  async settle(record: OperationResultRecord): Promise<void> {
-    await Promise.all([...this.connections.values()].filter((session) =>
-      session.source.submissionId === record.operationId).map(async (session) => {
-      session.terminal = record;
-      try {
-        if (session.replay) await session.replay;
-        await this.finish(session, record);
-      } catch { this.discard(session); }
-    }));
-    if (this.active?.submissionId === record.operationId) {
-      this.broadcastResponse({ id: this.active.requestId, body: "", done: true });
+  async release(runtime: SessionHarness): Promise<void> {
+    if (this.active?.runtime === runtime) this.active = undefined;
+    for (const session of [...this.connections.values()]) {
+      if (session.source.runtime !== runtime) continue;
+      await session.watch.stop(); await session.delivery; this.connections.delete(session.connection.id);
     }
   }
-
-  /** Called after a drive returns, outside Pi event listeners. */
-  async release(lane: AgentLane): Promise<void> {
-    if (this.active?.lane === lane) this.active = undefined;
-    await Promise.all([...this.connections.values()].filter((session) => session.source.lane === lane)
-      .map(async (session) => {
-        try {
-          await session.ready;
-          if (session.replay) await session.replay;
-          if (session.projection) {
-            await session.watch?.drain();
-            this.discard(session);
-          } else {
-            session.watch?.unsubscribe();
-            session.watch = undefined;
-            session.released = true;
-          }
-        } catch { this.discard(session); }
-      }));
-  }
-
   disconnect(connection: Pick<Connection, "id">): void {
     const session = this.connections.get(connection.id);
-    if (session) this.discard(session);
+    if (session) { this.connections.delete(connection.id); void session.watch.stop(); }
   }
-
-  private discard(session: ResumeConnection): void {
-    if (this.connections.get(session.connection.id) !== session) return;
-    session.watch?.unsubscribe();
-    this.connections.delete(session.connection.id);
-  }
-
   broadcastResponse(frame: { id: string; body: string; done: boolean; error?: boolean; continuation?: boolean }): void {
-    // Approval is a Host fact, so it has no duplicate Pi event for the watch to project.
-    const isApproval = frame.body && JSON.parse(frame.body).type === "tool-approval-request";
-    const excluded = isApproval ? [] : [...this.connections.values()]
-      .filter((session) => session.source.requestId === frame.id).map(({ connection }) => connection.id);
+    const approval = frame.body && JSON.parse(frame.body).type === "tool-approval-request";
+    const excluded = approval ? [] : [...this.connections.values()].filter((session) => session.source.requestId === frame.id).map((session) => session.connection.id);
     this.host.broadcast(JSON.stringify({ type: MessageType.CF_AGENT_USE_CHAT_RESPONSE, ...frame }), excluded);
   }
 }