offrouter-core 0.2.0 → 0.2.2

package/src/delegation.ts

@@ -1,605 +0,0 @@
-/**
- * Minimal in-process delegation runtime for OffRouter V1.
- *
- * - Routes with digest/preview only until policy allows a provider.
- * - Full prompt text is sent to ProviderAdapter only after allow.
- * - Active tasks live in memory in this process.
- * - Cancellation only affects active same-process tasks.
- */
-import { randomBytes } from "node:crypto";
-import { InMemoryAuditStore, type AuditStore } from "./audit.js";
-import type { PolicyConfig } from "./policy.js";
-import type { ProviderAdapter } from "./providers/adapter.js";
-import { isProviderError } from "./providers/adapter.js";
-import { routeRequest } from "./router.js";
-import type {
-  PolicyDenial,
-  ProviderCandidate,
-  RouteDecision,
-  RouteRequest,
-} from "./types.js";
-
-export type DelegationMode = "oneshot" | "stream" | "background";
-export type DelegationOutput = "text" | "json" | "patch";
-export type DelegationTaskStatus =
-  "queued" | "running" | "completed" | "cancelled" | "failed";
-
-/**
- * Delegation carries full prompt text only after the caller is past policy.
- * The runtime still re-checks policy before invoke and rejects when blocked.
- */
-export interface DelegationRequest {
-  taskId: string;
-  mode: DelegationMode;
-  output: DelegationOutput;
-  /** Full user prompt; never audited raw. */
-  prompt: string;
-  route: RouteRequest;
-  model?: string;
-  providerId?: string;
-  maxOutputTokens?: number;
-  temperature?: number;
-}
-
-export type DelegationEvent =
-  | { type: "start"; taskId: string; callId: string; model: string }
-  | { type: "text-delta"; taskId: string; callId: string; text: string }
-  | {
-      type: "usage";
-      taskId: string;
-      callId: string;
-      inputTokens?: number;
-      outputTokens?: number;
-      totalTokens?: number;
-    }
-  | {
-      type: "done";
-      taskId: string;
-      callId: string;
-      finishReason?: string;
-      text?: string;
-    }
-  | {
-      type: "error";
-      taskId: string;
-      callId?: string;
-      message: string;
-      code?: string;
-    }
-  | { type: "cancelled"; taskId: string; callId?: string };
-
-export interface DelegationTask {
-  taskId: string;
-  callId: string;
-  status: DelegationTaskStatus;
-  mode: DelegationMode;
-  requestId: string;
-  providerId?: string;
-  model?: string;
-  createdAt: string;
-  updatedAt: string;
-  text?: string;
-  error?: string;
-  events: DelegationEvent[];
-  decision?: RouteDecision;
-}
-
-export interface DelegationResult {
-  taskId: string;
-  status: DelegationTaskStatus;
-  text?: string;
-  error?: string;
-  events: DelegationEvent[];
-  decision?: RouteDecision;
-}
-
-export interface DelegationRuntimeOptions {
-  adapters: Record<string, ProviderAdapter>;
-  candidates: ProviderCandidate[];
-  policy: PolicyConfig;
-  audit?: AuditStore;
-  now?: () => Date;
-  /** Default true: store redacted prompt preview on audit append. */
-  includePromptPreview?: boolean;
-}
-
-export class DelegationPolicyError extends Error {
-  readonly decision: RouteDecision;
-
-  constructor(message: string, decision: RouteDecision) {
-    super(message);
-    this.name = "DelegationPolicyError";
-    this.decision = decision;
-  }
-}
-
-function newCallId(): string {
-  return `call_${randomBytes(8).toString("hex")}`;
-}
-
-export class DelegationRuntime {
-  private readonly adapters: Record<string, ProviderAdapter>;
-  private readonly candidates: ProviderCandidate[];
-  private readonly policy: PolicyConfig;
-  private readonly audit: AuditStore;
-  private readonly now: () => Date;
-  private readonly includePromptPreview: boolean;
-  private readonly tasks = new Map<string, DelegationTask>();
-  private readonly controllers = new Map<string, AbortController>();
-  private readonly waiters = new Map<string, Promise<DelegationTask>>();
-
-  constructor(options: DelegationRuntimeOptions) {
-    this.adapters = options.adapters;
-    this.candidates = options.candidates;
-    this.policy = options.policy;
-    this.audit = options.audit ?? new InMemoryAuditStore();
-    this.now = options.now ?? (() => new Date());
-    this.includePromptPreview = options.includePromptPreview ?? true;
-  }
-
-  getTask(taskId: string): DelegationTask | undefined {
-    const t = this.tasks.get(taskId);
-    return t ? cloneTask(t) : undefined;
-  }
-
-  listTasks(): DelegationTask[] {
-    return [...this.tasks.values()].map(cloneTask);
-  }
-
-  /**
-   * One-shot: run to completion and return aggregated text + events.
-   */
-  async delegate(request: DelegationRequest): Promise<DelegationResult> {
-    const events: DelegationEvent[] = [];
-    for await (const event of this.#run(request, "oneshot")) {
-      events.push(event);
-    }
-    const task = this.tasks.get(request.taskId);
-    if (!task) {
-      throw new Error(`delegation task ${request.taskId} missing after run`);
-    }
-    if (task.status === "failed") {
-      // still return a result object for inspectability when policy error throws
-    }
-    return {
-      taskId: task.taskId,
-      status: task.status,
-      text: task.text,
-      error: task.error,
-      events: [...task.events],
-      decision: task.decision,
-    };
-  }
-
-  /**
-   * Streaming async iterator of DelegationEvents.
-   */
-  async *stream(
-    request: DelegationRequest,
-  ): AsyncGenerator<DelegationEvent, void, undefined> {
-    yield* this.#run(request, "stream");
-  }
-
-  /**
-   * Start background work; returns immediately with a running/queued task.
-   */
-  async startBackground(request: DelegationRequest): Promise<DelegationTask> {
-    const existing = this.tasks.get(request.taskId);
-    if (existing && existing.status === "running") {
-      return cloneTask(existing);
-    }
-
-    const stamped = this.#stampTask(request, "background");
-    this.tasks.set(request.taskId, stamped);
-
-    let releaseRunning!: () => void;
-    const runningGate = new Promise<void>((resolve) => {
-      releaseRunning = resolve;
-    });
-
-    const runPromise = (async () => {
-      try {
-        for await (const event of this.#run(request, "background", {
-          preRegistered: true,
-          onRunning: releaseRunning,
-        })) {
-          void event;
-          // drain
-        }
-      } catch {
-        // policy/provider failure already reflected on task; still open the gate
-        releaseRunning();
-      } finally {
-        releaseRunning();
-      }
-      return this.tasks.get(request.taskId)!;
-    })();
-
-    this.waiters.set(request.taskId, runPromise);
-    // Wait until policy passed (or failed) and task entered a terminal/running state.
-    await runningGate;
-    const current = this.tasks.get(request.taskId);
-    return cloneTask(current ?? stamped);
-  }
-
-  async wait(taskId: string): Promise<DelegationTask> {
-    const pending = this.waiters.get(taskId);
-    if (pending) {
-      const task = await pending;
-      return cloneTask(task);
-    }
-    const task = this.tasks.get(taskId);
-    if (!task) {
-      throw new Error(`unknown delegation task ${taskId}`);
-    }
-    if (
-      task.status === "completed" ||
-      task.status === "cancelled" ||
-      task.status === "failed"
-    ) {
-      return cloneTask(task);
-    }
-    // Still running without waiter - poll briefly
-    for (let i = 0; i < 200; i++) {
-      await sleep(10);
-      const t = this.tasks.get(taskId);
-      if (
-        t &&
-        (t.status === "completed" ||
-          t.status === "cancelled" ||
-          t.status === "failed")
-      ) {
-        return cloneTask(t);
-      }
-    }
-    throw new Error(`timeout waiting for task ${taskId}`);
-  }
-
-  async cancel(taskId: string): Promise<DelegationTask | undefined> {
-    const task = this.tasks.get(taskId);
-    if (!task) return undefined;
-
-    if (
-      task.status === "completed" ||
-      task.status === "cancelled" ||
-      task.status === "failed"
-    ) {
-      return cloneTask(task);
-    }
-
-    this.controllers.get(taskId)?.abort();
-    const adapter =
-      task.providerId != null ? this.adapters[task.providerId] : undefined;
-    if (adapter && task.callId) {
-      await adapter.cancel(task.callId);
-    }
-
-    task.status = "cancelled";
-    task.updatedAt = this.now().toISOString();
-    const event: DelegationEvent = {
-      type: "cancelled",
-      taskId,
-      callId: task.callId,
-    };
-    task.events.push(event);
-
-    await this.audit.markCancelled(task.requestId, {
-      reason: "delegation_cancelled",
-      now: this.now,
-    });
-
-    return cloneTask(task);
-  }
-
-  async *#run(
-    request: DelegationRequest,
-    forcedMode: DelegationMode,
-    options: { preRegistered?: boolean; onRunning?: () => void } = {},
-  ): AsyncGenerator<DelegationEvent, void, undefined> {
-    const mode = forcedMode;
-    const taskId = request.taskId;
-    let task = this.tasks.get(taskId);
-
-    if (!options.preRegistered || !task) {
-      task = this.#stampTask(request, mode);
-      this.tasks.set(taskId, task);
-    } else {
-      task.mode = mode;
-    }
-
-    // Policy/routing with digest-only route request - do not rely on full prompt.
-    let decision = routeRequest(request.route, this.candidates, this.policy);
-    decision = applyRouteOverrideDenial(request, decision);
-    task.decision = decision;
-
-    await this.audit.appendDecision(request.route, decision, {
-      includePromptPreview: this.includePromptPreview,
-      now: this.now,
-    });
-
-    if (decision.blocked || !decision.route) {
-      task.status = "failed";
-      task.error =
-        decision.explanation || decision.reason || "policy blocked delegation";
-      task.updatedAt = this.now().toISOString();
-      const event: DelegationEvent = {
-        type: "error",
-        taskId,
-        message: task.error,
-        code: "policy_blocked",
-      };
-      task.events.push(event);
-      options.onRunning?.();
-      yield event;
-      throw new DelegationPolicyError(task.error, decision);
-    }
-
-    const providerId = decision.route.provider;
-    const model = decision.route.model;
-    const adapter = this.adapters[providerId];
-    if (!adapter) {
-      task.status = "failed";
-      task.error = `no adapter registered for provider ${providerId}`;
-      task.updatedAt = this.now().toISOString();
-      const event: DelegationEvent = {
-        type: "error",
-        taskId,
-        message: task.error,
-        code: "adapter_missing",
-      };
-      task.events.push(event);
-      yield event;
-      throw new Error(task.error);
-    }
-
-    const callId = task.callId || newCallId();
-    task.callId = callId;
-    task.providerId = providerId;
-    task.model = model;
-    task.status = "running";
-    task.updatedAt = this.now().toISOString();
-    options.onRunning?.();
-
-    const controller = new AbortController();
-    this.controllers.set(taskId, controller);
-
-    if (controller.signal.aborted || statusOf(task) === "cancelled") {
-      yield* this.#markCancelled(task);
-      return;
-    }
-
-    const textParts: string[] = [];
-    try {
-      // Full prompt is only forwarded after policy allowed the provider.
-      for await (const pev of adapter.invoke({
-        callId,
-        model,
-        messages: [{ role: "user", content: request.prompt }],
-        stream: mode !== "oneshot",
-        maxOutputTokens: request.maxOutputTokens,
-        temperature: request.temperature,
-        signal: controller.signal,
-      })) {
-        // Honor mid-flight cancellation.
-        if (statusOf(task) === "cancelled" || controller.signal.aborted) {
-          yield* this.#markCancelled(task);
-          return;
-        }
-
-        const mapped = mapProviderEvent(taskId, pev);
-        if (mapped) {
-          task.events.push(mapped);
-          if (mapped.type === "text-delta") {
-            textParts.push(mapped.text);
-          }
-          yield mapped;
-          if (mapped.type === "error") {
-            if (mapped.code === "cancelled") {
-              task.status = "cancelled";
-              task.updatedAt = this.now().toISOString();
-              await this.audit.markCancelled(task.requestId, {
-                reason: "provider_cancelled",
-                now: this.now,
-              });
-              return;
-            }
-            task.status = "failed";
-            task.error = mapped.message;
-            task.updatedAt = this.now().toISOString();
-            return;
-          }
-          if (mapped.type === "done") {
-            task.text = textParts.join("");
-            task.status = "completed";
-            task.updatedAt = this.now().toISOString();
-            await this.audit.markCompleted(task.requestId, { now: this.now });
-            return;
-          }
-        }
-      }
-
-      // Exhausted without done
-      if (statusOf(task) === "running") {
-        task.text = textParts.join("");
-        task.status = "completed";
-        task.updatedAt = this.now().toISOString();
-        const done: DelegationEvent = {
-          type: "done",
-          taskId,
-          callId,
-          text: task.text,
-        };
-        task.events.push(done);
-        yield done;
-        await this.audit.markCompleted(task.requestId, { now: this.now });
-      }
-    } catch (err) {
-      if (statusOf(task) === "cancelled" || controller.signal.aborted) {
-        yield* this.#markCancelled(task);
-        return;
-      }
-      if (isProviderError(err) && err.code === "cancelled") {
-        yield* this.#markCancelled(task);
-        return;
-      }
-      const message =
-        err instanceof Error ? err.message : "provider invoke failed";
-      task.status = "failed";
-      task.error = message;
-      task.updatedAt = this.now().toISOString();
-      const event: DelegationEvent = {
-        type: "error",
-        taskId,
-        callId,
-        message,
-        code: isProviderError(err) ? err.code : "unknown",
-      };
-      task.events.push(event);
-      yield event;
-    } finally {
-      this.controllers.delete(taskId);
-    }
-  }
-
-  #stampTask(request: DelegationRequest, mode: DelegationMode): DelegationTask {
-    const ts = this.now().toISOString();
-    return {
-      taskId: request.taskId,
-      callId: newCallId(),
-      status: "queued",
-      mode,
-      requestId: request.route.requestId,
-      createdAt: ts,
-      updatedAt: ts,
-      events: [],
-    };
-  }
-
-  async *#markCancelled(
-    task: DelegationTask,
-  ): AsyncGenerator<DelegationEvent, void, undefined> {
-    if (task.status !== "cancelled") {
-      task.status = "cancelled";
-      task.updatedAt = this.now().toISOString();
-      const event: DelegationEvent = {
-        type: "cancelled",
-        taskId: task.taskId,
-        callId: task.callId,
-      };
-      task.events.push(event);
-      await this.audit.markCancelled(task.requestId, {
-        reason: "delegation_cancelled",
-        now: this.now,
-      });
-      yield event;
-    }
-  }
-}
-
-function mapProviderEvent(
-  taskId: string,
-  event: import("./providers/adapter.js").ProviderEvent,
-): DelegationEvent | undefined {
-  switch (event.type) {
-    case "start":
-      return {
-        type: "start",
-        taskId,
-        callId: event.callId,
-        model: event.model,
-      };
-    case "text-delta":
-      return {
-        type: "text-delta",
-        taskId,
-        callId: event.callId,
-        text: event.text,
-      };
-    case "usage":
-      return {
-        type: "usage",
-        taskId,
-        callId: event.callId,
-        inputTokens: event.inputTokens,
-        outputTokens: event.outputTokens,
-        totalTokens: event.totalTokens,
-      };
-    case "done":
-      return {
-        type: "done",
-        taskId,
-        callId: event.callId,
-        finishReason: event.finishReason,
-      };
-    case "error":
-      return {
-        type: "error",
-        taskId,
-        callId: event.callId,
-        message: event.error.message,
-        code: event.error.code,
-      };
-    case "tool-call":
-      return undefined;
-    default:
-      return undefined;
-  }
-}
-
-function statusOf(task: DelegationTask): DelegationTaskStatus {
-  return task.status;
-}
-
-function applyRouteOverrideDenial(
-  request: DelegationRequest,
-  decision: RouteDecision,
-): RouteDecision {
-  if (!decision.route) return decision;
-
-  const denials: PolicyDenial[] = [];
-  if (
-    request.providerId !== undefined &&
-    request.providerId !== decision.route.provider
-  ) {
-    denials.push({
-      code: "provider_denied",
-      target: "provider",
-      id: request.providerId,
-      message: `Requested provider ${request.providerId} does not match policy-selected provider ${decision.route.provider}.`,
-    });
-  }
-  if (request.model !== undefined && request.model !== decision.route.model) {
-    denials.push({
-      code: "provider_denied",
-      target: "model",
-      id: request.model,
-      message: `Requested model ${request.model} does not match policy-selected model ${decision.route.model}.`,
-    });
-  }
-
-  if (denials.length === 0) return decision;
-
-  return {
-    ...decision,
-    route: null,
-    reason: "provider_override_denied",
-    explanation: denials.map((d) => d.message).join(" "),
-    policyDenials: [...(decision.policyDenials ?? []), ...denials],
-    blocked: true,
-    needsConfiguration: false,
-    confidence: 1,
-    auditSummary: `Blocked provider override profile=${request.route.harness.profile} digest=${request.route.task.promptDigest}`,
-  };
-}
-
-function cloneTask(task: DelegationTask): DelegationTask {
-  return {
-    ...task,
-    events: [...task.events],
-    decision: task.decision ? { ...task.decision } : undefined,
-  };
-}
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}