@oscharko-dev/keiko 0.1.5 → 0.1.7

package/node_modules/@oscharko-dev/keiko-harness/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/node_modules/@oscharko-dev/keiko-harness/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/node_modules/@oscharko-dev/keiko-harness/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/node_modules/@oscharko-dev/keiko-harness/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/node_modules/@oscharko-dev/keiko-harness/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/node_modules/@oscharko-dev/keiko-harness/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/node_modules/@oscharko-dev/keiko-harness/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/node_modules/@oscharko-dev/keiko-harness/dist/ports.d.ts

@@ -0,0 +1,27 @@
+import type { GatewayRequest, 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>;
+}
+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/node_modules/@oscharko-dev/keiko-harness/dist/ports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../src/ports.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AAC5F,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;CAC9F;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/node_modules/@oscharko-dev/keiko-harness/dist/ports.js

@@ -0,0 +1,9 @@
+// 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) moved to
+// @oscharko-dev/keiko-contracts in issue #162: they are SHARED between the harness consumer
+// and the tools-package implementer, so both sides import from contracts. Re-exported here
+// so every existing `import ... from "../harness/ports.js"` keeps resolving unchanged.
+export {};

package/node_modules/@oscharko-dev/keiko-harness/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/node_modules/@oscharko-dev/keiko-harness/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"}

package/node_modules/@oscharko-dev/keiko-harness/dist/session.js

@@ -0,0 +1,119 @@
+// The public session/run API. createSession() builds the run context, kicks off the loop
+// asynchronously, and exposes the run id, config fingerprint, a result Promise, and a
+// cancel() that aborts the single per-run AbortController (ADR-0004 D4, D9).
+import { HARNESS_VERSION } from "@oscharko-dev/keiko-contracts";
+import { systemClock } from "@oscharko-dev/keiko-model-gateway/internal/resilience";
+import { newCounters } from "./context.js";
+import { Emitter } from "./emitter.js";
+import { HARNESS_CODES, toFailure } from "./errors.js";
+import { defaultFingerprinter, defaultIdSource } from "./fingerprint.js";
+import { runLoop } from "./loop.js";
+import { MemoryEventSink } from "./sinks.js";
+import { resolveTaskPlan } from "./tasks/policy.js";
+import { DEFAULT_LIMITS, } from "./types.js";
+// HARNESS_VERSION lives in @oscharko-dev/keiko-contracts (issue #162); re-exported here so
+// every existing `import { HARNESS_VERSION } from "../harness/session.js"` keeps resolving.
+export { HARNESS_VERSION };
+function resolveLimits(config) {
+    return { ...DEFAULT_LIMITS, ...config.limits };
+}
+function resolveDryRun(config) {
+    return config.dryRun ?? true;
+}
+function buildResult(ctx, outcome, sink, identity) {
+    return {
+        runId: identity.runId,
+        fingerprint: identity.fingerprint,
+        outcome,
+        taskType: ctx.taskType,
+        ...(ctx.report === undefined ? {} : { report: ctx.report }),
+        ...(ctx.patchDiff === undefined ? {} : { patchDiff: ctx.patchDiff }),
+        ...(ctx.failure === undefined ? {} : { failure: ctx.failure }),
+        startedAt: ctx.startedAt,
+        finishedAt: ctx.clock.now(),
+        events: sink.events(),
+    };
+}
+function buildContext(task, config, deps, signal, runId, fingerprint) {
+    const clock = deps.clock ?? systemClock;
+    const memory = new MemoryEventSink();
+    const plan = resolveTaskPlan(task);
+    const ctx = {
+        model: deps.model,
+        tools: deps.tools,
+        emitter: new Emitter([memory, deps.sink], clock, runId, fingerprint),
+        clock,
+        signal,
+        limits: resolveLimits(config),
+        modelId: config.model,
+        taskType: task.taskType,
+        plan,
+        startedAt: clock.now(),
+        counters: newCounters(),
+        messages: [...plan.messages],
+        lastResponse: undefined,
+        patchDiff: undefined,
+        report: undefined,
+        failure: undefined,
+        cancelReason: undefined,
+        cancelledAtState: undefined,
+    };
+    return { ctx, memory };
+}
+function armWallTimeDeadline(ctx, controller, clock) {
+    let cleared = false;
+    const deadlineController = new AbortController();
+    void clock
+        .sleep(ctx.limits.maxWallTimeMs, deadlineController.signal)
+        .then(() => {
+        if (cleared || controller.signal.aborted) {
+            return;
+        }
+        ctx.failure = toFailure(HARNESS_CODES.LIMIT_WALL_TIME, "wall-time budget exhausted");
+        ctx.cancelReason = "maxWallTimeMs exceeded";
+        controller.abort("maxWallTimeMs exceeded");
+    })
+        .catch(() => undefined);
+    return () => {
+        cleared = true;
+        deadlineController.abort("run finished");
+    };
+}
+export function createSession(task, config, deps) {
+    const limits = resolveLimits(config);
+    const dryRun = resolveDryRun(config);
+    const runId = (deps.idSource ?? defaultIdSource).newRunId();
+    const fingerprint = (deps.fingerprinter ?? defaultFingerprinter).compute({
+        taskType: task.taskType,
+        taskInput: task,
+        limits,
+        modelId: config.model,
+        workingDirectory: config.workingDirectory,
+        dryRun,
+        harnessVersion: HARNESS_VERSION,
+    });
+    const controller = new AbortController();
+    const { ctx, memory } = buildContext(task, config, deps, controller.signal, runId, fingerprint);
+    const clearDeadline = armWallTimeDeadline(ctx, controller, ctx.clock);
+    ctx.emitter.emit({
+        type: "run:started",
+        taskType: task.taskType,
+        modelId: config.model,
+        limits,
+    });
+    // Defer the loop to a microtask so a cancel() issued synchronously after createSession is
+    // observed at the loop's first abort check, before any model or tool call is made.
+    const result = Promise.resolve()
+        .then(() => runLoop(ctx))
+        .finally(clearDeadline)
+        .then((outcome) => buildResult(ctx, outcome, memory, { runId, fingerprint }));
+    return {
+        runId,
+        fingerprint,
+        result,
+        cancel: (reason) => {
+            ctx.cancelReason = reason;
+            controller.abort(reason);
+        },
+    };
+}

package/node_modules/@oscharko-dev/keiko-harness/dist/sinks.d.ts

@@ -0,0 +1,31 @@
+import type { EventSink } from "./ports.js";
+import type { HarnessEvent, RunManifest } from "./types.js";
+export interface EventWriter {
+    readonly out: (text: string) => void;
+    readonly err: (text: string) => void;
+}
+export interface ManifestSeed {
+    readonly runId: string;
+    readonly fingerprint: string;
+    readonly harnessVersion: string;
+    readonly taskType: RunManifest["taskType"];
+    readonly taskInput: RunManifest["taskInput"];
+    readonly limits: RunManifest["limits"];
+    readonly modelId: string;
+    readonly workingDirectory: string;
+    readonly dryRun: boolean;
+    readonly startedAt: string;
+}
+export declare class MemoryEventSink implements EventSink {
+    readonly retainsRawContent = true;
+    private readonly collected;
+    emit(event: HarnessEvent): void;
+    events(): readonly HarnessEvent[];
+    collectManifest(seed: ManifestSeed): RunManifest;
+}
+export declare class CliEventSink implements EventSink {
+    private readonly io;
+    constructor(io: EventWriter);
+    emit(event: HarnessEvent): void;
+}
+//# sourceMappingURL=sinks.d.ts.map

package/node_modules/@oscharko-dev/keiko-harness/dist/sinks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sinks.d.ts","sourceRoot":"","sources":["../src/sinks.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG5D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AAGD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC;IAC3C,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IAC7C,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,qBAAa,eAAgB,YAAW,SAAS;IAG/C,QAAQ,CAAC,iBAAiB,QAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsB;IAEhD,IAAI,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAI/B,MAAM,IAAI,SAAS,YAAY,EAAE;IAIjC,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG,WAAW;CAGjD;AA0DD,qBAAa,YAAa,YAAW,SAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,WAAW;IAE5C,IAAI,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;CAQhC"}

package/node_modules/@oscharko-dev/keiko-harness/dist/sinks.js

@@ -0,0 +1,72 @@
+// Event sinks. MemoryEventSink collects events in order for tests and for assembling
+// the replay manifest (issue #10 persists it). CliEventSink renders a one-line summary
+// per event for the CLI; it NEVER prints SENSITIVE fields verbatim (rationale,
+// modelResponse, diff) — only safe metadata and byte counts (ADR-0004 D6).
+export class MemoryEventSink {
+    // The in-memory collector retains SENSITIVE fields verbatim so the manifest is a faithful
+    // replay record. The audit ledger (issue #10) applies its own redaction before persistence.
+    retainsRawContent = true;
+    collected = [];
+    emit(event) {
+        this.collected.push(event);
+    }
+    events() {
+        return this.collected;
+    }
+    collectManifest(seed) {
+        return { ...seed, events: this.collected };
+    }
+}
+// Per-variant one-line summary. SENSITIVE fields (rationale, modelResponse, diff) are
+// never included — only safe metadata and byte counts. The handler map keeps cyclomatic
+// complexity bounded (one entry per event type, no growing switch).
+const SUMMARISERS = {
+    "run:started": (e) => `task=${e.taskType} model=${e.modelId}`,
+    "state:transition": (e) => `${e.from} -> ${e.to} (${e.reason})`,
+    "model:call:started": (e) => `model=${e.modelId} messages=${String(e.messageCount)} bytes=${String(e.contextBytes)}`,
+    "model:call:completed": (e) => `model=${e.modelId} finish=${e.finishReason} tools=${String(e.toolCallCount)}`,
+    "model:call:failed": (e) => `model=${e.modelId} code=${e.errorCode}`,
+    "tool:call:started": (e) => `tool=${e.toolName} id=${e.toolCallId}`,
+    "tool:call:completed": (e) => `tool=${e.toolName} id=${e.toolCallId}`,
+    "tool:call:failed": (e) => `tool=${e.toolName} code=${e.errorCode}`,
+    "sandbox:configured": (e) => `env=${e.envAllowlist.join(",")} network=${e.network} timeoutMs=${String(e.timeoutMs)} maxOutputBytes=${String(e.maxOutputBytes)} cwdRequested=${String(e.cwdRequested)}`,
+    "command:executed": (e) => `exec=${e.executable} args=${String(e.argCount)} exit=${String(e.exitCode)} timedOut=${String(e.timedOut)}`,
+    "patch:applied": (e) => `changed=${String(e.changedFiles)} created=${String(e.created)} deleted=${String(e.deleted)}`,
+    "reasoning:trace": (e) => `phase=${e.phase} (rationale redacted)`,
+    "patch:proposed": (e) => `file=${e.targetFile} bytes=${String(e.patchBytes)} (diff redacted)`,
+    "verification:result": (e) => `passed=${String(e.passed)}`,
+    "run:completed": () => "completed",
+    "run:cancelled": (e) => `cancelled at ${e.atState}${e.reason === undefined ? "" : ` (${e.reason})`}`,
+    "run:failed": (e) => `${e.failure.category}: ${e.failure.message}`,
+    // ADR-0017 — browser-tool events. originOnly is the scheme+authority only; never a path/query.
+    "browser:session-opened": (e) => `session=${e.sessionId} port=${String(e.cdpPort)} target=${e.targetId}`,
+    "browser:navigated": (e) => `session=${e.sessionId} origin=${e.originOnly} status=${String(e.httpStatus)}`,
+    "browser:screenshot-captured": (e) => `session=${e.sessionId} seq=${String(e.captureSeq)} persisted=${String(e.persisted)}`,
+    "browser:page-content-captured": (e) => `session=${e.sessionId} seq=${String(e.captureSeq)} bytes=${String(e.byteLength)}`,
+    "browser:session-closed": (e) => `session=${e.sessionId} reason=${e.reason}`,
+    "browser:trust-warning": (e) => `session=${e.sessionId} warning=${e.warning}`,
+    "browser:error": (e) => `session=${e.sessionId} code=${e.code}`,
+};
+function summarise(event) {
+    const handler = SUMMARISERS[event.type];
+    return handler(event);
+}
+function isFailureEvent(event) {
+    return (event.type === "run:failed" ||
+        event.type === "model:call:failed" ||
+        event.type === "tool:call:failed");
+}
+export class CliEventSink {
+    io;
+    constructor(io) {
+        this.io = io;
+    }
+    emit(event) {
+        const line = `[${String(event.seq)}] ${event.type} ${summarise(event)}\n`;
+        if (isFailureEvent(event)) {
+            this.io.err(line);
+            return;
+        }
+        this.io.out(line);
+    }
+}

package/node_modules/@oscharko-dev/keiko-harness/dist/tasks/explain-plan.d.ts

@@ -0,0 +1,4 @@
+import type { ExplainPlanInput } from "../types.js";
+import type { TaskPlan } from "./policy.js";
+export declare function buildExplainPlan(input: ExplainPlanInput): TaskPlan;
+//# sourceMappingURL=explain-plan.d.ts.map

package/node_modules/@oscharko-dev/keiko-harness/dist/tasks/explain-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain-plan.d.ts","sourceRoot":"","sources":["../../src/tasks/explain-plan.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAc5C,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,GAAG,QAAQ,CAiBlE"}

package/node_modules/@oscharko-dev/keiko-harness/dist/tasks/explain-plan.js

@@ -0,0 +1,29 @@
+// explain-plan: a read-only task. The harness must never enter tool-call, patch-proposal,
+// or verification for this task type — enforced here by setting all `allows*` flags false.
+// State path: intake -> planning -> context-selection -> model-call -> reporting -> completed.
+const SYSTEM_PROMPT = "You are a senior engineer. Explain only the provided file excerpt and the user's question. " +
+    "Do not infer APIs, constants, or behavior that are not present in the excerpt. If the excerpt " +
+    "is missing or insufficient, say that explicitly. Do not propose code edits; this is a " +
+    "read-only explanation task.";
+function contextBlock(input) {
+    return input.context === undefined
+        ? "\n\nFile excerpt: not available. State that limitation before answering."
+        : `\n\nFile excerpt:\n${input.context}`;
+}
+export function buildExplainPlan(input) {
+    const question = input.question === undefined
+        ? `Explain how the file at ${input.filePath} works.`
+        : `Regarding ${input.filePath}: ${input.question}`;
+    const messages = [
+        { role: "system", content: SYSTEM_PROMPT },
+        { role: "user", content: `${question}${contextBlock(input)}` },
+    ];
+    return {
+        allowsTools: false,
+        allowsPatch: false,
+        allowsVerification: false,
+        targetFile: input.filePath,
+        messages,
+        rationale: `explain-plan over ${input.filePath} (read-only)`,
+    };
+}

package/node_modules/@oscharko-dev/keiko-harness/dist/tasks/generate-unit-tests.d.ts

@@ -0,0 +1,4 @@
+import type { GenerateUnitTestsInput } from "../types.js";
+import type { TaskPlan } from "./policy.js";
+export declare function buildGenerateUnitTests(input: GenerateUnitTestsInput): TaskPlan;
+//# sourceMappingURL=generate-unit-tests.d.ts.map

package/node_modules/@oscharko-dev/keiko-harness/dist/tasks/generate-unit-tests.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-unit-tests.d.ts","sourceRoot":"","sources":["../../src/tasks/generate-unit-tests.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAe5C,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,sBAAsB,GAAG,QAAQ,CAa9E"}

package/node_modules/@oscharko-dev/keiko-harness/dist/tasks/generate-unit-tests.js

@@ -0,0 +1,28 @@
+// generate-unit-tests: proposes a test patch for a target file. The harness may reach
+// patch-proposal and verification, but NEVER applies the patch (dry-run by default).
+// Tool use is not part of this task path. State path:
+// intake -> planning -> context-selection -> model-call -> patch-proposal -> verification
+//        -> reporting -> completed (verification may loop back to model-call).
+const SYSTEM_PROMPT = "You are a senior engineer writing rigorous unit tests. Produce a unified diff that " +
+    "adds tests for the target. Cover edge cases (null, empty, boundary, error paths). " +
+    "Output only the diff.";
+function userMessage(input) {
+    const target = input.targetFunction === undefined
+        ? `Write unit tests for the public API in ${input.filePath}.`
+        : `Write unit tests for the function ${input.targetFunction} in ${input.filePath}.`;
+    return input.context === undefined ? target : `${target}\n\nContext: ${input.context}`;
+}
+export function buildGenerateUnitTests(input) {
+    const messages = [
+        { role: "system", content: SYSTEM_PROMPT },
+        { role: "user", content: userMessage(input) },
+    ];
+    return {
+        allowsTools: false,
+        allowsPatch: true,
+        allowsVerification: true,
+        targetFile: input.filePath,
+        messages,
+        rationale: `generate-unit-tests for ${input.filePath}`,
+    };
+}

package/node_modules/@oscharko-dev/keiko-harness/dist/tasks/investigate-bug.d.ts

@@ -0,0 +1,4 @@
+import type { InvestigateBugInput } from "../types.js";
+import type { TaskPlan } from "./policy.js";
+export declare function buildInvestigateBug(input: InvestigateBugInput): TaskPlan;
+//# sourceMappingURL=investigate-bug.d.ts.map

package/node_modules/@oscharko-dev/keiko-harness/dist/tasks/investigate-bug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"investigate-bug.d.ts","sourceRoot":"","sources":["../../src/tasks/investigate-bug.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAkB5C,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,mBAAmB,GAAG,QAAQ,CAcxE"}