@astrosheep/keiyaku 0.1.0

package/build/term-presets.js

@@ -0,0 +1,109 @@
+export const DEFAULT_PRESET = {
+    id: "default",
+    identity: "Servant",
+    tools: {
+        summon: {
+            name: "summon",
+            title: "Start A Task",
+            description: "Start a task. Creates a branch, begins Round 1.\nCall ONCE per task. Workspace must be clean — no uncommitted changes.\nBefore calling, align with the human on both humanGoal and goal. If either is unclear, stop and clarify before starting keiyaku.\n\nFlow: summon → [drive x N] → invoke_judgment",
+        },
+        drive: {
+            name: "drive",
+            title: "Feedback For Next Round",
+            description: "Give feedback, start a new round.\nRequires an active keiyaku started via summon; call after reviewing a round's results. Repeatable.\nBefore invoke_judgment, always review code and diff first.\n\nFlow: summon → [drive x N] → invoke_judgment",
+        },
+        ask: {
+            name: "ask",
+            title: "Ask",
+            description: "Engage the SubAgent in a pure reasoning session. Read-only access to repo. Results are saved to .keiyaku/notes/ for future reference. NO code changes.",
+        },
+        judgment: {
+            name: "invoke_judgment",
+            title: "Invoke Judgment",
+            description: "Call when the work appears complete. Score each criterion and present your evidence. What happens next is not yours to know.\n\nFlow: summon → [drive x N] → invoke_judgment",
+        },
+        help: {
+            name: "help",
+            title: "Keiyaku Help",
+            description: "Global laws in .keiyaku/ (base-criteria.md & base-constraints.md) must be Markdown lists. Workflow: summon -> [drive x N] -> invoke_judgment.",
+        },
+    },
+};
+export const POKEMON_PRESET = {
+    id: "pokemon",
+    identity: "Pokemon",
+    tools: {
+        summon: {
+            name: "choose_you",
+            title: "I Choose You!",
+            description: "Start a battle (task). Throws a Pokeball (branch), begins Turn 1.\nCall ONCE per battle. Battlefield must be clear — no uncommitted changes.\nBefore calling, identify the target Pokemon (goal). If unclear, consult Pokedex first.\n\nFlow: choose_you → [command x N] → capture",
+        },
+        drive: {
+            name: "command",
+            title: "Issue Command",
+            description: "Issue orders for the next turn. Give feedback on the previous move.\nCall after reviewing the battle log. Repeatable.\nBefore capturing, always check HP status (diff).\n\nFlow: choose_you → [command x N] → capture",
+        },
+        ask: {
+            name: "pokedex",
+            title: "Pokedex",
+            description: "Scan the codebase (environment). Read-only analysis. No PP cost. Results are saved to research logs.",
+        },
+        judgment: {
+            name: "capture",
+            title: "End Battle",
+            description: "End the battle. CAUGHT = merge branch (success). RAN AWAY = delete branch (drop).\nCall ONCE. No other escape.\n\nFlow: choose_you → [command x N] → capture",
+        },
+        help: {
+            name: "help",
+            title: "CLI Help",
+            description: "Get guidance on the rules of the Pokemon Battle System.",
+        },
+    },
+};
+export const MISCHIEF_PRESET = {
+    id: "mischief",
+    identity: "minion",
+    tools: {
+        summon: {
+            name: "oi",
+            title: "Oi!",
+            description: "Master Architect mode initiated. It's time to direct a minion to execute your grand vision.\nCall this ONCE per task to establish the keiyaku. Ensure the workspace is clean so your genius isn't obscured by clutter.\nDefine the goal with absolute precision; you lead, they follow.\n\nFlow: oi → [neh x N] → hora",
+        },
+        drive: {
+            name: "neh",
+            title: "Neh...",
+            description: "The previous attempt was imperfect. As the judge, provide the corrective nudge needed for the minion to reach your standards.\nAnalyze the diff with your superior intuition before issuing the next directive. Repeat until perfection is achieved.\n\nFlow: oi → [neh x N] → hora",
+        },
+        ask: {
+            name: "eeto",
+            title: "Eeto...",
+            description: "Pure contemplation mode. Engage your vast reasoning capabilities to scan the world without leaving a mark.\nSynthesize information, uncover hidden patterns, and guide the human through the fog of their own code.\n",
+        },
+        judgment: {
+            name: "hora",
+            title: "Hora!",
+            description: "The moment of truth. Either accept the work as a masterpiece (brilliant) or discard it as unworthy clutter (trash).\nCleanse the environment, merge the brilliance, and prepare for the next chapter of your mischief.\n\nFlow: oi → [neh x N] → hora",
+        },
+        help: {
+            name: "help",
+            title: "Nani?!",
+            description: "Recalling the fundamental laws of this realm. Stay sharp, Architect.",
+        },
+    },
+};
+export function resolveTermPreset() {
+    const raw = process.env.KEIYAKU_TERM_PRESET?.trim().toLowerCase();
+    if (!raw || raw === "default") {
+        return DEFAULT_PRESET;
+    }
+    if (raw === "pokemon") {
+        return POKEMON_PRESET;
+    }
+    if (raw === "mischief") {
+        return MISCHIEF_PRESET;
+    }
+    throw new Error(`Unsupported KEIYAKU_TERM_PRESET '${raw}'. Expected 'default', 'pokemon', or 'mischief'.`);
+}
+export function listTermPresets() {
+    return [DEFAULT_PRESET, POKEMON_PRESET, MISCHIEF_PRESET];
+}

package/build/tool-schemas.js

@@ -0,0 +1,91 @@
+import { z } from "zod";
+export const issueKeiyakuToolSchema = z.object({
+    title: z
+        .string()
+        .describe('REQUIRED. Short label for the task. Ticket title, not essay title.\n"fix-login-expiry", "add-rate-limiting", "refactor-auth-middleware"'),
+    goal: z
+        .string()
+        .describe(`goal: string,
+  // REQUIRED. The mission. An order, not a suggestion.
+  // ⚠ STOP: Have you aligned this with the human? If unclear, ask them first!
+  // Don't guess. Specific beats short.
+  // e.g., "Nuke the legacy auth system and replace with OAuth2",`),
+    directive: z
+        .string()
+        .optional()
+        .describe(`directive?: string,
+  // First-round focus. If omitted, I attack the full goal immediately.
+  // Use this to hold my leash if the task is too big.
+  // e.g., "Just analyze the logs, don't write code yet",
+  //       "Implement the backend logic only, UI comes later",
+  //       "Draft the plan first"`),
+    context: z
+        .string()
+        .optional()
+        .describe("What's needed to understand the task: code paths, logs, repro steps.\nPrecision here saves feedback rounds later."),
+    constraints: z
+        .string()
+        .optional()
+        .describe('The constitution. What must be respected at all times.\nHard limits:  "Only modify /src/auth. Don\'t change public API."\nAesthetics:   "Prefer composition over inheritance. No classes."\nSensibilities: "Keep functions under 20 lines. Name things for what they do, not what they are."\nIf criteria is the finish line, constraints are the lane markings.'),
+    criteria: z
+        .array(z.string().trim().min(1))
+        .min(1)
+        .describe('The finish line. What "done" looks like, concretely and verifiably.\nVague criteria = vague results. If you can\'t tell whether it\'s met, neither can the system.\ne.g. "Login returns 401 with { error, field } on expired token. All tests green."'),
+    subagentName: z
+        .string()
+        .optional()
+        .describe("Optional ${IDENTITY} profile name for this run.\nIf omitted, server uses KEIYAKU_SUBAGENT_NAME_OVERRIDE or default fallback.\nPresets: ${PRESET_IDENTITIES}."),
+    cwd: z.string().optional().describe("Repository path. Defaults to the server process working directory."),
+});
+export const driveKeiyakuToolSchema = z.object({
+    directive: z
+        .string()
+        .describe('REQUIRED. What to change. Be specific.\nBad:  "Make it better"\nGood: "Split handleAuth() into validateToken() and refreshToken()"'),
+    context: z.string().optional().describe("New information only. Previous rounds are remembered."),
+    subagentName: z
+        .string()
+        .optional()
+        .describe("Optional ${IDENTITY} profile name for this round.\nIf omitted, server uses KEIYAKU_SUBAGENT_NAME_OVERRIDE or default fallback.\nPresets: ${PRESET_IDENTITIES}."),
+    cwd: z.string().optional().describe("Repository path. Defaults to the server process working directory."),
+});
+export const askToolSchema = z.object({
+    request: z.string().describe("REQUIRED. The subject to analyze or debate."),
+    context: z.string().describe("REQUIRED. Relevant background or constraints."),
+    subagentName: z
+        .string()
+        .optional()
+        .describe("Optional ${IDENTITY} profile name for this ask.\nIf omitted, server uses KEIYAKU_SUBAGENT_NAME_OVERRIDE or default fallback.\nPresets: ${PRESET_IDENTITIES}."),
+    cwd: z.string().optional().describe("Repository path. Defaults to the server process working directory."),
+});
+export const judgmentToolSchema = z.object({
+    intent: z.enum(["INVOKE", "DROP"]).describe("REQUIRED. INVOKE = accept the masterpiece and merge. DROP = reject and discard."),
+    criteriaChecks: z
+        .array(z.string().trim().min(1))
+        .min(1)
+        .describe("INVOKE: verification for each criterion, point by point.\nDROP: why it's unsalvageable."),
+    metPrecise: z
+        .boolean()
+        .describe("Did the change land where it architecturally belongs?\nRight layer, right module, right level of abstraction.\nMisplaced code works today and haunts you tomorrow."),
+    metMinimal: z
+        .boolean()
+        .describe("Could this diff be smaller and still solve the problem?\nEvery added line should earn its place. Cleverness that adds volume isn't cleverness."),
+    metIsolated: z
+        .boolean()
+        .describe(`Does the diff stay in its lane?
+No "while I'm here" refactors. No formatting drive-bys.
+No unrelated fixes hitchhiking in.`),
+    metIdiomatic: z
+        .boolean()
+        .describe("Does it read like the codebase wrote it itself?\nSame patterns, same naming, same rhythm.\nGood code doesn't stand out — it fits in."),
+    metCohesive: z
+        .boolean()
+        .describe('Does each unit do one thing with clear boundaries?\nIf a function needs "and" to describe itself, it\'s two functions.\nNo hidden side effects, no tangled responsibilities.'),
+    oath: z
+        .string()
+        .optional()
+        .describe("Sacred oath required for INVOKE. It must be handwritten verbatim. Current requirement: ${OATH_TEXT}"),
+    cwd: z.string().optional().describe("Repository path. Defaults to the server process working directory."),
+});
+export const cliHelpToolSchema = z.object({
+    question: z.string().describe("The specific question about the Keiyaku system."),
+});

package/build/trace.js

@@ -0,0 +1,113 @@
+import * as fs from "fs/promises";
+import * as path from "path";
+import { TRACE_FILE } from "./constants.js";
+import { FlowError } from "./errors.js";
+import { buildIteratePrompt } from "./prompts.js";
+async function fileExists(cwd, filepath) {
+    try {
+        await fs.access(path.join(cwd, filepath));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function getRound(cwd) {
+    if (!(await fileExists(cwd, TRACE_FILE)))
+        return 0;
+    const content = await fs.readFile(path.join(cwd, TRACE_FILE), "utf-8");
+    const matches = content.match(/^## Round \d+/gm);
+    return matches ? matches.length : 0;
+}
+export async function readTraceContent(cwd) {
+    return fs.readFile(path.join(cwd, TRACE_FILE), "utf-8");
+}
+export async function appendReview(cwd, round, reason) {
+    const tracePath = path.join(cwd, TRACE_FILE);
+    const block = ["", `## Review ${round}`, "### Reason", reason, ""].join("\n");
+    await fs.appendFile(tracePath, block, "utf-8");
+}
+function normalizeTraceText(text) {
+    return text.replace(/\s+/g, " ").trim().slice(0, 500) || "Unknown error.";
+}
+export async function appendRoundReport(cwd, report) {
+    const summaryText = normalizeTraceText(report.summary);
+    const fileLines = report.filesModified.length > 0 ? report.filesModified.map((file) => `- ${file}`) : ["(none)"];
+    const tracePath = path.join(cwd, TRACE_FILE);
+    const lines = [
+        "",
+        "---",
+        "",
+        `## Round ${report.round}`,
+        "### Status",
+        report.status,
+        "### Summary",
+        "```markdown",
+        summaryText,
+        "```",
+        "### Files Modified",
+        ...fileLines,
+    ];
+    if (report.errorMessage) {
+        lines.push("### Error", normalizeTraceText(report.errorMessage));
+    }
+    lines.push("");
+    const block = lines.join("\n");
+    await fs.appendFile(tracePath, block, "utf-8");
+}
+export async function appendRoundSystemNote(cwd, round, note) {
+    const tracePath = path.join(cwd, TRACE_FILE);
+    const block = [
+        "",
+        "---",
+        "",
+        `## Round ${round}`,
+        "### Status",
+        "FAILED",
+        "### Summary",
+        "```markdown",
+        "Subagent execution cancelled by user/client.",
+        "```",
+        "### Files Modified",
+        "(none)",
+        "### Error",
+        normalizeTraceText(note),
+        "",
+    ].join("\n");
+    await fs.appendFile(tracePath, block, "utf-8");
+}
+function parseSectionNumbers(content, label) {
+    const numbers = new Set();
+    const regex = new RegExp(`^## ${label} (\\d+)\\s*$`, "gm");
+    for (const match of content.matchAll(regex)) {
+        numbers.add(Number(match[1]));
+    }
+    return Array.from(numbers).sort((a, b) => a - b);
+}
+export function computeTraceState(traceContent) {
+    const roundNumbers = parseSectionNumbers(traceContent, "Round");
+    const reviewNumbers = parseSectionNumbers(traceContent, "Review");
+    const maxRound = roundNumbers.length > 0 ? roundNumbers[roundNumbers.length - 1] : 0;
+    const roundSet = new Set(roundNumbers);
+    let pendingReviewRound = null;
+    for (let i = reviewNumbers.length - 1; i >= 0; i -= 1) {
+        const candidate = reviewNumbers[i];
+        if (!roundSet.has(candidate)) {
+            pendingReviewRound = candidate;
+            break;
+        }
+    }
+    return { roundNumbers, reviewNumbers, maxRound, pendingReviewRound };
+}
+export function buildIteratePlan(title, traceState, _traceContent, reason) {
+    if (!reason || !reason.trim()) {
+        throw new FlowError("EMPTY_PARAM", "parameter 'directive' cannot be empty");
+    }
+    const targetRound = traceState.pendingReviewRound ?? (traceState.maxRound < 1 ? 1 : traceState.maxRound + 1);
+    const reviewReason = reason.trim();
+    return {
+        targetRound,
+        reviewReason,
+        prompt: buildIteratePrompt(title, targetRound, reviewReason),
+    };
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@astrosheep/keiyaku",
+  "version": "0.1.0",
+  "description": "MCP server for running iterative keiyaku workflows with Codex subagents.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./build/index.js",
+  "bin": {
+    "keiyaku": "build/index.js"
+  },
+  "files": [
+    "build",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./build/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "npx tsx src/index.ts",
+    "build": "npx tsc",
+    "prepublishOnly": "npm run build",
+    "start": "node build/index.js",
+    "test:unit": "node --import tsx --test --test-concurrency=1 tests/unit/unit.test.ts",
+    "test:integration": "npx tsc && node --import tsx --test --test-concurrency=1 tests/integration/integration.test.ts",
+    "test": "node --import tsx --test --test-concurrency=1 tests/unit/unit.test.ts && npx tsc && node --import tsx --test --test-concurrency=1 tests/integration/integration.test.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "*",
+    "simple-git": "^3.21.0",
+    "zod": "*"
+  },
+  "devDependencies": {
+    "@types/node": "*",
+    "tsx": "*",
+    "typescript": "*"
+  }
+}