@oisin-ee/oisinpi 0.7.2 → 0.9.0

package/node_modules/@oisin-ee/pi-tiers/src/ports.ts

@@ -0,0 +1,29 @@
+import type { Change, Health } from "./health.ts";
+import type { ExtensionContext, ModelRouteRequest } from "@earendil-works/pi-coding-agent";
+import type { State } from "./policy.ts";
+
+/** Pi authority used by routing and settlement. */
+interface Context {
+  readonly model: ExtensionContext["model"];
+  readonly modelRegistry: Pick<ExtensionContext["modelRegistry"], "getAvailable">;
+  readonly sessionManager: Pick<ExtensionContext["sessionManager"], "getBranch">;
+  readonly signal?: AbortSignal | undefined;
+}
+/** External effects owned by the host adapter. */
+interface Effects {
+  readonly change: (change: Change) => Promise<void>;
+  readonly now: () => number;
+  readonly quota: () => Promise<string>;
+  readonly read: () => Promise<Health>;
+  readonly wait: (delay: number, signal?: AbortSignal) => Promise<void>;
+}
+/** Read-only Pi routing request. */
+type Request = Readonly<
+  Pick<ModelRouteRequest<State>, "model" | "reason" | "signal" | "state" | "thinkingLevel">
+> & {
+  readonly failed?: {
+    readonly message: { readonly errorMessage?: string; readonly stopReason: string };
+  };
+};
+
+export type { Context, Effects, Request };

package/node_modules/@oisin-ee/pi-tiers/src/quota.ts

@@ -0,0 +1,81 @@
+/** One validated account window from Dogsled. */
+interface Window {
+  readonly account: string;
+  readonly pool: string;
+  readonly resets_ms: number | null;
+  readonly used_pct: number;
+}
+
+const ZERO = 0,
+  VERSION = 1,
+  FULL = 100,
+  /**
+   * Validates the fields used by quota policy.
+   * @param {unknown} value External window.
+   * @returns {boolean} Whether the window is usable.
+   */
+  isWindow = (value: unknown): value is Window =>
+    typeof value === "object" &&
+    value !== null &&
+    "account" in value &&
+    typeof value.account === "string" &&
+    "pool" in value &&
+    typeof value.pool === "string" &&
+    "used_pct" in value &&
+    typeof value.used_pct === "number" &&
+    Number.isFinite(value.used_pct) &&
+    value.used_pct >= ZERO &&
+    value.used_pct <= FULL &&
+    "resets_ms" in value &&
+    (value.resets_ms === null ||
+      (typeof value.resets_ms === "number" &&
+        Number.isSafeInteger(value.resets_ms) &&
+        value.resets_ms >= ZERO)),
+  /**
+   * Rejects malformed or unsupported snapshots instead of filtering from partial data.
+   * @param {string} source JSON snapshot.
+   * @returns {readonly Window[]} Validated windows, or no filtering.
+   */
+  parseQuota = (source: string): readonly Window[] => {
+    try {
+      const value: unknown = JSON.parse(source);
+      if (
+        typeof value !== "object" ||
+        value === null ||
+        !("version" in value) ||
+        value.version !== VERSION ||
+        !("pools" in value) ||
+        !Array.isArray(value.pools) ||
+        !value.pools.every(isWindow)
+      ) {
+        return [];
+      }
+      return value.pools;
+    } catch {
+      return [];
+    }
+  },
+  /**
+   * Finds when any account in an exhausted pool first becomes available.
+   * @param {readonly Window[]} windows Snapshot windows.
+   * @param {string} pool Pool name.
+   * @param {number} now Current time.
+   * @returns {number | undefined} Pool reset, only when every account is exhausted.
+   */
+  exhaustedUntil = (windows: readonly Window[], pool: string, now: number): number | undefined => {
+    const accounts = new Map<string, number>();
+    for (const window of windows.filter((entry) => entry.pool === pool)) {
+      const reset =
+        window.used_pct >= FULL && window.resets_ms !== null && window.resets_ms > now
+          ? window.resets_ms
+          : ZERO;
+      accounts.set(window.account, Math.max(accounts.get(window.account) ?? ZERO, reset));
+    }
+    const resets = [...accounts.values()];
+    return resets.length > ZERO && resets.every((reset) => reset > now)
+      ? Math.min(...resets)
+      : undefined;
+  };
+
+export { exhaustedUntil, parseQuota };
+export type { Window };

package/node_modules/@oisin-ee/pi-tiers/src/recovery.ts

@@ -0,0 +1,114 @@
+import type {
+  AgentBeforeSettleEvent,
+  BoundaryResult,
+  SessionEntry,
+} from "@earendil-works/pi-coding-agent";
+import type { Failure, State } from "./policy.ts";
+import { RECOVERY, branchState } from "./branch.ts";
+import type { Context } from "./ports.ts";
+import type { Router } from "./router.ts";
+import type { Tiers } from "./config.ts";
+import { classify } from "./policy.ts";
+
+const ZERO = 0,
+  ONE = 1;
+
+/** Final-boundary recovery runs only after Pi's automatic retry policy ends. */
+class Recovery {
+  readonly #router: Readonly<Pick<Router, "failed" | "next">> & {
+    readonly responses: Readonly<Router["responses"]>;
+  };
+  readonly #tiers: Readonly<Tiers>;
+
+  /**
+   * Connects boundary recovery to routing policy.
+   * @param {Readonly<Router>} router Routing owner.
+   * @param {Readonly<Tiers>} tiers Ordered targets.
+   */
+  public constructor(
+    router: Readonly<Pick<Router, "failed" | "next">> & {
+      readonly responses: Readonly<Router["responses"]>;
+    },
+    tiers: Readonly<Tiers>,
+  ) {
+    this.#router = router;
+    this.#tiers = tiers;
+  }
+
+  /**
+   * Applies a classified failure to the recovery budget and target choice.
+   * @param {Failure} failure Failure class.
+   * @param {State} state Branch state.
+   * @param {readonly string[]} targets Tier targets.
+   * @returns {Promise<State | undefined>} Recovery state, when permitted.
+   */
+  async #next(
+    failure: Failure,
+    state: State,
+    targets: readonly string[],
+  ): Promise<State | undefined> {
+    await this.#router.failed(failure, state.chosen);
+    if (failure === "request" || state.budget === ZERO) {
+      return undefined;
+    }
+    const attempted = failure === "gateway" ? state.attempted : [...state.attempted, state.chosen],
+      next = Object.assign({}, state, { attempted, budget: state.budget - ONE }),
+      chosen = failure === "gateway" ? state.chosen : await this.#router.next(targets, next);
+    return chosen === undefined ? undefined : Object.assign({}, next, { chosen });
+  }
+
+  /**
+   * Omits only the failed assistant and appends a state-only recovery marker.
+   * @param {AgentBeforeSettleEvent} event Final actionable boundary.
+   * @param {Context} ctx Pi authority.
+   * @returns {Promise<BoundaryResult | undefined>} Bounded recovery, or no action.
+   */
+  public async settle(
+    event: AgentBeforeSettleEvent,
+    ctx: Context,
+  ): Promise<BoundaryResult | undefined> {
+    if (
+      event.outcome !== "error" ||
+      ctx.signal?.aborted === true ||
+      ctx.model?.provider !== "tier"
+    ) {
+      return undefined;
+    }
+    const tier = ctx.model.id,
+      state = branchState(ctx.sessionManager.getBranch(), tier),
+      targets = this.#tiers.get(tier),
+      message = event.context.contextMessages.findLast((item) => item.role === "assistant"),
+      entry = event.context.contextEntries.findLast(
+        (item: Readonly<{ sourceEntry: SessionEntry; messages: readonly unknown[] }>) =>
+          item.messages.includes(message),
+      );
+    if (
+      state === undefined ||
+      targets === undefined ||
+      entry === undefined ||
+      message?.role !== "assistant" ||
+      message.stopReason !== "error" ||
+      `${message.provider}/${message.model}` !== state.chosen
+    ) {
+      return undefined;
+    }
+    const text = message.errorMessage ?? "",
+      next = await this.#next(classify(text, this.#router.responses.status(text)), state, targets);
+    if (next === undefined || Boolean(ctx.signal?.aborted)) {
+      return undefined;
+    }
+    return {
+      continue: true,
+      entries: [
+        { replacement: null, targetId: entry.sourceEntry.id, type: "context_edit" },
+        {
+          customType: RECOVERY,
+          data: { modelId: tier, provider: "tier", state: next },
+          type: "custom",
+        },
+      ],
+    };
+  }
+}
+
+export { Recovery };

package/node_modules/@oisin-ee/pi-tiers/src/responses.ts

@@ -0,0 +1,44 @@
+const ZERO = 0,
+  ONE = 1,
+  LIMIT = 128;
+
+/** Correlates HTTP status only when the error identifies the same response. */
+class Responses {
+  readonly #statuses = new Map<string, number>();
+
+  /**
+   * Records bounded response metadata, never headers or credentials.
+   * @param {Readonly<Record<string, string>>} headers Response headers.
+   * @param {number} status HTTP status.
+   */
+  public observe(headers: Readonly<Record<string, string>>, status: number): void {
+    const id = headers["x-request-id"] ?? headers["request-id"];
+    if (this.#statuses.size >= LIMIT) {
+      this.#statuses.clear();
+    }
+    if (id !== undefined && id.length > ZERO) {
+      this.#statuses.set(id, status);
+    }
+  }
+
+  /**
+   * Uses status only when a provider error explicitly includes its request ID.
+   * @param {string} message Error text.
+   * @returns {number | undefined} Correlated status.
+   */
+  public status(message: string): number | undefined {
+    const tokens: readonly string[] = message.match(/[a-z0-9_-]+/giu) ?? [],
+      matches = [...this.#statuses].filter(([id]: readonly [string, number]) =>
+        tokens.includes(id),
+      ),
+      [match] = matches;
+    return matches.length === ONE ? match?.[ONE] : undefined;
+  }
+
+  /** Removes metadata after settlement or session navigation. */
+  public clear(): void {
+    this.#statuses.clear();
+  }
+}
+
+export { Responses };

package/node_modules/@oisin-ee/pi-tiers/src/router.ts

@@ -0,0 +1,176 @@
+import { BUDGET, classify, target } from "./policy.ts";
+import type { Context, Effects, Request } from "./ports.ts";
+import type { Failure, State } from "./policy.ts";
+import { branchState, newUserTurn } from "./branch.ts";
+import { exhaustedUntil, parseQuota } from "./quota.ts";
+import type { Health } from "./health.ts";
+import type { ModelRoute } from "@earendil-works/pi-coding-agent";
+import { Responses } from "./responses.ts";
+import type { Window } from "./quota.ts";
+
+const ZERO = 0,
+  ONE = 1,
+  CACHE_MS = 60_000;
+
+/** Sticky routing with host-wide quota and gateway health. */
+class Router {
+  readonly #effects: Effects;
+  public readonly responses = new Responses();
+  #quota: readonly Window[] = [];
+  #quotaUntil = ZERO;
+
+  /**
+   * Connects policy to host effects.
+   * @param {Effects} effects External authority.
+   */
+  public constructor(effects: Effects) {
+    this.#effects = effects;
+  }
+
+  /**
+   * Refreshes only the local cached quota snapshot, at most once per minute.
+   * @returns {Promise<void>} Completion.
+   */
+  async #refresh(): Promise<void> {
+    if (this.#effects.now() >= this.#quotaUntil) {
+      this.#quota = parseQuota(await this.#effects.quota());
+      this.#quotaUntil = this.#effects.now() + CACHE_MS;
+    }
+  }
+
+  /**
+   * Checks both explicit cooldowns and account windows.
+   * @param {string} reference Model reference.
+   * @param {Health} health Shared snapshot.
+   * @returns {boolean} Availability.
+   */
+  #available(reference: string, health: Health): boolean {
+    const { pool } = target(reference),
+      now = this.#effects.now();
+    return (
+      (health.pools[pool]?.until ?? ZERO) <= now &&
+      exhaustedUntil(this.#quota, pool, now) === undefined
+    );
+  }
+
+  /**
+   * Chooses the first unattempted available target without changing state.
+   * @param {readonly string[]} targets Ordered tier.
+   * @param {State} state Branch state.
+   * @returns {Promise<string | undefined>} Next target.
+   */
+  public async next(targets: readonly string[], state: State): Promise<string | undefined> {
+    await this.#refresh();
+    const health = await this.#effects.read();
+    return targets.find(
+      (candidate) => !state.attempted.includes(candidate) && this.#available(candidate, health),
+    );
+  }
+
+  /**
+   * Records only gateway circuits or quota cooldowns.
+   * @param {Failure} failure Classified failure.
+   * @param {string} reference Failed physical model.
+   * @returns {Promise<void>} Completion.
+   */
+  public async failed(failure: Failure, reference: string): Promise<void> {
+    if (failure === "gateway" || failure === "quota") {
+      await this.#refresh();
+      const parsed = target(reference),
+        now = this.#effects.now();
+      await this.#effects.change({
+        key: failure === "gateway" ? parsed.provider : parsed.pool,
+        kind: failure,
+        now,
+        reset: failure === "quota" ? exhaustedUntil(this.#quota, parsed.pool, now) : undefined,
+      });
+    }
+  }
+
+  /**
+   * Keeps native transient retries on their current physical model.
+   * @param {Request} request Pi request.
+   * @param {State} state Current branch state.
+   * @returns {Promise<State>} State after a native retry failure.
+   */
+  async #retry(request: Request, state: State): Promise<State> {
+    const { failed } = request;
+    if (failed === undefined) {
+      return state;
+    }
+    const message = failed.message.errorMessage ?? "",
+      failure = classify(message, this.responses.status(message));
+    if (failed.message.stopReason === "aborted" || failure === "request") {
+      throw new Error(message || "Tier request stopped.");
+    }
+    await this.failed(failure, state.chosen);
+    if (failure === "quota" && state.budget === ZERO) {
+      throw new Error("Tier recovery budget exhausted.");
+    }
+    return failure === "quota"
+      ? Object.assign({}, state, {
+          attempted: [...state.attempted, state.chosen],
+          budget: state.budget - ONE,
+        })
+      : state;
+  }
+
+  /**
+   * Dispatches with the selected thinking level after checking shared health.
+   * @param {Request} request Pi request.
+   * @param {Context} ctx Pi authority.
+   * @param {State} state Chosen state.
+   * @returns {Promise<ModelRoute<State>>} Physical route.
+   */
+  async #dispatch(request: Request, ctx: Context, state: State): Promise<ModelRoute<State>> {
+    const parsed = target(state.chosen),
+      model = ctx.modelRegistry
+        .getAvailable()
+        .find((candidate) => candidate.provider === parsed.provider && candidate.id === parsed.id);
+    if (model === undefined) {
+      throw new Error(`Unknown model: ${state.chosen}`);
+    }
+    const health = await this.#effects.read(),
+      until = health.circuits[parsed.provider]?.until ?? ZERO;
+    await this.#effects.wait(until - this.#effects.now(), request.signal);
+    request.signal?.throwIfAborted();
+    return { model, state, thinkingLevel: request.thinkingLevel };
+  }
+
+  /**
+   * Routes a tier without fabricating conversation messages.
+   * @param {readonly string[]} targets Ordered physical models.
+   * @param {Request} request Pi request.
+   * @param {Context} ctx Pi authority.
+   * @returns {Promise<ModelRoute<State>>} Physical dispatch.
+   */
+  public async route(
+    targets: readonly string[],
+    request: Request,
+    ctx: Context,
+  ): Promise<ModelRoute<State>> {
+    request.signal?.throwIfAborted();
+    await this.#refresh();
+    const previous =
+        request.reason === "direct"
+          ? undefined
+          : (branchState(ctx.sessionManager.getBranch(), request.model.id) ?? request.state),
+      initial = previous ?? { attempted: [], budget: BUDGET, chosen: targets[ZERO] ?? "" },
+      current =
+        request.reason === "user" && newUserTurn(ctx.sessionManager.getBranch())
+          ? Object.assign({}, initial, { attempted: [], budget: BUDGET })
+          : initial,
+      state = await this.#retry(request, current),
+      health = await this.#effects.read(),
+      chosen =
+        !state.attempted.includes(state.chosen) && this.#available(state.chosen, health)
+          ? state.chosen
+          : await this.next(targets, state);
+    if (chosen === undefined) {
+      throw new Error("No available target in tier.");
+    }
+    return this.#dispatch(request, ctx, Object.assign({}, state, { chosen }));
+  }
+}
+
+export { Router };