@noetaris/harness 0.1.0

package/dist/index.js

@@ -0,0 +1,1141 @@
+// src/harness/state-field.ts
+function field(options) {
+  return { ...options };
+}
+
+// src/harness/ctx-markers.ts
+var REQUIRED_TAG = "__noetaris_required__";
+var RUNTIME_TAG = "__noetaris_runtime__";
+function required() {
+  return { _tag: REQUIRED_TAG };
+}
+function runtime() {
+  return { _tag: RUNTIME_TAG };
+}
+function isRequiredMarker(value) {
+  return value !== null && typeof value === "object" && "_tag" in value && value._tag === REQUIRED_TAG;
+}
+function isRuntimeMarker(value) {
+  return value !== null && typeof value === "object" && "_tag" in value && value._tag === RUNTIME_TAG;
+}
+
+// src/loop/loop-dsl.ts
+var InvalidLoopBuilderError = class extends Error {
+  constructor() {
+    super("argument is not a LoopBuilder instance \u2014 was it created by createLoopBuilder?");
+    this.name = "InvalidLoopBuilderError";
+  }
+};
+var _builderState = /* @__PURE__ */ Symbol("builderState");
+function deepFreeze(obj) {
+  Object.freeze(obj);
+  for (const value of Object.values(obj)) {
+    if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+      deepFreeze(value);
+    }
+  }
+  return obj;
+}
+function createLoopBuilder() {
+  const state = {
+    startCalled: false,
+    entryStep: void 0,
+    steps: [],
+    onError: void 0
+  };
+  const builder = {
+    start() {
+      state.startCalled = true;
+      return this;
+    },
+    step(name, options) {
+      const stepDef = {
+        name,
+        run: options.run,
+        // as: contravariance in state parameter
+        route: options.route,
+        // as: contravariance in state parameter
+        transitions: [],
+        next: void 0,
+        errorAware: options.optin === "$error"
+      };
+      state.steps.push(stepDef);
+      if (state.startCalled && state.entryStep === void 0) {
+        state.entryStep = name;
+      }
+      return this;
+    },
+    on(signal) {
+      if (state.steps.length === 0) {
+        return {
+          to: () => this,
+          end: () => this
+        };
+      }
+      const currentStep = state.steps.at(-1);
+      return {
+        to: (step) => {
+          currentStep?.transitions.push({
+            signal,
+            target: { kind: "step", name: step }
+          });
+          return this;
+        },
+        end: () => {
+          currentStep?.transitions.push({
+            signal,
+            target: { kind: "end" }
+          });
+          return this;
+        }
+      };
+    },
+    next(name) {
+      if (state.steps.length > 0) {
+        const currentStep = state.steps.at(-1);
+        if (currentStep !== void 0) {
+          currentStep.next = name;
+        }
+      }
+      return this;
+    },
+    onError(step) {
+      state.onError = step;
+      return this;
+    }
+  };
+  builder[_builderState] = state;
+  return builder;
+}
+function extractLoopDefinition(builder) {
+  if (builder === null || builder === void 0 || !(_builderState in builder)) {
+    throw new InvalidLoopBuilderError();
+  }
+  const state = builder[_builderState];
+  const immutableSteps = state.steps.map((step) => {
+    const transitions = Object.freeze([...step.transitions]);
+    for (const transition of transitions) {
+      Object.freeze(transition);
+      Object.freeze(transition.target);
+    }
+    const stepDef = {
+      name: step.name,
+      run: step.run,
+      route: step.route,
+      transitions,
+      next: step.next,
+      errorAware: step.errorAware
+    };
+    return Object.freeze(stepDef);
+  });
+  const definition = {
+    startCalled: state.startCalled,
+    entryStep: state.entryStep,
+    steps: Object.freeze(immutableSteps),
+    onError: state.onError
+  };
+  return deepFreeze(definition);
+}
+
+// src/loop/loop-validator.ts
+var LoopValidationError = class extends Error {
+  violations;
+  constructor(violations) {
+    super(`loop validation failed:
+${violations.map((v) => `  - ${v}`).join("\n")}`);
+    this.name = "LoopValidationError";
+    this.violations = violations;
+  }
+};
+function validateLoop(def) {
+  const violations = [];
+  const names = new Set(def.steps.map((s) => s.name));
+  for (const step of def.steps) {
+    if (step.run === void 0 && step.route === void 0) {
+      violations.push(`step "${step.name}" must have at least one of run or route`);
+    }
+  }
+  for (const step of def.steps) {
+    if (step.route !== void 0 && step.transitions.length === 0) {
+      violations.push(`step "${step.name}" has route but no .on() transitions \u2014 every signal must be handled`);
+    }
+  }
+  for (const [i, step] of def.steps.entries()) {
+    if (step === void 0) continue;
+    if (step.route === void 0) {
+      const isLast = i === def.steps.length - 1;
+      if (isLast && step.next === void 0) {
+        violations.push(
+          `step "${step.name}" has no route, no explicit .next(), and no following step \u2014 no exit path`
+        );
+      }
+    }
+  }
+  for (const step of def.steps) {
+    if (step.route !== void 0 && step.next !== void 0) {
+      violations.push(`step "${step.name}" has both route and .next() \u2014 these are mutually exclusive`);
+    }
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const step of def.steps) {
+    if (seen.has(step.name)) {
+      violations.push(`duplicate step name "${step.name}"`);
+    }
+    seen.add(step.name);
+  }
+  for (const step of def.steps) {
+    for (const transition of step.transitions) {
+      if (transition.target.kind === "step") {
+        if (!names.has(transition.target.name)) {
+          violations.push(
+            `step "${step.name}" has .on("${transition.signal}").to("${transition.target.name}") but step "${transition.target.name}" is not declared`
+          );
+        }
+      }
+    }
+    if (step.next !== void 0) {
+      if (!names.has(step.next)) {
+        violations.push(
+          `step "${step.name}" has .next("${step.next}") but step "${step.next}" is not declared`
+        );
+      }
+    }
+  }
+  if (def.onError !== void 0) {
+    if (!names.has(def.onError)) {
+      violations.push(`onError target "${def.onError}" is not a declared step`);
+    }
+  }
+  if (def.startCalled === false) {
+    violations.push(`loop is missing .start() \u2014 call l.start() before declaring steps`);
+  }
+  if (def.startCalled && def.entryStep === void 0) {
+    violations.push(`l.start() was called but no step was declared after it \u2014 declare at least one step`);
+  }
+  let hasExit = false;
+  for (const step of def.steps) {
+    for (const transition of step.transitions) {
+      if (transition.target.kind === "end") {
+        hasExit = true;
+        break;
+      }
+    }
+    if (hasExit) break;
+  }
+  if (!hasExit) {
+    violations.push(`loop has no exit \u2014 add at least one .on("<signal>").end()`);
+  }
+  if (def.entryStep !== void 0) {
+    const reachable = /* @__PURE__ */ new Set([def.entryStep]);
+    const queue = [def.entryStep];
+    if (def.onError !== void 0) {
+      reachable.add(def.onError);
+      if (!queue.includes(def.onError)) {
+        queue.push(def.onError);
+      }
+    }
+    while (queue.length > 0) {
+      const currentName = queue.shift();
+      const currentStep = def.steps.find((s) => s.name === currentName);
+      if (!currentStep) continue;
+      for (const transition of currentStep.transitions) {
+        if (transition.target.kind === "step") {
+          if (!reachable.has(transition.target.name)) {
+            reachable.add(transition.target.name);
+            queue.push(transition.target.name);
+          }
+        }
+      }
+      if (currentStep.route !== void 0) {
+        if (currentStep.next !== void 0 && !reachable.has(currentStep.next)) {
+          reachable.add(currentStep.next);
+          queue.push(currentStep.next);
+        }
+      } else {
+        if (currentStep.next !== void 0) {
+          if (!reachable.has(currentStep.next)) {
+            reachable.add(currentStep.next);
+            queue.push(currentStep.next);
+          }
+        } else {
+          const currentIndex = def.steps.findIndex((s) => s.name === currentName);
+          if (currentIndex !== -1 && currentIndex < def.steps.length - 1) {
+            const nextStep = def.steps[currentIndex + 1];
+            if (nextStep !== void 0) {
+              const nextStepName = nextStep.name;
+              if (!reachable.has(nextStepName)) {
+                reachable.add(nextStepName);
+                queue.push(nextStepName);
+              }
+            }
+          }
+        }
+      }
+    }
+    for (const step of def.steps) {
+      if (!reachable.has(step.name)) {
+        violations.push(`step "${step.name}" is unreachable from the entry step "${def.entryStep}"`);
+      }
+    }
+  }
+  for (const step of def.steps) {
+    if (step.route === void 0 && step.transitions.length > 0) {
+      violations.push(
+        `step "${step.name}" has .on() transitions but no route \u2014 .on() is only valid when route is set`
+      );
+    }
+  }
+  if (violations.length > 0) {
+    throw new LoopValidationError(violations);
+  }
+}
+
+// src/harness/harness-builder.ts
+var _internals = /* @__PURE__ */ Symbol("_internals");
+function getInternals(harness) {
+  if (harness === null || typeof harness !== "object" || !(_internals in harness)) {
+    throw new HarnessInternalsError();
+  }
+  return harness[_internals];
+}
+var HarnessInternalsError = class extends Error {
+  constructor() {
+    super("value is not a HarnessBuilder instance \u2014 was it created by createHarness?");
+    this.name = "HarnessInternalsError";
+  }
+};
+function createHarness() {
+  return (stateSchema) => {
+    const internals = {
+      stateSchema,
+      // as: S extends object; cast to internal schema representation
+      providers: Object.freeze([]),
+      loopDef: void 0,
+      _req: void 0,
+      _run: void 0,
+      _state: void 0
+    };
+    return createBuilderInstance(internals);
+  };
+}
+function createBuilderInstance(internals) {
+  const builder = {
+    // any: TypeScript cannot infer overloaded call signatures from object literal method definitions
+    provide(key, value) {
+      const newProviders = Object.freeze([
+        ...internals.providers,
+        { kind: "provide", key: String(key), value }
+      ]);
+      const newInternals = {
+        // any: same reason as return type annotation above
+        stateSchema: internals.stateSchema,
+        providers: newProviders,
+        loopDef: internals.loopDef,
+        _req: void 0,
+        _run: void 0,
+        _state: void 0
+      };
+      return createBuilderInstance(newInternals);
+    },
+    store(stores) {
+      const newProviders = Object.freeze([
+        ...internals.providers,
+        { kind: "store", key: "__store__", value: stores }
+      ]);
+      const newInternals = {
+        stateSchema: internals.stateSchema,
+        providers: newProviders,
+        loopDef: internals.loopDef,
+        _req: void 0,
+        _run: void 0,
+        _state: void 0
+      };
+      return createBuilderInstance(newInternals);
+    },
+    loop(builderFn) {
+      const lb = createLoopBuilder();
+      builderFn(lb);
+      const def = extractLoopDefinition(lb);
+      validateLoop(def);
+      const newInternals = {
+        stateSchema: internals.stateSchema,
+        providers: internals.providers,
+        loopDef: def,
+        _req: void 0,
+        _run: void 0,
+        _state: void 0
+      };
+      return createBuilderInstance(newInternals);
+    },
+    [_internals]: internals
+  };
+  return builder;
+}
+
+// src/agent/session-lifecycle.ts
+import { randomUUID } from "crypto";
+
+// src/agent/ctx-interrupt.ts
+var InterruptPause = class extends Error {
+  interruptId;
+  prompt;
+  constructor(interruptId, prompt) {
+    super(`interrupt requested for id "${interruptId}"`);
+    this.name = "InterruptPause";
+    this.interruptId = interruptId;
+    this.prompt = prompt;
+  }
+};
+function isInterruptPause(error) {
+  return error instanceof InterruptPause;
+}
+function createInterruptFn(state, callCountRef) {
+  return async (prompt, id) => {
+    const isAutoId = id === void 0;
+    const effectiveId = isAutoId ? `$auto:${callCountRef.current}` : id;
+    if (isAutoId) {
+      callCountRef.current++;
+    }
+    const responses = state.$interruptResponses;
+    if (effectiveId in responses) {
+      return responses[effectiveId];
+    }
+    state.$interrupt = { interruptId: effectiveId, prompt };
+    throw new InterruptPause(effectiveId, prompt);
+  };
+}
+
+// src/agent/ctx-emit.ts
+function createEmitFn(listeners) {
+  return (name, payload) => {
+    listeners[name]?.(payload);
+  };
+}
+function extractRunListeners(resources) {
+  const raw = resources["listeners"];
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    return {};
+  }
+  return raw;
+}
+
+// src/loop/loop-executor.ts
+var UnknownSignalError = class extends Error {
+  step;
+  signal;
+  constructor(step, signal) {
+    super(`step "${step}" emitted signal "${signal}" with no matching .on() transition`);
+    this.name = "UnknownSignalError";
+    this.step = step;
+    this.signal = signal;
+  }
+};
+var NoNextStepError = class extends Error {
+  step;
+  constructor(step) {
+    super(
+      `step "${step}" has no route, no explicit next, and is the last declared step \u2014 execution cannot continue`
+    );
+    this.name = "NoNextStepError";
+    this.step = step;
+  }
+};
+function buildImplicitNextMap(graph) {
+  const map = /* @__PURE__ */ new Map();
+  for (let i = 0; i < graph.steps.length; i++) {
+    const step = graph.steps[i];
+    const next = i + 1 < graph.steps.length ? graph.steps[i + 1].name : null;
+    map.set(step.name, next);
+  }
+  return map;
+}
+function applyUpdate(state, update, schema) {
+  for (const [key, value] of Object.entries(update)) {
+    if (key === "$error" || key === "$interrupt" || key === "$interruptResponses") continue;
+    const reducer = schema?.[key]?.reduce;
+    if (reducer !== void 0) {
+      state[key] = reducer(state[key], value);
+    } else {
+      state[key] = value;
+    }
+  }
+}
+async function runLoop(graph, state, ctx, schema, shouldStop, startCursor, callbacks) {
+  const { onBeforeStep, onAfterStep, onError, onComplete, onInterrupt } = callbacks ?? {};
+  const implicitNextMap = buildImplicitNextMap(graph);
+  if (!("$error" in state)) state.$error = null;
+  if (!("$interrupt" in state)) state.$interrupt = null;
+  if (!("$interruptResponses" in state)) state.$interruptResponses = {};
+  const callCountRef = { current: 0 };
+  ctx["interrupt"] = createInterruptFn(state, callCountRef);
+  ctx["emit"] = createEmitFn(callbacks?.listeners ?? {});
+  let cursor = startCursor ?? graph.entryStep;
+  while (true) {
+    if (shouldStop?.()) {
+      return { state, signal: null, cursor, paused: true };
+    }
+    onBeforeStep?.(cursor, { ...state });
+    const step = graph.steps.find((s) => s.name === cursor);
+    callCountRef.current = 0;
+    let runSucceeded = false;
+    if (step.run !== void 0) {
+      const hadResponses = Object.keys(state.$interruptResponses).length > 0;
+      try {
+        const update = await step.run(
+          state,
+          ctx
+        );
+        applyUpdate(state, update, schema);
+        if (hadResponses) {
+          state.$interrupt = null;
+          state.$interruptResponses = {};
+        }
+        runSucceeded = true;
+      } catch (e) {
+        if (isInterruptPause(e)) {
+          onInterrupt?.(e.prompt, e.interruptId);
+          return { state, signal: "$interrupt", cursor, paused: true };
+        }
+        state.$error = e instanceof Error ? e : new Error(String(e));
+        onError?.(state.$error, cursor);
+      }
+    }
+    if (runSucceeded) {
+      state.$error = null;
+      onAfterStep?.(cursor, state);
+    }
+    const callRoute = step.route !== void 0 && (runSucceeded || step.run === void 0 || step.errorAware);
+    if (callRoute) {
+      const routeFn = step.route;
+      let signal;
+      try {
+        signal = routeFn(state);
+      } catch (e) {
+        state.$error = e instanceof Error ? e : new Error(String(e));
+        return { state, signal: "$error", cursor, paused: true };
+      }
+      const transition = step.transitions.find((t) => t.signal === signal);
+      if (transition === void 0) {
+        throw new UnknownSignalError(cursor, signal);
+      }
+      if (transition.target.kind === "end") {
+        onComplete?.(state, signal);
+        return { state, signal, cursor: null, paused: false };
+      }
+      cursor = transition.target.name;
+    } else if (step.run !== void 0 && !runSucceeded) {
+      if (graph.onError !== void 0) {
+        cursor = graph.onError;
+      } else {
+        return { state, signal: "$error", cursor, paused: true };
+      }
+    } else {
+      const next = step.next ?? implicitNextMap.get(cursor) ?? null;
+      if (next === null) {
+        throw new NoNextStepError(cursor);
+      }
+      cursor = next;
+    }
+  }
+}
+
+// src/agent/session-store.ts
+function storedSessionToPhase(loaded) {
+  if (loaded === null) {
+    return { phase: "fresh" };
+  }
+  if (loaded.phase === "paused") {
+    const step = loaded.step ?? "";
+    if (loaded.signal !== void 0) {
+      return { phase: "paused", step, signal: loaded.signal };
+    }
+    return { phase: "paused", step };
+  }
+  if (loaded.signal !== void 0) {
+    return { phase: "completed", signal: loaded.signal };
+  }
+  return { phase: "completed" };
+}
+function initializeState(stored, initialStateArg, schema) {
+  const argKeys = new Set(Object.keys(initialStateArg));
+  if (stored === null) {
+    return buildFreshState(initialStateArg, argKeys, schema);
+  }
+  return buildResumedState(stored, initialStateArg, argKeys, schema);
+}
+function buildFreshState(initialStateArg, argKeys, schema) {
+  const result = { ...initialStateArg };
+  if (schema === void 0 || Object.keys(schema).length === 0) {
+    return result;
+  }
+  for (const key of Object.keys(schema)) {
+    if (argKeys.has(key)) {
+      continue;
+    }
+    const field2 = schema[key];
+    if (field2 !== void 0 && field2.default !== void 0) {
+      result[key] = field2.default();
+    }
+  }
+  return result;
+}
+function buildResumedState(stored, initialStateArg, argKeys, schema) {
+  const result = { ...stored.finalState };
+  for (const key of argKeys) {
+    const fieldDef = schema?.[key];
+    if (fieldDef?.reduce !== void 0) {
+      result[key] = fieldDef.reduce(stored.finalState[key], initialStateArg[key]);
+    } else {
+      result[key] = initialStateArg[key];
+    }
+  }
+  if (schema !== void 0) {
+    for (const key of Object.keys(schema)) {
+      if (argKeys.has(key)) continue;
+      if (key in stored.finalState) continue;
+      const field2 = schema[key];
+      if (field2 !== void 0 && field2.default !== void 0) {
+        result[key] = field2.default();
+      }
+    }
+  }
+  return result;
+}
+
+// src/agent/concurrency-errors.ts
+var SessionInFlightError = class extends Error {
+  sessionId;
+  constructor(sessionId) {
+    super(`session "${sessionId}" is already in-flight`);
+    this.name = "SessionInFlightError";
+    this.sessionId = sessionId;
+  }
+};
+var SessionPendingInterruptError = class extends Error {
+  sessionId;
+  constructor(sessionId) {
+    super(`session "${sessionId}" is paused on an interrupt \u2014 use agent.resume() instead of agent.run()`);
+    this.name = "SessionPendingInterruptError";
+    this.sessionId = sessionId;
+  }
+};
+var StoreLoadError = class extends Error {
+  cause;
+  constructor(cause) {
+    super("session store failed to load session");
+    this.name = "StoreLoadError";
+    this.cause = cause;
+  }
+};
+
+// src/agent/session-lifecycle.ts
+function resolveSessionStore(storeEntries) {
+  let result = void 0;
+  for (const entry of storeEntries) {
+    if (entry.kind !== "store") continue;
+    const value = entry.value;
+    if (value === null || typeof value !== "object") continue;
+    const rec = value;
+    if (!("session" in rec)) continue;
+    const session = rec["session"];
+    if (session === null || typeof session !== "object") continue;
+    const s = session;
+    if (typeof s["load"] === "function" && typeof s["save"] === "function") {
+      result = session;
+    }
+  }
+  return result;
+}
+async function querySessionPhase(store, sessionId) {
+  if (store === void 0) {
+    return { phase: "fresh" };
+  }
+  const loaded = await store.load(sessionId);
+  return storedSessionToPhase(loaded);
+}
+async function runWithSession(store, sessionId, graph, initialStateArg, schema, ctx, options) {
+  if (store === void 0) {
+    const state2 = initializeState(null, initialStateArg, schema);
+    return runLoop(graph, state2, ctx, schema, options?.shouldStop, void 0, options);
+  }
+  let loaded;
+  try {
+    loaded = await store.load(sessionId);
+  } catch (error) {
+    const storeError = new StoreLoadError(error);
+    options?.onStoreError?.(storeError, "load");
+    const failState = initializeState(null, initialStateArg, schema);
+    failState["$error"] = storeError;
+    return { state: failState, signal: "$error", paused: false, cursor: null };
+  }
+  const runId = randomUUID();
+  const state = initializeState(loaded, initialStateArg, schema);
+  const initialStateSnapshot = { ...state };
+  const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const result = await runLoop(graph, state, ctx, schema, options?.shouldStop, loaded?.step, options);
+  const settledAt = (/* @__PURE__ */ new Date()).toISOString();
+  try {
+    if (result.paused) {
+      const saved = {
+        runId,
+        sessionId,
+        startedAt,
+        settledAt,
+        phase: "paused",
+        initialState: initialStateSnapshot,
+        finalState: result.state,
+        step: result.cursor,
+        ...result.signal !== null ? { signal: result.signal } : {}
+      };
+      await store.save(sessionId, saved);
+    } else {
+      const saved = {
+        runId,
+        sessionId,
+        startedAt,
+        settledAt,
+        phase: "completed",
+        initialState: initialStateSnapshot,
+        finalState: result.state,
+        ...result.signal !== null ? { signal: result.signal } : {}
+      };
+      await store.save(sessionId, saved);
+    }
+  } catch (error) {
+    options?.onStoreError?.(error, "persist");
+  }
+  return result;
+}
+
+// src/agent/interrupt-resume.ts
+var NoInterruptError = class extends Error {
+  constructor() {
+    super(
+      'resume() called but the session is not paused on a matching interrupt \u2014 verify the session exists, its phase is "paused", and interruptId matches'
+    );
+    this.name = "NoInterruptError";
+  }
+};
+async function injectInterruptResponse(store, sessionId, interruptId, response) {
+  const loaded = await store.load(sessionId);
+  if (loaded === null) throw new NoInterruptError();
+  if (loaded.phase !== "paused") throw new NoInterruptError();
+  const interrupt = loaded.finalState.$interrupt;
+  if (interrupt === null) throw new NoInterruptError();
+  if (interrupt.interruptId !== interruptId) throw new NoInterruptError();
+  const existingResponses = loaded.finalState.$interruptResponses ?? {};
+  const newState = {
+    ...loaded.finalState,
+    $interrupt: null,
+    $interruptResponses: { ...existingResponses, [interruptId]: response }
+  };
+  const updated = {
+    runId: loaded.runId,
+    sessionId: loaded.sessionId,
+    startedAt: loaded.startedAt,
+    settledAt: loaded.settledAt,
+    phase: "paused",
+    initialState: loaded.initialState,
+    finalState: newState,
+    ...loaded.step !== void 0 ? { step: loaded.step } : {},
+    ...loaded.signal !== void 0 ? { signal: loaded.signal } : {}
+  };
+  await store.save(sessionId, updated);
+}
+
+// src/agent/run-handle.ts
+function createRunHandle(sessionId, execution, stopFlag, stepRef, resumeFn) {
+  let settledOutcome = null;
+  const settled = execution.then(
+    (outcome) => {
+      settledOutcome = outcome;
+      stepRef.current = null;
+      return outcome;
+    },
+    (err) => {
+      stepRef.current = null;
+      throw err;
+    }
+  );
+  const handle = {
+    then(onfulfilled, onrejected) {
+      return settled.then(onfulfilled, onrejected);
+    },
+    stop() {
+      stopFlag.stopped = true;
+    },
+    resume(response, interruptId) {
+      if (settledOutcome === null && resumeFn === void 0) {
+        throw new Error("not implemented \u2014 requires F9");
+      }
+      if (settledOutcome === null) {
+        throw new NoInterruptError();
+      }
+      if (settledOutcome.signal !== "$interrupt") {
+        throw new NoInterruptError();
+      }
+      if (resumeFn === void 0) {
+        throw new NoInterruptError();
+      }
+      return resumeFn(response, interruptId);
+    },
+    get sessionId() {
+      return sessionId;
+    },
+    get currentStep() {
+      return stepRef.current;
+    }
+  };
+  return handle;
+}
+
+// src/agent/create-agent.ts
+import { randomUUID as randomUUID2 } from "crypto";
+
+// src/agent/event-callbacks.ts
+function extractRunEvents(resources) {
+  const raw = resources["events"];
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    return {};
+  }
+  return raw;
+}
+
+// src/agent/create-agent.ts
+var MissingLoopError = class extends Error {
+  constructor() {
+    super("harness has no loop \u2014 call h.loop() before createAgent()");
+    this.name = "MissingLoopError";
+  }
+};
+var MissingSlotError = class extends Error {
+  key;
+  constructor(key) {
+    super(`required slot "${key}" was not provided in createAgent slots`);
+    this.name = "MissingSlotError";
+    this.key = key;
+  }
+};
+var RuntimeSlotInAgentError = class extends Error {
+  key;
+  constructor(key) {
+    super(`slot "${key}" is a runtime() slot \u2014 provide it in agent.run(), not createAgent()`);
+    this.name = "RuntimeSlotInAgentError";
+    this.key = key;
+  }
+};
+var UnknownSlotError = class extends Error {
+  key;
+  constructor(key) {
+    super(`slot "${key}" is not declared in the harness \u2014 remove it or add h.provide("${key}", required())`);
+    this.name = "UnknownSlotError";
+    this.key = key;
+  }
+};
+var MissingRuntimeSlotError = class extends Error {
+  key;
+  constructor(key) {
+    super(`runtime slot "${key}" was not provided in agent.run() resources`);
+    this.name = "MissingRuntimeSlotError";
+    this.key = key;
+  }
+};
+var RequiredSlotInRunError = class extends Error {
+  key;
+  constructor(key) {
+    super(`slot "${key}" is a required() slot \u2014 provide it in createAgent(), not agent.run()`);
+    this.name = "RequiredSlotInRunError";
+    this.key = key;
+  }
+};
+var UnknownRunSlotError = class extends Error {
+  key;
+  constructor(key) {
+    super(`slot "${key}" is not a runtime() slot \u2014 do not pass it in agent.run() resources`);
+    this.name = "UnknownRunSlotError";
+    this.key = key;
+  }
+};
+var _agentInternals = /* @__PURE__ */ Symbol("_agentInternals");
+function createAgent(h, slots) {
+  const internals = getInternals(h);
+  if (internals.loopDef === void 0) {
+    throw new MissingLoopError();
+  }
+  const providerMap = /* @__PURE__ */ new Map();
+  for (const entry of internals.providers) {
+    if (entry.kind === "provide") {
+      providerMap.set(entry.key, entry);
+    }
+  }
+  for (const key of Object.keys(slots)) {
+    if (!providerMap.has(key)) {
+      throw new UnknownSlotError(key);
+    }
+  }
+  for (const key of Object.keys(slots)) {
+    const entry = providerMap.get(key);
+    if (entry && isRuntimeMarker(entry.value)) {
+      throw new RuntimeSlotInAgentError(key);
+    }
+  }
+  for (const entry of internals.providers) {
+    if (entry.kind === "provide" && isRequiredMarker(entry.value)) {
+      if (!(entry.key in slots)) {
+        throw new MissingSlotError(entry.key);
+      }
+    }
+  }
+  const resolvedProviders = /* @__PURE__ */ new Map();
+  const storeEntries = [];
+  const runtimeKeys = /* @__PURE__ */ new Set();
+  const requiredKeys = /* @__PURE__ */ new Set();
+  for (const entry of internals.providers) {
+    if (entry.kind === "store") {
+      storeEntries.push(entry);
+    } else if (entry.kind === "provide") {
+      if (isRequiredMarker(entry.value)) {
+        resolvedProviders.set(entry.key, slots[entry.key]);
+        requiredKeys.add(entry.key);
+      } else if (isRuntimeMarker(entry.value)) {
+        runtimeKeys.add(entry.key);
+      } else {
+        resolvedProviders.set(entry.key, entry.value);
+      }
+    }
+  }
+  const capturedStore = resolveSessionStore(storeEntries);
+  const agentInternals = {
+    resolvedProviders,
+    storeEntries,
+    loopDef: internals.loopDef,
+    // Guaranteed to be non-undefined by validation 1
+    stateSchema: internals.stateSchema,
+    runtimeKeys,
+    requiredKeys
+  };
+  const reservedRunKeys = /* @__PURE__ */ new Set(["sessionId", "signal", "events", "listeners"]);
+  const inFlightSessions = /* @__PURE__ */ new Set();
+  const interruptPendingSessions = /* @__PURE__ */ new Set();
+  const makeAgentResumeHandle = (resp, sId, iId) => {
+    const flag = { stopped: false };
+    const ref = { current: null };
+    const exec = (async () => {
+      await Promise.resolve();
+      try {
+        if (capturedStore === void 0) throw new NoInterruptError();
+        await injectInterruptResponse(capturedStore, sId, iId, resp);
+        const agentCtx = {
+          ...Object.fromEntries(agentInternals.resolvedProviders),
+          sessionId: sId
+        };
+        const r = await runWithSession(
+          capturedStore,
+          sId,
+          agentInternals.loopDef,
+          {},
+          agentInternals.stateSchema,
+          agentCtx,
+          {
+            shouldStop: () => flag.stopped,
+            onBeforeStep: (n) => {
+              ref.current = n;
+            }
+            // _state unused in cross-process resume — no events available
+          }
+        );
+        if (r.signal === "$interrupt") interruptPendingSessions.add(sId);
+        return { state: r.state, signal: r.signal };
+      } finally {
+        inFlightSessions.delete(sId);
+      }
+    })();
+    const resumeFn = (r, i) => {
+      if (inFlightSessions.has(sId)) throw new SessionInFlightError(sId);
+      interruptPendingSessions.delete(sId);
+      inFlightSessions.add(sId);
+      return makeAgentResumeHandle(r, sId, i);
+    };
+    return createRunHandle(sId, exec, flag, ref, resumeFn);
+  };
+  const agent = {
+    run: (initialState, resources) => {
+      for (const key of Object.keys(resources)) {
+        if (reservedRunKeys.has(key)) continue;
+        if (!agentInternals.runtimeKeys.has(key) && !agentInternals.requiredKeys.has(key)) {
+          throw new UnknownRunSlotError(key);
+        }
+      }
+      for (const key of Object.keys(resources)) {
+        if (reservedRunKeys.has(key)) continue;
+        if (agentInternals.requiredKeys.has(key)) {
+          throw new RequiredSlotInRunError(key);
+        }
+      }
+      for (const key of agentInternals.runtimeKeys) {
+        if (!(key in resources)) {
+          throw new MissingRuntimeSlotError(key);
+        }
+      }
+      const sessionId = typeof resources["sessionId"] === "string" ? resources["sessionId"] : randomUUID2();
+      if (inFlightSessions.has(sessionId)) throw new SessionInFlightError(sessionId);
+      if (interruptPendingSessions.has(sessionId)) throw new SessionPendingInterruptError(sessionId);
+      inFlightSessions.add(sessionId);
+      const stopFlag = { stopped: false };
+      const rawSignal = resources["signal"];
+      if (rawSignal instanceof AbortSignal) {
+        rawSignal.addEventListener("abort", () => {
+          stopFlag.stopped = true;
+        }, { once: true });
+        if (rawSignal.aborted) stopFlag.stopped = true;
+      }
+      const stepRef = { current: null };
+      const runtimeSlots = {};
+      for (const key of agentInternals.runtimeKeys) {
+        if (reservedRunKeys.has(key)) continue;
+        runtimeSlots[key] = resources[key];
+      }
+      const ctx = {
+        ...Object.fromEntries(agentInternals.resolvedProviders),
+        ...runtimeSlots,
+        sessionId
+      };
+      const events = extractRunEvents(resources);
+      const listeners = extractRunListeners(resources);
+      const options = {
+        shouldStop: () => stopFlag.stopped,
+        onBeforeStep: (name, state) => {
+          stepRef.current = name;
+          events.onBeforeStep?.(name, state);
+        },
+        // spread optional event callbacks only when defined (exactOptionalPropertyTypes requires omission, not undefined)
+        ...events.onStoreError !== void 0 ? { onStoreError: events.onStoreError } : {},
+        ...events.onAfterStep !== void 0 ? { onAfterStep: events.onAfterStep } : {},
+        ...events.onError !== void 0 ? { onError: events.onError } : {},
+        ...events.onComplete !== void 0 ? { onComplete: events.onComplete } : {},
+        ...events.onInterrupt !== void 0 ? { onInterrupt: events.onInterrupt } : {},
+        ...Object.keys(listeners).length > 0 ? { listeners } : {}
+      };
+      let lastResult = null;
+      const execution = (async () => {
+        await Promise.resolve();
+        try {
+          const r = await runWithSession(
+            capturedStore,
+            sessionId,
+            agentInternals.loopDef,
+            initialState,
+            agentInternals.stateSchema,
+            ctx,
+            options
+          );
+          if (r.signal === "$interrupt") interruptPendingSessions.add(sessionId);
+          lastResult = { state: r.state, cursor: r.cursor };
+          return { state: r.state, signal: r.signal };
+        } finally {
+          inFlightSessions.delete(sessionId);
+        }
+      })();
+      const buildResumeFn = () => {
+        return (response, interruptId) => {
+          if (inFlightSessions.has(sessionId)) throw new SessionInFlightError(sessionId);
+          interruptPendingSessions.delete(sessionId);
+          inFlightSessions.add(sessionId);
+          const resumeStopFlag = { stopped: false };
+          const resumeStepRef = { current: null };
+          const resumeExecution = (async () => {
+            await Promise.resolve();
+            try {
+              if (capturedStore !== void 0) {
+                await injectInterruptResponse(capturedStore, sessionId, interruptId, response);
+                const r2 = await runWithSession(
+                  capturedStore,
+                  sessionId,
+                  agentInternals.loopDef,
+                  {},
+                  agentInternals.stateSchema,
+                  ctx,
+                  {
+                    shouldStop: () => resumeStopFlag.stopped,
+                    onBeforeStep: (n, s) => {
+                      resumeStepRef.current = n;
+                      events.onBeforeStep?.(n, s);
+                    },
+                    // spread optional event callbacks only when defined (exactOptionalPropertyTypes requires omission, not undefined)
+                    ...events.onStoreError !== void 0 ? { onStoreError: events.onStoreError } : {},
+                    ...events.onAfterStep !== void 0 ? { onAfterStep: events.onAfterStep } : {},
+                    ...events.onError !== void 0 ? { onError: events.onError } : {},
+                    ...events.onComplete !== void 0 ? { onComplete: events.onComplete } : {},
+                    ...events.onInterrupt !== void 0 ? { onInterrupt: events.onInterrupt } : {},
+                    ...Object.keys(listeners).length > 0 ? { listeners } : {}
+                  }
+                );
+                if (r2.signal === "$interrupt") interruptPendingSessions.add(sessionId);
+                lastResult = { state: r2.state, cursor: r2.cursor };
+                return { state: r2.state, signal: r2.signal };
+              }
+              const prev = lastResult;
+              if (prev === null) throw new NoInterruptError();
+              const state = prev.state;
+              const existing = state.$interruptResponses ?? {};
+              state.$interruptResponses = { ...existing, [interruptId]: response };
+              state.$interrupt = null;
+              const cursor = prev.cursor ?? void 0;
+              const r = await runLoop(
+                agentInternals.loopDef,
+                state,
+                ctx,
+                agentInternals.stateSchema,
+                () => resumeStopFlag.stopped,
+                cursor,
+                {
+                  onBeforeStep: (n, s) => {
+                    resumeStepRef.current = n;
+                    events.onBeforeStep?.(n, s);
+                  },
+                  ...events.onAfterStep !== void 0 ? { onAfterStep: events.onAfterStep } : {},
+                  ...events.onError !== void 0 ? { onError: events.onError } : {},
+                  ...events.onComplete !== void 0 ? { onComplete: events.onComplete } : {},
+                  ...events.onInterrupt !== void 0 ? { onInterrupt: events.onInterrupt } : {},
+                  ...Object.keys(listeners).length > 0 ? { listeners } : {}
+                }
+              );
+              if (r.signal === "$interrupt") interruptPendingSessions.add(sessionId);
+              lastResult = { state: r.state, cursor: r.cursor };
+              return { state: r.state, signal: r.signal };
+            } finally {
+              inFlightSessions.delete(sessionId);
+            }
+          })();
+          return createRunHandle(sessionId, resumeExecution, resumeStopFlag, resumeStepRef, buildResumeFn());
+        };
+      };
+      return createRunHandle(sessionId, execution, stopFlag, stepRef, buildResumeFn());
+    },
+    resume: (response, sessionId, interruptId) => {
+      if (inFlightSessions.has(sessionId)) throw new SessionInFlightError(sessionId);
+      interruptPendingSessions.delete(sessionId);
+      inFlightSessions.add(sessionId);
+      return makeAgentResumeHandle(response, sessionId, interruptId);
+    },
+    status: (sessionId) => querySessionPhase(capturedStore, sessionId),
+    [_agentInternals]: agentInternals
+  };
+  return agent;
+}
+export {
+  NoInterruptError,
+  REQUIRED_TAG,
+  RUNTIME_TAG,
+  SessionInFlightError,
+  SessionPendingInterruptError,
+  StoreLoadError,
+  createAgent,
+  createHarness,
+  field,
+  isRequiredMarker,
+  isRuntimeMarker,
+  required,
+  runtime
+};
+//# sourceMappingURL=index.js.map