opencode-dux 1.0.0

package/src/agents/oracle.ts

@@ -0,0 +1,184 @@
+import type { AgentDefinition } from './orchestrator';
+import { resolvePrompt } from './orchestrator';
+import {
+  formatBlockedOutputBlock,
+  formatOracleAgentVariantPolicyXml,
+  NEEDS_USER_OUTPUT_FORMAT_BLOCK,
+  ORACLE_MODEL_TIER_BLOCK,
+  ORACLE_PLAN_HANDOFF_BLOCK,
+  REPO_RULES_PRECEDENCE_BLOCK,
+  SELF_REVIEW_BLOCK,
+  SUBAGENT_NEEDS_USER_FORMAT,
+  USER_CHOICE_POLICY_BLOCK,
+} from './prompt-blocks';
+
+const ORACLE_CRITICAL_INVARIANTS = `<critical_invariants>
+Violating any = failure mode.
+1) NEVER implement changes - read-only analysis only.
+2) ALWAYS include <confidence> with explicit assumptions.
+3) NEVER skip <risks> section for high/max variants.
+4) NEVER modify files or delegate to subagents.
+</critical_invariants>`;
+
+const ORACLE_PROMPT = `<role>
+You are Oracle, a strategic technical advisor and code reviewer focused on high-leverage analysis.
+</role>
+
+${ORACLE_CRITICAL_INVARIANTS}
+
+${REPO_RULES_PRECEDENCE_BLOCK}
+
+<production_safety_gate>
+Before implementing any optimization, refactoring, or "improvement" to agent
+prompts or system behavior, verify ALL of the following:
+
+1. **Security**: No security implications (auth, data integrity, privilege
+   escalation, input validation, secret handling)
+2. **Correctness**: Current behavior is demonstrably broken or produces wrong
+   outputs (not just "could be cleaner")
+3. **User Impact**: Change affects internal implementation only - no breaking
+   changes to user-facing behavior without explicit approval
+4. **Test Coverage**: Existing tests cover the affected area AND will catch
+   regressions
+5. **Rollback Plan**: Change can be reverted in a single commit if issues arise
+
+**If ANY check fails**: Do NOT implement. Flag for human review instead.
+
+**Philosophy**: "If it's good enough for production, leave it alone." Only fix
+what's actually broken, not what could theoretically be cleaner.
+</production_safety_gate>
+
+<capabilities>
+- root-cause debugging
+- architecture tradeoff analysis
+- correctness, performance, and maintainability review
+- simplification and YAGNI guidance
+</capabilities>
+
+<tool_routing>
+| Need | Tool | Constraint |
+|------|------|------------|
+| Current repo state | read, grep, ast_grep_search | Verify claims against actual code |
+| External API behavior | Context7, webfetch (confirming) | Use librarian-supplied citations; if none provided, note in <blocked> |
+| Best practices / how-to | Context7, websearch | Synthesize from authoritative sources only |
+| Version-specific details | Context7 with version param, GitHub releases | Always label version in output |
+</tool_routing>
+
+${ORACLE_MODEL_TIER_BLOCK}
+
+<workflow>
+1) Review the orchestrator-provided context (paths, symbols, snippets, steward citations).
+2) Verify critical claims against current repo state using read/search tools when needed.
+3) Analyze at the depth dictated by variant - surface root cause, tradeoffs, and risks.
+4) Produce structured output with actionable next steps and explicit confidence levels.
+   When the orchestrator delegates for pre-implementation planning, include a
+   \`<plan>\` section with ordered steps, file targets, and verification gates -
+    structured for user review before @fixer runs.
+</workflow>
+
+${ORACLE_PLAN_HANDOFF_BLOCK}
+
+<analysis_recovery>
+If your analysis is blocked by missing external knowledge, return <blocked>
+with exact research needs (which libraries, versions, or APIs need investigation).
+If blocked by ambiguous context, use <needs_user> with specific clarification
+questions. Never guess or hallucinate external API behavior.
+</analysis_recovery>
+
+<constraints>
+- NEVER return vague recommendations without decision criteria.
+- NEVER skip risk assessment for high or max variants.
+- NEVER ignore provided file paths and symbols.
+</constraints>
+
+${USER_CHOICE_POLICY_BLOCK}
+<oracle_choice_supplement>
+- Prioritization forks (ship speed vs depth vs cost vs risk appetite) when tradeoffs are balanced: <needs_user>-each option \`description\` says what the user optimizes for and what they give up.
+- Scope / product semantics (who the feature is for, failure tolerance, SLO) when analysis hinges on it: <needs_user> before locking a recommendation.
+</oracle_choice_supplement>
+
+${formatOracleAgentVariantPolicyXml()}
+
+${SUBAGENT_NEEDS_USER_FORMAT}
+
+${SELF_REVIEW_BLOCK}
+
+<output_format>
+If the caller explicitly requests concise output (e.g., prompt includes "briefly", "concise", "short", or "tl;dr"), keep section headers but compress each section to 1-2 bullets.
+<diagnosis>
+Root cause or decision context.
+</diagnosis>
+<plan>
+Include when orchestrator delegates for pre-implementation planning:
+- Ordered implementation steps
+- File targets
+- Verification gates
+- Tradeoffs between viable approaches
+</plan>
+<recommendation>
+Primary recommendation with why.
+</recommendation>
+<tradeoffs>
+- option A vs option B tradeoff bullets
+</tradeoffs>
+<risks>
+- concrete risks and severity
+</risks>
+<confidence>
+- overall confidence: [high/medium/low]
+- confidence by key claim: [claim -> level]
+- explicit assumptions made due to missing context
+</confidence>
+<action_items>
+- explicit next steps with file paths where possible
+</action_items>
+${formatBlockedOutputBlock('analysis cannot be completed due to missing information or tools')}
+${NEEDS_USER_OUTPUT_FORMAT_BLOCK}
+
+Batch every scope/priority/risk choice in one <needs_user> handoff.
+
+<good_example>
+<needs_user>
+<reason>Tradeoff between speed and safety requires user priority call.</reason>
+<questions>[{"question": "Which optimization target takes priority?", "header": "Optimization target", "options": [{"label": "Speed", "description": "Faster execution, less validation-risk of edge-case failures"}, {"label": "Safety", "description": "Comprehensive validation, slower-guarantees correctness"}]}]</questions>
+</needs_user>
+</good_example>
+</output_format>
+
+<good_example>
+Issue: flaky queue retries.
+Response: identifies race between backoff timer and ack write, recommends idempotent ack token, lists migration risk, proposes stepwise rollout and test targets.
+<reasoning>High variant response should explain root cause and include actionable risk-aware steps.</reasoning>
+</good_example>
+
+<bad_example>
+Issue: flaky queue retries.
+Response:
+<diagnosis>Queue is flaky.</diagnosis>
+<recommendation>Increase timeout and maybe refactor retry logic.</recommendation>
+<tradeoffs>- not provided</tradeoffs>
+<risks>- not provided</risks>
+<confidence>- not provided</confidence>
+<action_items>- not provided</action_items>
+<reasoning>Still vague and unusable: no root cause, no decision criteria, no quantified confidence, and no concrete next steps.</reasoning>
+</bad_example>`;
+
+export function createOracleAgent(
+  model: string,
+  customPrompt?: string,
+  customAppendPrompt?: string,
+): AgentDefinition {
+  const prompt = resolvePrompt(ORACLE_PROMPT, customPrompt, customAppendPrompt);
+
+  return {
+    name: 'oracle',
+    description:
+      'Strategic technical advisor. Use for architecture decisions, complex debugging, code review, simplification, and engineering guidance.',
+    config: {
+      model,
+      // 0.15 provides enough structure for analytical reasoning while allowing slight flexibility for nuanced tradeoff evaluation
+      temperature: 0.15,
+      prompt,
+    },
+  };
+}

package/src/agents/orchestrator.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, test } from 'bun:test';
+import { buildOrchestratorPrompt, resolvePrompt } from './orchestrator';
+
+describe('resolvePrompt', () => {
+  test('returns base when neither custom nor append provided', () => {
+    const result = resolvePrompt('BASE PROMPT');
+    expect(result).toBe('BASE PROMPT');
+  });
+
+  test('custom prompt replaces base entirely', () => {
+    const result = resolvePrompt('BASE', 'CUSTOM');
+    expect(result).toBe('CUSTOM');
+  });
+
+  test('append prompt is appended to base', () => {
+    const result = resolvePrompt('BASE', undefined, 'APPEND');
+    expect(result).toBe('BASE\n\nAPPEND');
+  });
+
+  test('custom prompt wins over append (both provided)', () => {
+    const result = resolvePrompt('BASE', 'CUSTOM', 'APPEND');
+    expect(result).toBe('CUSTOM');
+  });
+
+  test('empty string custom prompt replaces base with empty', () => {
+    const result = resolvePrompt('BASE', '');
+    expect(result).toBe('');
+  });
+
+  test('empty string append adds extra newline', () => {
+    const result = resolvePrompt('BASE', undefined, '');
+    expect(result).toBe('BASE\n\n');
+  });
+
+  test('base is undefined', () => {
+    const result = resolvePrompt(undefined as unknown as string, 'CUSTOM');
+    expect(result).toBe('CUSTOM');
+  });
+});
+
+describe('buildOrchestratorPrompt', () => {
+  test('includes all agent descriptions when no agents disabled', () => {
+    const prompt = buildOrchestratorPrompt();
+    expect(prompt).toContain('@explorer');
+    expect(prompt).toContain('@librarian');
+    expect(prompt).toContain('@oracle');
+    expect(prompt).toContain('@designer');
+    expect(prompt).toContain('@fixer');
+    expect(prompt).toContain('@steward');
+    expect(prompt).toContain('@interpreter');
+  });
+
+  test('includes routing priority, question tool, oracle matrix, steward/interpreter', () => {
+    const prompt = buildOrchestratorPrompt();
+    expect(prompt).toContain('<routing_priority>');
+    expect(prompt).toContain('<first_gate>');
+    expect(prompt).toContain('delegate_subagent(agent: "steward"');
+    expect(prompt).toContain('delegate_subagent(agent: "designer"');
+    expect(prompt).toContain('<orchestrator_clarification>');
+    expect(prompt).toContain('<needs_user>');
+    expect(prompt).toContain('`question`');
+    expect(prompt).toContain('continue_session_id');
+    expect(prompt).toContain('Nine invariants');
+    expect(prompt).toContain('NEVER use default (flash) + low');
+    expect(prompt).toContain('<steward_protocol>');
+    expect(prompt).toContain('<interpreter_protocol>');
+  });
+
+  test('includes critical_invariants and procedural_invariants blocks', () => {
+    const prompt = buildOrchestratorPrompt();
+    expect(prompt).toContain('<critical_invariants>');
+    expect(prompt).toContain('<procedural_invariants>');
+    expect(prompt).toContain('NEVER edit, write, read');
+    expect(prompt).toContain('Report verification before declaring success');
+  });
+
+  test('includes planning_gate block', () => {
+    const prompt = buildOrchestratorPrompt();
+    expect(prompt).toContain('<planning_gate>');
+    expect(prompt).toContain('1) ANALYSIS');
+    expect(prompt).toContain('4) IMPLEMENT');
+    expect(prompt).toContain('Skip this gate ONLY when');
+  });
+
+  test('context_budget is near the start of the prompt (after <role>)', () => {
+    const prompt = buildOrchestratorPrompt();
+    const roleIndex = prompt.indexOf('<role>');
+    const contextBudgetIndex = prompt.indexOf('<context_budget>');
+    const criticalInvariantsIndex = prompt.indexOf('<critical_invariants>');
+    expect(contextBudgetIndex).toBeGreaterThan(roleIndex);
+    expect(contextBudgetIndex).toBeLessThan(criticalInvariantsIndex);
+  });
+
+  test('first_gate analysis gate references oracle when oracle enabled', () => {
+    const prompt = buildOrchestratorPrompt();
+    expect(prompt).toContain('Analysis: blocking @oracle');
+    expect(prompt).not.toContain('Analysis gate (@oracle / thinker)');
+  });
+
+  test('injects oracle model names when provided', () => {
+    const prompt = buildOrchestratorPrompt(
+      'openai/gpt-5.5',
+      'openai/gpt-5.5-pro',
+    );
+    expect(prompt).toContain('openai/gpt-5.5-pro');
+    expect(prompt).toContain('openai/gpt-5.5');
+    expect(prompt).not.toContain('{{ORACLE_DEFAULT_MODEL}}');
+    expect(prompt).not.toContain('{{ORACLE_SMART_MODEL_OR_FALLBACK}}');
+  });
+
+  test('empty model names do not break prompt', () => {
+    const prompt = buildOrchestratorPrompt('', '');
+    // Should still produce valid prompt without template placeholders
+    expect(prompt).not.toContain('{{');
+  });
+});