@omercnet/paseo-omp 0.4.0 → 1.0.0

package/server/provider/session-terminal.ts

@@ -0,0 +1,307 @@
+import { randomUUID } from "node:crypto";
+import type { ProviderError } from "@getpaseo/plugin/server/provider";
+import type { OmpMessage, OmpRpcEvent } from "./omp-rpc-protocol";
+
+export type PendingUser = {
+  clientMessageId: string;
+  text: string;
+  accepted: boolean;
+  fallbackOnFinish: boolean;
+  bufferedEchoes: OmpMessage[];
+};
+type TerminalCorrelationEvidence = "fresh-native-user" | "current-assistant";
+
+type TerminalCorrelation = {
+  policy: "initial-turn" | "ordered-legacy" | "native-command";
+  evidence: Map<TerminalCorrelationEvidence, number>;
+};
+
+export type TerminalCandidate = {
+  event: Extract<OmpRpcEvent, { type: "agent_end" }>;
+  arrivalSequence: number;
+  confidence:
+    | "keyed"
+    | "initial-turn"
+    | "ordered-legacy"
+    | "native-command"
+    | "interrupted"
+    | "ambiguous";
+};
+
+export type ActiveTurn = {
+  turnId: string;
+  clientMessageId: string;
+  generation: number;
+  promptResultEmitted: boolean;
+  started: boolean;
+  terminal: boolean;
+  interrupted: boolean;
+  starting: boolean;
+  nativeActivity: boolean;
+  userEchoObserved: boolean;
+  localOnlyDisabled: boolean;
+  localOnlyEligible: boolean;
+  awaitingPermissionEvidence: boolean;
+  activitySequence: number;
+  acknowledged: boolean;
+  terminalCorrelation: TerminalCorrelation;
+  replayingBufferedEvents: boolean;
+  agentInvoked?: boolean;
+  nativeRequestId?: string;
+  promptAcceptedEventIndex?: number;
+  localOnlyTimer?: unknown;
+  usagePollTimer?: unknown;
+  usagePoll?: Promise<void>;
+  usageSampleFloor: number;
+  manualCompaction: boolean;
+  manualCompactionPending: boolean;
+  manualCompactionDeadlineTimer?: unknown;
+  agentEndPending: boolean;
+  agentEndRetryTimer?: unknown;
+  agentEndDeadlineTimer?: unknown;
+  agentEndCheck?: Promise<void>;
+  ambiguousTerminalTimer?: unknown;
+  terminalizing: boolean;
+  terminalization?: Promise<void>;
+  terminalOutcome?: TurnOutcome;
+  operationalTerminalStage?: "failed" | "unresolved";
+  terminalWake?: VoidDeferred;
+  steerReady: VoidDeferred;
+  steersInFlight: number;
+  deferredAgentEnd?: TerminalCandidate;
+  activeToolCallIds: Set<string>;
+  bufferedEvents: OmpRpcEvent[];
+  pendingUsers: PendingUser[];
+  userEchoes: OmpMessage[];
+  userCorrelationActive: boolean;
+  userLookups: Set<Promise<void>>;
+  completedMessageCount: number;
+  streamedMessageEntryIds: string[];
+  streamedMessageIdentityComplete: boolean;
+  lastCompletedAssistantOutcome?: AgentEndOutcome;
+  lastCompletedAssistantEntryId?: string;
+};
+
+export type VoidDeferred = {
+  promise: Promise<void>;
+  resolve(value?: void | PromiseLike<void>): void;
+  reject(reason?: unknown): void;
+};
+
+export type TurnOutcome = {
+  state: "completed" | "failed" | "canceled";
+  error?: ProviderError;
+  usageSampled: boolean;
+};
+
+export function nativeEntryId(message: OmpMessage): string | undefined {
+  return message.entryId;
+}
+
+export type AgentEndOutcome = "completed" | "failed" | "canceled";
+type AssistantTerminalStatus = AgentEndOutcome | "unavailable";
+
+export function assistantTerminalOutcome(
+  message: Extract<OmpMessage, { role: "assistant" }>,
+): AgentEndOutcome {
+  const stopReason = message.stopReason?.toLowerCase();
+  if (stopReason === "aborted" || stopReason === "canceled" || stopReason === "cancelled") {
+    return "canceled";
+  }
+  return stopReason === "error" || message.errorMessage ? "failed" : "completed";
+}
+
+function lastAssistantStatus(
+  messages: readonly OmpMessage[],
+  startIndex = 0,
+): AssistantTerminalStatus {
+  for (let index = messages.length - 1; index >= startIndex; index -= 1) {
+    const message = messages[index];
+    if (message?.role !== "assistant") continue;
+    return assistantTerminalOutcome(message);
+  }
+  return "unavailable";
+}
+
+export function terminalOutcome(
+  event: Extract<OmpRpcEvent, { type: "agent_end" }>,
+  turn: Pick<ActiveTurn, "completedMessageCount" | "lastCompletedAssistantOutcome">,
+): AgentEndOutcome | undefined {
+  const messages = event.messages;
+  if (
+    messages !== undefined &&
+    (event.messageCount === undefined || messages.length >= event.messageCount)
+  ) {
+    const status = lastAssistantStatus(messages);
+    return status === "unavailable" ? "completed" : status;
+  }
+  if (event.messageCount === 0) return "completed";
+  if (
+    turn.lastCompletedAssistantOutcome !== undefined &&
+    (event.messageCount === undefined || turn.completedMessageCount >= event.messageCount)
+  ) {
+    return turn.lastCompletedAssistantOutcome;
+  }
+  return undefined;
+}
+
+export function historyTerminalOutcome(
+  messages: readonly OmpMessage[],
+  declaredCount: number,
+  turn: Pick<
+    ActiveTurn,
+    | "streamedMessageEntryIds"
+    | "streamedMessageIdentityComplete"
+    | "lastCompletedAssistantOutcome"
+    | "lastCompletedAssistantEntryId"
+  >,
+  retainedMessages: readonly OmpMessage[],
+): AgentEndOutcome | undefined {
+  if (
+    messages.length < declaredCount ||
+    !turn.streamedMessageIdentityComplete ||
+    turn.streamedMessageEntryIds.length === 0
+  ) {
+    return undefined;
+  }
+  const startIndex = messages.length - declaredCount;
+  let historyIndex = startIndex;
+  for (const entryId of turn.streamedMessageEntryIds) {
+    while (historyIndex < messages.length) {
+      const historyMessage = messages[historyIndex];
+      if (historyMessage && nativeEntryId(historyMessage) === entryId) break;
+      historyIndex += 1;
+    }
+    if (historyIndex >= messages.length) return undefined;
+    const correlated = messages[historyIndex];
+    if (
+      entryId === turn.lastCompletedAssistantEntryId &&
+      (correlated?.role !== "assistant" ||
+        assistantTerminalOutcome(correlated) !== turn.lastCompletedAssistantOutcome)
+    )
+      return undefined;
+    historyIndex += 1;
+  }
+  historyIndex = startIndex;
+  for (const retained of retainedMessages) {
+    const entryId = nativeEntryId(retained);
+    if (!entryId) return undefined;
+    while (historyIndex < messages.length) {
+      const historyMessage = messages[historyIndex];
+      if (historyMessage && nativeEntryId(historyMessage) === entryId) break;
+      historyIndex += 1;
+    }
+    if (historyIndex >= messages.length) return undefined;
+    const correlated = messages[historyIndex];
+    if (!correlated || correlated.role !== retained.role) return undefined;
+    if (
+      retained.role === "assistant" &&
+      correlated.role === "assistant" &&
+      assistantTerminalOutcome(retained) !== assistantTerminalOutcome(correlated)
+    )
+      return undefined;
+    historyIndex += 1;
+  }
+  const status = lastAssistantStatus(messages, startIndex);
+  return status === "unavailable" ? undefined : status;
+}
+
+export function unknownTerminalOutcomeError(
+  event: Extract<OmpRpcEvent, { type: "agent_end" }>,
+  turn: Pick<ActiveTurn, "completedMessageCount" | "lastCompletedAssistantOutcome">,
+): string {
+  const retainedMessages = event.messages?.length ?? 0;
+  const retainedStatus = event.messages ? lastAssistantStatus(event.messages) : "unavailable";
+  const lastStatus =
+    retainedStatus === "unavailable"
+      ? (turn.lastCompletedAssistantOutcome ?? "unavailable")
+      : retainedStatus;
+  return (
+    "OMP agent_end omitted terminal messages; outcome is unknown " +
+    `(declaredCount=${event.messageCount ?? "unavailable"}, ` +
+    `observedCount=${turn.completedMessageCount}, ` +
+    `retainedTerminalMessages=${retainedMessages}, lastAssistantStatus=${lastStatus})`
+  );
+}
+
+export function createActiveTurn(
+  clientMessageId: string,
+  text: string,
+  generation: number,
+  terminalPolicy: TerminalCorrelation["policy"],
+  manualCompaction = false,
+): ActiveTurn {
+  return {
+    turnId: randomUUID(),
+    clientMessageId,
+    agentInvoked: undefined,
+    generation,
+    promptResultEmitted: false,
+    started: false,
+    terminal: false,
+    awaitingPermissionEvidence: false,
+    interrupted: false,
+    starting: true,
+    nativeActivity: false,
+    userEchoObserved: false,
+    localOnlyDisabled: false,
+    localOnlyEligible: false,
+    usageSampleFloor: 0,
+    agentEndPending: false,
+    terminalizing: false,
+    manualCompactionPending: manualCompaction,
+    manualCompaction,
+    activitySequence: 0,
+    acknowledged: false,
+    terminalCorrelation: { policy: terminalPolicy, evidence: new Map() },
+    replayingBufferedEvents: false,
+    steersInFlight: 0,
+    activeToolCallIds: new Set(),
+    steerReady: Promise.withResolvers<void>(),
+    userCorrelationActive: false,
+    userLookups: new Set(),
+    userEchoes: [],
+    completedMessageCount: 0,
+    bufferedEvents: [],
+    streamedMessageEntryIds: [],
+    streamedMessageIdentityComplete: true,
+    pendingUsers: [
+      {
+        clientMessageId,
+        text,
+        accepted: true,
+        fallbackOnFinish: true,
+        bufferedEchoes: [],
+      },
+    ],
+  };
+}
+export function classifyTerminalCandidate(
+  turn: ActiveTurn,
+  event: Extract<OmpRpcEvent, { type: "agent_end" }>,
+  arrivalSequence = turn.activitySequence,
+): TerminalCandidate {
+  if (event.requestId !== undefined) return { event, confidence: "keyed", arrivalSequence };
+  if (turn.agentInvoked === false) return { event, confidence: "ambiguous", arrivalSequence };
+  if (turn.terminalCorrelation.policy === "initial-turn") {
+    return { event, confidence: "initial-turn", arrivalSequence };
+  }
+  const assistantSequence = turn.terminalCorrelation.evidence.get("current-assistant");
+  if (
+    turn.terminalCorrelation.policy === "native-command" &&
+    assistantSequence !== undefined &&
+    assistantSequence <= arrivalSequence
+  ) {
+    return { event, confidence: "native-command", arrivalSequence };
+  }
+  const userSequence = turn.terminalCorrelation.evidence.get("fresh-native-user");
+  if (
+    userSequence !== undefined &&
+    assistantSequence !== undefined &&
+    userSequence < assistantSequence &&
+    assistantSequence <= arrivalSequence
+  ) {
+    return { event, confidence: "ordered-legacy", arrivalSequence };
+  }
+  return { event, confidence: "ambiguous", arrivalSequence };
+}

package/server/provider/session-usage.ts

@@ -0,0 +1,234 @@
+import type { ProviderEvent, ProviderUsage } from "@getpaseo/plugin/server/provider";
+import type { OmpRuntimeSession } from "./omp-rpc";
+import type { OmpSessionState, OmpSessionStats } from "./omp-rpc-protocol";
+import type { ActiveTurn } from "./session-terminal";
+import type { OmpTimelineScheduler } from "./timeline-projector";
+
+const USAGE_POLL_MS = 1_000;
+
+interface UsageContext {
+  closed: boolean;
+  runtimeDead: boolean;
+  generation: number;
+  runtime: OmpRuntimeSession;
+  activeTurn: ActiveTurn | null;
+}
+
+type Emit = (event: ProviderEvent) => void;
+type ReadContext = () => UsageContext;
+type IsPollable = (turn: ActiveTurn) => boolean;
+
+interface UsageSample {
+  turn: ActiveTurn;
+  generation: number;
+  runtime: OmpRuntimeSession;
+  epoch: number;
+  sequence: number;
+  promise: Promise<OmpSessionState | undefined>;
+}
+
+function usageFrom(
+  state: OmpSessionState | undefined,
+  stats: OmpSessionStats | undefined,
+): ProviderUsage | undefined {
+  if (!state?.contextUsage && !stats) return undefined;
+  const stateContext = state?.contextUsage;
+  const statsContext = stats?.contextUsage;
+  const modelCapacity = state?.model?.contextWindow;
+  const inputTokens = stats?.tokens?.input;
+  const cachedInputTokens = stats?.tokens?.cacheRead;
+  const outputTokens = stats?.tokens?.output;
+  const totalCostUsd = stats?.cost;
+  const contextTokens =
+    typeof stateContext?.tokens === "number"
+      ? stateContext.tokens
+      : typeof statsContext?.tokens === "number"
+        ? statsContext.tokens
+        : undefined;
+  const contextWindow =
+    typeof stateContext?.contextWindow === "number" && stateContext.contextWindow > 0
+      ? stateContext.contextWindow
+      : typeof statsContext?.contextWindow === "number" && statsContext.contextWindow > 0
+        ? statsContext.contextWindow
+        : typeof modelCapacity === "number" && modelCapacity > 0
+          ? modelCapacity
+          : undefined;
+  const usage: ProviderUsage = {
+    ...(typeof inputTokens === "number" ? { inputTokens } : {}),
+    ...(typeof cachedInputTokens === "number" ? { cachedInputTokens } : {}),
+    ...(typeof outputTokens === "number" ? { outputTokens } : {}),
+    ...(typeof totalCostUsd === "number" ? { totalCostUsd } : {}),
+    ...(contextTokens !== undefined ? { contextWindowUsedTokens: contextTokens } : {}),
+    ...(contextWindow !== undefined ? { contextWindowMaxTokens: contextWindow } : {}),
+  };
+  return Object.keys(usage).length > 0 ? usage : undefined;
+}
+
+export class OmpSessionUsage {
+  private epoch = 0;
+  private sequence = 0;
+  private sample: UsageSample | null = null;
+  private lastUsage: ProviderUsage | null = null;
+
+  constructor(
+    private readonly sessionId: string,
+    private readonly emit: Emit,
+    private readonly scheduler: OmpTimelineScheduler,
+    private readonly readContext: ReadContext,
+    private readonly isPollable: IsPollable,
+  ) {}
+
+  get latest(): ProviderUsage | null {
+    return this.lastUsage;
+  }
+
+  private ownsSample(turn: ActiveTurn, generation: number, runtime: OmpRuntimeSession): boolean {
+    const context = this.readContext();
+    return (
+      !context.closed &&
+      !context.runtimeDead &&
+      !turn.terminal &&
+      generation === context.generation &&
+      runtime === context.runtime &&
+      context.activeTurn === turn
+    );
+  }
+
+  publishSnapshot(
+    turn: ActiveTurn,
+    minimumEpoch = this.epoch,
+    minimumSequence = turn.usageSampleFloor,
+  ): Promise<OmpSessionState | undefined> {
+    const { generation, runtime } = this.readContext();
+    if (!this.ownsSample(turn, generation, runtime)) return Promise.resolve(undefined);
+    const current = this.sample;
+    if (current) {
+      if (
+        current.turn === turn &&
+        current.generation === generation &&
+        current.runtime === runtime &&
+        current.epoch >= minimumEpoch &&
+        current.sequence >= minimumSequence
+      ) {
+        return current.promise;
+      }
+      return current.promise.then(() => {
+        if (!this.ownsSample(turn, generation, runtime)) return undefined;
+        return this.publishSnapshot(turn, minimumEpoch, minimumSequence);
+      });
+    }
+    const epoch = this.epoch;
+    const sequence = ++this.sequence;
+    const promise = Promise.allSettled([runtime.getState(), runtime.getSessionStats()]).then(
+      ([stateResult, statsResult]) => {
+        if (
+          !this.ownsSample(turn, generation, runtime) ||
+          epoch !== this.epoch ||
+          epoch < minimumEpoch ||
+          sequence < turn.usageSampleFloor ||
+          sequence < minimumSequence
+        ) {
+          return undefined;
+        }
+        const state = stateResult.status === "fulfilled" ? stateResult.value : undefined;
+        const stats = statsResult.status === "fulfilled" ? statsResult.value : undefined;
+        const usage = usageFrom(state, stats);
+        if (usage) {
+          this.lastUsage = usage;
+          this.emit({
+            type: "session.usage",
+            sessionId: this.sessionId,
+            turnId: turn.turnId,
+            usage,
+          });
+        }
+        return state;
+      },
+    );
+    this.sample = { turn, generation, runtime, epoch, sequence, promise };
+    void promise.finally(() => {
+      if (this.sample?.promise === promise) this.sample = null;
+    });
+    return promise;
+  }
+
+  async boundedSnapshot(turn: ActiveTurn, timeoutMs: number): Promise<OmpSessionState | undefined> {
+    const timeout = Promise.withResolvers<undefined>();
+    const timer = this.scheduler.set(() => timeout.resolve(undefined), timeoutMs);
+    try {
+      return await Promise.race([this.publishSnapshot(turn), timeout.promise]);
+    } finally {
+      this.scheduler.clear(timer);
+    }
+  }
+
+  async boundedTerminalState(
+    turn: ActiveTurn,
+    timeoutMs: number,
+  ): Promise<OmpSessionState | undefined> {
+    const { generation, runtime } = this.readContext();
+    const timeout = Promise.withResolvers<undefined>();
+    const timer = this.scheduler.set(() => timeout.resolve(undefined), timeoutMs);
+    try {
+      const state = await Promise.race([runtime.getState(), timeout.promise]);
+      return this.ownsSample(turn, generation, runtime) ? state : undefined;
+    } catch {
+      return undefined;
+    } finally {
+      this.scheduler.clear(timer);
+    }
+  }
+
+  schedulePoll(turn: ActiveTurn, delayMs = USAGE_POLL_MS): void {
+    if (!this.isPollable(turn) || turn.usagePollTimer !== undefined) return;
+    turn.usagePollTimer = this.scheduler.set(() => {
+      turn.usagePollTimer = undefined;
+      this.poll(turn);
+    }, delayMs);
+  }
+
+  poll(turn: ActiveTurn): void {
+    if (!this.isPollable(turn) || turn.usagePoll) return;
+    const poll = this.publishSnapshot(turn).then(() => undefined);
+    turn.usagePoll = poll;
+    void poll.finally(() => {
+      if (turn.usagePoll === poll) turn.usagePoll = undefined;
+      this.schedulePoll(turn);
+    });
+  }
+
+  stopPoll(turn: ActiveTurn): void {
+    if (turn.usagePollTimer === undefined) return;
+    this.scheduler.clear(turn.usagePollTimer);
+    turn.usagePollTimer = undefined;
+  }
+
+  invalidateBeforeNextSample(turn: ActiveTurn): void {
+    turn.usageSampleFloor = this.sequence + 1;
+    if (this.sample?.turn === turn && this.sample.sequence < turn.usageSampleFloor) {
+      this.sample = null;
+    }
+  }
+
+  completeCompaction(): void {
+    this.epoch += 1;
+    const staleSample = this.sample;
+    if (staleSample && staleSample.epoch < this.epoch) {
+      this.sample = null;
+      staleSample.turn.usagePoll = undefined;
+    }
+    this.lastUsage = null;
+  }
+  clearLatest(): void {
+    this.lastUsage = null;
+  }
+
+  clearSample(turn: ActiveTurn): void {
+    if (this.sample?.turn === turn) this.sample = null;
+  }
+
+  reset(): void {
+    this.sample = null;
+    this.lastUsage = null;
+  }
+}