Skip to content

armgit / qm

Public Imported from GitHub
0

Multiplayer agent harness for work.

6.0 KB
Raw Blame
import type { SubscribeOptions } from "../util/event-bus.ts";
import type { RunSignal, RunSignalStore } from "./run-signal-store.ts";
import type { TurnResult } from "../types.ts";
import type { OrchestratorInput } from "../core/orchestrator.ts";
import { isPersonAuthored, resolveTurnOrigin } from "../core/turn-origin.ts";
import { traceCarrier } from "../../plugins/chassis/src/error-reporting.ts";

type RunStatus = "pending" | "running" | "done" | "failed";

export type RunPriority = 0 | 1 | 2;
export const MAX_PREEMPTIONS = 3;

export function withTraceCarrier(request: OrchestratorInput): OrchestratorInput {
  const { trace: _stale, ...rest } = request;
  const trace = request.swarm ? undefined : traceCarrier();
  return trace ? { ...rest, trace } : rest;
}

export function runPriority(request: OrchestratorInput, delegating: RunPriority | null): RunPriority {
  if (request.swarm || (request.delegatingRunId && delegating === null)) return 2;
  if (request.delegatingRunId) return delegating === 2 ? 2 : 1;
  return isPersonAuthored(resolveTurnOrigin(request).kind) ? 0 : 2;
}

export interface ReapEvent {
  runId: string;
  sessionId: string;
  workerId: string | null;
  attempts: number;
  errorAttempts: number;
  outcome: "requeued" | "parked";
}

export interface RunDeliveryState {
  replying?: boolean;
  editRef?: string;
}

export type RunStop =
  | { kind: "shutdown" }
  | { kind: "parked" }
  | { kind: "lease_expired" }
  | { kind: "error"; code?: string; status?: number };

export const PARKED: RunStop = { kind: "parked" };

export function stopErrorCode(stop: RunStop | undefined): { errorCode?: string } {
  return stop?.kind === "error" && stop.code ? { errorCode: stop.code } : {};
}

export function handbackStop(shutdown: AbortSignal): RunStop {
  return shutdown.reason === PARKED ? PARKED : { kind: "shutdown" };
}

export interface Run {
  id: string;
  sessionId: string;
  status: RunStatus;
  request: OrchestratorInput;
  result: TurnResult | null;
  deliveryState: RunDeliveryState | null;
  turnUserSeq: number | null;
  dedupKey: string | null;
  attempts: number;
  errorAttempts: number;
  maxAttempts: number;
  priority: RunPriority;
  preemptions: number;
  leaseToken: string | null;
  leaseExpiresAt: number | null;
  workerId: string | null;
  createdAt: number;
  startedAt: number | null;
  finishedAt: number | null;
  lastStop?: RunStop | null;
}

interface TerminalCursor {
  finishedAt: number;
  id: string;
}

export interface EnqueueInput {
  sessionId: string;
  request: OrchestratorInput;
  dedupKey?: string;
  maxAttempts?: number;
}

export interface EnqueueResult {
  run: Run;
  deduped: boolean;
}

export interface RunStore {
  readonly maxClaims?: number;

  subscribeAvailable?(listener: () => void, options?: SubscribeOptions & { pollMs?: number }): () => void;

  enqueue(input: EnqueueInput): Promise<EnqueueResult>;
  getByDedupKey(dedupKey: string): Promise<Run | null>;

  claim(workerId: string, ttlMs: number): Promise<Run | null>;

  claimById(runId: string, workerId: string, ttlMs: number): Promise<Run | null>;

  claimForSession(sessionId: string, workerId: string, ttlMs: number): Promise<Run | null>;

  personWaiting(createdBefore: number): Promise<boolean>;

  heartbeat(runId: string, leaseToken: string, ttlMs: number): Promise<boolean>;

  releaseLease(runId: string, leaseToken: string, stop?: RunStop): Promise<boolean>;

  complete(runId: string, leaseToken: string, result: TurnResult): Promise<boolean>;

  fail(
    runId: string,
    leaseToken: string,
    error: string,
    opts?: { retry?: boolean; retryAfterMs?: number; stop?: RunStop },
  ): Promise<{ requeued: boolean }>;

  setDeliveryState(runId: string, leaseToken: string | null, state: RunDeliveryState): Promise<boolean>;

  noteTurnUserSeq(runId: string, seq: number): Promise<boolean>;

  latestForThreads(
    threadRefs: readonly string[],
    opts?: { excludePrivateMessages?: boolean },
  ): Promise<Map<string, Run>>;
  latestForThread(threadRef: string, opts?: { excludePrivateMessages?: boolean }): Promise<Run | null>;
  pendingReturns(limit?: number, afterId?: string): Promise<Run[]>;
  terminalFinished(after: TerminalCursor, beforeMs: number, limit: number): Promise<Run[]>;
  markReturned(runId: string): Promise<void>;
  deferReturn(runId: string, delayMs: number): Promise<void>;

  onTerminal(listener: (run: Run) => void): void;

  get(runId: string): Promise<Run | null>;

  activeForThread(sessionId: string): Promise<Run | null>;

  inFlightForThread(sessionId: string): Promise<Run[]>;

  withdraw(runId: string, opts?: { unstartedOnly?: boolean }): Promise<boolean>;
  steerQueued(queuedRunId: string, targetRunId: string, signal: RunSignal, signals: RunSignalStore): Promise<boolean>;

  editPendingText(runId: string, text: string, expectedText: string): Promise<boolean>;

  activeSessionIds(): Promise<string[]>;

  list(opts?: { limit?: number; threadRef?: string }): Promise<Run[]>;

  reapExpired(
    onRetired?: (sessionIds: string[]) => Promise<void>,
    opts?: { maxAgeMs?: number; onReap?: (event: ReapEvent) => void },
  ): Promise<{ requeued: number; parked: number }>;

  waitFor(runId: string, timeoutMs?: number): Promise<Run>;

  close?(): Promise<void>;
}

const TERMINAL = new Set<Run["status"]>(["done", "failed"]);
export function isTerminal(status: Run["status"]): boolean {
  return TERMINAL.has(status);
}

export function releasesDedupKey(result: TurnResult): boolean {
  return result.refusalKind === "session_busy";
}

export function countedClaims(run: Pick<Run, "attempts" | "preemptions">): number {
  return run.attempts - run.preemptions;
}

export function errorParks(
  run: Pick<Run, "errorAttempts" | "maxAttempts" | "attempts" | "preemptions">,
  maxClaims?: number,
): boolean {
  return run.errorAttempts + 1 >= run.maxAttempts || (maxClaims !== undefined && countedClaims(run) >= maxClaims);
}

export function leaseLapsed(run: Pick<Run, "status" | "leaseExpiresAt">, asOf: number): boolean {
  return run.status === "running" && run.leaseExpiresAt !== null && run.leaseExpiresAt <= asOf;
}