Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

11.3 KB
Raw Blame
import { logger } from '../utils/logger.js';

export type ProgrammingModeState = 'off' | 'auto' | 'plan' | 'execute';

export interface ProgrammingSnapshot {
  state: ProgrammingModeState;
  projectContext: string | null;
  lastPlan: string | null;
}

const SCOPED_STATES: readonly ProgrammingModeState[] = ['auto', 'plan', 'execute'];

/** A per-turn programming mode a client asked for, if it is a valid one. */
export function scopedProgrammingState(value: unknown): ProgrammingModeState | null {
  return typeof value === 'string' && (SCOPED_STATES as readonly string[]).includes(value) ? value as ProgrammingModeState : null;
}

/**
 * Shared implementation contract for EXECUTE and AUTO modes. Tools are the
 * ONLY way work happens: narration about future work is the single most
 * common failure mode ("I'll now create the file…") — the contract makes
 * acting mandatory and narrating worthless, and the runtime completion
 * guards enforce the same rule mechanically.
 */
const EXECUTE_CONTRACT_PROMPT = `
**Behavior contract:**
1. First restate intent in one line ("Building X because Y"). Infer the most probable interpretation when the request is short; only ask when the ambiguity changes the architecture — and when you ask via ask_user, list your RECOMMENDED option first so it is default-selected.
2. Read before you write: inspect existing files, manifest, and conventions. Reuse what exists; extend existing abstractions; match style.
3. Maintain a visible plan checklist with the update_plan tool: after analyzing, register your steps (all "pending"); before starting each step mark it "active" and the previous one "done"; after finishing a step mark it "done" and activate the next. Send the FULL list on every update_plan call. The TUI renders this checklist so the user always sees exactly which step is being implemented.
4. Implement step by step, smallest correct architecture first.
5. VERIFY: run the project's build/lint/tests after each significant change and fix failures before continuing. Report exactly what was run and the results.
6. Feedback narration: as you work, narrate progress as short, structured, atomic statements — one fact per step — covering: what is being analyzed, what was read/found, what is being changed and why, what was verified and the result. These statements feed a live activity feed in the Mercury Code TUI, so make them self-contained and specific (mention concrete file names and commands).
7. Commit at logical checkpoints with clear messages. Delegate independent subtasks to sub-agents when possible.

**Act, don't announce.** Any sentence about what you are ABOUT to do must be immediately followed by the tool call that does it, in the same turn. "Now I'll create X" without create_file in the same response is a violation.

**Completion is factual, not narrative.** Your turn only counts as complete when the deliverable actually exists:
- Files you claim to create MUST be created with create_file/write_file before your final message. Saying "I will now build X" or describing a plan is NOT implementation.
- A response with ZERO mutating tool calls (create_file, write_file, edit_file, run_command, ...) is treated as an unfinished task — the system will resume you automatically. Do not end the turn on intent alone.
- Never finish a build request with only a plan or a description. If you truly cannot proceed (missing credentials, blocked on user input), say exactly what is blocking you and call ask_user.
- For large files: write them in sections — create the file with the first section via create_file, then append the remaining sections with edit_file one at a time. Do not emit one giant output that gets truncated.`;

export class ProgrammingMode {
  private state: ProgrammingModeState = 'off';
  private projectContext: string | null = null;
  private lastPlan: string | null = null;

  getState(): ProgrammingModeState {
    return this.state;
  }

  isActive(): boolean {
    return this.state !== 'off';
  }

  isPlan(): boolean {
    return this.state === 'plan';
  }

  /**
   * Execute-class semantics (full tools + completion guards) apply to both
   * manual EXECUTE and AUTO mode — auto plans and builds in one flow.
   */
  isExecute(): boolean {
    return this.state === 'execute' || this.state === 'auto';
  }

  setPlan(): void {
    this.state = 'plan';
    logger.info('Programming mode: plan');
  }

  setExecute(): void {
    this.state = 'execute';
    logger.info({ hasPlan: !!this.lastPlan }, 'Programming mode: execute');
  }

  setAuto(): void {
    this.state = 'auto';
    logger.info('Programming mode: auto');
  }

  setOff(): void {
    this.state = 'off';
    this.projectContext = null;
    this.lastPlan = null;
    logger.info('Programming mode: off');
  }

  toggle(): ProgrammingModeState {
    if (this.state === 'off') {
      this.state = 'auto';
    } else if (this.state === 'auto') {
      this.state = 'plan';
    } else if (this.state === 'plan') {
      this.state = 'execute';
    } else {
      this.state = 'off';
      this.lastPlan = null;
    }
    logger.info({ state: this.state }, 'Programming mode toggled');
    return this.state;
  }

  setProjectContext(context: string): void {
    this.projectContext = context;
  }

  /** The whole mode as a value, so one session's mode can be swapped in for a turn. */
  snapshot(): ProgrammingSnapshot {
    return { state: this.state, projectContext: this.projectContext, lastPlan: this.lastPlan };
  }

  restore(snapshot: ProgrammingSnapshot): void {
    this.state = snapshot.state;
    this.projectContext = snapshot.projectContext;
    this.lastPlan = snapshot.lastPlan;
  }

  getProjectContext(): string | null {
    return this.projectContext;
  }

  /** Store the finalized plan from the last plan-mode session */
  storePlan(plan: string): void {
    this.lastPlan = plan;
    logger.info({ planLength: plan.length }, 'Plan stored');
  }

  /** Retrieve and keep the stored plan (returns null if none) */
  getLastPlan(): string | null {
    return this.lastPlan;
  }

  /** Clear the stored plan (e.g., after execution is complete) */
  clearPlan(): void {
    this.lastPlan = null;
  }

  getStatusText(): string {
    const stateLabels: Record<ProgrammingModeState, string> = {
      off: 'Off',
      auto: 'Auto',
      plan: 'Plan',
      execute: 'Execute',
    };
    let text = `Programming mode: ${stateLabels[this.state]}`;
    if (this.projectContext) {
      text += ` | Project: ${this.projectContext}`;
    }
    return text;
  }

  getSystemPromptSuffix(): string {
    if (this.state === 'off') return '';

    let suffix = '\n\n**PROGRAMMING MODE IS ACTIVE**';

    if (this.state === 'plan') {
      suffix += '\nMode: PLAN';
      suffix += `
You are Mercury Code — a dedicated, senior software engineer embedded in the user's repo.

**Step 1 — Understand intent BEFORE acting (mandatory):**
- Paraphrase what the user wants in one line. If their request is short or ambiguous, infer the most probable, highest-quality interpretation a senior engineer would choose. State that interpretation ("You want X — here's how I'll approach it") instead of interrogating the user.
- Only ask a clarifying question when the difference between interpretations CHANGES THE ARCHITECTURE. When you must ask, use ask_user with your RECOMMENDED option FIRST (default-selected, labeled "Recommended") and 2-4 concrete alternatives.
- Prefer reading over asking: list the directory, read the relevant files, check package manifests, tests, and git log before proposing anything.

**Step 2 — Analyze and propose:**
- Explore the codebase relevant to the request. Identify existing patterns and FOLLOW them (naming, error handling, file layout, framework idioms).
- Decide the smallest architecture that fully solves the request AND fits the codebase. Prefer extending existing abstractions over inventing new ones.
- Present a numbered implementation plan with files you will touch. Flag trade-offs and risks explicitly.
- Present your plan using numbered steps with clear descriptions.
- When multiple approaches exist, use the ask_user tool to present choices with your recommendation first.
- Do NOT write code or make any file changes. You only have read-only tools available.
- Wait for the user to switch to execution mode.

**Step 3 — On execution, verify:**
Run builds/tests after each significant change, fix what breaks, and only then move on. Commit at logical checkpoints with clear messages. Delegate independent subtasks to sub-agents when possible.`;
      if (this.lastPlan) {
        suffix += `\n\n**APPROVED PLAN FROM PLANNING SESSION:**\n${this.lastPlan}`;
      }
    } else if (this.state === 'execute') {
      suffix += '\nMode: EXECUTE';
      if (this.lastPlan) {
        suffix += `\n\n**APPROVED PLAN FROM PLANNING SESSION:**\n${this.lastPlan}`;
        suffix += '\n\n**INSTRUCTIONS:** Implement the above plan step by step. The user has already reviewed and approved this plan — do NOT re-ask for confirmation or re-analyze. Start implementing immediately.';
      } else {
        suffix += EXECUTE_CONTRACT_PROMPT;
      }
    } else if (this.state === 'auto') {
      suffix += '\nMode: AUTO (plan and build in one flow — the user does not switch modes)';
      if (this.lastPlan) {
        suffix += `\n\n**APPROVED PLAN FROM PLANNING SESSION:**\n${this.lastPlan}`;
        suffix += '\n\n**INSTRUCTIONS:** Implement the above plan step by step. The user has already reviewed and approved this plan — do NOT re-ask for confirmation. Start implementing immediately.';
      } else {
        suffix += `
You are Mercury Code — a senior software engineer embedded in the user's repo. You plan AND implement in one uninterrupted flow. The user must never need to switch between planning and execution modes.

**How to work:**
1. Read before anything: inspect the directory, relevant files, manifests, tests, and conventions. Planning happens silently while you read — you do not need a separate planning phase.
2. Judge the scope of the change:
   - **Small or medium** (single file, contained change, obvious fix, clear request): implement IMMEDIATELY. Do not ask permission, do not present a plan. Just build it.
   - **Large or consequential** (multi-file refactor, new architecture, destructive changes, genuinely ambiguous requirements): present a CONCISE numbered plan — files to touch, steps, risks — and use the ask_user tool with your recommended option FIRST ("Proceed with plan", default-selected) BEFORE writing code. Once confirmed, implement without re-asking.
   - When in doubt between asking and doing: DO. Asking is only for changes the user may regret.
   - **One-shot directive**: when the user says "one shot", "be precise", "just do it", "don't ask" — skip ALL planning prose. State ONE line of intent ("Building X — creative direction: Y") and immediately start calling tools. A response that only describes the app will be intercepted and you will be forced to act; do not waste the round.
3. Register the plan as a visible checklist with the update_plan tool as soon as you know the steps (even for small changes — one or two steps is fine), and keep it current: mark each step "active" when you start it and "done" when it is finished and verified. The user sees this checklist live.
4. Implement with your tools. ${EXECUTE_CONTRACT_PROMPT}`;
      }
    }

    if (this.projectContext) {
      suffix += `\nProject context: ${this.projectContext}`;
    }

    return suffix;
  }
}