@gobing-ai/ts-ai-runner 0.4.4 → 0.4.6

package/dist/doctor-runner.d.ts

@@ -2,8 +2,8 @@ import { type Logger } from '@gobing-ai/ts-infra';
 import { type FileSystem } from '@gobing-ai/ts-runtime';
 import { AgentDetector } from './agent-detector';
 import { type AuthState } from './agents/auth-shims';
-import { type AgentName } from './agents/shims';
 import { AiRunner } from './ai-runner';
+import { ModelHealthProbeRegistry, type ModelHealthResult } from './model-health-probe';
 /** Health-check result for one coding agent. */
 export interface DoctorResult {
     /** Agent identifier. */
@@ -32,10 +32,21 @@ export interface DoctorResult {
     /** True when the resolved canonical id is marked deprecated. */
     deprecated?: boolean;
     /** Canonical replacement when the resolved id is deprecated, if any. */
-    replacedBy?: AgentName;
+    replacedBy?: string;
+    /** Model health status when a probe was run; `null` when no model override applies. */
+    modelStatus?: ModelHealthResult | null;
     /** Probe error when unavailable. */
     error: string | null;
 }
+/** Executor configuration — mirrors Spur's AgentExecutorConfig for doctor probing. */
+export interface ExecutorConfig {
+    /** Executor name (e.g. `omp-zai`, `omp-zai-volc`). */
+    name: string;
+    /** Underlying agent binary (e.g. `omp`). */
+    agent: string;
+    /** Model string in `provider/model` form (e.g. `zai/glm-5.2`). */
+    model?: string;
+}
 /** Constructor options for DoctorRunner. */
 export interface DoctorRunnerOptions {
     /** Shared detector. */
@@ -50,6 +61,12 @@ export interface DoctorRunnerOptions {
     logger?: Logger;
     /** Filesystem for auth-file checks. Defaults to `createNodeFileSystem()`; inject to test without disk. */
     fileSystem?: FileSystem;
+    /** Executor configurations — when present, doctor probes each executor's model health. */
+    executors?: ExecutorConfig[];
+    /** Probe registry for model health checks. Defaults to a registry with {@link OmpModelProbe}. */
+    probeRegistry?: ModelHealthProbeRegistry;
+    /** Model health probe timeout in milliseconds (default 10s). */
+    probeTimeoutMs?: number;
 }
 /** Runs installation, liveness, and auth health checks for supported coding agents. */
 export declare class DoctorRunner {
@@ -59,11 +76,25 @@ export declare class DoctorRunner {
     private readonly env;
     private readonly fs;
     private readonly logger;
+    private readonly executors;
+    private readonly probeRegistry;
+    private readonly probeTimeoutMs;
     constructor(options?: DoctorRunnerOptions);
+    /** Create the default probe registry with OmpModelProbe for all known omp providers. */
+    private createDefaultRegistry;
     /** Run a health check on all supported agents. */
     runAll(): Promise<DoctorResult[]>;
+    /**
+     * Executor-aware runAll: iterate configured executors instead of
+     * DISPLAY_ORDER, giving each executor its own row with model health.
+     */
+    private runAllWithExecutors;
     /** Run a health check on one agent. */
     runOne(agent: string): Promise<DoctorResult>;
+    /** Probe model health for a `provider/model` string. */
+    private probeModel;
+    /** Resolve API key from env using `{PROVIDER_UPPERCASE}_API_KEY` convention. */
+    private resolveApiKey;
     private buildResult;
 }
 //# sourceMappingURL=doctor-runner.d.ts.map

package/dist/doctor-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor-runner.d.ts","sourceRoot":"","sources":["../src/doctor-runner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAwB,KAAK,UAAU,EAAiB,MAAM,uBAAuB,CAAC;AAC7F,OAAO,EAAE,aAAa,EAAsB,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,KAAK,SAAS,EAAmB,MAAM,qBAAqB,CAAC;AACtE,OAAO,EAAE,KAAK,SAAS,EAAiD,MAAM,gBAAgB,CAAC;AAC/F,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,gDAAgD;AAChD,MAAM,WAAW,YAAY;IACzB,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,SAAS,EAAE,OAAO,CAAC;IACnB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB;;;;;OAKG;IACH,aAAa,EAAE,SAAS,CAAC;IACzB;;;;OAIG;IACH,MAAM,EAAE,OAAO,CAAC;IAChB,oEAAoE;IACpE,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC;IACZ,wDAAwD;IACxD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,gEAAgE;IAChE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,wEAAwE;IACxE,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB,oCAAoC;IACpC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,4CAA4C;AAC5C,MAAM,WAAW,mBAAmB;IAChC,uBAAuB;IACvB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,qBAAqB;IACrB,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0GAA0G;IAC1G,UAAU,CAAC,EAAE,UAAU,CAAC;CAC3B;AAID,uFAAuF;AACvF,qBAAa,YAAY;IACrB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqC;IACzD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAa;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,OAAO,GAAE,mBAAwB;IAS7C,kDAAkD;IAC5C,MAAM,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAkBvC,uCAAuC;IACjC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;YAIpC,WAAW;CA4B5B"}
+{"version":3,"file":"doctor-runner.d.ts","sourceRoot":"","sources":["../src/doctor-runner.ts"],"names":[],"mappings":"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"}

package/dist/doctor-runner.js

@@ -4,6 +4,7 @@ import { AgentDetector } from './agent-detector.js';
 import { isAuthenticated } from './agents/auth-shims.js';
 import { DISPLAY_ORDER, resolveAgentName, TIER2_AGENTS } from './agents/shims.js';
 import { AiRunner } from './ai-runner.js';
+import { DEFAULT_PROBE_TIMEOUT_MS, extractProvider, ModelHealthProbeRegistry, OmpModelProbe, } from './model-health-probe.js';
 const DEFAULT_TIMEOUT_MS = 5_000;
 /** Runs installation, liveness, and auth health checks for supported coding agents. */
 export class DoctorRunner {
@@ -13,6 +14,9 @@ export class DoctorRunner {
     env;
     fs;
     logger;
+    executors;
+    probeRegistry;
+    probeTimeoutMs;
     constructor(options = {}) {
         this.runner = options.runner ?? new AiRunner();
         this.detector = options.agentDetector ?? new AgentDetector({ runner: this.runner });
@@ -20,9 +24,24 @@ export class DoctorRunner {
         this.env = options.env ?? getProcessEnv();
         this.fs = options.fileSystem ?? createNodeFileSystem();
         this.logger = options.logger ?? getLogger('doctor');
+        this.executors = options.executors ?? [];
+        this.probeTimeoutMs = options.probeTimeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
+        this.probeRegistry = options.probeRegistry ?? this.createDefaultRegistry();
+    }
+    /** Create the default probe registry with OmpModelProbe for all known omp providers. */
+    createDefaultRegistry() {
+        const registry = new ModelHealthProbeRegistry();
+        const probe = new OmpModelProbe();
+        for (const provider of ['zai', 'volc', 'minimax', 'deepseek']) {
+            registry.register(provider, probe);
+        }
+        return registry;
     }
     /** Run a health check on all supported agents. */
     async runAll() {
+        if (this.executors.length > 0) {
+            return await this.runAllWithExecutors();
+        }
         const detected = await this.detector.detectAll();
         const byName = new Map(detected.map((agent) => [agent.name, agent]));
         return await Promise.all(DISPLAY_ORDER.map((agent) => this.buildResult(byName.get(agent) ?? {
@@ -33,10 +52,74 @@ export class DoctorRunner {
             error: `Unknown agent: ${agent}`,
         })));
     }
+    /**
+     * Executor-aware runAll: iterate configured executors instead of
+     * DISPLAY_ORDER, giving each executor its own row with model health.
+     */
+    async runAllWithExecutors() {
+        const detected = await this.detector.detectAll();
+        const byName = new Map(detected.map((agent) => [agent.name, agent]));
+        const results = [];
+        for (const executor of this.executors) {
+            const agentDetected = byName.get(executor.agent) ?? {
+                name: executor.agent,
+                installed: false,
+                version: null,
+                channels: [],
+                error: `Unknown agent: ${executor.agent}`,
+            };
+            const result = await this.buildResult(agentDetected);
+            // Override the agent name with the executor name for display
+            result.agent = executor.name;
+            // R1: probe model health when a model override is present; null otherwise.
+            result.modelStatus = executor.model ? await this.probeModel(executor.model) : null;
+            results.push(result);
+        }
+        return results;
+    }
     /** Run a health check on one agent. */
     async runOne(agent) {
+        // When executors are configured, match executor name first
+        if (this.executors.length > 0) {
+            const executor = this.executors.find((e) => e.name === agent);
+            if (executor) {
+                const detected = await this.detector.detectOne(executor.agent);
+                const result = await this.buildResult(detected);
+                result.agent = executor.name;
+                result.modelStatus = executor.model ? await this.probeModel(executor.model) : null;
+                return result;
+            }
+        }
         return this.buildResult(await this.detector.detectOne(agent));
     }
+    /** Probe model health for a `provider/model` string. */
+    async probeModel(model) {
+        const provider = extractProvider(model);
+        const probe = this.probeRegistry.resolve(model);
+        if (!probe) {
+            return {
+                status: 'unknown',
+                detail: `no probe registered for provider '${provider}'`,
+                checkedAt: new Date().toISOString(),
+            };
+        }
+        const apiKey = this.resolveApiKey(provider);
+        if (!apiKey) {
+            return {
+                status: 'unknown',
+                detail: `API key not found for provider '${provider}'`,
+                checkedAt: new Date().toISOString(),
+            };
+        }
+        return await probe.probe(provider, model, {
+            apiKey,
+            timeoutMs: this.probeTimeoutMs,
+        });
+    }
+    /** Resolve API key from env using `{PROVIDER_UPPERCASE}_API_KEY` convention. */
+    resolveApiKey(provider) {
+        return this.env[`${provider.toUpperCase()}_API_KEY`];
+    }
     async buildResult(detected) {
         const canonical = resolveAgentName(detected.name) ?? null;
         const tier = canonical !== null && TIER2_AGENTS.has(canonical) ? 2 : 1;
@@ -54,8 +137,8 @@ export class DoctorRunner {
             installed: detected.installed,
             version: detected.version,
             authenticated,
-            // Liveness only: auth never gates runnability. A logged-out agent
-            // is usable (it fails at runtime with its own error).
+            // Liveness only: auth never gates runnability. A logged-out
+            // agent is usable (it fails at runtime with its own error).
             usable: detected.installed && detected.version !== null,
             tier,
             channels: detected.channels,

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export * from './doctor-runner';
 export * from './events';
 export * from './identity';
 export * from './messages';
+export * from './model-health-probe';
 export * from './slash-command';
 export * from './team-agent-process';
 export * from './team-orchestrator';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC"}

package/dist/index.js

@@ -7,6 +7,7 @@ export * from './doctor-runner.js';
 export * from './events.js';
 export * from './identity.js';
 export * from './messages.js';
+export * from './model-health-probe.js';
 export * from './slash-command.js';
 export * from './team-agent-process.js';
 export * from './team-orchestrator.js';

package/dist/model-health-probe.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Model health probe infrastructure.
+ *
+ * Provides a pluggable probe interface for checking model-level liveness and
+ * quota state on provider APIs. The {@link ModelHealthProbeRegistry} maps
+ * provider prefixes (e.g. `volc/`, `zai/`) to probe implementations, so new
+ * providers can be added without modifying {@link DoctorRunner} core (R9).
+ *
+ * The shipped {@link OmpModelProbe} handles all `omp`-configured providers by
+ * issuing a minimal 1-token completion request and interpreting the HTTP
+ * response (R3).
+ */
+import { type APIClientConfig } from '@gobing-ai/ts-infra';
+/** Health status for a single model endpoint. */
+export type ModelHealthStatus = 'available' | 'quota_exhausted' | 'rate_limited' | 'unavailable' | 'unknown';
+/** Result of probing one model's health (R2). */
+export interface ModelHealthResult {
+    status: ModelHealthStatus;
+    /** Sanitized provider error message — never contains API keys or headers. */
+    detail?: string;
+    /** ISO 8601 timestamp of when the probe completed. */
+    checkedAt: string;
+}
+/** Configuration passed to a probe — the probe is a pure HTTP client (R3). */
+export interface ProbeConfig {
+    /** API key for the provider, resolved by the caller (DoctorRunner) from env. */
+    apiKey: string;
+    /** Bounded timeout in milliseconds (default 10s). A timeout resolves to `unknown` (R8). */
+    timeoutMs: number;
+    /** Optional endpoint override (for testing or custom deployments). */
+    endpoint?: string;
+}
+/** Provider-agnostic probe interface (R2). */
+export interface ModelHealthProbe {
+    probe(provider: string, model: string, config: ProbeConfig): Promise<ModelHealthResult>;
+}
+/**
+ * Maps provider prefixes to probe implementations (R9).
+ * The provider prefix is extracted from the model string's first path segment
+ * (e.g. `volc/glm-5.2` → `volc`).
+ */
+export declare class ModelHealthProbeRegistry {
+    private readonly probes;
+    /** Register a probe for a provider prefix (e.g. `volc`, `zai`). */
+    register(providerPrefix: string, probe: ModelHealthProbe): void;
+    /** Resolve a probe for a model string, or `null` when no probe is registered. */
+    resolve(model: string): ModelHealthProbe | null;
+}
+/** Extract the provider prefix from a `provider/model` string. */
+export declare function extractProvider(model: string): string;
+/** Extract the model name from a `provider/model` string. */
+export declare function extractModelName(model: string): string;
+declare const DEFAULT_PROBE_TIMEOUT_MS = 10000;
+/** Options for constructing an {@link OmpModelProbe}. */
+export interface OmpModelProbeOptions {
+    /**
+     * Optional {@link APIClientConfig} (without `baseUrl` — the probe owns the
+     * provider→baseUrl mapping). Pass `fetch` here to inject a custom fetch
+     * for testing; omit to use `globalThis.fetch` (resolved lazily per request
+     * by `APIClient`, so test-time `globalThis.fetch` mutations take effect).
+     */
+    apiClientConfig?: Omit<APIClientConfig, 'baseUrl'>;
+}
+/**
+ * Probe for `omp`-configured providers (R3).
+ *
+ * Issues a minimal 1-token completion request (`prompt: "ping"`, `max_tokens: 1`)
+ * to the provider's API and interprets the response:
+ * - 200 → `available`
+ * - 429 + quota body → `quota_exhausted`
+ * - 429 + rate-limit body → `rate_limited`
+ * - Other 4xx/5xx → `unavailable`
+ * - HTTP timeout (via APIClient, reported as APIError status 0) → `unknown`
+ *
+ * Uses {@link APIClient} from `@gobing-ai/ts-infra` for all HTTP — the
+ * centralized HTTP seam per `external-api-boundaries` rule. Supports both
+ * `openai-completions` and `anthropic-messages` API formats. The
+ * provider→apiType mapping is built into this probe since it is specifically
+ * the `OmpModelProbe` — pluggability (R9) is at the registry level.
+ */
+export declare class OmpModelProbe implements ModelHealthProbe {
+    private readonly apiClientConfig?;
+    constructor(options?: OmpModelProbeOptions);
+    probe(provider: string, model: string, config: ProbeConfig): Promise<ModelHealthResult>;
+    /** Issue a minimal completion request based on the API format. */
+    private issueRequest;
+    /** Interpret the HTTP response into a {@link ModelHealthResult}. */
+    private interpretResponse;
+    /** Best-effort JSON body parse; returns null on failure. */
+    private parseBody;
+}
+/** Default probe timeout in milliseconds (R8). */
+export { DEFAULT_PROBE_TIMEOUT_MS };
+//# sourceMappingURL=model-health-probe.d.ts.map

package/dist/model-health-probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-health-probe.d.ts","sourceRoot":"","sources":["../src/model-health-probe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAa,KAAK,eAAe,EAAkC,MAAM,qBAAqB,CAAC;AAEtG,iDAAiD;AACjD,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,iBAAiB,GAAG,cAAc,GAAG,aAAa,GAAG,SAAS,CAAC;AAE7G,iDAAiD;AACjD,MAAM,WAAW,iBAAiB;IAC9B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;CACrB;AAED,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IACxB,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf,2FAA2F;IAC3F,SAAS,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,8CAA8C;AAC9C,MAAM,WAAW,gBAAgB;IAC7B,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAC3F;AAED;;;;GAIG;AACH,qBAAa,wBAAwB;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuC;IAE9D,mEAAmE;IACnE,QAAQ,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAI/D,iFAAiF;IACjF,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI;CAKlD;AAED,kEAAkE;AAClE,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED,6DAA6D;AAC7D,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGtD;AAgBD,QAAA,MAAM,wBAAwB,QAAS,CAAC;AAExC,yDAAyD;AACzD,MAAM,WAAW,oBAAoB;IACjC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,SAAS,CAAC,CAAC;CACtD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,aAAc,YAAW,gBAAgB;IAClD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAmC;gBAExD,OAAO,CAAC,EAAE,oBAAoB;IAIpC,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA6B7F,kEAAkE;YACpD,YAAY;IAiD1B,oEAAoE;IACpE,OAAO,CAAC,iBAAiB;IAwBzB,4DAA4D;IAC5D,OAAO,CAAC,SAAS;CAOpB;AAED,kDAAkD;AAClD,OAAO,EAAE,wBAAwB,EAAE,CAAC"}

package/dist/model-health-probe.js

@@ -0,0 +1,153 @@
+/**
+ * Model health probe infrastructure.
+ *
+ * Provides a pluggable probe interface for checking model-level liveness and
+ * quota state on provider APIs. The {@link ModelHealthProbeRegistry} maps
+ * provider prefixes (e.g. `volc/`, `zai/`) to probe implementations, so new
+ * providers can be added without modifying {@link DoctorRunner} core (R9).
+ *
+ * The shipped {@link OmpModelProbe} handles all `omp`-configured providers by
+ * issuing a minimal 1-token completion request and interpreting the HTTP
+ * response (R3).
+ */
+import { APIClient, APIError } from '@gobing-ai/ts-infra';
+/**
+ * Maps provider prefixes to probe implementations (R9).
+ * The provider prefix is extracted from the model string's first path segment
+ * (e.g. `volc/glm-5.2` → `volc`).
+ */
+export class ModelHealthProbeRegistry {
+    probes = new Map();
+    /** Register a probe for a provider prefix (e.g. `volc`, `zai`). */
+    register(providerPrefix, probe) {
+        this.probes.set(providerPrefix, probe);
+    }
+    /** Resolve a probe for a model string, or `null` when no probe is registered. */
+    resolve(model) {
+        const slashIndex = model.indexOf('/');
+        const provider = slashIndex >= 0 ? model.slice(0, slashIndex) : model;
+        return this.probes.get(provider) ?? null;
+    }
+}
+/** Extract the provider prefix from a `provider/model` string. */
+export function extractProvider(model) {
+    const slashIndex = model.indexOf('/');
+    return slashIndex >= 0 ? model.slice(0, slashIndex) : model;
+}
+/** Extract the model name from a `provider/model` string. */
+export function extractModelName(model) {
+    const slashIndex = model.indexOf('/');
+    return slashIndex >= 0 ? model.slice(slashIndex + 1) : model;
+}
+/** Known omp provider configurations (baseUrl + API format). */
+const OMP_PROVIDERS = {
+    zai: { baseUrl: 'https://api.z.ai/api/coding/paas/v4', apiType: 'openai-completions' },
+    volc: { baseUrl: 'https://ark.cn-beijing.volces.com/api/coding', apiType: 'anthropic-messages' },
+    minimax: { baseUrl: 'https://api.minimaxi.com/v1', apiType: 'openai-completions' },
+    deepseek: { baseUrl: 'https://api.deepseek.com', apiType: 'openai-completions' },
+};
+const DEFAULT_PROBE_TIMEOUT_MS = 10_000;
+/**
+ * Probe for `omp`-configured providers (R3).
+ *
+ * Issues a minimal 1-token completion request (`prompt: "ping"`, `max_tokens: 1`)
+ * to the provider's API and interprets the response:
+ * - 200 → `available`
+ * - 429 + quota body → `quota_exhausted`
+ * - 429 + rate-limit body → `rate_limited`
+ * - Other 4xx/5xx → `unavailable`
+ * - HTTP timeout (via APIClient, reported as APIError status 0) → `unknown`
+ *
+ * Uses {@link APIClient} from `@gobing-ai/ts-infra` for all HTTP — the
+ * centralized HTTP seam per `external-api-boundaries` rule. Supports both
+ * `openai-completions` and `anthropic-messages` API formats. The
+ * provider→apiType mapping is built into this probe since it is specifically
+ * the `OmpModelProbe` — pluggability (R9) is at the registry level.
+ */
+export class OmpModelProbe {
+    apiClientConfig;
+    constructor(options) {
+        this.apiClientConfig = options?.apiClientConfig;
+    }
+    async probe(provider, model, config) {
+        const checkedAt = new Date().toISOString();
+        const providerConfig = OMP_PROVIDERS[provider];
+        if (!providerConfig) {
+            return { status: 'unknown', detail: `unknown omp provider '${provider}'`, checkedAt };
+        }
+        const baseUrl = config.endpoint ?? providerConfig.baseUrl;
+        try {
+            const response = await this.issueRequest(providerConfig.apiType, baseUrl, model, config.apiKey, config.timeoutMs);
+            return this.interpretResponse(response, checkedAt);
+        }
+        catch (error) {
+            // APIClient reports timeouts as APIError with status 0.
+            if (error instanceof APIError && error.status === 0) {
+                return { status: 'unknown', detail: 'probe timed out', checkedAt };
+            }
+            const message = error instanceof Error ? error.message : 'probe failed';
+            return { status: 'unknown', detail: message, checkedAt };
+        }
+    }
+    /** Issue a minimal completion request based on the API format. */
+    async issueRequest(apiType, baseUrl, model, apiKey, timeoutMs) {
+        const client = new APIClient({ ...this.apiClientConfig, baseUrl });
+        if (apiType === 'anthropic-messages') {
+            return await client.rawRequest('POST', '/messages', JSON.stringify({
+                model,
+                messages: [{ role: 'user', content: 'ping' }],
+                max_tokens: 1,
+            }), {
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-api-key': apiKey,
+                    'anthropic-version': '2023-06-01',
+                },
+                timeout: timeoutMs,
+                operationName: 'model-health-probe anthropic-messages',
+            });
+        }
+        return await client.rawRequest('POST', '/chat/completions', JSON.stringify({
+            model,
+            messages: [{ role: 'user', content: 'ping' }],
+            max_tokens: 1,
+        }), {
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${apiKey}`,
+            },
+            timeout: timeoutMs,
+            operationName: 'model-health-probe openai-completions',
+        });
+    }
+    /** Interpret the HTTP response into a {@link ModelHealthResult}. */
+    interpretResponse(response, checkedAt) {
+        if (response.status === 200) {
+            return { status: 'available', checkedAt };
+        }
+        if (response.status === 429) {
+            const body = this.parseBody(response.body);
+            const errorType = body?.error?.type ?? body?.error?.code ?? '';
+            const errorMessage = body?.error?.message ?? '';
+            if (errorType.includes('quota') ||
+                errorType.includes('insufficient_quota') ||
+                errorType.includes('insufficient')) {
+                return { status: 'quota_exhausted', detail: errorMessage || 'quota exceeded', checkedAt };
+            }
+            return { status: 'rate_limited', detail: errorMessage || 'rate limited', checkedAt };
+        }
+        // Other 4xx/5xx → unavailable
+        return { status: 'unavailable', detail: `HTTP ${response.status}`, checkedAt };
+    }
+    /** Best-effort JSON body parse; returns null on failure. */
+    parseBody(body) {
+        try {
+            return JSON.parse(body);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/** Default probe timeout in milliseconds (R8). */
+export { DEFAULT_PROBE_TIMEOUT_MS };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-ai-runner",
-    "version": "0.4.4",
+    "version": "0.4.6",
     "description": "@gobing-ai/ts-ai-runner — Coding-agent shims, detection, doctor checks, and prompt execution.",
     "keywords": [
         "typescript",
@@ -47,9 +47,9 @@
         "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-ai-runner-v<version> && git push --tags' && exit 1"
     },
     "dependencies": {
-        "@gobing-ai/ts-db": "^0.4.4",
-        "@gobing-ai/ts-infra": "^0.4.4",
-        "@gobing-ai/ts-runtime": "^0.4.4"
+        "@gobing-ai/ts-db": "^0.4.6",
+        "@gobing-ai/ts-infra": "^0.4.6",
+        "@gobing-ai/ts-runtime": "^0.4.6"
     },
     "devDependencies": {
         "@types/bun": "1.3.14"

package/src/doctor-runner.ts

@@ -2,8 +2,15 @@ import { getLogger, type Logger } from '@gobing-ai/ts-infra';
 import { createNodeFileSystem, type FileSystem, getProcessEnv } from '@gobing-ai/ts-runtime';
 import { AgentDetector, type DetectedAgent } from './agent-detector';
 import { type AuthState, isAuthenticated } from './agents/auth-shims';
-import { type AgentName, DISPLAY_ORDER, resolveAgentName, TIER2_AGENTS } from './agents/shims';
+import { DISPLAY_ORDER, resolveAgentName, TIER2_AGENTS } from './agents/shims';
 import { AiRunner } from './ai-runner';
+import {
+    DEFAULT_PROBE_TIMEOUT_MS,
+    extractProvider,
+    ModelHealthProbeRegistry,
+    type ModelHealthResult,
+    OmpModelProbe,
+} from './model-health-probe';
 
 /** Health-check result for one coding agent. */
 export interface DoctorResult {
@@ -33,11 +40,23 @@ export interface DoctorResult {
     /** True when the resolved canonical id is marked deprecated. */
     deprecated?: boolean;
     /** Canonical replacement when the resolved id is deprecated, if any. */
-    replacedBy?: AgentName;
+    replacedBy?: string;
+    /** Model health status when a probe was run; `null` when no model override applies. */
+    modelStatus?: ModelHealthResult | null;
     /** Probe error when unavailable. */
     error: string | null;
 }
 
+/** Executor configuration — mirrors Spur's AgentExecutorConfig for doctor probing. */
+export interface ExecutorConfig {
+    /** Executor name (e.g. `omp-zai`, `omp-zai-volc`). */
+    name: string;
+    /** Underlying agent binary (e.g. `omp`). */
+    agent: string;
+    /** Model string in `provider/model` form (e.g. `zai/glm-5.2`). */
+    model?: string;
+}
+
 /** Constructor options for DoctorRunner. */
 export interface DoctorRunnerOptions {
     /** Shared detector. */
@@ -52,6 +71,12 @@ export interface DoctorRunnerOptions {
     logger?: Logger;
     /** Filesystem for auth-file checks. Defaults to `createNodeFileSystem()`; inject to test without disk. */
     fileSystem?: FileSystem;
+    /** Executor configurations — when present, doctor probes each executor's model health. */
+    executors?: ExecutorConfig[];
+    /** Probe registry for model health checks. Defaults to a registry with {@link OmpModelProbe}. */
+    probeRegistry?: ModelHealthProbeRegistry;
+    /** Model health probe timeout in milliseconds (default 10s). */
+    probeTimeoutMs?: number;
 }
 
 const DEFAULT_TIMEOUT_MS = 5_000;
@@ -64,6 +89,9 @@ export class DoctorRunner {
     private readonly env: Record<string, string | undefined>;
     private readonly fs: FileSystem;
     private readonly logger: Logger;
+    private readonly executors: ExecutorConfig[];
+    private readonly probeRegistry: ModelHealthProbeRegistry;
+    private readonly probeTimeoutMs: number;
 
     constructor(options: DoctorRunnerOptions = {}) {
         this.runner = options.runner ?? new AiRunner();
@@ -72,10 +100,26 @@ export class DoctorRunner {
         this.env = options.env ?? getProcessEnv();
         this.fs = options.fileSystem ?? createNodeFileSystem();
         this.logger = options.logger ?? getLogger('doctor');
+        this.executors = options.executors ?? [];
+        this.probeTimeoutMs = options.probeTimeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
+        this.probeRegistry = options.probeRegistry ?? this.createDefaultRegistry();
+    }
+
+    /** Create the default probe registry with OmpModelProbe for all known omp providers. */
+    private createDefaultRegistry(): ModelHealthProbeRegistry {
+        const registry = new ModelHealthProbeRegistry();
+        const probe = new OmpModelProbe();
+        for (const provider of ['zai', 'volc', 'minimax', 'deepseek']) {
+            registry.register(provider, probe);
+        }
+        return registry;
     }
 
     /** Run a health check on all supported agents. */
     async runAll(): Promise<DoctorResult[]> {
+        if (this.executors.length > 0) {
+            return await this.runAllWithExecutors();
+        }
         const detected = await this.detector.detectAll();
         const byName = new Map(detected.map((agent) => [agent.name, agent]));
         return await Promise.all(
@@ -93,11 +137,78 @@ export class DoctorRunner {
         );
     }
 
+    /**
+     * Executor-aware runAll: iterate configured executors instead of
+     * DISPLAY_ORDER, giving each executor its own row with model health.
+     */
+    private async runAllWithExecutors(): Promise<DoctorResult[]> {
+        const detected = await this.detector.detectAll();
+        const byName = new Map(detected.map((agent) => [agent.name, agent]));
+        const results: DoctorResult[] = [];
+        for (const executor of this.executors) {
+            const agentDetected = byName.get(executor.agent) ?? {
+                name: executor.agent,
+                installed: false,
+                version: null,
+                channels: [],
+                error: `Unknown agent: ${executor.agent}`,
+            };
+            const result = await this.buildResult(agentDetected);
+            // Override the agent name with the executor name for display
+            result.agent = executor.name;
+            // R1: probe model health when a model override is present; null otherwise.
+            result.modelStatus = executor.model ? await this.probeModel(executor.model) : null;
+            results.push(result);
+        }
+        return results;
+    }
+
     /** Run a health check on one agent. */
     async runOne(agent: string): Promise<DoctorResult> {
+        // When executors are configured, match executor name first
+        if (this.executors.length > 0) {
+            const executor = this.executors.find((e) => e.name === agent);
+            if (executor) {
+                const detected = await this.detector.detectOne(executor.agent);
+                const result = await this.buildResult(detected);
+                result.agent = executor.name;
+                result.modelStatus = executor.model ? await this.probeModel(executor.model) : null;
+                return result;
+            }
+        }
         return this.buildResult(await this.detector.detectOne(agent));
     }
 
+    /** Probe model health for a `provider/model` string. */
+    private async probeModel(model: string): Promise<ModelHealthResult> {
+        const provider = extractProvider(model);
+        const probe = this.probeRegistry.resolve(model);
+        if (!probe) {
+            return {
+                status: 'unknown',
+                detail: `no probe registered for provider '${provider}'`,
+                checkedAt: new Date().toISOString(),
+            };
+        }
+        const apiKey = this.resolveApiKey(provider);
+        if (!apiKey) {
+            return {
+                status: 'unknown',
+                detail: `API key not found for provider '${provider}'`,
+                checkedAt: new Date().toISOString(),
+            };
+        }
+        return await probe.probe(provider, model, {
+            apiKey,
+            timeoutMs: this.probeTimeoutMs,
+        });
+    }
+
+    /** Resolve API key from env using `{PROVIDER_UPPERCASE}_API_KEY` convention. */
+    private resolveApiKey(provider: string): string | undefined {
+        return this.env[`${provider.toUpperCase()}_API_KEY`];
+    }
+
     private async buildResult(detected: DetectedAgent): Promise<DoctorResult> {
         const canonical = resolveAgentName(detected.name) ?? null;
         const tier = canonical !== null && TIER2_AGENTS.has(canonical) ? 2 : 1;
@@ -116,8 +227,8 @@ export class DoctorRunner {
             installed: detected.installed,
             version: detected.version,
             authenticated,
-            // Liveness only: auth never gates runnability. A logged-out agent
-            // is usable (it fails at runtime with its own error).
+            // Liveness only: auth never gates runnability. A logged-out
+            // agent is usable (it fails at runtime with its own error).
             usable: detected.installed && detected.version !== null,
             tier,
             channels: detected.channels,

package/src/index.ts

@@ -7,6 +7,7 @@ export * from './doctor-runner';
 export * from './events';
 export * from './identity';
 export * from './messages';
+export * from './model-health-probe';
 export * from './slash-command';
 export * from './team-agent-process';
 export * from './team-orchestrator';

package/src/model-health-probe.ts

@@ -0,0 +1,241 @@
+/**
+ * Model health probe infrastructure.
+ *
+ * Provides a pluggable probe interface for checking model-level liveness and
+ * quota state on provider APIs. The {@link ModelHealthProbeRegistry} maps
+ * provider prefixes (e.g. `volc/`, `zai/`) to probe implementations, so new
+ * providers can be added without modifying {@link DoctorRunner} core (R9).
+ *
+ * The shipped {@link OmpModelProbe} handles all `omp`-configured providers by
+ * issuing a minimal 1-token completion request and interpreting the HTTP
+ * response (R3).
+ */
+import { APIClient, type APIClientConfig, APIError, type RawHttpResponse } from '@gobing-ai/ts-infra';
+
+/** Health status for a single model endpoint. */
+export type ModelHealthStatus = 'available' | 'quota_exhausted' | 'rate_limited' | 'unavailable' | 'unknown';
+
+/** Result of probing one model's health (R2). */
+export interface ModelHealthResult {
+    status: ModelHealthStatus;
+    /** Sanitized provider error message — never contains API keys or headers. */
+    detail?: string;
+    /** ISO 8601 timestamp of when the probe completed. */
+    checkedAt: string;
+}
+
+/** Configuration passed to a probe — the probe is a pure HTTP client (R3). */
+export interface ProbeConfig {
+    /** API key for the provider, resolved by the caller (DoctorRunner) from env. */
+    apiKey: string;
+    /** Bounded timeout in milliseconds (default 10s). A timeout resolves to `unknown` (R8). */
+    timeoutMs: number;
+    /** Optional endpoint override (for testing or custom deployments). */
+    endpoint?: string;
+}
+
+/** Provider-agnostic probe interface (R2). */
+export interface ModelHealthProbe {
+    probe(provider: string, model: string, config: ProbeConfig): Promise<ModelHealthResult>;
+}
+
+/**
+ * Maps provider prefixes to probe implementations (R9).
+ * The provider prefix is extracted from the model string's first path segment
+ * (e.g. `volc/glm-5.2` → `volc`).
+ */
+export class ModelHealthProbeRegistry {
+    private readonly probes = new Map<string, ModelHealthProbe>();
+
+    /** Register a probe for a provider prefix (e.g. `volc`, `zai`). */
+    register(providerPrefix: string, probe: ModelHealthProbe): void {
+        this.probes.set(providerPrefix, probe);
+    }
+
+    /** Resolve a probe for a model string, or `null` when no probe is registered. */
+    resolve(model: string): ModelHealthProbe | null {
+        const slashIndex = model.indexOf('/');
+        const provider = slashIndex >= 0 ? model.slice(0, slashIndex) : model;
+        return this.probes.get(provider) ?? null;
+    }
+}
+
+/** Extract the provider prefix from a `provider/model` string. */
+export function extractProvider(model: string): string {
+    const slashIndex = model.indexOf('/');
+    return slashIndex >= 0 ? model.slice(0, slashIndex) : model;
+}
+
+/** Extract the model name from a `provider/model` string. */
+export function extractModelName(model: string): string {
+    const slashIndex = model.indexOf('/');
+    return slashIndex >= 0 ? model.slice(slashIndex + 1) : model;
+}
+
+/** Provider configuration for omp-managed providers. */
+interface OmpProviderConfig {
+    baseUrl: string;
+    apiType: 'openai-completions' | 'anthropic-messages';
+}
+
+/** Known omp provider configurations (baseUrl + API format). */
+const OMP_PROVIDERS: Record<string, OmpProviderConfig> = {
+    zai: { baseUrl: 'https://api.z.ai/api/coding/paas/v4', apiType: 'openai-completions' },
+    volc: { baseUrl: 'https://ark.cn-beijing.volces.com/api/coding', apiType: 'anthropic-messages' },
+    minimax: { baseUrl: 'https://api.minimaxi.com/v1', apiType: 'openai-completions' },
+    deepseek: { baseUrl: 'https://api.deepseek.com', apiType: 'openai-completions' },
+};
+
+const DEFAULT_PROBE_TIMEOUT_MS = 10_000;
+
+/** Options for constructing an {@link OmpModelProbe}. */
+export interface OmpModelProbeOptions {
+    /**
+     * Optional {@link APIClientConfig} (without `baseUrl` — the probe owns the
+     * provider→baseUrl mapping). Pass `fetch` here to inject a custom fetch
+     * for testing; omit to use `globalThis.fetch` (resolved lazily per request
+     * by `APIClient`, so test-time `globalThis.fetch` mutations take effect).
+     */
+    apiClientConfig?: Omit<APIClientConfig, 'baseUrl'>;
+}
+
+/**
+ * Probe for `omp`-configured providers (R3).
+ *
+ * Issues a minimal 1-token completion request (`prompt: "ping"`, `max_tokens: 1`)
+ * to the provider's API and interprets the response:
+ * - 200 → `available`
+ * - 429 + quota body → `quota_exhausted`
+ * - 429 + rate-limit body → `rate_limited`
+ * - Other 4xx/5xx → `unavailable`
+ * - HTTP timeout (via APIClient, reported as APIError status 0) → `unknown`
+ *
+ * Uses {@link APIClient} from `@gobing-ai/ts-infra` for all HTTP — the
+ * centralized HTTP seam per `external-api-boundaries` rule. Supports both
+ * `openai-completions` and `anthropic-messages` API formats. The
+ * provider→apiType mapping is built into this probe since it is specifically
+ * the `OmpModelProbe` — pluggability (R9) is at the registry level.
+ */
+export class OmpModelProbe implements ModelHealthProbe {
+    private readonly apiClientConfig?: Omit<APIClientConfig, 'baseUrl'>;
+
+    constructor(options?: OmpModelProbeOptions) {
+        this.apiClientConfig = options?.apiClientConfig;
+    }
+
+    async probe(provider: string, model: string, config: ProbeConfig): Promise<ModelHealthResult> {
+        const checkedAt = new Date().toISOString();
+        const providerConfig = OMP_PROVIDERS[provider];
+
+        if (!providerConfig) {
+            return { status: 'unknown', detail: `unknown omp provider '${provider}'`, checkedAt };
+        }
+
+        const baseUrl = config.endpoint ?? providerConfig.baseUrl;
+
+        try {
+            const response = await this.issueRequest(
+                providerConfig.apiType,
+                baseUrl,
+                model,
+                config.apiKey,
+                config.timeoutMs,
+            );
+            return this.interpretResponse(response, checkedAt);
+        } catch (error) {
+            // APIClient reports timeouts as APIError with status 0.
+            if (error instanceof APIError && error.status === 0) {
+                return { status: 'unknown', detail: 'probe timed out', checkedAt };
+            }
+            const message = error instanceof Error ? error.message : 'probe failed';
+            return { status: 'unknown', detail: message, checkedAt };
+        }
+    }
+
+    /** Issue a minimal completion request based on the API format. */
+    private async issueRequest(
+        apiType: OmpProviderConfig['apiType'],
+        baseUrl: string,
+        model: string,
+        apiKey: string,
+        timeoutMs: number,
+    ): Promise<RawHttpResponse> {
+        const client = new APIClient({ ...this.apiClientConfig, baseUrl });
+
+        if (apiType === 'anthropic-messages') {
+            return await client.rawRequest(
+                'POST',
+                '/messages',
+                JSON.stringify({
+                    model,
+                    messages: [{ role: 'user', content: 'ping' }],
+                    max_tokens: 1,
+                }),
+                {
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'x-api-key': apiKey,
+                        'anthropic-version': '2023-06-01',
+                    },
+                    timeout: timeoutMs,
+                    operationName: 'model-health-probe anthropic-messages',
+                },
+            );
+        }
+
+        return await client.rawRequest(
+            'POST',
+            '/chat/completions',
+            JSON.stringify({
+                model,
+                messages: [{ role: 'user', content: 'ping' }],
+                max_tokens: 1,
+            }),
+            {
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${apiKey}`,
+                },
+                timeout: timeoutMs,
+                operationName: 'model-health-probe openai-completions',
+            },
+        );
+    }
+
+    /** Interpret the HTTP response into a {@link ModelHealthResult}. */
+    private interpretResponse(response: RawHttpResponse, checkedAt: string): ModelHealthResult {
+        if (response.status === 200) {
+            return { status: 'available', checkedAt };
+        }
+
+        if (response.status === 429) {
+            const body = this.parseBody(response.body);
+            const errorType = body?.error?.type ?? body?.error?.code ?? '';
+            const errorMessage = body?.error?.message ?? '';
+
+            if (
+                errorType.includes('quota') ||
+                errorType.includes('insufficient_quota') ||
+                errorType.includes('insufficient')
+            ) {
+                return { status: 'quota_exhausted', detail: errorMessage || 'quota exceeded', checkedAt };
+            }
+            return { status: 'rate_limited', detail: errorMessage || 'rate limited', checkedAt };
+        }
+
+        // Other 4xx/5xx → unavailable
+        return { status: 'unavailable', detail: `HTTP ${response.status}`, checkedAt };
+    }
+
+    /** Best-effort JSON body parse; returns null on failure. */
+    private parseBody(body: string): { error?: { type?: string; code?: string; message?: string } } | null {
+        try {
+            return JSON.parse(body) as { error?: { type?: string; code?: string; message?: string } };
+        } catch {
+            return null;
+        }
+    }
+}
+
+/** Default probe timeout in milliseconds (R8). */
+export { DEFAULT_PROBE_TIMEOUT_MS };