@oscharko-dev/keiko 0.1.0-beta.0

package/dist/harness/context.d.ts

@@ -0,0 +1,33 @@
+import type { ChatMessage } from "../gateway/types.js";
+import type { Clock } from "../gateway/types.js";
+import { Emitter } from "./emitter.js";
+import type { NormalizedResponse } from "../gateway/types.js";
+import type { ModelPort, ToolPort } from "./ports.js";
+import type { TaskPlan } from "./tasks/policy.js";
+import type { HarnessFailure, HarnessLimits, HarnessStateName, RunCounters, TaskType } from "./types.js";
+export interface RunContext {
+    readonly model: ModelPort;
+    readonly tools: ToolPort;
+    readonly emitter: Emitter;
+    readonly clock: Clock;
+    readonly signal: AbortSignal;
+    readonly limits: HarnessLimits;
+    readonly modelId: string;
+    readonly taskType: TaskType;
+    readonly plan: TaskPlan;
+    readonly startedAt: number;
+    readonly counters: RunCounters;
+    messages: ChatMessage[];
+    lastResponse: NormalizedResponse | undefined;
+    patchDiff: string | undefined;
+    report: string | undefined;
+    failure: HarnessFailure | undefined;
+    cancelReason: string | undefined;
+    cancelledAtState: HarnessStateName | undefined;
+}
+export interface StateStep {
+    readonly to: HarnessStateName;
+    readonly reason: string;
+}
+export declare function newCounters(): RunCounters;
+export declare function contextBytes(messages: readonly ChatMessage[]): number;

package/dist/harness/context.js

@@ -0,0 +1,21 @@
+// Mutable run state shared across the state handlers. Created once per run by the loop;
+// handlers read ports/limits/clock and mutate counters, the message accumulator, and the
+// terminal-outcome carriers (patchDiff, report, failure). Keeping this in one place lets
+// each handler file stay small and free of cross-handler imports.
+import { Emitter } from "./emitter.js";
+export function newCounters() {
+    return {
+        iterations: 0,
+        modelCalls: 0,
+        toolCalls: 0,
+        commandExecutions: 0,
+        failureAttempts: 0,
+        browserNavigations: 0,
+    };
+}
+// UTF-8 byte length of the serialised message array — the zero-dependency context-size
+// proxy (ADR-0004 D3). Tokens require a model-specific tokeniser; bytes do not.
+const encoder = new TextEncoder();
+export function contextBytes(messages) {
+    return encoder.encode(JSON.stringify(messages)).length;
+}

package/dist/harness/emitter.d.ts

@@ -0,0 +1,15 @@
+import type { Clock } from "../gateway/types.js";
+import type { EventSink } from "./ports.js";
+import type { HarnessEvent } from "./types.js";
+type IdentityField = "schemaVersion" | "runId" | "fingerprint" | "seq" | "ts";
+type EventBody = HarnessEvent extends infer E ? E extends HarnessEvent ? Omit<E, IdentityField> : never : never;
+export declare class Emitter {
+    private readonly sinks;
+    private readonly clock;
+    private readonly runId;
+    private readonly fingerprint;
+    private seq;
+    constructor(sinks: readonly EventSink[], clock: Clock, runId: string, fingerprint: string);
+    emit(body: EventBody): void;
+}
+export {};

package/dist/harness/emitter.js

@@ -0,0 +1,72 @@
+// Stamps every harness event with run identity, a monotonic seq, and a clock timestamp,
+// then forwards it to the sink. SENSITIVE fields (rationale, modelResponse, diff) are
+// redacted before forwarding UNLESS the sink retains raw content for replay (ADR-0004 D6).
+import { redact } from "../gateway/redaction.js";
+function redactReasoningTrace(event) {
+    return {
+        ...event,
+        rationale: redact(event.rationale),
+        ...(event.modelResponse === undefined ? {} : { modelResponse: redact(event.modelResponse) }),
+    };
+}
+function redactRunCompleted(event) {
+    // WHY: report and patchDiff carry full model output; keep known secret formats out of every
+    // sink that does not explicitly retain raw content for replay.
+    return {
+        ...event,
+        report: redact(event.report),
+        ...(event.patchDiff === undefined ? {} : { patchDiff: redact(event.patchDiff) }),
+    };
+}
+function redactRunFailed(event) {
+    const failure = {
+        ...event.failure,
+        message: redact(event.failure.message),
+        ...(event.failure.detail === undefined ? {} : { detail: redact(event.failure.detail) }),
+    };
+    return { ...event, failure };
+}
+const REDACTORS = {
+    "reasoning:trace": redactReasoningTrace,
+    "patch:proposed": (event) => ({ ...event, diff: redact(event.diff) }),
+    "model:call:failed": (event) => ({ ...event, message: redact(event.message) }),
+    "tool:call:failed": (event) => ({ ...event, message: redact(event.message) }),
+    "verification:result": (event) => ({ ...event, detail: redact(event.detail) }),
+    "run:completed": redactRunCompleted,
+    "run:cancelled": (event) => event.reason === undefined ? event : { ...event, reason: redact(event.reason) },
+    "run:failed": redactRunFailed,
+};
+function redactSensitive(event) {
+    const redactor = REDACTORS[event.type];
+    return redactor === undefined ? event : redactor(event);
+}
+export class Emitter {
+    sinks;
+    clock;
+    runId;
+    fingerprint;
+    seq = 0;
+    // Fans every event out to all sinks. Each sink receives raw SENSITIVE fields only if it
+    // declares `retainsRawContent`; otherwise it receives a redacted copy.
+    constructor(sinks, clock, runId, fingerprint) {
+        this.sinks = sinks;
+        this.clock = clock;
+        this.runId = runId;
+        this.fingerprint = fingerprint;
+    }
+    emit(body) {
+        this.seq += 1;
+        const event = {
+            schemaVersion: "1",
+            runId: this.runId,
+            fingerprint: this.fingerprint,
+            seq: this.seq,
+            ts: this.clock.now(),
+            ...body,
+        };
+        const redacted = redactSensitive(event);
+        for (const sink of this.sinks) {
+            sink.emit(sink.retainsRawContent === true ? event : redacted);
+        }
+    }
+}

package/dist/harness/errors.d.ts

@@ -0,0 +1,21 @@
+import { HARNESS_CODES, type HarnessCode, type HarnessFailure } from "./types.js";
+export { HARNESS_CODES };
+export type { HarnessCode };
+export declare abstract class HarnessError extends Error {
+    abstract readonly code: HarnessCode;
+    constructor(message: string, secrets?: readonly string[]);
+}
+export declare class LimitExceededError extends HarnessError {
+    readonly code: HarnessCode;
+    constructor(code: HarnessCode, message: string, secrets?: readonly string[]);
+}
+export declare class HarnessModelError extends HarnessError {
+    readonly code: "HARNESS_MODEL_ERROR";
+}
+export declare class HarnessToolError extends HarnessError {
+    readonly code: "HARNESS_TOOL_ERROR";
+}
+export declare class HarnessInternalError extends HarnessError {
+    readonly code: "HARNESS_INTERNAL";
+}
+export declare function toFailure(category: HarnessCode, message: string, detail?: string): HarnessFailure;

package/dist/harness/errors.js

@@ -0,0 +1,39 @@
+// Harness error taxonomy, mirroring the gateway pattern (ADR-0003). Errors carry a
+// stable `code` discriminant; callers switch on `code`, never parse `message`.
+// Messages are redacted at construction so they are always safe to log.
+import { redact } from "../gateway/redaction.js";
+import { HARNESS_CODES } from "./types.js";
+export { HARNESS_CODES };
+export class HarnessError extends Error {
+    constructor(message, secrets = []) {
+        super(redact(message, secrets));
+        this.name = new.target.name;
+    }
+}
+// Raised when a configured safety limit is breached. Carries the precise category so
+// the loop can map it onto a `limit-exceeded` terminal state with a typed failure.
+export class LimitExceededError extends HarnessError {
+    code;
+    constructor(code, message, secrets = []) {
+        super(message, secrets);
+        this.code = code;
+    }
+}
+// Raised for a non-recoverable model-port error after retries are exhausted.
+export class HarnessModelError extends HarnessError {
+    code = HARNESS_CODES.MODEL_ERROR;
+}
+// Raised for a non-recoverable tool-port error.
+export class HarnessToolError extends HarnessError {
+    code = HARNESS_CODES.TOOL_ERROR;
+}
+// Raised for an unexpected harness-internal invariant violation (e.g. an explain-plan
+// task receiving a tool_calls finishReason, which the read-only path forbids).
+export class HarnessInternalError extends HarnessError {
+    code = HARNESS_CODES.INTERNAL;
+}
+// Builds the machine-readable failure record carried on the run result and the
+// `run:failed` event. `detail` is SENSITIVE and must be redacted before persistence.
+export function toFailure(category, message, detail) {
+    return detail === undefined ? { category, message } : { category, message, detail };
+}

package/dist/harness/executor.d.ts

@@ -0,0 +1,3 @@
+import { type RunContext, type StateStep } from "./context.js";
+export declare function handleModelCall(ctx: RunContext): Promise<StateStep>;
+export declare function handleToolCall(ctx: RunContext): Promise<StateStep>;

package/dist/harness/executor.js

@@ -0,0 +1,211 @@
+// Handlers for the model-call and tool-call states. The harness — not the model — owns
+// control flow: it inspects finishReason and toolCalls and decides the next state. A model
+// response is never executed as an instruction (ADR-0004 D1).
+import { CancelledError, GatewayError } from "../gateway/errors.js";
+import { ToolError } from "../tools/errors.js";
+import { WorkspaceError } from "../workspace/errors.js";
+import { contextBytes } from "./context.js";
+import { HARNESS_CODES, toFailure } from "./errors.js";
+const RUN_COMMAND_TOOL = "run_command";
+function toolFailureCode(error) {
+    if (error instanceof ToolError || error instanceof WorkspaceError) {
+        return error.code;
+    }
+    return "TOOL_ERROR";
+}
+function buildRequest(ctx) {
+    const tools = ctx.plan.allowsTools ? ctx.tools.listTools() : undefined;
+    return tools === undefined
+        ? { modelId: ctx.modelId, messages: ctx.messages }
+        : { modelId: ctx.modelId, messages: ctx.messages, tools };
+}
+function routeAfterModel(ctx, response) {
+    if (response.finishReason === "tool_calls") {
+        if (!ctx.plan.allowsTools) {
+            ctx.failure = toFailure(HARNESS_CODES.INTERNAL, "model requested tool calls on a read-only task type");
+            return { to: "failed", reason: "tool_calls finishReason forbidden for this task type" };
+        }
+        return { to: "tool-call", reason: "model requested tool calls" };
+    }
+    if (ctx.plan.allowsPatch) {
+        return { to: "patch-proposal", reason: "model produced final content; assembling patch" };
+    }
+    return { to: "reporting", reason: "model produced final content; read-only task" };
+}
+function onModelError(ctx, error) {
+    if (ctx.signal.aborted || error instanceof CancelledError) {
+        if (ctx.failure?.category === HARNESS_CODES.LIMIT_WALL_TIME) {
+            return { to: "limit-exceeded", reason: "maxWallTimeMs exceeded during model call" };
+        }
+        return { to: "cancelled", reason: "abort detected during model call" };
+    }
+    const code = error instanceof GatewayError ? error.code : "UNKNOWN";
+    const message = error instanceof Error ? error.message : "model call failed";
+    ctx.emitter.emit({ type: "model:call:failed", modelId: ctx.modelId, errorCode: code, message });
+    const retryable = error instanceof GatewayError && error.retryable;
+    if (!retryable) {
+        ctx.failure = toFailure(HARNESS_CODES.MODEL_ERROR, message);
+        return { to: "failed", reason: "non-retryable model error" };
+    }
+    ctx.counters.failureAttempts += 1;
+    if (ctx.counters.failureAttempts >= ctx.limits.maxFailureAttempts) {
+        ctx.failure = toFailure(HARNESS_CODES.LIMIT_FAILURE_ATTEMPTS, "max failure attempts reached");
+        return { to: "limit-exceeded", reason: "maxFailureAttempts exceeded" };
+    }
+    return { to: "planning", reason: "retryable model error; re-planning" };
+}
+export async function handleModelCall(ctx) {
+    ctx.counters.modelCalls += 1;
+    ctx.emitter.emit({
+        type: "model:call:started",
+        modelId: ctx.modelId,
+        messageCount: ctx.messages.length,
+        contextBytes: contextBytes(ctx.messages),
+    });
+    let response;
+    try {
+        response = await ctx.model.call(buildRequest(ctx), ctx.signal);
+    }
+    catch (error) {
+        return onModelError(ctx, error);
+    }
+    ctx.emitter.emit({
+        type: "model:call:completed",
+        modelId: ctx.modelId,
+        finishReason: response.finishReason,
+        toolCallCount: response.toolCalls.length,
+        usage: {
+            requestId: response.usage.requestId,
+            promptTokens: response.usage.promptTokens,
+            completionTokens: response.usage.completionTokens,
+            latencyMs: response.usage.latencyMs,
+        },
+    });
+    ctx.emitter.emit({
+        type: "reasoning:trace",
+        phase: "model-call",
+        rationale: "evaluated model response and selected next state",
+        modelResponse: response.content,
+    });
+    ctx.messages = [...ctx.messages, assistantMessage(response)];
+    ctx.lastResponse = response;
+    return routeAfterModel(ctx, response);
+}
+function assistantMessage(response) {
+    return response.toolCalls.length === 0
+        ? { role: "assistant", content: response.content }
+        : { role: "assistant", content: response.content, toolCalls: response.toolCalls };
+}
+// S-M1: emits the redacted audit event matching a tool's metadata, in addition to
+// tool:call:completed, so the issue #10 ledger sees THAT a command ran / a patch applied — never
+// the args, stdout, or file paths. No-op when the tool returned no metadata (read-only tools).
+function emitToolMetadata(ctx, metadata, durationMs) {
+    if (metadata === undefined) {
+        return;
+    }
+    if (metadata.kind === "command") {
+        ctx.emitter.emit({
+            type: "sandbox:configured",
+            envAllowlist: metadata.sandbox.envAllowlist,
+            network: metadata.sandbox.network,
+            maxOutputBytes: metadata.sandbox.maxOutputBytes,
+            timeoutMs: metadata.sandbox.timeoutMs,
+            terminationGraceMs: metadata.sandbox.terminationGraceMs,
+            cwdRequested: metadata.sandbox.cwdRequested,
+        });
+        ctx.emitter.emit({
+            type: "command:executed",
+            executable: metadata.executable,
+            argCount: metadata.argCount,
+            exitCode: metadata.exitCode,
+            timedOut: metadata.timedOut,
+            durationMs,
+        });
+        return;
+    }
+    ctx.emitter.emit({
+        type: "patch:applied",
+        changedFiles: metadata.changedFiles,
+        created: metadata.created,
+        deleted: metadata.deleted,
+    });
+}
+function abortStep(ctx, reason) {
+    if (ctx.failure?.category === HARNESS_CODES.LIMIT_WALL_TIME) {
+        return { to: "limit-exceeded", reason: "maxWallTimeMs exceeded during tool call" };
+    }
+    return { to: "cancelled", reason };
+}
+function commandBudgetExceeded(ctx) {
+    ctx.failure = toFailure(HARNESS_CODES.LIMIT_COMMAND_EXEC, "command-execution budget exhausted");
+    return { to: "limit-exceeded", reason: "maxCommandExecutions exceeded" };
+}
+function toolOutputBudgetExceeded(ctx, bytes) {
+    ctx.failure = toFailure(HARNESS_CODES.LIMIT_CONTEXT_SIZE, `context ${String(bytes)} bytes exceeds limit ${String(ctx.limits.maxContextBytes)}`);
+    return { to: "limit-exceeded", reason: "maxContextBytes exceeded after tool output" };
+}
+function isStateStep(value) {
+    return "to" in value;
+}
+async function runOneTool(ctx, call) {
+    ctx.counters.toolCalls += 1;
+    ctx.emitter.emit({ type: "tool:call:started", toolName: call.name, toolCallId: call.id });
+    try {
+        const result = await ctx.tools.execute({
+            toolCallId: call.id,
+            toolName: call.name,
+            arguments: call.arguments,
+            signal: ctx.signal,
+        });
+        if (result.commandExecuted === true) {
+            ctx.counters.commandExecutions += 1;
+        }
+        ctx.emitter.emit({
+            type: "tool:call:completed",
+            toolName: call.name,
+            toolCallId: call.id,
+            durationMs: result.durationMs,
+        });
+        emitToolMetadata(ctx, result.metadata, result.durationMs);
+        return { role: "tool", content: result.output, toolCallId: call.id };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "tool execution failed";
+        ctx.emitter.emit({
+            type: "tool:call:failed",
+            toolName: call.name,
+            toolCallId: call.id,
+            errorCode: toolFailureCode(error),
+            message,
+        });
+        if (ctx.signal.aborted || error instanceof CancelledError) {
+            return abortStep(ctx, "abort detected during tool call");
+        }
+        ctx.failure = toFailure(HARNESS_CODES.TOOL_ERROR, message);
+        return { to: "failed", reason: "tool execution failed" };
+    }
+}
+export async function handleToolCall(ctx) {
+    const calls = ctx.lastResponse?.toolCalls ?? [];
+    const results = [];
+    for (const call of calls) {
+        if (ctx.signal.aborted) {
+            return abortStep(ctx, "abort detected before tool call");
+        }
+        if (call.name === RUN_COMMAND_TOOL &&
+            ctx.counters.commandExecutions >= ctx.limits.maxCommandExecutions) {
+            return commandBudgetExceeded(ctx);
+        }
+        const result = await runOneTool(ctx, call);
+        if (isStateStep(result)) {
+            return result;
+        }
+        const bytes = contextBytes([...ctx.messages, ...results, result]);
+        if (bytes > ctx.limits.maxContextBytes) {
+            return toolOutputBudgetExceeded(ctx, bytes);
+        }
+        results.push(result);
+    }
+    ctx.messages = [...ctx.messages, ...results];
+    return { to: "model-call", reason: "tool results fed back to model" };
+}

package/dist/harness/fingerprint.d.ts

@@ -0,0 +1,6 @@
+import type { Fingerprinter, FingerprintInput, IdSource } from "./ports.js";
+export declare function canonicalise(value: unknown): string;
+export declare function configFingerprint(input: FingerprintInput): string;
+export declare const defaultFingerprinter: Fingerprinter;
+export declare const defaultIdSource: IdSource;
+export declare function counterIdSource(): IdSource;

package/dist/harness/fingerprint.js

@@ -0,0 +1,43 @@
+// Deterministic run-ID and configuration-fingerprint sources. Production uses
+// node:crypto (randomUUID, SHA-256); tests inject a counter so IDs are fixed and
+// runs are reproducible for replay (ADR-0004 D7).
+import { createHash, randomUUID } from "node:crypto";
+// Canonical JSON: object keys sorted recursively, array order preserved, undefined
+// values omitted (matching JSON.stringify semantics). Two structurally equal configs
+// thus serialise to byte-identical strings regardless of key insertion order.
+export function canonicalise(value) {
+    if (value === undefined) {
+        return "null";
+    }
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => canonicalise(item)).join(",")}]`;
+    }
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([key, v]) => `${JSON.stringify(key)}:${canonicalise(v)}`);
+    return `{${entries.join(",")}}`;
+}
+export function configFingerprint(input) {
+    const canonical = canonicalise(input);
+    return createHash("sha256").update(canonical, "utf8").digest("hex");
+}
+export const defaultFingerprinter = {
+    compute: configFingerprint,
+};
+export const defaultIdSource = {
+    newRunId: () => randomUUID(),
+};
+// Test/replay helper: deterministic monotonically increasing run IDs.
+export function counterIdSource() {
+    let n = 0;
+    return {
+        newRunId: () => {
+            n += 1;
+            return `run-${String(n)}`;
+        },
+    };
+}

package/dist/harness/index.d.ts

@@ -0,0 +1,9 @@
+export { createSession, HARNESS_VERSION, type AgentConfig, type AgentSession, type HarnessDeps, } from "./session.js";
+export { createSession as runAgent } from "./session.js";
+export { DEFAULT_LIMITS, HARNESS_CODES, TERMINAL_STATES, type ExplainPlanInput, type GenerateUnitTestsInput, type HarnessCode, type HarnessEvent, type HarnessFailure, type HarnessLimits, type HarnessStateName, type InvestigateBugInput, type ModelCallCompletedEvent, type ModelCallFailedEvent, type ModelCallStartedEvent, type PatchProposedEvent, type ReasoningTraceEvent, type RunCancelledEvent, type RunCompletedEvent, type RunCounters, type RunFailedEvent, type RunManifest, type RunOutcome, type RunResult, type RunStartedEvent, type StateTransition, type StateTransitionEvent, type TaskInput, type TaskType, type TerminalState, type ToolCallCompletedEvent, type ToolCallFailedEvent, type ToolCallStartedEvent, type VerificationResultEvent, } from "./types.js";
+export { HarnessError, HarnessInternalError, HarnessModelError, HarnessToolError, LimitExceededError, toFailure, } from "./errors.js";
+export type { EventSink, Fingerprinter, FingerprintInput, IdSource, ModelPort, ToolCallRequest, ToolCallResult, ToolPort, } from "./ports.js";
+export { DryRunToolPort, GatewayModelPort, type ChatModel, type RecordedToolCall, } from "./adapters.js";
+export { CliEventSink, MemoryEventSink, type EventWriter, type ManifestSeed } from "./sinks.js";
+export { canonicalise, configFingerprint, counterIdSource, defaultFingerprinter, defaultIdSource, } from "./fingerprint.js";
+export { resolveTaskPlan, type TaskPlan } from "./tasks/policy.js";

package/dist/harness/index.js

@@ -0,0 +1,13 @@
+// Public barrel for the agent harness: the session API, all ports/adapters/sinks, the
+// task types, the event schema, the limit/error taxonomy, and the deterministic ID and
+// fingerprint sources. Downstream issues (#6 tools, #10 audit, #13 UI) depend only on
+// these typed seams (ADR-0004 D2).
+export { createSession, HARNESS_VERSION, } from "./session.js";
+// runAgent is the ergonomic SDK alias of createSession; both start a bounded run.
+export { createSession as runAgent } from "./session.js";
+export { DEFAULT_LIMITS, HARNESS_CODES, TERMINAL_STATES, } from "./types.js";
+export { HarnessError, HarnessInternalError, HarnessModelError, HarnessToolError, LimitExceededError, toFailure, } from "./errors.js";
+export { DryRunToolPort, GatewayModelPort, } from "./adapters.js";
+export { CliEventSink, MemoryEventSink } from "./sinks.js";
+export { canonicalise, configFingerprint, counterIdSource, defaultFingerprinter, defaultIdSource, } from "./fingerprint.js";
+export { resolveTaskPlan } from "./tasks/policy.js";

package/dist/harness/loop.d.ts

@@ -0,0 +1,3 @@
+import { type RunContext } from "./context.js";
+import { type RunOutcome } from "./types.js";
+export declare function runLoop(ctx: RunContext): Promise<RunOutcome>;

package/dist/harness/loop.js

@@ -0,0 +1,159 @@
+// The state-machine driver. The harness owns all control flow: it checks abort and limit
+// guards at the top of the loop and before each port call, dispatches the current state to
+// its handler, and emits a state:transition before every change (ADR-0004 D1, D3, D4).
+import { HARNESS_CODES, toFailure } from "./errors.js";
+import { contextBytes } from "./context.js";
+import { handleModelCall, handleToolCall } from "./executor.js";
+import { handlePatchProposal, handleReporting, handleVerification } from "./patcher.js";
+import { handleContextSelection, handlePlanning } from "./planner.js";
+import { TERMINAL_STATES } from "./types.js";
+const MAX_LOOP_STEPS = 10_000; // absolute safety net; bounded states make this unreachable.
+function abortStep(reason) {
+    return { to: "cancelled", reason };
+}
+function checkWallTime(ctx) {
+    if (ctx.clock.now() - ctx.startedAt > ctx.limits.maxWallTimeMs) {
+        ctx.failure = toFailure(HARNESS_CODES.LIMIT_WALL_TIME, "wall-time budget exhausted");
+        return { to: "limit-exceeded", reason: "maxWallTimeMs exceeded" };
+    }
+    return null;
+}
+// Limit checks evaluated when re-entering planning (iterations) plus the wall-time gate for
+// the run as a whole.
+function checkLoopLimits(ctx) {
+    const wallTime = checkWallTime(ctx);
+    if (wallTime !== null) {
+        return wallTime;
+    }
+    if (ctx.counters.iterations >= ctx.limits.maxIterations) {
+        ctx.failure = toFailure(HARNESS_CODES.LIMIT_ITERATIONS, "iteration budget exhausted");
+        return { to: "limit-exceeded", reason: "maxIterations exceeded" };
+    }
+    return null;
+}
+// Context-size and model-call-count checks, evaluated at every model-call entry so the
+// limit bounds calls that follow tool-call (not only the initial context-selection path).
+function checkModelCallLimits(ctx) {
+    if (ctx.counters.modelCalls >= ctx.limits.maxModelCalls) {
+        ctx.failure = toFailure(HARNESS_CODES.LIMIT_MODEL_CALLS, "model-call budget exhausted");
+        return { to: "limit-exceeded", reason: "maxModelCalls exceeded" };
+    }
+    const bytes = contextBytes(ctx.messages);
+    if (bytes > ctx.limits.maxContextBytes) {
+        ctx.failure = toFailure(HARNESS_CODES.LIMIT_CONTEXT_SIZE, `context ${String(bytes)} bytes exceeds limit ${String(ctx.limits.maxContextBytes)}`);
+        return { to: "limit-exceeded", reason: "maxContextBytes exceeded" };
+    }
+    return null;
+}
+// Per-state-entry guards: abort is honoured before any state; call-count limits are
+// enforced immediately before the state that consumes the bounded resource.
+function checkEntryGuards(ctx, state) {
+    const wallTime = checkWallTime(ctx);
+    if (wallTime !== null) {
+        return wallTime;
+    }
+    if (ctx.signal.aborted) {
+        return abortStep("abort detected before state entry");
+    }
+    if (state === "model-call") {
+        return checkModelCallLimits(ctx);
+    }
+    if (state === "tool-call") {
+        return checkToolLimits(ctx);
+    }
+    return null;
+}
+function checkToolLimits(ctx) {
+    const pending = ctx.lastResponse?.toolCalls.length ?? 0;
+    if (ctx.counters.toolCalls + pending > ctx.limits.maxToolCalls) {
+        ctx.failure = toFailure(HARNESS_CODES.LIMIT_TOOL_CALLS, "tool-call budget exhausted");
+        return { to: "limit-exceeded", reason: "maxToolCalls exceeded" };
+    }
+    if (ctx.counters.commandExecutions >= ctx.limits.maxCommandExecutions) {
+        ctx.failure = toFailure(HARNESS_CODES.LIMIT_COMMAND_EXEC, "command-execution budget exhausted");
+        return { to: "limit-exceeded", reason: "maxCommandExecutions exceeded" };
+    }
+    return null;
+}
+async function dispatch(ctx, state) {
+    switch (state) {
+        case "planning":
+            ctx.counters.iterations += 1;
+            return handlePlanning(ctx);
+        case "context-selection":
+            return handleContextSelection(ctx);
+        case "model-call":
+            return handleModelCall(ctx);
+        case "tool-call":
+            return handleToolCall(ctx);
+        case "patch-proposal":
+            return handlePatchProposal(ctx);
+        case "verification":
+            return handleVerification(ctx);
+        case "reporting":
+            return handleReporting(ctx);
+        default:
+            ctx.failure = toFailure(HARNESS_CODES.INTERNAL, `no handler for state ${state}`);
+            return { to: "failed", reason: "internal: unhandled state" };
+    }
+}
+function transition(ctx, from, step) {
+    if (step.to === "cancelled") {
+        ctx.cancelledAtState = from;
+    }
+    ctx.emitter.emit({ type: "state:transition", from, to: step.to, reason: step.reason });
+    return step.to;
+}
+function emitTerminal(ctx, state) {
+    if (state === "completed") {
+        ctx.emitter.emit({
+            type: "run:completed",
+            report: ctx.report ?? "no model output",
+            ...(ctx.patchDiff === undefined ? {} : { patchDiff: ctx.patchDiff }),
+        });
+        return;
+    }
+    if (state === "cancelled") {
+        ctx.emitter.emit({
+            type: "run:cancelled",
+            atState: ctx.cancelledAtState ?? state,
+            ...(ctx.cancelReason === undefined ? {} : { reason: ctx.cancelReason }),
+        });
+        return;
+    }
+    if (state === "failed" || state === "limit-exceeded") {
+        const failure = ctx.failure ?? toFailure(HARNESS_CODES.INTERNAL, "run failed without a failure record");
+        ctx.failure = failure;
+        ctx.emitter.emit({ type: "run:failed", failure, atState: state });
+    }
+}
+// Runs the state machine from `intake` to a terminal state and returns the outcome.
+export async function runLoop(ctx) {
+    let state = transition(ctx, "intake", {
+        to: "planning",
+        reason: "task validated",
+    });
+    for (let step = 0; step < MAX_LOOP_STEPS && !TERMINAL_STATES.has(state); step += 1) {
+        if (ctx.signal.aborted) {
+            state = transition(ctx, state, abortStep("abort detected at top of loop"));
+            break;
+        }
+        const guard = state === "planning" ? checkLoopLimits(ctx) : checkEntryGuards(ctx, state);
+        if (guard !== null) {
+            state = transition(ctx, state, guard);
+            continue;
+        }
+        const dispatched = await dispatch(ctx, state);
+        const postDispatchGuard = checkWallTime(ctx);
+        state = transition(ctx, state, postDispatchGuard ?? dispatched);
+    }
+    if (!TERMINAL_STATES.has(state)) {
+        ctx.failure = toFailure(HARNESS_CODES.INTERNAL, "state-machine safety step limit exceeded");
+        state = transition(ctx, state, {
+            to: "failed",
+            reason: "internal: state-machine step limit exceeded",
+        });
+    }
+    emitTerminal(ctx, state);
+    return state;
+}

package/dist/harness/patcher.d.ts

@@ -0,0 +1,4 @@
+import type { RunContext, StateStep } from "./context.js";
+export declare function handlePatchProposal(ctx: RunContext): StateStep;
+export declare function handleVerification(ctx: RunContext): StateStep;
+export declare function handleReporting(ctx: RunContext): StateStep;