@gobing-ai/ts-ai-runner 0.3.20 → 0.3.21

package/src/agents/shims.ts

@@ -1,5 +1,16 @@
-/** Identifier for one supported coding agent. */
-export type AgentName = 'claude' | 'codex' | 'gemini' | 'pi' | 'opencode' | 'antigravity' | 'openclaw';
+import { getLogger } from '@gobing-ai/ts-infra';
+
+/** Identifier for one supported coding agent (canonical id). */
+export type AgentName =
+    | 'claude'
+    | 'codex'
+    | 'gemini'
+    | 'pi'
+    | 'opencode'
+    | 'antigravity-cli'
+    | 'openclaw'
+    | 'hermes'
+    | 'omp';
 
 /** Output mode for prompt invocations. */
 export type OutputMode = 'text' | 'json';
@@ -34,14 +45,26 @@ export interface PromptOptions {
     peers?: Array<{ id: string; type: string; purpose?: string }>;
 }
 
+/** Deprecation metadata attached to a retired or superseded agent shim. */
+export interface AgentDeprecation {
+    /** Release date (ISO) when the id was marked deprecated. */
+    readonly since: string;
+    /** Canonical replacement, when one exists. */
+    readonly replacedBy?: AgentName;
+}
+
 /** Pure command builder for one coding-agent CLI. */
 export interface AgentShim {
-    /** Stable agent identifier. */
+    /** Stable canonical agent identifier. */
     readonly name: AgentName;
     /** Executable command name. */
     readonly command: string;
     /** Capability tier: 1 = direct CLI, 2 = gateway/TUI constrained. */
     readonly tier: 1 | 2;
+    /** Non-canonical ids that resolve to this shim (aliases map to this canonical id). */
+    readonly aliases?: readonly string[];
+    /** Deprecation marker; resolving a deprecated id warns and reports canonical status. */
+    readonly deprecated?: AgentDeprecation;
     /** Build a help-display command. */
     getHelpCommand(): ShimCommand;
     /** Build a version-detection command. */
@@ -90,6 +113,7 @@ const geminiShim: AgentShim = {
     name: 'gemini',
     command: 'gemini',
     tier: 1,
+    deprecated: { since: '2026-06-20', replacedBy: 'antigravity-cli' },
     getHelpCommand: () => ({ command: 'gemini', args: ['--help'] }),
     getVersionCommand: () => ({ command: 'gemini', args: ['--version'] }),
     getPromptCommand: (options) => {
@@ -136,13 +160,24 @@ const opencodeShim: AgentShim = {
     getAuthCommand: () => ({ command: 'opencode', args: ['providers'] }),
 };
 
-const antigravityShim: AgentShim = {
-    name: 'antigravity',
+/**
+ * Antigravity CLI (`agy`) — the scriptable/headless successor to Gemini CLI
+ * (Antigravity 2.0 split, 2026-06). Tier-1: `-p`/`--print` one-shot, `--model`,
+ * `agy models`, `--continue` resumes the most recent session.
+ */
+const antigravityCliShim: AgentShim = {
+    name: 'antigravity-cli',
     command: 'agy',
-    tier: 2,
+    tier: 1,
+    aliases: ['antigravity'],
     getHelpCommand: () => ({ command: 'agy', args: ['--help'] }),
     getVersionCommand: () => ({ command: 'agy', args: ['--version'] }),
-    getPromptCommand: (options) => ({ command: 'agy', args: ['chat', options.input ?? ''] }),
+    getPromptCommand: (options) => {
+        const args = ['-p', options.input ?? ''];
+        if (options.continue === true) args.push('--continue');
+        if (options.model !== undefined) args.push('--model', options.model);
+        return { command: 'agy', args };
+    },
     getAuthCommand: () => null,
 };
 
@@ -156,19 +191,70 @@ const openclawShim: AgentShim = {
     getAuthCommand: () => ({ command: 'openclaw', args: ['health'] }),
 };
 
-/** All bundled agent shims keyed by agent name. */
+/**
+ * Hermes Agent (NousResearch) — OpenClaw-compatible coding agent. One-shot via
+ * `hermes chat -q <input>`; model/provider overrides; `hermes doctor` health probe.
+ */
+const hermesShim: AgentShim = {
+    name: 'hermes',
+    command: 'hermes',
+    tier: 1,
+    getHelpCommand: () => ({ command: 'hermes', args: ['chat', '--help'] }),
+    getVersionCommand: () => ({ command: 'hermes', args: ['--version'] }),
+    getPromptCommand: (options) => {
+        const args = ['chat', '-q', options.input ?? ''];
+        if (options.continue === true) args.push('--continue');
+        if (options.model !== undefined) args.push('-m', options.model);
+        return { command: 'hermes', args };
+    },
+    getAuthCommand: () => ({ command: 'hermes', args: ['doctor'] }),
+};
+
+/**
+ * omp (oh-my-pi) — a Pi fork. argv is Pi-compatible for the one-shot surface
+ * (`--no-session`, `-p`, `-c`, `--model`, `--mode`); speaks Pi's `/skill:` slash dialect.
+ */
+const ompShim: AgentShim = {
+    name: 'omp',
+    command: 'omp',
+    tier: 1,
+    getHelpCommand: () => ({ command: 'omp', args: ['--help'] }),
+    getVersionCommand: () => ({ command: 'omp', args: ['--version'] }),
+    getPromptCommand: (options) => {
+        const args: string[] = [];
+        if (options.continue !== true) args.push('--no-session');
+        args.push('-p', options.input ?? '');
+        if (options.continue === true) args.push('-c');
+        if (options.model !== undefined) args.push('--model', options.model);
+        args.push('--mode', options.mode ?? 'text');
+        return { command: 'omp', args };
+    },
+    getAuthCommand: () => ({ command: 'omp', args: ['--list-models'] }),
+};
+
+/** All bundled agent shims keyed by canonical agent name. */
 export const AGENT_SHIMS: Readonly<Record<AgentName, AgentShim>> = {
     claude: claudeShim,
     codex: codexShim,
     gemini: geminiShim,
     pi: piShim,
     opencode: opencodeShim,
-    antigravity: antigravityShim,
+    'antigravity-cli': antigravityCliShim,
     openclaw: openclawShim,
+    hermes: hermesShim,
+    omp: ompShim,
 };
 
-/** Tier-1 auto-selection priority. */
-export const TIER1_PRIORITY: readonly AgentName[] = ['pi', 'codex', 'gemini', 'claude', 'opencode'];
+/** Tier-1 auto-selection priority. Deprecated ids are excluded. */
+export const TIER1_PRIORITY: readonly AgentName[] = [
+    'pi',
+    'omp',
+    'codex',
+    'antigravity-cli',
+    'claude',
+    'hermes',
+    'opencode',
+];
 
 /** Display order for doctor and list commands. */
 export const DISPLAY_ORDER: readonly AgentName[] = [
@@ -176,20 +262,73 @@ export const DISPLAY_ORDER: readonly AgentName[] = [
     'codex',
     'gemini',
     'pi',
+    'omp',
     'opencode',
-    'antigravity',
+    'antigravity-cli',
     'openclaw',
+    'hermes',
 ];
 
 /** Set of gateway/TUI-constrained agents. */
-export const TIER2_AGENTS: ReadonlySet<AgentName> = new Set(['antigravity', 'openclaw']);
+export const TIER2_AGENTS: ReadonlySet<AgentName> = new Set(['openclaw']);
 
-/** Return true when a value is a supported agent identifier. */
-export function isAgentName(value: string): value is AgentName {
-    return Object.hasOwn(AGENT_SHIMS, value);
+/** Logger for alias/deprecation resolution diagnostics. */
+const logger = getLogger('ai-runner.shims');
+
+/** Alias → canonical id, derived once from `AGENT_SHIMS[*].aliases`. */
+const ALIAS_TO_CANONICAL: Readonly<Record<string, AgentName>> = Object.fromEntries(
+    Object.values(AGENT_SHIMS).flatMap((shim) => (shim.aliases ?? []).map((alias) => [alias, shim.name] as const)),
+);
+
+/**
+ * Resolve a canonical or alias id to its canonical `AgentName`.
+ *
+ * - Canonical ids resolve to themselves.
+ * - Aliases resolve to their canonical id (e.g. `'antigravity' → 'antigravity-cli'`).
+ * - Unknown ids resolve to `undefined`.
+ *
+ * Resolving a deprecated or aliased id emits exactly one `warn` through the
+ * logger seam and never throws.
+ */
+export function resolveAgentName(input: string): AgentName | undefined {
+    if (isCanonicalName(input)) return input;
+    const canonical = ALIAS_TO_CANONICAL[input];
+    if (canonical !== undefined) {
+        warnDeprecatedOrAlias(input, canonical);
+        return canonical;
+    }
+    return undefined;
+}
+
+/** Return true when a value is a known canonical id or alias. Does not narrow;
+ * use `resolveAgentName()` to obtain the canonical `AgentName`. */
+export function isAgentName(value: string): boolean {
+    return isCanonicalName(value) || value in ALIAS_TO_CANONICAL;
 }
 
-/** Look up a bundled agent shim. */
+/** Look up a bundled agent shim, resolving aliases to the canonical shim. */
 export function getAgentShim(agent: AgentName): AgentShim {
-    return AGENT_SHIMS[agent];
+    const canonical = resolveAgentName(agent);
+    if (canonical === undefined) {
+        throw new Error(`Unsupported agent: ${agent}`);
+    }
+    return AGENT_SHIMS[canonical];
+}
+
+function isCanonicalName(value: string): value is AgentName {
+    return Object.hasOwn(AGENT_SHIMS, value);
+}
+
+function warnDeprecatedOrAlias(input: string, canonical: AgentName): void {
+    const shim = AGENT_SHIMS[canonical];
+    if (shim.deprecated !== undefined) {
+        const replacement = shim.deprecated.replacedBy ?? canonical;
+        logger.warn(`agent '${input}' is deprecated (since ${shim.deprecated.since}); use '${replacement}'`, {
+            input,
+            canonical,
+            replacedBy: replacement,
+        });
+    } else {
+        logger.warn(`agent '${input}' is an alias; resolving to canonical '${canonical}'`, { input, canonical });
+    }
 }

package/src/ai-runner.ts

@@ -113,7 +113,9 @@ export class AiRunner {
 
     /** Build an agent prompt command without executing it. */
     buildPromptCommand(agent: AgentName, promptOptions: PromptOptions, options: AgentRunOptions = {}): ShimCommand {
-        return getAgentShim(agent).getPromptCommand(this.withIdentityPreamble(agent, promptOptions, options));
+        return buildAgentCommand(agent, promptOptions, {
+            workspace: options.cwd ?? this.defaultCwd ?? getProcessCwd(),
+        });
     }
 
     /** Run an agent authentication command, or return null when unsupported. */
@@ -164,26 +166,6 @@ export class AiRunner {
             durationMs: result.durationMs,
         };
     }
-
-    private withIdentityPreamble(
-        agent: AgentName,
-        promptOptions: PromptOptions,
-        options: AgentRunOptions,
-    ): PromptOptions {
-        if (!hasIdentityOptions(promptOptions)) return promptOptions;
-        const workspace = options.cwd ?? this.defaultCwd ?? getProcessCwd();
-        const preamble = buildIdentityPreamble({
-            agentId: agent,
-            agentType: agent,
-            workspace,
-            purpose: promptOptions.purpose,
-            systemPrompt: promptOptions.systemPrompt,
-            taskId: promptOptions.taskId,
-            peers: promptOptions.peers,
-        });
-        const input = promptOptions.input === undefined ? preamble : `${preamble}\n${promptOptions.input}`;
-        return { ...promptOptions, input };
-    }
 }
 
 function hasIdentityOptions(options: PromptOptions): boolean {
@@ -194,3 +176,36 @@ function hasIdentityOptions(options: PromptOptions): boolean {
         (options.peers !== undefined && options.peers.length > 0)
     );
 }
+
+/**
+ * Shared command-build seam: identity preamble + shim dispatch. Both the
+ * one-shot path (`AiRunner.buildPromptCommand`) and the team-mode path
+ * (`TeamOrchestrator.startAgent`) resolve argv through this single function
+ * so equivalent `PromptOptions` produce equivalent argv (R5 parity).
+ */
+export function buildAgentCommand(
+    agent: AgentName,
+    promptOptions: PromptOptions,
+    context: { workspace: string },
+): ShimCommand {
+    return getAgentShim(agent).getPromptCommand(applyIdentityPreamble(agent, promptOptions, context));
+}
+
+function applyIdentityPreamble(
+    agent: AgentName,
+    promptOptions: PromptOptions,
+    context: { workspace: string },
+): PromptOptions {
+    if (!hasIdentityOptions(promptOptions)) return promptOptions;
+    const preamble = buildIdentityPreamble({
+        agentId: agent,
+        agentType: agent,
+        workspace: context.workspace,
+        purpose: promptOptions.purpose,
+        systemPrompt: promptOptions.systemPrompt,
+        taskId: promptOptions.taskId,
+        peers: promptOptions.peers,
+    });
+    const input = promptOptions.input === undefined ? preamble : `${preamble}\n${promptOptions.input}`;
+    return { ...promptOptions, input };
+}

package/src/doctor-runner.ts

@@ -1,7 +1,7 @@
 import { getLogger, type Logger } from '@gobing-ai/ts-infra';
-import { getProcessEnv, joinPath, NodeFileSystem } from '@gobing-ai/ts-runtime';
+import { createNodeFileSystem, type FileSystem, getProcessEnv, joinPath } from '@gobing-ai/ts-runtime';
 import { AgentDetector, type DetectedAgent } from './agent-detector';
-import { type AgentName, DISPLAY_ORDER, isAgentName, TIER2_AGENTS } from './agents/shims';
+import { type AgentName, DISPLAY_ORDER, resolveAgentName, TIER2_AGENTS } from './agents/shims';
 import { type AgentRunResult, AiRunner } from './ai-runner';
 
 /** Health-check result for one coding agent. */
@@ -20,6 +20,10 @@ export interface DoctorResult {
     tier: 1 | 2;
     /** Agent-specific channels or models when available. */
     channels: string[];
+    /** True when the resolved canonical id is marked deprecated. */
+    deprecated?: boolean;
+    /** Canonical replacement when the resolved id is deprecated, if any. */
+    replacedBy?: AgentName;
     /** Probe error when unavailable. */
     error: string | null;
 }
@@ -36,6 +40,8 @@ export interface DoctorRunnerOptions {
     env?: Record<string, string | undefined>;
     /** Logger for health-check diagnostics. Defaults to `getLogger('doctor')`. */
     logger?: Logger;
+    /** Filesystem for auth-file checks. Defaults to `createNodeFileSystem()`; inject to test without disk. */
+    fileSystem?: FileSystem;
 }
 
 const DEFAULT_TIMEOUT_MS = 5_000;
@@ -61,6 +67,14 @@ const AUTH_PATTERNS: Partial<Record<AgentName, { positive: RegExp; negative: Reg
         positive: /\S/,
         negative: /not[\s_-]*authenticated|not[\s_-]*logged[\s_-]*in|unauthenticated|no[\s_-]+providers?/i,
     },
+    omp: {
+        positive: /\S/,
+        negative: /not[\s_-]*authenticated|not[\s_-]*logged[\s_-]*in|unauthenticated|no[\s_-]+providers?/i,
+    },
+    hermes: {
+        positive: /(^|[^a-z])ok([^a-z]|$)|healthy|configured|ready/i,
+        negative: /not[\s_-]*(configured|healthy|ok)|unhealthy|missing[\s_-]+dependenc|error|failed/i,
+    },
 };
 
 /** True when a value is a defined, non-blank string. */
@@ -74,7 +88,7 @@ export class DoctorRunner {
     private readonly runner: AiRunner;
     private readonly timeout: number;
     private readonly env: Record<string, string | undefined>;
-    private readonly fs = new NodeFileSystem();
+    private readonly fs: FileSystem;
     private readonly logger: Logger;
 
     constructor(options: DoctorRunnerOptions = {}) {
@@ -82,6 +96,7 @@ export class DoctorRunner {
         this.detector = options.agentDetector ?? new AgentDetector({ runner: this.runner });
         this.timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
         this.env = options.env ?? getProcessEnv();
+        this.fs = options.fileSystem ?? createNodeFileSystem();
         this.logger = options.logger ?? getLogger('doctor');
     }
 
@@ -110,10 +125,10 @@ export class DoctorRunner {
     }
 
     private async buildResult(detected: DetectedAgent): Promise<DoctorResult> {
-        const tier = TIER2_AGENTS.has(detected.name as AgentName) ? 2 : 1;
+        const canonical = resolveAgentName(detected.name) ?? null;
+        const tier = canonical !== null && TIER2_AGENTS.has(canonical) ? 2 : 1;
         this.logger.debug('checking agent', { agent: detected.name, installed: detected.installed, tier });
-        const authenticated =
-            detected.installed && isAgentName(detected.name) ? await this.checkAuth(detected.name) : false;
+        const authenticated = detected.installed && canonical !== null ? await this.checkAuth(canonical) : false;
         return {
             agent: detected.name,
             installed: detected.installed,
@@ -122,6 +137,8 @@ export class DoctorRunner {
             usable: detected.installed && detected.version !== null && authenticated,
             tier,
             channels: detected.channels,
+            deprecated: detected.deprecated,
+            replacedBy: detected.replacedBy,
             error: detected.error,
         };
     }
@@ -130,9 +147,12 @@ export class DoctorRunner {
         const home = this.env.HOME || this.env.USERPROFILE || '';
         if (agent === 'gemini') return this.geminiSettingsContainCredentials(home);
         if (agent === 'codex') return this.checkCodexAuth(home);
-        // pi reads provider keys from the environment; require a non-empty value
-        // rather than mere presence (an empty export is not a usable credential).
-        if (agent === 'pi' && (isNonEmpty(this.env.GOOGLE_API_KEY) || isNonEmpty(this.env.ANTHROPIC_API_KEY)))
+        // pi and omp read provider keys from the environment; require a non-empty
+        // value rather than mere presence (an empty export is not a usable credential).
+        if (
+            (agent === 'pi' || agent === 'omp') &&
+            (isNonEmpty(this.env.GOOGLE_API_KEY) || isNonEmpty(this.env.ANTHROPIC_API_KEY))
+        )
             return true;
         return (await this.probeAuthOutput(agent)) === true;
     }

package/src/slash-command.ts

@@ -35,6 +35,7 @@ export function translateSlashCommand(agent: AgentName, input: string): string {
         case 'codex':
             return `$${plugin}-${command}${suffix}`;
         case 'pi':
+        case 'omp':
             return `/skill:${plugin}-${command}${suffix}`;
         default:
             return `/${plugin}-${command}${suffix}`;

package/src/team-orchestrator.ts

@@ -2,9 +2,9 @@ import type { InboxMessageDao } from '@gobing-ai/ts-db/inbox';
 import { EventBus } from '@gobing-ai/ts-infra';
 import type { AgentSpec } from './agent-spec';
 import { loadAgentSpecs } from './agent-spec';
-import { type AgentName, getAgentShim, isAgentName } from './agents/shims';
+import { type AgentName, resolveAgentName } from './agents/shims';
+import { buildAgentCommand } from './ai-runner';
 import type { AgentEvents } from './events';
-import { buildIdentityPreamble } from './identity';
 import { formatMessage } from './messages';
 import { TeamAgentProcess } from './team-agent-process';
 
@@ -35,38 +35,33 @@ export class TeamOrchestrator {
         this.events = options.events ?? new EventBus<AgentEvents>();
     }
 
-    loadSpecs(): AgentSpec[] {
-        this.specs = loadAgentSpecs(this.configDir);
+    async loadSpecs(): Promise<AgentSpec[]> {
+        this.specs = await loadAgentSpecs(this.configDir);
         return [...this.specs];
     }
 
-    getSpec(id: string): AgentSpec | undefined {
-        if (this.specs.length === 0) this.loadSpecs();
+    async getSpec(id: string): Promise<AgentSpec | undefined> {
+        if (this.specs.length === 0) await this.loadSpecs();
         return this.specs.find((spec) => spec.id === id);
     }
 
     async startAgent(id: string): Promise<TeamAgentProcess> {
-        const spec = this.requireSpec(id);
+        const spec = await this.requireSpec(id);
         const agentType = this.requireAgentName(spec.type);
-        const peers = this.getPeerSpecs(spec.workspace, spec.id).map((peer) => ({
+        const peers = (await this.getPeerSpecs(spec.workspace, spec.id)).map((peer) => ({
             id: peer.id,
             type: peer.type,
             purpose: peer.purpose,
         }));
-        const identityPreamble = buildIdentityPreamble({
-            agentId: spec.id,
-            agentType: spec.type,
-            workspace: spec.workspace,
-            purpose: spec.purpose,
-            systemPrompt: typeof spec.config.systemPrompt === 'string' ? spec.config.systemPrompt : undefined,
-            peers,
-        });
-        const command = getAgentShim(agentType).getPromptCommand({
-            input: identityPreamble,
-            purpose: spec.purpose,
-            systemPrompt: typeof spec.config.systemPrompt === 'string' ? spec.config.systemPrompt : undefined,
-            peers,
-        });
+        const command = buildAgentCommand(
+            agentType,
+            {
+                purpose: spec.purpose,
+                systemPrompt: typeof spec.config.systemPrompt === 'string' ? spec.config.systemPrompt : undefined,
+                peers,
+            },
+            { workspace: spec.workspace },
+        );
         const process = this.processFactory({
             spec,
             command: [command.command, ...command.args],
@@ -108,14 +103,14 @@ export class TeamOrchestrator {
         return new Map(this.running);
     }
 
-    getAgentStatus(id: string): 'running' | 'stopped' | 'errored' | 'unknown' {
+    async getAgentStatus(id: string): Promise<'running' | 'stopped' | 'errored' | 'unknown'> {
         const process = this.running.get(id);
-        if (process === undefined) return this.getSpec(id) === undefined ? 'unknown' : 'stopped';
+        if (process === undefined) return (await this.getSpec(id)) === undefined ? 'unknown' : 'stopped';
         return process.getStatus();
     }
 
-    getPeerSpecs(workspace: string, excludeId?: string): AgentSpec[] {
-        if (this.specs.length === 0) this.loadSpecs();
+    async getPeerSpecs(workspace: string, excludeId?: string): Promise<AgentSpec[]> {
+        if (this.specs.length === 0) await this.loadSpecs();
         return this.specs.filter((spec) => spec.workspace === workspace && spec.id !== excludeId);
     }
 
@@ -128,15 +123,16 @@ export class TeamOrchestrator {
         return () => this.events.off(event, listener);
     }
 
-    private requireSpec(id: string): AgentSpec {
-        const spec = this.getSpec(id);
+    private async requireSpec(id: string): Promise<AgentSpec> {
+        const spec = await this.getSpec(id);
         if (spec === undefined) throw new Error(`Agent spec not found: ${id}`);
         return spec;
     }
 
     private requireAgentName(type: string): AgentName {
-        if (!isAgentName(type)) throw new Error(`Unsupported agent type: ${type}`);
-        return type;
+        const canonical = resolveAgentName(type);
+        if (canonical === undefined) throw new Error(`Unsupported agent type: ${type}`);
+        return canonical;
     }
 
     private async injectPendingMessages(process: TeamAgentProcess): Promise<boolean> {