opencode-dux 1.0.0

package/src/utils/agent-variant.test.ts

@@ -0,0 +1,244 @@
+import { describe, expect, test } from 'bun:test';
+import type { PluginConfig } from '../config';
+import {
+  applyAgentVariant,
+  normalizeAgentName,
+  resolveAgentVariant,
+  resolveRuntimeAgentName,
+  rewriteDisplayNameMentions,
+} from './agent-variant';
+
+describe('normalizeAgentName', () => {
+  test('returns name unchanged if no @ prefix', () => {
+    expect(normalizeAgentName('oracle')).toBe('oracle');
+  });
+
+  test('strips @ prefix from agent name', () => {
+    expect(normalizeAgentName('@oracle')).toBe('oracle');
+  });
+
+  test('trims whitespace', () => {
+    expect(normalizeAgentName('  oracle  ')).toBe('oracle');
+  });
+
+  test('handles @ prefix with whitespace', () => {
+    expect(normalizeAgentName('  @explore  ')).toBe('explore');
+  });
+
+  test('handles empty string', () => {
+    expect(normalizeAgentName('')).toBe('');
+  });
+});
+
+describe('resolveAgentVariant', () => {
+  test('returns undefined when config is undefined', () => {
+    expect(resolveAgentVariant(undefined, 'oracle')).toBeUndefined();
+  });
+
+  test('returns undefined when agents is undefined', () => {
+    const config = {} as PluginConfig;
+    expect(resolveAgentVariant(config, 'oracle')).toBeUndefined();
+  });
+
+  test('returns undefined when agent has no variant', () => {
+    const config = {
+      agents: {
+        oracle: { model: 'gpt-4' },
+      },
+    } as PluginConfig;
+    expect(resolveAgentVariant(config, 'oracle')).toBeUndefined();
+  });
+
+  test('returns variant when configured', () => {
+    const config = {
+      agents: {
+        oracle: { variant: 'high' },
+      },
+    } as PluginConfig;
+    expect(resolveAgentVariant(config, 'oracle')).toBe('high');
+  });
+
+  test('normalizes agent name with @ prefix', () => {
+    const config = {
+      agents: {
+        oracle: { variant: 'low' },
+      },
+    } as PluginConfig;
+    expect(resolveAgentVariant(config, '@oracle')).toBe('low');
+  });
+
+  test('returns undefined for empty string variant', () => {
+    const config = {
+      agents: {
+        oracle: { variant: '' },
+      },
+    } as PluginConfig;
+    expect(resolveAgentVariant(config, 'oracle')).toBeUndefined();
+  });
+
+  test('returns undefined for whitespace-only variant', () => {
+    const config = {
+      agents: {
+        oracle: { variant: '   ' },
+      },
+    } as PluginConfig;
+    expect(resolveAgentVariant(config, 'oracle')).toBeUndefined();
+  });
+
+  test('trims variant whitespace', () => {
+    const config = {
+      agents: {
+        oracle: { variant: '  medium  ' },
+      },
+    } as PluginConfig;
+    expect(resolveAgentVariant(config, 'oracle')).toBe('medium');
+  });
+
+  test('returns undefined for non-string variant', () => {
+    const config = {
+      agents: {
+        oracle: { variant: 123 as unknown as string },
+      },
+    } as PluginConfig;
+    expect(resolveAgentVariant(config, 'oracle')).toBeUndefined();
+  });
+
+  test('resolves displayName alias to internal agent for variant lookup', () => {
+    const config = {
+      agents: {
+        oracle: { displayName: 'advisor', variant: 'high' },
+      },
+    } as PluginConfig;
+    expect(resolveAgentVariant(config, '@advisor')).toBe('high');
+  });
+});
+
+describe('resolveRuntimeAgentName', () => {
+  test('keeps internal agent names unchanged', () => {
+    const config = {
+      agents: {
+        oracle: { displayName: 'advisor' },
+      },
+    } as PluginConfig;
+
+    expect(resolveRuntimeAgentName(config, 'oracle')).toBe('oracle');
+  });
+
+  test('resolves displayName to internal name', () => {
+    const config = {
+      agents: {
+        oracle: { displayName: 'advisor' },
+      },
+    } as PluginConfig;
+
+    expect(resolveRuntimeAgentName(config, 'advisor')).toBe('oracle');
+  });
+
+  test('resolves displayName with @ prefix and whitespace', () => {
+    const config = {
+      agents: {
+        oracle: { displayName: 'advisor' },
+      },
+    } as PluginConfig;
+
+    expect(resolveRuntimeAgentName(config, '  @advisor  ')).toBe('oracle');
+  });
+
+  test('resolves displayName configured via legacy alias key', () => {
+    const config = {
+      agents: {
+        explore: { displayName: 'researcher' },
+      },
+    } as PluginConfig;
+
+    expect(resolveRuntimeAgentName(config, 'researcher')).toBe('explorer');
+  });
+
+  test('returns normalized name when no displayName match exists', () => {
+    const config = {
+      agents: {
+        oracle: { displayName: 'advisor' },
+      },
+    } as PluginConfig;
+
+    expect(resolveRuntimeAgentName(config, '  @unknown  ')).toBe('unknown');
+  });
+});
+
+describe('rewriteDisplayNameMentions', () => {
+  test('rewrites displayName mentions to internal names for direct invocation', () => {
+    const config = {
+      agents: {
+        oracle: { displayName: 'advisor' },
+      },
+    } as PluginConfig;
+
+    expect(rewriteDisplayNameMentions(config, 'ask @advisor about this')).toBe(
+      'ask @oracle about this',
+    );
+  });
+
+  test('keeps internal mentions working while rewriting aliases', () => {
+    const config = {
+      agents: {
+        oracle: { displayName: 'advisor' },
+      },
+    } as PluginConfig;
+
+    expect(
+      rewriteDisplayNameMentions(config, 'compare @advisor with @oracle'),
+    ).toBe('compare @oracle with @oracle');
+  });
+
+  test('does not rewrite embedded text such as email addresses', () => {
+    const config = {
+      agents: {
+        oracle: { displayName: 'advisor' },
+      },
+    } as PluginConfig;
+
+    expect(
+      rewriteDisplayNameMentions(
+        config,
+        'email foo@advisor.com and ask @advisor directly',
+      ),
+    ).toBe('email foo@advisor.com and ask @oracle directly');
+  });
+});
+
+describe('applyAgentVariant', () => {
+  test('returns body unchanged when variant is undefined', () => {
+    const body = { agent: 'oracle', parts: [] };
+    const result = applyAgentVariant(undefined, body);
+    expect(result).toEqual(body);
+    expect(result).toBe(body); // Same reference
+  });
+
+  test('returns body unchanged when body already has variant', () => {
+    const body = { agent: 'oracle', variant: 'medium', parts: [] };
+    const result = applyAgentVariant('high', body);
+    expect(result.variant).toBe('medium');
+    expect(result).toBe(body); // Same reference
+  });
+
+  test('applies variant to body without variant', () => {
+    const body = { agent: 'oracle', parts: [] };
+    const result = applyAgentVariant('high', body);
+    expect(result.variant).toBe('high');
+    expect(result.agent).toBe('oracle');
+    expect(result).not.toBe(body); // New object
+  });
+
+  test('preserves all existing body properties', () => {
+    const body = {
+      agent: 'oracle',
+      parts: [{ type: 'text' as const, text: 'hello' }],
+      tools: { task: false },
+    };
+    const result = applyAgentVariant('low', body);
+    expect(result.agent).toBe('oracle');
+    expect(result.parts).toEqual([{ type: 'text', text: 'hello' }]);
+    expect(result.tools).toEqual({ task: false });
+    expect(result.variant).toBe('low');
+  });
+});

package/src/utils/agent-variant.ts

@@ -0,0 +1,187 @@
+import {
+  ALL_AGENT_NAMES,
+  getAgentOverride,
+  type PluginConfig,
+} from '../config';
+import { log } from './logger';
+
+/**
+ * Normalizes an agent name by trimming whitespace and removing the optional @ prefix.
+ *
+ * @param agentName - The agent name to normalize (e.g., "@oracle" or "oracle")
+ * @returns The normalized agent name without @ prefix and trimmed of whitespace
+ *
+ * @example
+ * normalizeAgentName("@oracle") // returns "oracle"
+ * normalizeAgentName("  explore  ") // returns "explore"
+ */
+export function normalizeAgentName(agentName: string): string {
+  const trimmed = agentName.trim();
+  return trimmed.startsWith('@') ? trimmed.slice(1) : trimmed;
+}
+
+function getRuntimeAgentNames(_config?: PluginConfig): string[] {
+  return [...ALL_AGENT_NAMES];
+}
+
+/**
+ * Resolves the variant configuration for a specific agent.
+ *
+ * Looks up the agent's variant in the plugin configuration. Returns undefined if:
+ * - No config is provided
+ * - The agent has no variant configured
+ * - The variant is not a string
+ * - The variant is empty or whitespace-only
+ *
+ * @param config - The plugin configuration object
+ * @param agentName - The name of the agent (with or without @ prefix)
+ * @returns The trimmed variant string, or undefined if no valid variant is found
+ *
+ * @example
+ * resolveAgentVariant(config, "@oracle") // returns "high" if configured
+ */
+export function resolveAgentVariant(
+  config: PluginConfig | undefined,
+  agentName: string,
+): string | undefined {
+  const normalized = resolveRuntimeAgentName(config, agentName);
+  const rawVariant = getAgentOverride(config, normalized)?.variant;
+
+  if (typeof rawVariant !== 'string') {
+    return undefined;
+  }
+
+  const trimmed = rawVariant.trim();
+  if (trimmed.length === 0) {
+    return undefined;
+  }
+
+  log(`[variant] resolved variant="${trimmed}" for agent "${normalized}"`);
+  return trimmed;
+}
+
+/**
+ * Resolve a runtime-provided agent name to an internal agent name.
+ *
+ * Supports:
+ * - internal names (e.g. "oracle")
+ * - @-prefixed names (e.g. "@oracle")
+ * - displayName aliases (e.g. "advisor" -> "oracle")
+ */
+export function resolveRuntimeAgentName(
+  config: PluginConfig | undefined,
+  agentName: string,
+): string {
+  const normalized = normalizeAgentName(agentName);
+  if (!normalized) {
+    return normalized;
+  }
+
+  if ((ALL_AGENT_NAMES as readonly string[]).includes(normalized)) {
+    return normalized;
+  }
+
+  for (const internalName of getRuntimeAgentNames(config)) {
+    const displayName = getAgentOverride(config, internalName)?.displayName;
+    if (!displayName) {
+      continue;
+    }
+
+    if (normalizeAgentName(displayName) === normalized) {
+      return internalName;
+    }
+  }
+
+  return normalized;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export type DisplayNameMentionRewriter = (text: string) => string;
+
+export function createDisplayNameMentionRewriter(
+  config: PluginConfig | undefined,
+): DisplayNameMentionRewriter {
+  const replacements: Array<{ regex: RegExp; internalName: string }> = [];
+
+  for (const internalName of getRuntimeAgentNames(config)) {
+    const displayName = getAgentOverride(config, internalName)?.displayName;
+    if (!displayName) {
+      continue;
+    }
+
+    const normalizedDisplayName = normalizeAgentName(displayName);
+    if (!normalizedDisplayName || normalizedDisplayName === internalName) {
+      continue;
+    }
+
+    replacements.push({
+      regex: new RegExp(
+        `(^|[^\\w.])@${escapeRegExp(normalizedDisplayName)}\\b`,
+        'g',
+      ),
+      internalName,
+    });
+  }
+
+  if (replacements.length === 0) {
+    return (text) => text;
+  }
+
+  return (text) => {
+    if (!text.includes('@')) {
+      return text;
+    }
+
+    let rewritten = text;
+    for (const replacement of replacements) {
+      rewritten = rewritten.replace(
+        replacement.regex,
+        `$1@${replacement.internalName}`,
+      );
+    }
+
+    return rewritten;
+  };
+}
+
+/**
+ * Rewrites user-facing display-name mentions (e.g. @advisor) into internal
+ * agent mentions (e.g. @oracle) for runtime routing.
+ */
+export function rewriteDisplayNameMentions(
+  config: PluginConfig | undefined,
+  text: string,
+): string {
+  return createDisplayNameMentionRewriter(config)(text);
+}
+
+/**
+ * Applies a variant to a request body if the body doesn't already have one.
+ *
+ * This function will NOT override an existing variant in the body. If no variant
+ * is provided or the body already has a variant, the original body is returned.
+ *
+ * @template T - The type of the body object, must have an optional variant property
+ * @param variant - The variant string to apply (or undefined)
+ * @param body - The request body object
+ * @returns The body with the variant applied (new object) or the original body unchanged
+ *
+ * @example
+ * applyAgentVariant("high", { agent: "oracle" }) // returns { agent: "oracle", variant: "high" }
+ * applyAgentVariant("high", { agent: "oracle", variant: "low" }) // returns original body with variant: "low"
+ */
+export function applyAgentVariant<T extends { variant?: string }>(
+  variant: string | undefined,
+  body: T,
+): T {
+  if (!variant) {
+    return body;
+  }
+  if (body.variant) {
+    return body;
+  }
+  return { ...body, variant };
+}

package/src/utils/compat.ts

@@ -0,0 +1,91 @@
+import type { ChildProcess } from 'node:child_process';
+import { spawn as nodeSpawn } from 'node:child_process';
+import { writeFile as fsWriteFile } from 'node:fs/promises';
+
+export const isBun = typeof globalThis.Bun !== 'undefined';
+
+export interface CrossSpawnResult {
+  proc: ChildProcess;
+  /** Collects all stdout into a string */
+  stdout: () => Promise<string>;
+  /** Collects all stderr into a string */
+  stderr: () => Promise<string>;
+  /** Resolves when process exits with exit code */
+  exited: Promise<number>;
+  /** Kill the process */
+  kill: (signal?: NodeJS.Signals | number) => boolean;
+  /** Current exit code or null if running */
+  get exitCode(): number | null;
+}
+
+function collectStream(
+  stream: NodeJS.ReadableStream | null,
+): () => Promise<string> {
+  if (!stream) return () => Promise.resolve('');
+  const chunks: Buffer[] = [];
+  stream.on('data', (chunk: Buffer) => chunks.push(chunk));
+  return () =>
+    new Promise<string>((resolve, reject) => {
+      if (!stream.readable) {
+        resolve(Buffer.concat(chunks).toString('utf-8'));
+        return;
+      }
+      stream.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+      stream.on('error', reject);
+    });
+}
+
+/**
+ * Cross-runtime spawn that works in both Bun and Node.js.
+ * API mimics Bun.spawn but uses node:child_process internally.
+ */
+export function crossSpawn(
+  command: string[],
+  options?: {
+    stdout?: 'pipe' | 'inherit' | 'ignore';
+    stderr?: 'pipe' | 'inherit' | 'ignore';
+    stdin?: 'pipe' | 'inherit' | 'ignore';
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+  },
+): CrossSpawnResult {
+  const [cmd, ...args] = command;
+  const proc = nodeSpawn(cmd, args, {
+    stdio: [
+      options?.stdin ?? 'ignore',
+      options?.stdout ?? 'pipe',
+      options?.stderr ?? 'pipe',
+    ],
+    cwd: options?.cwd,
+    env: options?.env as NodeJS.ProcessEnv,
+  });
+
+  const stdoutCollector = collectStream(proc.stdout);
+  const stderrCollector = collectStream(proc.stderr);
+
+  const exited = new Promise<number>((resolve, reject) => {
+    proc.on('error', reject);
+    proc.on('close', (code) => resolve(code ?? 1));
+  });
+
+  return {
+    proc,
+    stdout: stdoutCollector,
+    stderr: stderrCollector,
+    exited,
+    kill: (signal) => proc.kill(signal as NodeJS.Signals),
+    get exitCode() {
+      return proc.exitCode;
+    },
+  };
+}
+
+/**
+ * Cross-runtime file write that works in both Bun and Node.js.
+ */
+export async function crossWrite(
+  path: string,
+  data: ArrayBuffer | Buffer | string,
+): Promise<void> {
+  await fsWriteFile(path, Buffer.from(data as ArrayBuffer));
+}

package/src/utils/env.ts

@@ -0,0 +1,12 @@
+export function getEnv(name: string): string | undefined {
+  const bunValue = (globalThis as { Bun?: { env?: Record<string, string> } })
+    .Bun?.env?.[name];
+  if (typeof bunValue === 'string' && bunValue.length > 0) return bunValue;
+
+  const processValue = (
+    globalThis as { process?: { env?: Record<string, string | undefined> } }
+  ).process?.env?.[name];
+  return typeof processValue === 'string' && processValue.length > 0
+    ? processValue
+    : undefined;
+}

package/src/utils/index.ts

@@ -0,0 +1,9 @@
+export * from './agent-variant';
+export * from './env';
+export * from './internal-initiator';
+export { getLogDir, initLogger, log, resetLogger } from './logger';
+export * from './polling';
+export * from './session';
+export * from './session-manager';
+export * from './task';
+export { extractZip } from './zip-extractor';

package/src/utils/internal-initiator.ts

@@ -0,0 +1,28 @@
+export const SLIM_INTERNAL_INITIATOR_MARKER =
+  '<!-- SLIM_INTERNAL_INITIATOR -->';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+export function createInternalAgentTextPart(text: string): {
+  type: 'text';
+  text: string;
+} {
+  return {
+    type: 'text',
+    text: `${text}\n${SLIM_INTERNAL_INITIATOR_MARKER}`,
+  };
+}
+
+export function hasInternalInitiatorMarker(part: unknown): boolean {
+  if (!isRecord(part) || part.type !== 'text') {
+    return false;
+  }
+
+  if (typeof part.text !== 'string') {
+    return false;
+  }
+
+  return part.text.includes(SLIM_INTERNAL_INITIATOR_MARKER);
+}