@oscharko-dev/keiko-harness 0.2.0

package/dist/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 "@oscharko-dev/keiko-model-gateway";
+import { ToolError } from "@oscharko-dev/keiko-tools";
+import { WorkspaceError } from "@oscharko-dev/keiko-workspace";
+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/fingerprint.d.ts

@@ -0,0 +1,8 @@
+import { canonicalise } from "@oscharko-dev/keiko-security";
+import type { Fingerprinter, FingerprintInput, IdSource } from "./ports.js";
+export declare function configFingerprint(input: FingerprintInput): string;
+export declare const defaultFingerprinter: Fingerprinter;
+export declare const defaultIdSource: IdSource;
+export declare function counterIdSource(): IdSource;
+export { canonicalise };
+//# sourceMappingURL=fingerprint.d.ts.map

package/dist/fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.d.ts","sourceRoot":"","sources":["../src/fingerprint.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,YAAY,EAAa,MAAM,8BAA8B,CAAC;AACvE,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE5E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAEjE;AAED,eAAO,MAAM,oBAAoB,EAAE,aAElC,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,QAE7B,CAAC;AAGF,wBAAgB,eAAe,IAAI,QAAQ,CAQ1C;AAID,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/fingerprint.js

@@ -0,0 +1,28 @@
+// Deterministic run-ID and configuration-fingerprint sources. Production uses
+// node:crypto (randomUUID) for the random ID source and the shared security-package
+// hashing primitives (canonical-JSON + SHA-256 hex) for the config fingerprint; tests
+// inject a counter so IDs are fixed and runs are reproducible for replay (ADR-0004 D7).
+import { randomUUID } from "node:crypto";
+import { canonicalise, sha256Hex } from "@oscharko-dev/keiko-security";
+export function configFingerprint(input) {
+    return sha256Hex(canonicalise(input));
+}
+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)}`;
+        },
+    };
+}
+// Re-export the canonical-JSON serialiser at its historical name for any caller that still imports
+// it from this module. The implementation now lives in @oscharko-dev/keiko-security/hashing.
+export { canonicalise };

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { KEIKO_HARNESS_VERSION } from "./version.js";
+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, ToolCallMetadata, 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";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,EACL,aAAa,EACb,eAAe,EACf,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,WAAW,GACjB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,aAAa,IAAI,QAAQ,EAAE,MAAM,cAAc,CAAC;AAEzD,OAAO,EACL,cAAc,EACd,aAAa,EACb,eAAe,EACf,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,GAC7B,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,SAAS,GACV,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,QAAQ,EACR,SAAS,EACT,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,QAAQ,GACT,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,KAAK,SAAS,EACd,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAEhG,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,eAAe,EAAE,KAAK,QAAQ,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+// 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 tools, evidence, UI, and evaluation code depend only
+// on these typed seams (ADR-0004 D2).
+export { KEIKO_HARNESS_VERSION } from "./version.js";
+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/loop.d.ts

@@ -0,0 +1,4 @@
+import { type RunContext } from "./context.js";
+import { type RunOutcome } from "./types.js";
+export declare function runLoop(ctx: RunContext): Promise<RunOutcome>;
+//# sourceMappingURL=loop.d.ts.map

package/dist/loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../src/loop.ts"],"names":[],"mappings":"AAKA,OAAO,EAAgB,KAAK,UAAU,EAAkB,MAAM,cAAc,CAAC;AAI7E,OAAO,EAA0C,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAyIrF,wBAAsB,OAAO,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CA4BlE"}

package/dist/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/patcher.d.ts

@@ -0,0 +1,5 @@
+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;
+//# sourceMappingURL=patcher.d.ts.map

package/dist/patcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patcher.d.ts","sourceRoot":"","sources":["../src/patcher.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAQ1D,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,UAAU,GAAG,SAAS,CAkB9D;AAID,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,UAAU,GAAG,SAAS,CAgB7D;AAID,wBAAgB,eAAe,CAAC,GAAG,EAAE,UAAU,GAAG,SAAS,CAG1D"}

package/dist/patcher.js

@@ -0,0 +1,49 @@
+// Handlers for the patch-proposal, verification, and reporting states. The harness NEVER
+// applies a patch: the diff is emitted as a patch:proposed event and carried on the run
+// result. Nothing here touches the file system (ADR-0004 D8, dry-run by default).
+import { HARNESS_CODES, toFailure } from "./errors.js";
+const encoder = new TextEncoder();
+function patchByteLength(diff) {
+    return encoder.encode(diff).length;
+}
+export function handlePatchProposal(ctx) {
+    const diff = ctx.lastResponse?.content ?? "";
+    const bytes = patchByteLength(diff);
+    if (bytes > ctx.limits.maxPatchBytes) {
+        ctx.failure = toFailure(HARNESS_CODES.LIMIT_PATCH_SIZE, `patch ${String(bytes)} bytes exceeds limit ${String(ctx.limits.maxPatchBytes)}`);
+        return { to: "limit-exceeded", reason: "maxPatchBytes exceeded" };
+    }
+    ctx.patchDiff = diff;
+    ctx.emitter.emit({
+        type: "patch:proposed",
+        targetFile: ctx.plan.targetFile,
+        patchBytes: bytes,
+        diff,
+    });
+    return { to: "verification", reason: "patch assembled and proposed (not applied)" };
+}
+// Wave-1 verification is a structural check: a proposed patch must be non-empty. Real test/
+// command verification arrives with the tool execution layer (issue #6).
+export function handleVerification(ctx) {
+    const passed = (ctx.patchDiff ?? "").trim().length > 0;
+    ctx.emitter.emit({
+        type: "verification:result",
+        passed,
+        detail: passed ? "non-empty patch produced" : "empty patch",
+    });
+    if (passed) {
+        return { to: "reporting", reason: "verification passed" };
+    }
+    ctx.counters.failureAttempts += 1;
+    if (ctx.counters.failureAttempts >= ctx.limits.maxFailureAttempts) {
+        ctx.failure = toFailure(HARNESS_CODES.LIMIT_FAILURE_ATTEMPTS, "verification kept failing");
+        return { to: "limit-exceeded", reason: "maxFailureAttempts exceeded after verification" };
+    }
+    return { to: "planning", reason: "verification failed; re-planning" };
+}
+// Records the final report on the context. The run:completed event is emitted by the loop
+// once the terminal `completed` state is reached, so it is the last event in the stream.
+export function handleReporting(ctx) {
+    ctx.report = ctx.lastResponse?.content ?? "no model output";
+    return { to: "completed", reason: "report generated" };
+}

package/dist/planner.d.ts

@@ -0,0 +1,4 @@
+import { type RunContext, type StateStep } from "./context.js";
+export declare function handlePlanning(ctx: RunContext): StateStep;
+export declare function handleContextSelection(ctx: RunContext): StateStep;
+//# sourceMappingURL=planner.d.ts.map

package/dist/planner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner.d.ts","sourceRoot":"","sources":["../src/planner.ts"],"names":[],"mappings":"AAKA,OAAO,EAAgB,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAE7E,wBAAgB,cAAc,CAAC,GAAG,EAAE,UAAU,GAAG,SAAS,CAOzD;AAED,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,UAAU,GAAG,SAAS,CAUjE"}

package/dist/planner.js

@@ -0,0 +1,21 @@
+// Handlers for the planning and context-selection states. Planning emits the task
+// rationale as a reasoning:trace. Context-selection finalises the message array and
+// enforces maxContextBytes before any model call (ADR-0004 D3 enforcement point).
+import { HARNESS_CODES, toFailure } from "./errors.js";
+import { contextBytes } from "./context.js";
+export function handlePlanning(ctx) {
+    ctx.emitter.emit({
+        type: "reasoning:trace",
+        phase: "planning",
+        rationale: ctx.plan.rationale,
+    });
+    return { to: "context-selection", reason: "plan constructed" };
+}
+export function handleContextSelection(ctx) {
+    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 { to: "model-call", reason: "context assembled within byte budget" };
+}

package/dist/ports.d.ts

@@ -0,0 +1,28 @@
+import type { GatewayRequest, GatewayStreamChunk, NormalizedResponse } from "@oscharko-dev/keiko-model-gateway";
+import type { ToolCallMetadata, ToolCallRequest, ToolCallResult, ToolPort } from "@oscharko-dev/keiko-contracts";
+import type { HarnessEvent, HarnessLimits, TaskInput, TaskType } from "./types.js";
+export type { ToolCallMetadata, ToolCallRequest, ToolCallResult, ToolPort };
+export interface ModelPort {
+    readonly call: (request: GatewayRequest, signal: AbortSignal) => Promise<NormalizedResponse>;
+    readonly callStream?: (request: GatewayRequest, signal: AbortSignal) => AsyncIterable<GatewayStreamChunk>;
+}
+export interface EventSink {
+    readonly emit: (event: HarnessEvent) => void;
+    readonly retainsRawContent?: boolean | undefined;
+}
+export interface IdSource {
+    readonly newRunId: () => string;
+}
+export interface FingerprintInput {
+    readonly taskType: TaskType;
+    readonly taskInput: TaskInput;
+    readonly limits: HarnessLimits;
+    readonly modelId: string;
+    readonly workingDirectory: string;
+    readonly dryRun: boolean;
+    readonly harnessVersion: string;
+}
+export interface Fingerprinter {
+    readonly compute: (input: FingerprintInput) => string;
+}
+//# sourceMappingURL=ports.d.ts.map

package/dist/ports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../src/ports.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,QAAQ,EACT,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEnF,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,cAAc,EAAE,QAAQ,EAAE,CAAC;AAE5E,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAK7F,QAAQ,CAAC,UAAU,CAAC,EAAE,CACpB,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,WAAW,KAChB,aAAa,CAAC,kBAAkB,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IAI7C,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAClD;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,MAAM,CAAC;CACvD"}

package/dist/ports.js

@@ -0,0 +1,8 @@
+// Hexagonal port interfaces. The harness (high-level policy) depends only on these
+// abstractions, never on the concrete Gateway, file system, or terminal. Issues #6,
+// #10, and #13 each plug in their own implementations without touching the harness.
+//
+// The tool ports (ToolPort, ToolCallRequest, ToolCallResult, ToolCallMetadata) are
+// shared with the tools package via contracts. Re-export them here as part of the
+// harness package surface.
+export {};

package/dist/session.d.ts

@@ -0,0 +1,27 @@
+import { HARNESS_VERSION } from "@oscharko-dev/keiko-contracts";
+import type { Clock } from "@oscharko-dev/keiko-model-gateway";
+import type { EventSink, Fingerprinter, IdSource, ModelPort, ToolPort } from "./ports.js";
+import { type HarnessLimits, type RunResult, type TaskInput } from "./types.js";
+export { HARNESS_VERSION };
+export interface AgentConfig {
+    readonly model: string;
+    readonly workingDirectory: string;
+    readonly limits?: Partial<HarnessLimits> | undefined;
+    readonly dryRun?: boolean | undefined;
+}
+export interface HarnessDeps {
+    readonly model: ModelPort;
+    readonly tools: ToolPort;
+    readonly sink: EventSink;
+    readonly clock?: Clock | undefined;
+    readonly idSource?: IdSource | undefined;
+    readonly fingerprinter?: Fingerprinter | undefined;
+}
+export interface AgentSession {
+    readonly runId: string;
+    readonly fingerprint: string;
+    readonly result: Promise<RunResult>;
+    readonly cancel: (reason?: string) => void;
+}
+export declare function createSession(task: TaskInput, config: AgentConfig, deps: HarnessDeps): AgentSession;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mCAAmC,CAAC;AAO/D,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAG1F,OAAO,EAEL,KAAK,aAAa,EAElB,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,YAAY,CAAC;AAIpB,OAAO,EAAE,eAAe,EAAE,CAAC;AAE3B,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,SAAS,CAAC;IAGrD,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACvC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;CACpD;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5C;AA6FD,wBAAgB,aAAa,CAC3B,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,WAAW,GAChB,YAAY,CAqCd"}