opencode-dux 1.0.0

package/src/config/schema.ts

@@ -0,0 +1,248 @@
+import { z } from 'zod';
+
+const FALLBACK_AGENT_NAMES = [
+  'orchestrator',
+  'oracle',
+  'designer',
+  'explorer',
+  'librarian',
+  'fixer',
+  'steward',
+  'interpreter',
+] as const;
+
+const MANUAL_AGENT_NAMES = [
+  'orchestrator',
+  'oracle',
+  'designer',
+  'explorer',
+  'librarian',
+  'fixer',
+] as const;
+
+export const ProviderModelIdSchema = z
+  .string()
+  .regex(
+    /^[^/\s]+\/[^\s]+$/,
+    'Expected provider/model format (provider/.../model)',
+  );
+
+export const ManualAgentPlanSchema = z
+  .object({
+    primary: ProviderModelIdSchema,
+    fallback1: ProviderModelIdSchema,
+    fallback2: ProviderModelIdSchema,
+    fallback3: ProviderModelIdSchema,
+  })
+  .superRefine((value, ctx) => {
+    const unique = new Set([
+      value.primary,
+      value.fallback1,
+      value.fallback2,
+      value.fallback3,
+    ]);
+    if (unique.size !== 4) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: 'primary and fallbacks must be unique per agent',
+      });
+    }
+  });
+
+export const ManualPlanSchema = z
+  .object({
+    orchestrator: ManualAgentPlanSchema,
+    oracle: ManualAgentPlanSchema,
+    designer: ManualAgentPlanSchema,
+    explorer: ManualAgentPlanSchema,
+    librarian: ManualAgentPlanSchema,
+    fixer: ManualAgentPlanSchema,
+  })
+  .strict();
+
+export type ManualAgentName = (typeof MANUAL_AGENT_NAMES)[number];
+export type ManualAgentPlan = z.infer<typeof ManualAgentPlanSchema>;
+export type ManualPlan = z.infer<typeof ManualPlanSchema>;
+
+const AgentModelChainSchema = z.array(z.string()).min(1);
+
+const FallbackChainsSchema = z
+  .object({
+    orchestrator: AgentModelChainSchema.optional(),
+    oracle: AgentModelChainSchema.optional(),
+    designer: AgentModelChainSchema.optional(),
+    explorer: AgentModelChainSchema.optional(),
+    librarian: AgentModelChainSchema.optional(),
+    fixer: AgentModelChainSchema.optional(),
+    steward: AgentModelChainSchema.optional(),
+    interpreter: AgentModelChainSchema.optional(),
+  })
+  .catchall(AgentModelChainSchema);
+
+export type FallbackAgentName = (typeof FALLBACK_AGENT_NAMES)[number];
+
+const SkillOrMcpConfigSchema = z.union([
+  z.array(z.string()),
+  z.object({
+    'always-load': z.array(z.string()).optional(),
+    mandatory: z.array(z.string()).optional(), // DEPRECATED - remove in next release
+    wildcard: z.boolean().optional(),
+  }),
+]);
+
+// Agent override configuration (distinct from SDK's AgentConfig)
+export const AgentOverrideConfigSchema = z
+  .object({
+    model: z
+      .union([
+        z.string(),
+        z
+          .array(
+            z.union([
+              z.string(),
+              z.object({
+                id: z.string(),
+                variant: z.string().optional(),
+              }),
+            ]),
+          )
+          .min(1),
+      ])
+      .optional(),
+    temperature: z.number().min(0).max(2).optional(),
+    variant: z.string().optional().catch(undefined),
+    options: z.record(z.string(), z.unknown()).optional(), // provider-specific model options (e.g., textVerbosity, thinking budget)
+    displayName: z.string().min(1).optional(),
+    skills: SkillOrMcpConfigSchema.optional(), // skills this agent can use ("*" = all, "!item" = exclude)
+    mcps: SkillOrMcpConfigSchema.optional(), // MCPs this agent can use (same syntax as skills)
+  })
+  .strict();
+
+export type AgentOverrideConfig = z.infer<typeof AgentOverrideConfigSchema>;
+
+/** Normalized model entry with optional per-model variant. */
+export type ModelEntry = { id: string; variant?: string };
+
+export const PresetSchema = z.record(z.string(), AgentOverrideConfigSchema);
+
+export type Preset = z.infer<typeof PresetSchema>;
+
+// Websearch provider configuration
+export const WebsearchConfigSchema = z.object({
+  provider: z.enum(['exa', 'tavily']).default('exa'),
+});
+export type WebsearchConfig = z.infer<typeof WebsearchConfigSchema>;
+
+// MCP names
+export const McpNameSchema = z.enum(['websearch', 'context7', 'grep_app']);
+export type McpName = z.infer<typeof McpNameSchema>;
+
+export const SessionManagerConfigSchema = z.object({
+  maxSessionsPerAgent: z.number().int().min(1).max(10).default(2),
+  readContextMinLines: z.number().int().min(0).max(1000).default(10),
+  readContextMaxFiles: z.number().int().min(0).max(50).default(8),
+});
+
+export type SessionManagerConfig = z.infer<typeof SessionManagerConfigSchema>;
+
+// Todo continuation configuration
+export const TodoContinuationConfigSchema = z.object({
+  maxContinuations: z
+    .number()
+    .int()
+    .min(1)
+    .max(50)
+    .default(5)
+    .describe(
+      'Maximum consecutive auto-continuations before stopping to ask user',
+    ),
+  cooldownMs: z
+    .number()
+    .int()
+    .min(0)
+    .max(30_000)
+    .default(3000)
+    .describe('Delay in ms before auto-continuing (gives user time to abort)'),
+  autoEnable: z
+    .boolean()
+    .default(false)
+    .describe(
+      'Automatically enable auto-continue when the orchestrator session has enough todos',
+    ),
+  autoEnableThreshold: z
+    .number()
+    .int()
+    .min(1)
+    .max(50)
+    .default(4)
+    .describe(
+      'Number of todos that triggers auto-enable (only used when autoEnable is true)',
+    ),
+});
+
+export type TodoContinuationConfig = z.infer<
+  typeof TodoContinuationConfigSchema
+>;
+
+export const ContextPressureConfigSchema = z.object({
+  enabled: z
+    .boolean()
+    .default(true)
+    .describe(
+      'When true, warn the orchestrator on high context usage before the model fails.',
+    ),
+  warnThresholdPct: z
+    .number()
+    .min(1)
+    .max(99)
+    .default(75)
+    .describe(
+      'Inject a /compact reminder when context (used ÷ limit) is at least this percent.',
+    ),
+});
+
+export type ContextPressureConfig = z.infer<typeof ContextPressureConfigSchema>;
+
+export const FailoverConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  timeoutMs: z.number().min(0).default(15000),
+  retryDelayMs: z.number().min(0).default(500),
+  chains: FallbackChainsSchema.default({}),
+  retry_on_empty: z
+    .boolean()
+    .default(true)
+    .describe(
+      'When true (default), empty provider responses are treated as failures, ' +
+        'triggering fallback/retry. Set to false to treat them as successes.',
+    ),
+});
+
+export type FailoverConfig = z.infer<typeof FailoverConfigSchema>;
+
+export const PluginConfigSchema = z.object({
+  preset: z.string().optional(),
+  setDefaultAgent: z.boolean().optional(),
+  scoringEngineVersion: z.enum(['v1', 'v2-shadow', 'v2']).optional(),
+  balanceProviderUsage: z.boolean().optional(),
+  autoUpdate: z
+    .boolean()
+    .optional()
+    .describe(
+      'Disable automatic installation of plugin updates when false. Defaults to true.',
+    ),
+  manualPlan: ManualPlanSchema.optional(),
+  presets: z.record(z.string(), PresetSchema).optional(),
+  agents: z.record(z.string(), AgentOverrideConfigSchema).optional(),
+  websearch: WebsearchConfigSchema.optional(),
+  sessionManager: SessionManagerConfigSchema.optional(),
+  todoContinuation: TodoContinuationConfigSchema.optional(),
+  contextPressure: ContextPressureConfigSchema.optional(),
+  fallback: FailoverConfigSchema.optional(),
+});
+
+export type PluginConfig = z.infer<typeof PluginConfigSchema>;
+
+// Agent names - re-exported from constants for convenience
+export type { AgentName } from './constants';
+
+export type SkillOrMcpConfig = z.infer<typeof SkillOrMcpConfigSchema>;

package/src/config/utils.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, test } from 'bun:test';
+import type { PluginConfig } from './schema';
+import { getAgentOverride } from './utils';
+
+describe('getAgentOverride', () => {
+  test('reads override by explicit custom agent key', () => {
+    const config = {
+      agents: {
+        'custom-reviewer': { model: 'openai/gpt-5.4-mini' },
+      },
+    } as PluginConfig;
+
+    const override = getAgentOverride(config, 'custom-reviewer');
+
+    expect(override).toBeDefined();
+    expect(override?.model).toBe('openai/gpt-5.4-mini');
+  });
+
+  test('reads override from legacy alias when mapped', () => {
+    const config = {
+      agents: {
+        explore: { model: 'openai/gpt-5.4-mini' },
+      },
+    } as PluginConfig;
+
+    const override = getAgentOverride(config, 'explorer');
+
+    expect(override).toBeDefined();
+    expect(override?.model).toBe('openai/gpt-5.4-mini');
+  });
+
+  test('returns undefined when no override exists', () => {
+    const config = {
+      agents: {
+        explorer: { model: 'openai/gpt-5.4-mini' },
+      },
+    } as PluginConfig;
+
+    expect(getAgentOverride(config, 'no-such-agent')).toBeUndefined();
+  });
+});

package/src/config/utils.ts

@@ -0,0 +1,23 @@
+import { AGENT_ALIASES } from './constants';
+import type { AgentOverrideConfig, PluginConfig } from './schema';
+
+/**
+ * Get agent override config by name, supporting backward-compatible aliases.
+ * Checks both the current name and any legacy alias names.
+ *
+ * @param config - The plugin configuration
+ * @param name - The current agent name
+ * @returns The agent-specific override configuration if found
+ */
+export function getAgentOverride(
+  config: PluginConfig | undefined,
+  name: string,
+): AgentOverrideConfig | undefined {
+  const overrides = config?.agents ?? {};
+  return (
+    overrides[name] ??
+    overrides[
+      Object.keys(AGENT_ALIASES).find((k) => AGENT_ALIASES[k] === name) ?? ''
+    ]
+  );
+}

package/src/discovery/local/types.ts

@@ -0,0 +1,85 @@
+/**
+ * Type definitions for the discovery module.
+ *
+ * These types describe MCP servers and skills discovered from local
+ * filesystem sources (node_modules, skill directories, etc.).
+ *
+ * @module
+ */
+
+/**
+ * An MCP server discovered from a local source (e.g., node_modules).
+ */
+export interface DiscoveredMcp {
+  /** Unique name used as the config key (e.g., 'server-github'). */
+  name: string;
+  /** Command to launch the MCP server (e.g., `['npx', '@org/mcp-server']`). */
+  command: string[];
+  /** Human-readable description of what this MCP provides. */
+  description?: string;
+  /** Categorization tags (e.g., 'browser', 'github', 'filesystem'). */
+  tags: string[];
+  /** Source identifier indicating where this was found (e.g., 'node_modules'). */
+  source: string;
+  /** Absolute path to the package.json that defined this MCP. */
+  packageJsonPath: string;
+  /** Version from the package.json, if available. */
+  version?: string;
+}
+
+/**
+ * A skill discovered from a local source (skill directory, plugin root, etc.).
+ */
+export interface DiscoveredSkill {
+  /** Unique skill name (derived from folder name). */
+  name: string;
+  /** Human-readable description. */
+  description: string;
+  /** Absolute path to the SKILL.md file. */
+  path: string;
+  /** Tags for categorisation and matching. */
+  tags: string[];
+  /** Agents that are recommended to use this skill. */
+  recommendedAgents: string[];
+  /** Source identifier (e.g., 'plugin', 'user-skills-dir'). */
+  source: string;
+  /** Version of the skill, if available. */
+  version?: string;
+}
+
+/**
+ * Complete result of a local discovery scan.
+ */
+export interface LocalDiscoveryResult {
+  /** Discovered MCP servers. */
+  mcps: DiscoveredMcp[];
+  /** Discovered skills. */
+  skills: DiscoveredSkill[];
+  /** ISO timestamp when the scan was performed. */
+  scannedAt: string;
+  /** How long the scan took in milliseconds. */
+  scanDurationMs: number;
+}
+
+/**
+ * Options to control the behaviour of a local discovery scan.
+ */
+export interface ScanOptions {
+  /**
+   * Additional directories to scan for skills (absolute paths).
+   * Skills are discovered from each directory using the same SKILL.md
+   * convention as the plugin's built-in skills.
+   */
+  userSkillsDirs?: string[];
+
+  /**
+   * If true, skip scanning node_modules for MCP servers.
+   * Useful when the caller only needs skill discovery.
+   */
+  skipNodeModules?: boolean;
+
+  /**
+   * If true, bypass the module-level cache and force a fresh scan.
+   */
+  forceRefresh?: boolean;
+}