mahoraga-agent

AI agent dispatcher with adaptation loop for Mahoraga.

Install

npm install mahoraga-agent

Prerequisites

• opencode-ai CLI installed (npm install --global opencode-ai)
• .opencode.json with provider config and "permission": { "*": "allow" }
• gh CLI authenticated (for PR creation)

What It Does

Takes a detected UI issue, generates a fix using an AI coding agent (via OpenCode), validates the fix (build + test + diff size), and opens a draft PR — all in an isolated git worktree.

Usage

import { AgentDispatcher, OpenCodeExecutor } from 'mahoraga-agent';
import { FileSystemCodeMapper } from 'mahoraga-mapper';
import { defineConfig } from 'mahoraga-core';

const config = defineConfig({
  sources: [{ adapter: 'amplitude' }],
  agent: {
    allowedPaths: ['src/**/*.tsx'],
    deniedPaths: ['src/admin/**'],
  },
});

const executor = new OpenCodeExecutor();
const mapper = new FileSystemCodeMapper('./src');
await mapper.buildIndex();

const dispatcher = new AgentDispatcher(executor, mapper, config.agent);
const result = await dispatcher.dispatch([issueGroup], '/path/to/worktree');
// { status: 'pr_created', prUrl: 'https://github.com/user/repo/pull/123', ... }

Adaptation Loop

The agent's core differentiator:

1. Generate fix — AI agent produces a code change
2. Verify changes — Check that files were actually modified
3. Create test — Generate a localized test mimicking the user journey
4. Run test — Execute the test against the fix
5. Retry — If the test fails, feed error output back to the agent (up to maxRetries)
6. Validate — Only proceed to PR if build passes, tests pass, and diff is within limits

Governance Controls

| Control | Default | Description | |---------|---------|-------------| | allowedPaths | [] | Glob patterns the agent can modify | | deniedPaths | [] | Glob patterns the agent must not modify | | confidenceThreshold | 0.7 | Below this → GitHub issue instead of PR | | maxCostPerIssue | $2 | USD budget per issue | | maxCostPerRun | $20 | USD budget per run | | maxDiffLines | 500 | Reject diffs exceeding this | | maxRetries | 3 | Adaptation loop retry limit |

License

MIT