@crewx/sdk 0.9.0-rc.197 → 0.9.0-rc.199

package/dist/route/decide.d.ts

@@ -0,0 +1,54 @@
+import type { RouteObservationSource } from './eligibility.js';
+import type { RouteCandidate, RouteConfig, RouteDecision, RouteLinkError, RouteRequest, RouteRunner } from './types.js';
+import type { RouteDecisionStore } from './store.js';
+export interface RouteDecisionServiceOptions {
+    store: RouteDecisionStore;
+    observationSource?: RouteObservationSource;
+    workspaceRoot?: string;
+    clock?: () => number;
+    chainTimeoutMs?: number;
+    maxCasRetries?: number;
+    customRunners?: Readonly<Record<string, RouteRunner>>;
+    linkRunnerOverrides?: Readonly<Record<string, RouteRunner>>;
+}
+export interface RecordRouteQuotaFailureInput {
+    decision: RouteDecision;
+    accountRef?: string;
+    resetAt?: number | string;
+    now?: number;
+}
+export interface RoutePreviewItem {
+    candidateId: string;
+    provider: string;
+    model: string;
+    reason: string;
+    eligibleIds: string[];
+    blockedCauses: RouteDecision['blockedCauses'];
+    linkErrors: RouteLinkError[];
+}
+export declare function routeConfigRevision(route: RouteConfig): string;
+export declare class RouteDecisionService {
+    private readonly store;
+    private readonly observationSource?;
+    private readonly workspaceRoot;
+    private readonly clock;
+    private readonly chainTimeoutMs;
+    private readonly maxCasRetries;
+    private readonly customRunners;
+    private readonly linkRunnerOverrides;
+    private readonly routeLocks;
+    constructor(options: RouteDecisionServiceOptions);
+    private links;
+    private withRouteLock;
+    private decideSerial;
+    decide(routeId: string, route: RouteConfig, request: RouteRequest): Promise<RouteDecision>;
+    previewRoute(routeId: string, route: RouteConfig, request: RouteRequest, count?: number): Promise<RoutePreviewItem[]>;
+    recordQuotaFailure(input: RecordRouteQuotaFailureInput): Promise<void>;
+}
+export declare function previewRoute(route: RouteConfig, count: number, options?: {
+    routeId?: string;
+    candidates?: RouteCandidate[];
+    now?: number;
+    agentId?: string;
+    mode?: RouteRequest['mode'];
+}): RoutePreviewItem[];

package/dist/route/eligibility.d.ts

@@ -0,0 +1,11 @@
+import type { RouteBlockedCause, RouteCandidate, RouteCandidateConfig, RouteQuotaObservation } from './types.js';
+export declare const ROUTE_QUOTA_COOLDOWN_MS: number;
+export interface RouteObservationSource {
+    getObservations(candidates: readonly RouteCandidateConfig[], now: number): Promise<RouteQuotaObservation[]> | RouteQuotaObservation[];
+}
+export interface RouteEligibilityResult {
+    candidates: RouteCandidate[];
+    blockedCauses: RouteBlockedCause[];
+}
+export declare function evaluateRouteEligibility(candidates: readonly RouteCandidateConfig[], observations: readonly RouteQuotaObservation[], now: number): RouteEligibilityResult;
+export declare function quotaResetAt(resetAt: number | string | undefined, now: number): number;

package/dist/route/errors.d.ts

@@ -0,0 +1,11 @@
+export type RouteErrorCode = 'route_no_eligible_candidate' | 'route_state_contention' | 'sticky_unavailable' | 'route_observation_unavailable' | 'invalid_route_config';
+export declare class RouteError extends Error {
+    readonly code: RouteErrorCode;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(code: RouteErrorCode, message: string, details?: Record<string, unknown> | undefined);
+}
+export type RouteRunnerErrorCode = 'invalid_json' | 'input_too_large' | 'output_too_large' | 'outside_workspace' | 'module_not_found' | 'timeout' | 'process_failed';
+export declare class RouteRunnerError extends Error {
+    readonly code: RouteRunnerErrorCode;
+    constructor(code: RouteRunnerErrorCode, message: string);
+}

package/dist/route/index.d.ts

@@ -0,0 +1,14 @@
+export { RouteConfigSchema, RouteCandidateConfigSchema, RouteLinkConfigSchema } from './types.js';
+export type { JsonPrimitive, JsonValue, RouteBlockedCause, RouteCandidate, RouteCandidateConfig, RouteConfig, RouteContext, RouteDecision, RouteFunction, RouteHealth, RouteLinkConfig, RouteLinkError, RouteMode, RouteOutput, RoutePassOutput, RouteQuotaObservation, RouteRequest, RouteRunner, RouteSelectOutput, } from './types.js';
+export { RouteError, RouteRunnerError } from './errors.js';
+export type { RouteErrorCode, RouteRunnerErrorCode } from './errors.js';
+export { builtInStrategy, roundRobin, smoothWeighted } from './strategies.js';
+export { fnRunner, procRunner, resolveRouteModulePath, ROUTE_CHAIN_TIMEOUT_MS, ROUTE_JSON_MAX_BYTES, ROUTE_PROCESS_INPUT_MAX_BYTES, ROUTE_PROCESS_OUTPUT_MAX_BYTES, } from './runner.js';
+export type { ProcRunnerOptions } from './runner.js';
+export { evaluateRouteEligibility, quotaResetAt, ROUTE_QUOTA_COOLDOWN_MS } from './eligibility.js';
+export type { RouteEligibilityResult, RouteObservationSource } from './eligibility.js';
+export { MemoryRouteStore } from './store.js';
+export type { RouteCommitResult, RouteDecisionCommit, RouteDecisionStore, RouteObservationStore, RouteStateSnapshot, } from './store.js';
+export { RouteSqliteStore } from './sqlite-store.js';
+export { RouteDecisionService, previewRoute, routeConfigRevision } from './decide.js';
+export type { RecordRouteQuotaFailureInput, RouteDecisionServiceOptions, RoutePreviewItem, } from './decide.js';

package/dist/route/runner.d.ts

@@ -0,0 +1,15 @@
+import type { RouteFunction, RouteRunner } from './types.js';
+export declare const ROUTE_JSON_MAX_BYTES: number;
+export declare const ROUTE_PROCESS_INPUT_MAX_BYTES: number;
+export declare const ROUTE_PROCESS_OUTPUT_MAX_BYTES: number;
+export declare const ROUTE_CHAIN_TIMEOUT_MS = 2000;
+export interface ProcRunnerOptions {
+    workspaceRoot: string;
+    timeoutMs?: number;
+    maxInputBytes?: number;
+    maxOutputBytes?: number;
+    onSpawn?: (processGroupId: number | undefined) => void;
+}
+export declare function fnRunner(fn: RouteFunction): RouteRunner;
+export declare function procRunner(file: string, options: ProcRunnerOptions): RouteRunner;
+export declare function resolveRouteModulePath(file: string, workspaceRoot: string): string;

package/dist/route/sqlite-store.d.ts

@@ -0,0 +1,17 @@
+import { BaseSqliteRepository } from '../repository/base-sqlite-repository.js';
+import type { RouteDecision, RouteQuotaObservation, RouteCandidateConfig } from './types.js';
+import type { RouteDecisionCommit, RouteDecisionStore, RouteObservationStore, RouteStateSnapshot, RouteCommitResult } from './store.js';
+export declare class RouteSqliteStore extends BaseSqliteRepository implements RouteDecisionStore, RouteObservationStore {
+    private readonly configuredDbPath?;
+    constructor(options?: {
+        dbPath?: string;
+        dbRoot?: string;
+    });
+    resolveDbPath(): string;
+    private openHandle;
+    getDecision(routeId: string, taskId: string): Promise<RouteDecision | undefined>;
+    loadState(routeId: string, threadId: string | null, configRevision: string): Promise<RouteStateSnapshot>;
+    commitDecision(input: RouteDecisionCommit): Promise<RouteCommitResult>;
+    recordQuotaObservation(observation: RouteQuotaObservation, observedAt: number): Promise<void>;
+    getObservations(candidates: readonly RouteCandidateConfig[], _now: number): Promise<RouteQuotaObservation[]>;
+}

package/dist/route/store.d.ts

@@ -0,0 +1,45 @@
+import type { JsonValue, RouteDecision, RouteQuotaObservation, RouteCandidateConfig } from './types.js';
+export interface RouteStateSnapshot {
+    revision: number;
+    storedConfigRevision: string | null;
+    states: Record<string, JsonValue>;
+    stickyCandidateId?: string;
+}
+export interface RouteDecisionCommit {
+    decision: RouteDecision;
+    expectedRevision: number;
+    expectedStoredConfigRevision: string | null;
+    configRevision: string;
+    states: Record<string, JsonValue>;
+    threadId: string | null;
+    stickyCandidateId?: string;
+}
+export type RouteCommitResult = {
+    status: 'saved';
+    decision: RouteDecision;
+} | {
+    status: 'conflict';
+} | {
+    status: 'existing';
+    decision: RouteDecision;
+};
+export interface RouteDecisionStore {
+    getDecision(routeId: string, taskId: string): Promise<RouteDecision | undefined>;
+    loadState(routeId: string, threadId: string | null, configRevision: string): Promise<RouteStateSnapshot>;
+    commitDecision(input: RouteDecisionCommit): Promise<RouteCommitResult>;
+    recordQuotaObservation(observation: RouteQuotaObservation, observedAt: number): Promise<void>;
+}
+export interface RouteObservationStore {
+    getObservations(candidates: readonly RouteCandidateConfig[], now: number): Promise<RouteQuotaObservation[]>;
+}
+export declare class MemoryRouteStore implements RouteDecisionStore, RouteObservationStore {
+    private readonly states;
+    private readonly sticky;
+    private readonly decisions;
+    private readonly observations;
+    getDecision(routeId: string, taskId: string): Promise<RouteDecision | undefined>;
+    loadState(routeId: string, threadId: string | null, configRevision: string): Promise<RouteStateSnapshot>;
+    commitDecision(input: RouteDecisionCommit): Promise<RouteCommitResult>;
+    recordQuotaObservation(observation: RouteQuotaObservation, observedAt: number): Promise<void>;
+    getObservations(candidates: readonly RouteCandidateConfig[], _now: number): Promise<RouteQuotaObservation[]>;
+}

package/dist/route/strategies.d.ts

@@ -0,0 +1,4 @@
+import type { RouteContext, RouteOutput } from './types.js';
+export declare function roundRobin(ctx: Readonly<RouteContext>): RouteOutput;
+export declare function smoothWeighted(ctx: Readonly<RouteContext>): RouteOutput;
+export declare function builtInStrategy(strategy: 'round-robin' | 'weighted'): typeof roundRobin;

package/dist/route/types.d.ts

@@ -0,0 +1,212 @@
+import { z } from 'zod';
+export declare const RouteCandidateConfigSchema: z.ZodObject<{
+    id: z.ZodString;
+    provider: z.ZodString;
+    model: z.ZodString;
+    weight: z.ZodDefault<z.ZodNumber>;
+    account: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    model: string;
+    provider: string;
+    weight: number;
+    account?: string | undefined;
+}, {
+    id: string;
+    model: string;
+    provider: string;
+    weight?: number | undefined;
+    account?: string | undefined;
+}>;
+export declare const RouteLinkConfigSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"custom">;
+    run: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    kind: "custom";
+    run: string;
+}, {
+    kind: "custom";
+    run: string;
+}>;
+export declare const RouteConfigSchema: z.ZodEffects<z.ZodObject<{
+    strategy: z.ZodEnum<["round-robin", "weighted"]>;
+    chain: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kind: z.ZodLiteral<"custom">;
+        run: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        kind: "custom";
+        run: string;
+    }, {
+        kind: "custom";
+        run: string;
+    }>, "many">>;
+    candidates: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        provider: z.ZodString;
+        model: z.ZodString;
+        weight: z.ZodDefault<z.ZodNumber>;
+        account: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        model: string;
+        provider: string;
+        weight: number;
+        account?: string | undefined;
+    }, {
+        id: string;
+        model: string;
+        provider: string;
+        weight?: number | undefined;
+        account?: string | undefined;
+    }>, "many">;
+    sticky: z.ZodDefault<z.ZodEnum<["conversation", "none"]>>;
+    defaultCandidate: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    strategy: "round-robin" | "weighted";
+    candidates: {
+        id: string;
+        model: string;
+        provider: string;
+        weight: number;
+        account?: string | undefined;
+    }[];
+    sticky: "none" | "conversation";
+    chain?: {
+        kind: "custom";
+        run: string;
+    }[] | undefined;
+    defaultCandidate?: string | undefined;
+}, {
+    strategy: "round-robin" | "weighted";
+    candidates: {
+        id: string;
+        model: string;
+        provider: string;
+        weight?: number | undefined;
+        account?: string | undefined;
+    }[];
+    chain?: {
+        kind: "custom";
+        run: string;
+    }[] | undefined;
+    sticky?: "none" | "conversation" | undefined;
+    defaultCandidate?: string | undefined;
+}>, {
+    strategy: "round-robin" | "weighted";
+    candidates: {
+        id: string;
+        model: string;
+        provider: string;
+        weight: number;
+        account?: string | undefined;
+    }[];
+    sticky: "none" | "conversation";
+    chain?: {
+        kind: "custom";
+        run: string;
+    }[] | undefined;
+    defaultCandidate?: string | undefined;
+}, {
+    strategy: "round-robin" | "weighted";
+    candidates: {
+        id: string;
+        model: string;
+        provider: string;
+        weight?: number | undefined;
+        account?: string | undefined;
+    }[];
+    chain?: {
+        kind: "custom";
+        run: string;
+    }[] | undefined;
+    sticky?: "none" | "conversation" | undefined;
+    defaultCandidate?: string | undefined;
+}>;
+export type RouteCandidateConfig = z.infer<typeof RouteCandidateConfigSchema>;
+export type RouteLinkConfig = z.infer<typeof RouteLinkConfigSchema>;
+export type RouteConfig = z.infer<typeof RouteConfigSchema>;
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type RouteHealth = 'ok' | 'unknown' | 'blocked';
+export type RouteMode = 'query' | 'execute';
+export interface RouteCandidate {
+    id: string;
+    provider: string;
+    model: string;
+    weight: number;
+    eligible: boolean;
+    health: RouteHealth;
+    resetAt?: number;
+}
+export interface RouteContext {
+    v: 1;
+    route: {
+        id: string;
+        revision: string;
+    };
+    request: {
+        taskId: string;
+        threadId: string | null;
+        agentId: string;
+        mode: RouteMode;
+    };
+    now: number;
+    candidates: RouteCandidate[];
+    state: JsonValue;
+}
+export interface RouteSelectOutput {
+    type: 'select';
+    candidateId: string;
+    nextState: JsonValue;
+    reason: string;
+}
+export interface RoutePassOutput {
+    type: 'pass';
+}
+export type RouteOutput = RouteSelectOutput | RoutePassOutput;
+export type RouteFunction = (ctx: Readonly<RouteContext>) => RouteOutput | unknown | Promise<RouteOutput | unknown>;
+export type RouteRunner = (ctx: RouteContext, timeoutMs?: number) => Promise<unknown>;
+export interface RouteBlockedCause {
+    candidateId: string;
+    provider: string;
+    accountRef: string;
+    model?: string;
+    source: string;
+    scope: 'account' | 'account-model';
+    resetAt: number;
+}
+export interface RouteLinkError {
+    link: string;
+    code: string;
+    message: string;
+}
+export interface RouteDecision {
+    routeId: string;
+    taskId: string;
+    configRevision: string;
+    candidateId: string;
+    provider: string;
+    model: string;
+    reason: string;
+    eligibleIds: string[];
+    blockedCauses: RouteBlockedCause[];
+    linkErrors: RouteLinkError[];
+    createdAt: number;
+}
+export interface RouteQuotaObservation {
+    provider: string;
+    accountRef: string;
+    model?: string;
+    status: 'ok' | 'blocked';
+    source: string;
+    resetAt?: number;
+}
+export interface RouteRequest {
+    taskId: string;
+    threadId: string | null;
+    agentId: string;
+    mode: RouteMode;
+    namedAcpSession?: boolean;
+}

package/dist/schema/index.d.ts

@@ -27,3 +27,4 @@ export * from './schedule-runs.js';
 export * from './run-column-backfill.js';
 export * from './doc-sync-connect-requests.js';
 export * from './doc-sync-links.js';
+export * from './model-routes.js';