@n-dx/core 0.1.0

package/packages/hench/dist/agent/lifecycle/shared.js

@@ -0,0 +1,241 @@
+/**
+ * Shared lifecycle operations — common validation and orchestration logic
+ * used by both the API and CLI agent loops.
+ *
+ * Both `loop.ts` (API provider) and `cli-loop.ts` (CLI provider) share
+ * identical logic for brief assembly, dry run handling, task status
+ * transitions, run record initialization, review gating, post-task
+ * testing, and run finalization. This module extracts that shared logic
+ * to prevent behavioral divergence between the two execution paths.
+ *
+ * Provider-specific code (API calls vs CLI subprocess management) stays
+ * in the respective loop modules.
+ *
+ * @module
+ */
+import { randomUUID } from "node:crypto";
+import { getCurrentHead } from "../../process/index.js";
+import { SystemMemoryMonitor } from "../../process/memory-monitor.js";
+import { assembleTaskBrief, formatTaskBrief } from "../planning/brief.js";
+import { buildSystemPrompt } from "../planning/prompt.js";
+import { saveRun } from "../../store/index.js";
+import { buildRunSummary } from "../analysis/summary.js";
+import { collectReviewDiff, promptReview, revertChanges } from "../analysis/review.js";
+import { runPostTaskTests } from "../../tools/index.js";
+import { toolRexUpdateStatus, toolRexAppendLog } from "../../tools/rex.js";
+import { section, subsection, stream, detail, info } from "../../types/output.js";
+import { displayTaskInfo } from "./task-display.js";
+/**
+ * Assemble the task brief, format it, build the system prompt, and display
+ * task info. This sequence is identical in both API and CLI loops.
+ */
+export async function prepareBrief(store, config, taskId, options) {
+    const { brief, taskId: resolvedTaskId } = await assembleTaskBrief(store, taskId, options);
+    const briefText = formatTaskBrief(brief);
+    const systemPrompt = buildSystemPrompt(brief.project, config);
+    displayTaskInfo(brief);
+    return { brief, taskId: resolvedTaskId, briefText, systemPrompt };
+}
+/**
+ * Execute a dry run — display the system prompt, brief, and optional
+ * extra info, then return a synthetic completed RunRecord with zero
+ * tokens and zero turns.
+ */
+export function executeDryRun(opts) {
+    section(`Dry Run${opts.label ? ` (${opts.label})` : ""}`);
+    subsection("System Prompt");
+    info(opts.systemPrompt);
+    subsection("Task Brief");
+    info(opts.briefText);
+    if (opts.extraInfo) {
+        for (const { heading, content } of opts.extraInfo) {
+            subsection(heading);
+            info(content);
+        }
+    }
+    return {
+        id: randomUUID(),
+        taskId: opts.taskId,
+        taskTitle: opts.taskTitle,
+        startedAt: new Date().toISOString(),
+        finishedAt: new Date().toISOString(),
+        status: "completed",
+        turns: 0,
+        summary: "Dry run — no execution performed",
+        tokenUsage: { input: 0, output: 0 },
+        toolCalls: [],
+        model: opts.model,
+    };
+}
+// ---------------------------------------------------------------------------
+// Task status transition (identical in both loops)
+// ---------------------------------------------------------------------------
+/**
+ * Atomically transition a task to in_progress before any work begins.
+ * Idempotent: skips if the task is already in_progress (e.g. resumed).
+ */
+export async function transitionToInProgress(store, taskId, currentStatus) {
+    if (currentStatus !== "in_progress") {
+        await toolRexUpdateStatus(store, taskId, { status: "in_progress" });
+    }
+}
+/**
+ * Create a new RunRecord in "running" status and persist it.
+ * Also captures a system memory snapshot for later use in finalization.
+ * Both loops create identical initial records.
+ */
+export async function initRunRecord(opts) {
+    const run = {
+        id: randomUUID(),
+        taskId: opts.taskId,
+        taskTitle: opts.taskTitle,
+        startedAt: new Date().toISOString(),
+        status: "running",
+        turns: 0,
+        tokenUsage: { input: 0, output: 0 },
+        turnTokenUsage: [],
+        toolCalls: [],
+        model: opts.model,
+    };
+    run.lastActivityAt = new Date().toISOString();
+    await saveRun(opts.henchDir, run);
+    // Capture system memory at run start
+    const monitor = new SystemMemoryMonitor();
+    let memoryCtx;
+    try {
+        const snap = await monitor.snapshot();
+        memoryCtx = {
+            systemAvailableAtStartBytes: snap.availableBytes,
+            systemTotalBytes: snap.totalBytes,
+        };
+    }
+    catch {
+        memoryCtx = {
+            systemAvailableAtStartBytes: -1,
+            systemTotalBytes: -1,
+        };
+    }
+    return { run, memoryCtx };
+}
+// ---------------------------------------------------------------------------
+// Starting HEAD capture (identical in both loops)
+// ---------------------------------------------------------------------------
+/**
+ * Capture the git HEAD before the agent starts, so completion validation
+ * can diff against it even if the agent commits changes during the run.
+ */
+export function captureStartingHead(projectDir) {
+    return getCurrentHead(projectDir);
+}
+/**
+ * Run the review gate: show diff, prompt for approval, and revert if
+ * rejected. Returns whether the review was rejected.
+ *
+ * Only called when `review` option is enabled and the run completed
+ * successfully.
+ */
+export async function runReviewGate(projectDir, store, taskId, run) {
+    const reviewDiff = await collectReviewDiff(projectDir);
+    const reviewResult = await promptReview(reviewDiff);
+    if (!reviewResult.approved) {
+        run.status = "failed";
+        run.error = reviewResult.reason;
+        info(`\nChanges rejected — reverting...`);
+        await revertChanges(projectDir);
+        await toolRexUpdateStatus(store, taskId, { status: "pending" });
+        await toolRexAppendLog(store, taskId, {
+            event: "review_rejected",
+            detail: reviewResult.reason ?? "Changes rejected by reviewer",
+        });
+        return { rejected: true, reason: reviewResult.reason };
+    }
+    return { rejected: false };
+}
+// ---------------------------------------------------------------------------
+// Post-task testing (identical in both loops)
+// ---------------------------------------------------------------------------
+/**
+ * Run automatic post-task tests for completed runs.
+ * Only runs when the run status is "completed" and a test command is configured.
+ */
+export async function runPostTaskTestsIfNeeded(run, projectDir, testCommand) {
+    if (run.status !== "completed" || !testCommand || !run.structuredSummary) {
+        return;
+    }
+    subsection("Post-Task Tests");
+    const testResult = await runPostTaskTests({
+        projectDir,
+        filesChanged: run.structuredSummary.filesChanged,
+        testCommand,
+    });
+    run.structuredSummary.postRunTests = testResult;
+    if (testResult.ran) {
+        const scope = testResult.targetedFiles.length > 0
+            ? ` (${testResult.targetedFiles.length} targeted file(s))`
+            : " (full suite)";
+        const status = testResult.passed ? "passed" : "FAILED";
+        stream("Tests", `${status}${scope}`);
+        if (testResult.durationMs != null) {
+            detail(`${testResult.durationMs}ms`);
+        }
+        if (!testResult.passed && testResult.output) {
+            info(testResult.output.slice(-500));
+        }
+    }
+    else if (testResult.error) {
+        detail(testResult.error);
+    }
+}
+/**
+ * Finalize a run: build structured summary, capture memory stats,
+ * run post-task tests, set timestamps, and persist.
+ * Called at the end of both loops.
+ */
+export async function finalizeRun(opts) {
+    const { run, henchDir, projectDir, testCommand, heartbeat, memoryCtx } = opts;
+    run.structuredSummary = buildRunSummary(run.toolCalls);
+    // Assemble memory stats if context was captured at init
+    if (memoryCtx) {
+        const peakRssBytes = heartbeat?.peakRssBytes ?? process.memoryUsage().rss;
+        let systemAvailableAtEndBytes = -1;
+        try {
+            const monitor = new SystemMemoryMonitor();
+            const snap = await monitor.snapshot();
+            systemAvailableAtEndBytes = snap.availableBytes;
+        }
+        catch {
+            // Best-effort — leave as -1
+        }
+        run.memoryStats = {
+            peakRssBytes,
+            systemAvailableAtStartBytes: memoryCtx.systemAvailableAtStartBytes,
+            systemAvailableAtEndBytes,
+            systemTotalBytes: memoryCtx.systemTotalBytes,
+        };
+    }
+    await runPostTaskTestsIfNeeded(run, projectDir, testCommand);
+    run.finishedAt = new Date().toISOString();
+    run.lastActivityAt = run.finishedAt;
+    await saveRun(henchDir, run);
+}
+// ---------------------------------------------------------------------------
+// Error handling helpers (shared patterns)
+// ---------------------------------------------------------------------------
+/**
+ * Handle a failed or timed-out run by updating task status and logging.
+ * Used by both loops for their error/timeout paths.
+ */
+export async function handleRunFailure(store, taskId, status, event, detail) {
+    await toolRexUpdateStatus(store, taskId, { status });
+    await toolRexAppendLog(store, taskId, { event, detail });
+}
+/**
+ * Handle budget exceeded by updating task status and logging.
+ */
+export async function handleBudgetExceeded(store, taskId, run, totalUsed, budget) {
+    run.status = "budget_exceeded";
+    run.error = `Token budget exceeded: ${totalUsed} used of ${budget ?? 0} budget`;
+    stream("Budget", run.error);
+    await handleRunFailure(store, taskId, "pending", "budget_exceeded", run.error);
+}
+//# sourceMappingURL=shared.js.map

package/packages/hench/dist/agent/lifecycle/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../../src/agent/lifecycle/shared.ts"],"names":[],"mappings":"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"}

package/packages/hench/dist/agent/lifecycle/task-display.d.ts

@@ -0,0 +1,7 @@
+import type { TaskBrief } from "../../schema/index.js";
+/**
+ * Display task information before any work begins.
+ * Shows task ID, title, priority, parent chain, and acceptance criteria count.
+ * This gives the user immediate visibility into what the agent will work on.
+ */
+export declare function displayTaskInfo(brief: TaskBrief): void;

package/packages/hench/dist/agent/lifecycle/task-display.js

@@ -0,0 +1,22 @@
+import { subsection, stream, detail } from "../../types/output.js";
+/**
+ * Display task information before any work begins.
+ * Shows task ID, title, priority, parent chain, and acceptance criteria count.
+ * This gives the user immediate visibility into what the agent will work on.
+ */
+export function displayTaskInfo(brief) {
+    subsection("Task");
+    stream("Task", `${brief.task.title}`);
+    detail(`ID: ${brief.task.id}`);
+    if (brief.task.priority) {
+        detail(`Priority: ${brief.task.priority}`);
+    }
+    if (brief.parentChain.length > 0) {
+        const chain = brief.parentChain.map((p) => p.title).join(" → ");
+        detail(`Context: ${chain}`);
+    }
+    if (brief.task.acceptanceCriteria && brief.task.acceptanceCriteria.length > 0) {
+        detail(`Acceptance criteria: ${brief.task.acceptanceCriteria.length}`);
+    }
+}
+//# sourceMappingURL=task-display.js.map

package/packages/hench/dist/agent/lifecycle/task-display.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-display.js","sourceRoot":"","sources":["../../../src/agent/lifecycle/task-display.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAEnE;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,KAAgB;IAC9C,UAAU,CAAC,MAAM,CAAC,CAAC;IAEnB,MAAM,CAAC,MAAM,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IACtC,MAAM,CAAC,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;IAE/B,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACxB,MAAM,CAAC,aAAa,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC7C,CAAC;IAED,IAAI,KAAK,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAChE,MAAM,CAAC,YAAY,KAAK,EAAE,CAAC,CAAC;IAC9B,CAAC;IAED,IAAI,KAAK,CAAC,IAAI,CAAC,kBAAkB,IAAI,KAAK,CAAC,IAAI,CAAC,kBAAkB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9E,MAAM,CAAC,wBAAwB,KAAK,CAAC,IAAI,CAAC,kBAAkB,CAAC,MAAM,EAAE,CAAC,CAAC;IACzE,CAAC;AACH,CAAC"}

package/packages/hench/dist/agent/lifecycle/token-budget.d.ts

@@ -0,0 +1,18 @@
+import type { TokenUsage } from "../../schema/index.js";
+export interface TokenBudgetResult {
+    /** Whether the token budget has been met or exceeded. */
+    exceeded: boolean;
+    /** Total tokens consumed (input + output). */
+    totalUsed: number;
+    /** The configured budget (undefined if unlimited). */
+    budget: number | undefined;
+    /** Tokens remaining before budget is hit (0 if exceeded or unlimited). */
+    remaining: number;
+}
+/**
+ * Check whether a token budget has been exceeded.
+ *
+ * A budget of 0 or undefined means unlimited — the check always passes.
+ * The budget is measured against total tokens (input + output combined).
+ */
+export declare function checkTokenBudget(usage: TokenUsage, budget: number | undefined): TokenBudgetResult;

package/packages/hench/dist/agent/lifecycle/token-budget.js

@@ -0,0 +1,16 @@
+/**
+ * Check whether a token budget has been exceeded.
+ *
+ * A budget of 0 or undefined means unlimited — the check always passes.
+ * The budget is measured against total tokens (input + output combined).
+ */
+export function checkTokenBudget(usage, budget) {
+    const totalUsed = usage.input + usage.output;
+    if (!budget) {
+        return { exceeded: false, totalUsed, budget: undefined, remaining: 0 };
+    }
+    const exceeded = totalUsed >= budget;
+    const remaining = Math.max(0, budget - totalUsed);
+    return { exceeded, totalUsed, budget, remaining };
+}
+//# sourceMappingURL=token-budget.js.map

package/packages/hench/dist/agent/lifecycle/token-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-budget.js","sourceRoot":"","sources":["../../../src/agent/lifecycle/token-budget.ts"],"names":[],"mappings":"AAaA;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAiB,EACjB,MAA0B;IAE1B,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC;IAE7C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;IACzE,CAAC;IAED,MAAM,QAAQ,GAAG,SAAS,IAAI,MAAM,CAAC;IACrC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAElD,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AACpD,CAAC"}

package/packages/hench/dist/agent/lifecycle/token-usage.d.ts

@@ -0,0 +1,44 @@
+import type { TokenUsage } from "../../schema/index.js";
+import { parseApiTokenUsage as parseTokenUsage, parseStreamTokenUsage } from "../../prd/llm-gateway.js";
+export { parseTokenUsage, parseStreamTokenUsage };
+/** Aggregated token usage across multiple API calls. */
+export interface AggregateTokenUsage {
+    calls: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationInputTokens?: number;
+    cacheReadInputTokens?: number;
+}
+export type CodexUsageDiagnostic = "codex_usage_missing";
+export interface CodexTokenMapping {
+    usage: TokenUsage;
+    total: number;
+    diagnostic?: CodexUsageDiagnostic;
+}
+/**
+ * Map Codex usage payload fields into Hench's shared token usage shape.
+ *
+ * Explicit field mapping:
+ * - input: `input_tokens` | `prompt_tokens`
+ * - output: `output_tokens` | `completion_tokens`
+ * - total: `total_tokens` fallback, otherwise `input + output`
+ *
+ * When usage is missing, returns zeros and a non-fatal diagnostic flag.
+ */
+export declare function mapCodexUsageToTokenUsage(raw: unknown): CodexTokenMapping;
+/** Create an empty AggregateTokenUsage accumulator. */
+export declare function emptyAggregateTokenUsage(): AggregateTokenUsage;
+/**
+ * Accumulate a single call's token usage into the aggregate.
+ *
+ * Always increments the call count, even when `usage` is undefined
+ * (e.g. when the API response omitted usage data).
+ */
+export declare function accumulateTokenUsage(aggregate: AggregateTokenUsage, usage?: TokenUsage): void;
+/**
+ * Format aggregate token usage for display.
+ *
+ * Returns empty string when no tokens were used.
+ * Single-call usage omits the call count; multi-call includes "across N calls".
+ */
+export declare function formatTokenUsage(usage: AggregateTokenUsage): string;

package/packages/hench/dist/agent/lifecycle/token-usage.js

@@ -0,0 +1,102 @@
+import { parseApiTokenUsage as parseTokenUsage, parseStreamTokenUsage, } from "../../prd/llm-gateway.js";
+// Re-export parsing functions from the canonical source (@n-dx/llm-client).
+// `parseTokenUsage` is an alias for `parseApiTokenUsage` — same function,
+// kept here for backward-compatible imports within hench.
+export { parseTokenUsage, parseStreamTokenUsage };
+function asUsageRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    return value;
+}
+function readNumber(obj, keys) {
+    for (const key of keys) {
+        const value = obj[key];
+        if (typeof value === "number" && Number.isFinite(value)) {
+            return value;
+        }
+    }
+    return undefined;
+}
+/**
+ * Map Codex usage payload fields into Hench's shared token usage shape.
+ *
+ * Explicit field mapping:
+ * - input: `input_tokens` | `prompt_tokens`
+ * - output: `output_tokens` | `completion_tokens`
+ * - total: `total_tokens` fallback, otherwise `input + output`
+ *
+ * When usage is missing, returns zeros and a non-fatal diagnostic flag.
+ */
+export function mapCodexUsageToTokenUsage(raw) {
+    const top = asUsageRecord(raw);
+    const usage = asUsageRecord(top?.usage)
+        ?? asUsageRecord(asUsageRecord(top?.response)?.usage)
+        ?? asUsageRecord(asUsageRecord(top?.data)?.usage);
+    if (!usage && !top) {
+        return {
+            usage: { input: 0, output: 0 },
+            total: 0,
+            diagnostic: "codex_usage_missing",
+        };
+    }
+    const source = usage ?? top ?? {};
+    const input = readNumber(source, ["input_tokens", "prompt_tokens", "input"]) ?? 0;
+    const output = readNumber(source, ["output_tokens", "completion_tokens", "output"]) ?? 0;
+    const total = readNumber(source, ["total_tokens", "total"]) ?? (input + output);
+    const hasUsageFields = usage
+        ? input > 0 || output > 0 || total > 0
+        : readNumber(source, ["input_tokens", "prompt_tokens", "output_tokens", "completion_tokens", "total_tokens"]) !== undefined;
+    return {
+        usage: { input, output },
+        total,
+        ...(hasUsageFields ? {} : { diagnostic: "codex_usage_missing" }),
+    };
+}
+/** Create an empty AggregateTokenUsage accumulator. */
+export function emptyAggregateTokenUsage() {
+    return { calls: 0, inputTokens: 0, outputTokens: 0 };
+}
+/**
+ * Accumulate a single call's token usage into the aggregate.
+ *
+ * Always increments the call count, even when `usage` is undefined
+ * (e.g. when the API response omitted usage data).
+ */
+export function accumulateTokenUsage(aggregate, usage) {
+    aggregate.calls++;
+    if (!usage)
+        return;
+    aggregate.inputTokens += usage.input;
+    aggregate.outputTokens += usage.output;
+    if (usage.cacheCreationInput) {
+        aggregate.cacheCreationInputTokens =
+            (aggregate.cacheCreationInputTokens ?? 0) + usage.cacheCreationInput;
+    }
+    if (usage.cacheReadInput) {
+        aggregate.cacheReadInputTokens =
+            (aggregate.cacheReadInputTokens ?? 0) + usage.cacheReadInput;
+    }
+}
+/**
+ * Format aggregate token usage for display.
+ *
+ * Returns empty string when no tokens were used.
+ * Single-call usage omits the call count; multi-call includes "across N calls".
+ */
+export function formatTokenUsage(usage) {
+    if (usage.calls === 0 || (usage.inputTokens === 0 && usage.outputTokens === 0)) {
+        return "";
+    }
+    const total = usage.inputTokens + usage.outputTokens;
+    const parts = [
+        `${total.toLocaleString()} tokens`,
+        `(${usage.inputTokens.toLocaleString()} in`,
+        `/ ${usage.outputTokens.toLocaleString()} out)`,
+    ];
+    if (usage.calls > 1) {
+        parts.push(`across ${usage.calls} calls`);
+    }
+    return parts.join(" ");
+}
+//# sourceMappingURL=token-usage.js.map

package/packages/hench/dist/agent/lifecycle/token-usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-usage.js","sourceRoot":"","sources":["../../../src/agent/lifecycle/token-usage.ts"],"names":[],"mappings":"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"}

package/packages/hench/dist/agent/loop.d.ts

@@ -0,0 +1,24 @@
+import type { PRDStore } from "rex";
+import type { HenchConfig, RunRecord } from "../schema/index.js";
+export interface AgentLoopOptions {
+    config: HenchConfig;
+    store: PRDStore;
+    projectDir: string;
+    henchDir: string;
+    taskId?: string;
+    dryRun?: boolean;
+    maxTurns?: number;
+    /** Total token budget per run (input + output). Overrides config. */
+    tokenBudget?: number;
+    model?: string;
+    /** Show diff and prompt for approval before finalizing. */
+    review?: boolean;
+    /** Task IDs to skip during autoselection (e.g. stuck tasks). */
+    excludeTaskIds?: Set<string>;
+    /** Restrict task selection to this epic (ID). */
+    epicId?: string;
+}
+export interface AgentLoopResult {
+    run: RunRecord;
+}
+export declare function agentLoop(opts: AgentLoopOptions): Promise<AgentLoopResult>;