@yolk-sdk/harness 0.1.0-canary.77

package/dist/outcome.mjs

@@ -0,0 +1,159 @@
+import { Effect, Stream } from "effect";
+import { addAgentUsage, zeroAgentUsage } from "@yolk-sdk/agent/protocol";
+import { LLMError, collectModelTurnAttempt, runModelTurn, runToolBatch } from "@yolk-sdk/agent/loop";
+import { applyOverflowCompaction, isOverflowCompactionAttemptCount } from "@yolk-sdk/agent/compaction";
+//#region src/outcome.ts
+const completedOutcome = (result) => ({
+	_tag: "Completed",
+	needsContinuation: result.stopReason === "tool_use",
+	assistantMessage: result.assistantMessage,
+	toolCalls: result.toolCalls,
+	usage: result.usage,
+	stopReason: result.stopReason
+});
+const modelTurnResult = (result) => ({
+	assistantMessage: result.assistantMessage,
+	toolCalls: result.toolCalls,
+	usage: result.usage,
+	stopReason: result.stopReason
+});
+const invalidOverflowCompactionAttemptError = () => new LLMError({
+	cause: "validation_error",
+	message: "overflowCompactionAttempt must be a finite integer >= 0",
+	retryable: false
+});
+const isAgentLoopError = (error) => {
+	if (typeof error !== "object" || error === null || !("_tag" in error)) return false;
+	const tag = error._tag;
+	return tag === "LLMError" || tag === "FauxExhaustedError" || tag === "ToolError" || tag === "ContextTransformError" || tag === "AbortError";
+};
+const isOverflow = (error) => (error._tag === "LLMError" || error._tag === "ContextTransformError") && error.cause === "context_overflow";
+const isMissingDone = (error) => error._tag === "LLMError" && error.responseIssue === "missing_done";
+const isRetryableLlm = (error) => error._tag === "LLMError" && error.retryable;
+const classifyModelTurnFailure = (input) => {
+	if (isOverflow(input.error)) {
+		if (input.compact === void 0) return Effect.fail(input.error);
+		return applyOverflowCompaction({
+			compact: input.compact,
+			messages: input.messages,
+			attempt: input.overflowCompactionAttempt,
+			outputStarted: input.outputStarted
+		}).pipe(Effect.flatMap((result) => result._tag === "Compacted" ? Effect.succeed({
+			_tag: "Compacted",
+			messages: result.messages,
+			overflowCompactionAttempt: input.overflowCompactionAttempt + 1
+		}) : Effect.fail(input.error)));
+	}
+	if (isMissingDone(input.error) && !input.outputStarted) return Effect.succeed({
+		_tag: "RecoverFull",
+		error: input.error
+	});
+	if (isMissingDone(input.error) && input.outputStarted) return Effect.succeed({
+		_tag: "Continue",
+		error: input.error,
+		...modelTurnResult(input.collected)
+	});
+	if (isRetryableLlm(input.error) && !input.outputStarted) {
+		if (input.error.cause === "invalid_response") return Effect.succeed({
+			_tag: "RecoverFull",
+			error: input.error
+		});
+		return Effect.succeed({
+			_tag: "Retry",
+			error: input.error
+		});
+	}
+	if (isRetryableLlm(input.error) && input.outputStarted) return Effect.succeed({
+		_tag: "Continue",
+		error: input.error,
+		...modelTurnResult(input.collected)
+	});
+	return Effect.fail(input.error);
+};
+const attemptModelTurn = (config, options) => Effect.gen(function* () {
+	const overflowCompactionAttempt = options?.overflowCompactionAttempt ?? 0;
+	if (!isOverflowCompactionAttemptCount(overflowCompactionAttempt)) return yield* Effect.fail(invalidOverflowCompactionAttemptError());
+	const outcome = yield* collectModelTurnAttempt(runModelTurn(config), {
+		onEvent: options?.onEvent,
+		initialUsage: options?.initialUsage
+	});
+	switch (outcome._tag) {
+		case "Collected": return completedOutcome(outcome.collection);
+		case "SinkFailed": return yield* Effect.fail(outcome.error);
+		case "StreamFailed":
+			if (!isAgentLoopError(outcome.error)) return yield* Effect.fail(outcome.error);
+			return yield* classifyModelTurnFailure({
+				error: outcome.error,
+				collected: {
+					assistantMessage: outcome.collection.assistantMessage ?? outcome.collection.partialAssistantMessage,
+					toolCalls: outcome.collection.toolCalls,
+					usage: outcome.collection.usage,
+					stopReason: outcome.collection.stopReason
+				},
+				outputStarted: outcome.collection.outputStarted,
+				messages: config.messages,
+				overflowCompactionAttempt,
+				compact: options?.compact
+			});
+	}
+});
+const attemptToolBatch = (config, options) => {
+	const onEvent = options?.onEvent;
+	return runToolBatch(config).pipe(Stream.runFoldEffect(() => ({
+		requests: [],
+		usage: config.usage ?? zeroAgentUsage,
+		toolCalls: []
+	}), (acc, event) => {
+		const next = event._tag === "AgentAwaitingInput" ? {
+			...acc,
+			requests: event.requests,
+			usage: event.usage
+		} : event._tag === "UsageUpdate" ? {
+			...acc,
+			usage: addAgentUsage(acc.usage, event.usage)
+		} : event._tag === "ToolExecutionCompleted" || event._tag === "ToolExecutionAccepted" ? {
+			...acc,
+			toolCalls: [...acc.toolCalls, event.call]
+		} : acc;
+		return onEvent === void 0 ? Effect.succeed(next) : onEvent(event).pipe(Effect.as(next));
+	}), Effect.map((result) => {
+		if (result.requests.length === 0) {
+			const needsContinuation = result.toolCalls.length > 0;
+			return {
+				_tag: "Completed",
+				needsContinuation,
+				assistantMessage: void 0,
+				toolCalls: result.toolCalls,
+				usage: result.usage,
+				stopReason: needsContinuation ? "tool_use" : "stop"
+			};
+		}
+		return {
+			_tag: "AwaitingInput",
+			requests: result.requests,
+			usage: result.usage
+		};
+	}));
+};
+const hitlResponseMatchesRequest = (response, request) => {
+	switch (response._tag) {
+		case "ToolApprovalResponse": return request._tag === "ToolApprovalRequest" && response.requestId === request.requestId && response.toolCallId === request.toolCallId;
+		case "QuestionResponse": return request._tag === "QuestionRequest" && response.requestId === request.requestId && response.toolCallId === request.toolCallId;
+	}
+};
+const matchHitlResponse = (pending, response) => {
+	const matched = pending.find((request) => hitlResponseMatchesRequest(response, request));
+	return matched === void 0 ? { _tag: "Mismatch" } : {
+		_tag: "Match",
+		requestId: matched.requestId
+	};
+};
+const resumeHitlIfMatched = (input) => {
+	const matched = matchHitlResponse(input.pending, input.response);
+	if (matched._tag === "Mismatch") return Effect.succeed(matched);
+	return input.resume(matched.requestId);
+};
+//#endregion
+export { attemptModelTurn, attemptToolBatch, matchHitlResponse, resumeHitlIfMatched };
+
+//# sourceMappingURL=outcome.mjs.map

package/dist/outcome.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"outcome.mjs","names":[],"sources":["../src/outcome.ts"],"sourcesContent":["import { Effect, Stream } from 'effect'\nimport {\n  addAgentUsage,\n  zeroAgentUsage,\n  type AgentEvent,\n  type AgentMessage,\n  type AgentUsage,\n  type HitlRequest,\n  type HitlResponse\n} from '@yolk-sdk/agent/protocol'\nimport {\n  collectModelTurnAttempt,\n  LLMError,\n  runModelTurn,\n  runToolBatch,\n  type AgentLoopError,\n  type ContextTransformer,\n  type LLMProvider,\n  type LoopConfig,\n  type ModelTurnConfig,\n  type ModelTurnResult,\n  type ToolBatchConfig,\n  type ToolExecutor\n} from '@yolk-sdk/agent/loop'\nimport {\n  applyOverflowCompaction,\n  isOverflowCompactionAttemptCount\n} from '@yolk-sdk/agent/compaction'\n\nexport type OverflowCompactionResult =\n  | {\n      readonly _tag: 'Compacted'\n      readonly messages: ReadonlyArray<AgentMessage>\n    }\n  | {\n      readonly _tag: 'Skipped'\n    }\n\nexport type CompletedTurn = {\n  readonly _tag: 'Completed'\n  readonly needsContinuation: boolean\n} & ModelTurnResult\n\nexport type ModelTurnOutcome =\n  | CompletedTurn\n  | { readonly _tag: 'Retry'; readonly error: AgentLoopError }\n  | ({ readonly _tag: 'Continue'; readonly error: AgentLoopError } & ModelTurnResult)\n  | { readonly _tag: 'RecoverFull'; readonly error: AgentLoopError }\n  | {\n      readonly _tag: 'Compacted'\n      readonly messages: ReadonlyArray<AgentMessage>\n      readonly overflowCompactionAttempt: number\n    }\n\nexport type ToolBatchOutcome =\n  | CompletedTurn\n  | {\n      readonly _tag: 'AwaitingInput'\n      readonly requests: ReadonlyArray<HitlRequest>\n      readonly usage: AgentUsage\n    }\n\nexport type StepOutcome = ModelTurnOutcome | ToolBatchOutcome\n\nconst completedOutcome = (result: ModelTurnResult): CompletedTurn => ({\n  _tag: 'Completed',\n  needsContinuation: result.stopReason === 'tool_use',\n  assistantMessage: result.assistantMessage,\n  toolCalls: result.toolCalls,\n  usage: result.usage,\n  stopReason: result.stopReason\n})\n\nconst modelTurnResult = (result: ModelTurnResult): ModelTurnResult => ({\n  assistantMessage: result.assistantMessage,\n  toolCalls: result.toolCalls,\n  usage: result.usage,\n  stopReason: result.stopReason\n})\n\nconst invalidOverflowCompactionAttemptError = () =>\n  new LLMError({\n    cause: 'validation_error',\n    message: 'overflowCompactionAttempt must be a finite integer >= 0',\n    retryable: false\n  })\n\nconst isAgentLoopError = (error: unknown): error is AgentLoopError => {\n  if (typeof error !== 'object' || error === null || !('_tag' in error)) {\n    return false\n  }\n  const tag = error._tag\n  return (\n    tag === 'LLMError' ||\n    tag === 'FauxExhaustedError' ||\n    tag === 'ToolError' ||\n    tag === 'ContextTransformError' ||\n    tag === 'AbortError'\n  )\n}\n\nconst isOverflow = (error: AgentLoopError) =>\n  (error._tag === 'LLMError' || error._tag === 'ContextTransformError') &&\n  error.cause === 'context_overflow'\n\nconst isMissingDone = (error: AgentLoopError) =>\n  error._tag === 'LLMError' && error.responseIssue === 'missing_done'\n\nconst isRetryableLlm = (\n  error: AgentLoopError\n): error is Extract<AgentLoopError, { _tag: 'LLMError' }> =>\n  error._tag === 'LLMError' && error.retryable\n\nconst classifyModelTurnFailure = <E2, R2>(input: {\n  readonly error: AgentLoopError\n  readonly collected: ModelTurnResult\n  readonly outputStarted: boolean\n  readonly messages: ReadonlyArray<AgentMessage>\n  readonly overflowCompactionAttempt: number\n  readonly compact?: (\n    messages: ReadonlyArray<AgentMessage>\n  ) => Effect.Effect<OverflowCompactionResult, E2, R2>\n}): Effect.Effect<ModelTurnOutcome, AgentLoopError | E2, R2> => {\n  if (isOverflow(input.error)) {\n    if (input.compact === undefined) {\n      return Effect.fail(input.error)\n    }\n\n    return applyOverflowCompaction({\n      compact: input.compact,\n      messages: input.messages,\n      attempt: input.overflowCompactionAttempt,\n      outputStarted: input.outputStarted\n    }).pipe(\n      Effect.flatMap(result =>\n        result._tag === 'Compacted'\n          ? Effect.succeed({\n              _tag: 'Compacted' as const,\n              messages: result.messages,\n              overflowCompactionAttempt: input.overflowCompactionAttempt + 1\n            })\n          : Effect.fail(input.error)\n      )\n    )\n  }\n\n  if (isMissingDone(input.error) && !input.outputStarted) {\n    return Effect.succeed({ _tag: 'RecoverFull', error: input.error })\n  }\n\n  if (isMissingDone(input.error) && input.outputStarted) {\n    return Effect.succeed({\n      _tag: 'Continue',\n      error: input.error,\n      ...modelTurnResult(input.collected)\n    })\n  }\n\n  if (isRetryableLlm(input.error) && !input.outputStarted) {\n    if (input.error.cause === 'invalid_response') {\n      return Effect.succeed({ _tag: 'RecoverFull', error: input.error })\n    }\n    return Effect.succeed({ _tag: 'Retry', error: input.error })\n  }\n\n  if (isRetryableLlm(input.error) && input.outputStarted) {\n    return Effect.succeed({\n      _tag: 'Continue',\n      error: input.error,\n      ...modelTurnResult(input.collected)\n    })\n  }\n\n  return Effect.fail(input.error)\n}\n\nexport const attemptModelTurn = <E2 = never, R2 = never>(\n  config: ModelTurnConfig,\n  options?: {\n    readonly onEvent?: (event: AgentEvent) => Effect.Effect<void, E2, R2>\n    readonly initialUsage?: AgentUsage\n    readonly overflowCompactionAttempt?: number\n    readonly compact?: (\n      messages: ReadonlyArray<AgentMessage>\n    ) => Effect.Effect<OverflowCompactionResult, E2, R2>\n  }\n): Effect.Effect<\n  ModelTurnOutcome,\n  AgentLoopError | E2,\n  ContextTransformer | LLMProvider | LoopConfig | R2\n> =>\n  Effect.gen(function* () {\n    const overflowCompactionAttempt = options?.overflowCompactionAttempt ?? 0\n    if (!isOverflowCompactionAttemptCount(overflowCompactionAttempt)) {\n      return yield* Effect.fail(invalidOverflowCompactionAttemptError())\n    }\n\n    const outcome = yield* collectModelTurnAttempt(runModelTurn(config), {\n      onEvent: options?.onEvent,\n      initialUsage: options?.initialUsage\n    })\n\n    switch (outcome._tag) {\n      case 'Collected':\n        return completedOutcome(outcome.collection)\n      case 'SinkFailed':\n        return yield* Effect.fail(outcome.error)\n      case 'StreamFailed':\n        if (!isAgentLoopError(outcome.error)) {\n          return yield* Effect.fail(outcome.error)\n        }\n        return yield* classifyModelTurnFailure({\n          error: outcome.error,\n          collected: {\n            assistantMessage:\n              outcome.collection.assistantMessage ?? outcome.collection.partialAssistantMessage,\n            toolCalls: outcome.collection.toolCalls,\n            usage: outcome.collection.usage,\n            stopReason: outcome.collection.stopReason\n          },\n          outputStarted: outcome.collection.outputStarted,\n          messages: config.messages,\n          overflowCompactionAttempt,\n          compact: options?.compact\n        })\n    }\n  })\n\nexport const attemptToolBatch = <E2 = never, R2 = never>(\n  config: ToolBatchConfig,\n  options?: {\n    readonly onEvent?: (event: AgentEvent) => Effect.Effect<void, E2, R2>\n  }\n): Effect.Effect<ToolBatchOutcome, AgentLoopError | E2, LoopConfig | ToolExecutor | R2> => {\n  const onEvent = options?.onEvent\n\n  return runToolBatch(config).pipe(\n    Stream.runFoldEffect(\n      (): {\n        requests: ReadonlyArray<HitlRequest>\n        usage: AgentUsage\n        toolCalls: ModelTurnResult['toolCalls']\n      } => ({\n        requests: [],\n        usage: config.usage ?? zeroAgentUsage,\n        toolCalls: []\n      }),\n      (acc, event) => {\n        const next =\n          event._tag === 'AgentAwaitingInput'\n            ? { ...acc, requests: event.requests, usage: event.usage }\n            : event._tag === 'UsageUpdate'\n              ? { ...acc, usage: addAgentUsage(acc.usage, event.usage) }\n              : event._tag === 'ToolExecutionCompleted' || event._tag === 'ToolExecutionAccepted'\n                ? { ...acc, toolCalls: [...acc.toolCalls, event.call] }\n                : acc\n        return onEvent === undefined ? Effect.succeed(next) : onEvent(event).pipe(Effect.as(next))\n      }\n    ),\n    Effect.map((result): ToolBatchOutcome => {\n      if (result.requests.length === 0) {\n        const needsContinuation = result.toolCalls.length > 0\n        return {\n          _tag: 'Completed',\n          needsContinuation,\n          assistantMessage: undefined,\n          toolCalls: result.toolCalls,\n          usage: result.usage,\n          stopReason: needsContinuation ? 'tool_use' : 'stop'\n        }\n      }\n      return { _tag: 'AwaitingInput', requests: result.requests, usage: result.usage }\n    })\n  )\n}\n\nexport type HitlMatch =\n  | { readonly _tag: 'Match'; readonly requestId: string }\n  | { readonly _tag: 'Mismatch' }\n\nconst hitlResponseMatchesRequest = (response: HitlResponse, request: HitlRequest) => {\n  switch (response._tag) {\n    case 'ToolApprovalResponse':\n      return (\n        request._tag === 'ToolApprovalRequest' &&\n        response.requestId === request.requestId &&\n        response.toolCallId === request.toolCallId\n      )\n    case 'QuestionResponse':\n      return (\n        request._tag === 'QuestionRequest' &&\n        response.requestId === request.requestId &&\n        response.toolCallId === request.toolCallId\n      )\n  }\n}\n\nexport const matchHitlResponse = (\n  pending: ReadonlyArray<HitlRequest>,\n  response: HitlResponse\n): HitlMatch => {\n  const matched = pending.find(request => hitlResponseMatchesRequest(response, request))\n  return matched === undefined\n    ? { _tag: 'Mismatch' }\n    : { _tag: 'Match', requestId: matched.requestId }\n}\n\nexport const resumeHitlIfMatched = <A, E, R>(input: {\n  readonly pending: ReadonlyArray<HitlRequest>\n  readonly response: HitlResponse\n  readonly resume: (requestId: string) => Effect.Effect<A, E, R>\n}): Effect.Effect<A | { readonly _tag: 'Mismatch' }, E, R> => {\n  const matched = matchHitlResponse(input.pending, input.response)\n  if (matched._tag === 'Mismatch') return Effect.succeed(matched)\n  return input.resume(matched.requestId)\n}\n"],"mappings":"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"}

package/dist/store.d.mts

@@ -0,0 +1,25 @@
+import { Context, Effect, Layer } from "effect";
+
+//#region src/store.d.ts
+type RunStoreShape = {
+  readonly claim: (runId: string) => Effect.Effect<void>;
+  readonly release: (runId: string) => Effect.Effect<void>;
+  readonly isClaimed: (runId: string) => Effect.Effect<boolean>;
+  readonly claimed: Effect.Effect<ReadonlySet<string>>;
+  readonly incrementResumeCount: (runId: string) => Effect.Effect<number>;
+  readonly resumeCount: (runId: string) => Effect.Effect<number>;
+};
+declare const RunStore_base: Context.ServiceClass<RunStore, "@yolk-sdk/harness/RunStore", RunStoreShape>;
+declare class RunStore extends RunStore_base {}
+type DurableRunStoreSnapshot = {
+  readonly claimed: ReadonlyArray<string>;
+  readonly resumes: ReadonlyArray<readonly [string, number]>;
+};
+declare const makeSnapshotRunStoreLayer: (options: {
+  readonly load: Effect.Effect<DurableRunStoreSnapshot | undefined>;
+  readonly save: (snapshot: DurableRunStoreSnapshot) => Effect.Effect<void>;
+}) => Layer.Layer<RunStore>;
+declare const makeInMemoryRunStoreLayer: () => Layer.Layer<RunStore>;
+//#endregion
+export { DurableRunStoreSnapshot, RunStore, RunStoreShape, makeInMemoryRunStoreLayer, makeSnapshotRunStoreLayer };
+//# sourceMappingURL=store.d.mts.map

package/dist/store.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.mts","names":[],"sources":["../src/store.ts"],"mappings":";;;KAEY,aAAA;EAAA,SACD,KAAA,GAAQ,KAAA,aAAkB,MAAA,CAAO,MAAA;EAAA,SACjC,OAAA,GAAU,KAAA,aAAkB,MAAA,CAAO,MAAA;EAAA,SACnC,SAAA,GAAY,KAAA,aAAkB,MAAA,CAAO,MAAA;EAAA,SACrC,OAAA,EAAS,MAAA,CAAO,MAAA,CAAO,WAAA;EAAA,SACvB,oBAAA,GAAuB,KAAA,aAAkB,MAAA,CAAO,MAAA;EAAA,SAChD,WAAA,GAAc,KAAA,aAAkB,MAAA,CAAO,MAAA;AAAA;AAAA,cACjD,aAAA;cAEY,QAAA,SAAiB,aAE7B;AAAA,KAEW,uBAAA;EAAA,SACD,OAAA,EAAS,aAAA;EAAA,SACT,OAAA,EAAS,aAAa;AAAA;AAAA,cAgFpB,yBAAA,GAA6B,OAAA;EAAA,SAC/B,IAAA,EAAM,MAAA,CAAO,MAAA,CAAO,uBAAA;EAAA,SACpB,IAAA,GAAO,QAAA,EAAU,uBAAA,KAA4B,MAAA,CAAO,MAAA;AAAA,MAC3D,KAAA,CAAM,KAAA,CAAM,QAAA;AAAA,cAEH,yBAAA,QAAgC,KAAA,CAAM,KAAK,CAAC,QAAA"}

package/dist/store.mjs

@@ -0,0 +1,86 @@
+import { Context, Effect, Layer, Ref, Semaphore } from "effect";
+//#region src/store.ts
+var RunStore = class extends Context.Service()("@yolk-sdk/harness/RunStore") {};
+const emptySnapshot = {
+	claimed: [],
+	resumes: []
+};
+const snapshotFromMemory = (memory) => ({
+	claimed: [...memory.claimed],
+	resumes: [...memory.resumes.entries()]
+});
+const memoryFromSnapshot = (snapshot) => ({
+	claimed: new Set(snapshot.claimed),
+	resumes: new Map(snapshot.resumes)
+});
+const makeSnapshotRunStore = (options) => Effect.gen(function* () {
+	const loaded = yield* options.load;
+	const memory = yield* Ref.make(memoryFromSnapshot(loaded ?? emptySnapshot));
+	const lock = yield* Semaphore.make(1);
+	const mutate = (effect) => Effect.uninterruptibleMask((restore) => restore(lock.take(1)).pipe(Effect.flatMap(() => effect.pipe(Effect.ensuring(lock.release(1))))));
+	const commit = (next) => options.save(snapshotFromMemory(next)).pipe(Effect.flatMap(() => Ref.set(memory, next)));
+	return RunStore.of({
+		claim: (runId) => mutate(Effect.gen(function* () {
+			const current = yield* Ref.get(memory);
+			yield* commit({
+				claimed: new Set(current.claimed).add(runId),
+				resumes: current.resumes
+			});
+		})),
+		release: (runId) => mutate(Effect.gen(function* () {
+			const current = yield* Ref.get(memory);
+			const claimed = new Set(current.claimed);
+			claimed.delete(runId);
+			const resumes = new Map(current.resumes);
+			resumes.delete(runId);
+			yield* commit({
+				claimed,
+				resumes
+			});
+		})),
+		isClaimed: (runId) => Ref.get(memory).pipe(Effect.map((current) => current.claimed.has(runId))),
+		claimed: Ref.get(memory).pipe(Effect.map((current) => new Set(current.claimed))),
+		incrementResumeCount: (runId) => mutate(Effect.gen(function* () {
+			const current = yield* Ref.get(memory);
+			const nextCount = (current.resumes.get(runId) ?? 0) + 1;
+			const resumes = new Map(current.resumes);
+			resumes.set(runId, nextCount);
+			yield* commit({
+				claimed: current.claimed,
+				resumes
+			});
+			return nextCount;
+		})),
+		resumeCount: (runId) => Ref.get(memory).pipe(Effect.map((current) => current.resumes.get(runId) ?? 0))
+	});
+});
+const makeSnapshotRunStoreLayer = (options) => Layer.effect(RunStore, makeSnapshotRunStore(options));
+const makeInMemoryRunStoreLayer = () => Layer.effect(RunStore, Effect.gen(function* () {
+	const claimed = yield* Ref.make(/* @__PURE__ */ new Set());
+	const resumes = yield* Ref.make(/* @__PURE__ */ new Map());
+	return RunStore.of({
+		claim: (runId) => Ref.update(claimed, (current) => new Set(current).add(runId)),
+		release: (runId) => Effect.zip(Ref.update(claimed, (current) => {
+			const next = new Set(current);
+			next.delete(runId);
+			return next;
+		}), Ref.update(resumes, (current) => {
+			const next = new Map(current);
+			next.delete(runId);
+			return next;
+		})).pipe(Effect.asVoid),
+		isClaimed: (runId) => Ref.get(claimed).pipe(Effect.map((current) => current.has(runId))),
+		claimed: Ref.get(claimed).pipe(Effect.map((current) => new Set(current))),
+		incrementResumeCount: (runId) => Ref.modify(resumes, (current) => {
+			const nextCount = (current.get(runId) ?? 0) + 1;
+			const next = new Map(current);
+			next.set(runId, nextCount);
+			return [nextCount, next];
+		}),
+		resumeCount: (runId) => Ref.get(resumes).pipe(Effect.map((current) => current.get(runId) ?? 0))
+	});
+}));
+//#endregion
+export { RunStore, makeInMemoryRunStoreLayer, makeSnapshotRunStoreLayer };
+
+//# sourceMappingURL=store.mjs.map

package/dist/store.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.mjs","names":[],"sources":["../src/store.ts"],"sourcesContent":["import { Context, Effect, Layer, Ref, Semaphore } from 'effect'\n\nexport type RunStoreShape = {\n  readonly claim: (runId: string) => Effect.Effect<void>\n  readonly release: (runId: string) => Effect.Effect<void>\n  readonly isClaimed: (runId: string) => Effect.Effect<boolean>\n  readonly claimed: Effect.Effect<ReadonlySet<string>>\n  readonly incrementResumeCount: (runId: string) => Effect.Effect<number>\n  readonly resumeCount: (runId: string) => Effect.Effect<number>\n}\n\nexport class RunStore extends Context.Service<RunStore, RunStoreShape>()(\n  '@yolk-sdk/harness/RunStore'\n) {}\n\nexport type DurableRunStoreSnapshot = {\n  readonly claimed: ReadonlyArray<string>\n  readonly resumes: ReadonlyArray<readonly [string, number]>\n}\n\ntype MemorySnapshot = {\n  readonly claimed: ReadonlySet<string>\n  readonly resumes: ReadonlyMap<string, number>\n}\n\nconst emptySnapshot: DurableRunStoreSnapshot = {\n  claimed: [],\n  resumes: []\n}\n\nconst snapshotFromMemory = (memory: MemorySnapshot): DurableRunStoreSnapshot => ({\n  claimed: [...memory.claimed],\n  resumes: [...memory.resumes.entries()]\n})\n\nconst memoryFromSnapshot = (snapshot: DurableRunStoreSnapshot): MemorySnapshot => ({\n  claimed: new Set(snapshot.claimed),\n  resumes: new Map(snapshot.resumes)\n})\n\nconst makeSnapshotRunStore = (options: {\n  readonly load: Effect.Effect<DurableRunStoreSnapshot | undefined>\n  readonly save: (snapshot: DurableRunStoreSnapshot) => Effect.Effect<void>\n}): Effect.Effect<RunStore['Service']> =>\n  Effect.gen(function* () {\n    const loaded = yield* options.load\n    const memory = yield* Ref.make(memoryFromSnapshot(loaded ?? emptySnapshot))\n    const lock = yield* Semaphore.make(1)\n    const mutate = <A, E, R>(effect: Effect.Effect<A, E, R>) =>\n      Effect.uninterruptibleMask(restore =>\n        restore(lock.take(1)).pipe(\n          Effect.flatMap(() => effect.pipe(Effect.ensuring(lock.release(1))))\n        )\n      )\n    const commit = (next: MemorySnapshot) =>\n      options.save(snapshotFromMemory(next)).pipe(Effect.flatMap(() => Ref.set(memory, next)))\n\n    return RunStore.of({\n      claim: runId =>\n        mutate(\n          Effect.gen(function* () {\n            const current = yield* Ref.get(memory)\n            yield* commit({\n              claimed: new Set(current.claimed).add(runId),\n              resumes: current.resumes\n            })\n          })\n        ),\n      release: runId =>\n        mutate(\n          Effect.gen(function* () {\n            const current = yield* Ref.get(memory)\n            const claimed = new Set(current.claimed)\n            claimed.delete(runId)\n            const resumes = new Map(current.resumes)\n            resumes.delete(runId)\n            yield* commit({ claimed, resumes })\n          })\n        ),\n      isClaimed: runId => Ref.get(memory).pipe(Effect.map(current => current.claimed.has(runId))),\n      claimed: Ref.get(memory).pipe(Effect.map(current => new Set(current.claimed))),\n      incrementResumeCount: runId =>\n        mutate(\n          Effect.gen(function* () {\n            const current = yield* Ref.get(memory)\n            const nextCount = (current.resumes.get(runId) ?? 0) + 1\n            const resumes = new Map(current.resumes)\n            resumes.set(runId, nextCount)\n            yield* commit({ claimed: current.claimed, resumes })\n            return nextCount\n          })\n        ),\n      resumeCount: runId =>\n        Ref.get(memory).pipe(Effect.map(current => current.resumes.get(runId) ?? 0))\n    })\n  })\n\nexport const makeSnapshotRunStoreLayer = (options: {\n  readonly load: Effect.Effect<DurableRunStoreSnapshot | undefined>\n  readonly save: (snapshot: DurableRunStoreSnapshot) => Effect.Effect<void>\n}): Layer.Layer<RunStore> => Layer.effect(RunStore, makeSnapshotRunStore(options))\n\nexport const makeInMemoryRunStoreLayer = (): Layer.Layer<RunStore> =>\n  Layer.effect(\n    RunStore,\n    Effect.gen(function* () {\n      const claimed = yield* Ref.make(new Set<string>())\n      const resumes = yield* Ref.make(new Map<string, number>())\n\n      return RunStore.of({\n        claim: runId => Ref.update(claimed, current => new Set(current).add(runId)),\n        release: runId =>\n          Effect.zip(\n            Ref.update(claimed, current => {\n              const next = new Set(current)\n              next.delete(runId)\n              return next\n            }),\n            Ref.update(resumes, current => {\n              const next = new Map(current)\n              next.delete(runId)\n              return next\n            })\n          ).pipe(Effect.asVoid),\n        isClaimed: runId => Ref.get(claimed).pipe(Effect.map(current => current.has(runId))),\n        claimed: Ref.get(claimed).pipe(Effect.map(current => new Set(current))),\n        incrementResumeCount: runId =>\n          Ref.modify(resumes, current => {\n            const nextCount = (current.get(runId) ?? 0) + 1\n            const next = new Map(current)\n            next.set(runId, nextCount)\n            return [nextCount, next] as const\n          }),\n        resumeCount: runId => Ref.get(resumes).pipe(Effect.map(current => current.get(runId) ?? 0))\n      })\n    })\n  )\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@yolk-sdk/harness",
+  "version": "0.1.0-canary.77",
+  "description": "Domain-free agent run lifecycle: coordinator, store, inbox, and pluggable drivers.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/magoz/yolk-sdk.git",
+    "directory": "packages/harness"
+  },
+  "bugs": {
+    "url": "https://github.com/magoz/yolk-sdk/issues"
+  },
+  "homepage": "https://github.com/magoz/yolk-sdk#readme",
+  "keywords": [
+    "agent",
+    "harness",
+    "lifecycle",
+    "effect"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./coordinator": {
+      "types": "./dist/coordinator.d.mts",
+      "import": "./dist/coordinator.mjs",
+      "default": "./dist/coordinator.mjs"
+    },
+    "./store": {
+      "types": "./dist/store.d.mts",
+      "import": "./dist/store.mjs",
+      "default": "./dist/store.mjs"
+    },
+    "./inbox": {
+      "types": "./dist/inbox.d.mts",
+      "import": "./dist/inbox.mjs",
+      "default": "./dist/inbox.mjs"
+    },
+    "./driver": {
+      "types": "./dist/driver.d.mts",
+      "import": "./dist/driver.mjs",
+      "default": "./dist/driver.mjs"
+    },
+    "./driver/memory": {
+      "types": "./dist/driver/memory.d.mts",
+      "import": "./dist/driver/memory.mjs",
+      "default": "./dist/driver/memory.mjs"
+    },
+    "./driver/durable-object": {
+      "types": "./dist/driver/durable-object.d.mts",
+      "import": "./dist/driver/durable-object.mjs",
+      "default": "./dist/driver/durable-object.mjs"
+    },
+    "./outcome": {
+      "types": "./dist/outcome.d.mts",
+      "import": "./dist/outcome.mjs",
+      "default": "./dist/outcome.mjs"
+    }
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "dist/**/*",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "effect": "4.0.0-beta.80",
+    "@yolk-sdk/agent": "^0.1.0-canary.77"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:run": "vitest run --passWithNoTests"
+  }
+}

package/src/coordinator.ts

@@ -0,0 +1,254 @@
+/**
+ * Process-local run coordinator.
+ *
+ * Port of OpenCode v2 `SessionRunCoordinator` (MIT): one busy period per key,
+ * a doorbell that coalesces wakes, and interrupt that claims pending wakes so a
+ * dead intent cannot restart. Steering lands at the next drain boundary.
+ *
+ * @see https://github.com/sst/opencode (packages/core/src/session/run-coordinator.ts)
+ */
+import { Deferred, Effect, Fiber, FiberSet } from 'effect'
+import type { Exit, Scope } from 'effect'
+
+// Private settlement receipt: succeed the Deferred with Exit as a value so
+// interrupt fan-out does not skip Effect 4.0.0-beta.80 Deferred listeners.
+// Public waiters flatten that Exit; this is not a global Deferred fix.
+const awaitDone = <E>(done: Deferred.Deferred<Exit.Exit<void, E>>): Effect.Effect<void, E> =>
+  Deferred.await(done).pipe(Effect.flatMap(exit => exit))
+
+/** `"input"` subsumes `"steer"` when coalescing wakes. */
+export type Promotable = 'input' | 'steer'
+
+export type CapturedRun<E> =
+  | { readonly _tag: 'Started'; readonly join: Effect.Effect<void, E> }
+  | { readonly _tag: 'Joined'; readonly join: Effect.Effect<void, E> }
+  | { readonly _tag: 'Stopping'; readonly awaitSettlement: Effect.Effect<void> }
+
+export type StopReceipt =
+  | { readonly _tag: 'Idle' }
+  | { readonly _tag: 'Interrupted' }
+  | { readonly _tag: 'LiveStopping' }
+  | { readonly _tag: 'Settling' }
+
+export type Coordinator<Key, E, Reason = never> = {
+  readonly active: Effect.Effect<ReadonlySet<Key>>
+  readonly isActive: (key: Key) => Effect.Effect<boolean>
+  /** Starts an execution while idle, or joins the active execution. */
+  readonly run: (key: Key) => Effect.Effect<void, E>
+  /**
+   * Captures a run waiter without awaiting settlement.
+   * Idle starts force=true (`Started`); an active owner is joined (`Joined`),
+   * including during natural settlement. A stopping owner yields `Stopping` with a
+   * settlement waiter and no start.
+   */
+  readonly captureRun: (key: Key) => Effect.Effect<CapturedRun<E>>
+  /** Rings the doorbell: idle starts; active drains again before settling. */
+  readonly wake: (key: Key, scope?: Promotable) => Effect.Effect<void>
+  /**
+   * Stops the active execution and clears its doorbell. No-op when idle.
+   * Resolves once the interruption request is delivered, not when cleanup settles.
+   * First accepted `reason` is kept; use `terminalStop` to escalate.
+   */
+  readonly interrupt: (
+    key: Key,
+    reason?: Reason,
+    options?: { readonly awaitSettlement?: boolean }
+  ) => Effect.Effect<boolean>
+  /**
+   * Terminal stop receipt. Always clears pendingWake. Settling means the owner
+   * is already gone and the settled callback is chosen; Driver may release the
+   * claim under the Inbox gate. LiveStopping/Interrupted leave release to that
+   * owner's future settled callback. LiveStopping joins the same outstanding
+   * interruption request rather than forking a second one.
+   */
+  readonly terminalStop: (key: Key, reason: Reason) => Effect.Effect<StopReceipt>
+  /** Resolves once no execution is active. Never starts work. */
+  readonly awaitIdle: (key: Key) => Effect.Effect<void>
+}
+
+type Execution<E, Reason> = {
+  readonly done: Deferred.Deferred<Exit.Exit<void, E>>
+  owner?: Fiber.Fiber<void>
+  request?: Fiber.Fiber<void>
+  scope: Promotable
+  pendingWake?: Promotable
+  stopping: boolean
+  interruptionReason?: Reason
+}
+
+const widerScope = (current: Promotable | undefined, next: Promotable): Promotable =>
+  current === 'input' || next === 'input' ? 'input' : 'steer'
+
+export const makeCoordinator = <Key, E, Reason = never>(options: {
+  readonly drain: (key: Key, force: boolean, scope: Promotable) => Effect.Effect<void, E>
+  readonly started?: (key: Key) => Effect.Effect<void>
+  readonly settled?: (key: Key, exit: Exit.Exit<void, E>, reason?: Reason) => Effect.Effect<void>
+}): Effect.Effect<Coordinator<Key, E, Reason>, never, Scope.Scope> =>
+  Effect.gen(function* () {
+    const executions = new Map<Key, Execution<E, Reason>>()
+    const fork = yield* FiberSet.makeRuntime<never, void, never>()
+
+    const loop = (
+      key: Key,
+      execution: Execution<E, Reason>,
+      force: boolean
+    ): Effect.Effect<void, E> =>
+      Effect.suspend(() => {
+        if (execution.stopping) return Effect.void
+        return options.drain(key, force, execution.scope)
+      }).pipe(
+        Effect.andThen(
+          Effect.suspend(() => {
+            if (execution.stopping || execution.pendingWake === undefined) return Effect.void
+            execution.scope = execution.pendingWake
+            execution.pendingWake = undefined
+            return Effect.yieldNow.pipe(Effect.andThen(loop(key, execution, false)))
+          })
+        )
+      )
+
+    const settle = (key: Key, execution: Execution<E, Reason>, exit: Exit.Exit<void, E>) => {
+      if (execution.pendingWake !== undefined) start(key, false, execution.pendingWake)
+      else executions.delete(key)
+      return Deferred.succeed(execution.done, exit).pipe(Effect.asVoid)
+    }
+
+    const start = (key: Key, force: boolean, scope: Promotable) => {
+      const execution: Execution<E, Reason> = {
+        done: Deferred.makeUnsafe<Exit.Exit<void, E>>(),
+        scope,
+        stopping: false
+      }
+      executions.set(key, execution)
+      execution.owner = fork(
+        Effect.yieldNow.pipe(
+          Effect.andThen(
+            Effect.uninterruptible(Effect.suspend(() => options.started?.(key) ?? Effect.void))
+          ),
+          Effect.andThen(loop(key, execution, force)),
+          Effect.onExit(exit =>
+            Effect.suspend(() => {
+              execution.owner = undefined
+              return options.settled?.(key, exit, execution.interruptionReason) ?? Effect.void
+            })
+          ),
+          Effect.onExit(exit => settle(key, execution, exit)),
+          Effect.exit,
+          Effect.asVoid
+        )
+      )
+      return execution
+    }
+
+    const forkInterruptionRequest = (owner: Fiber.Fiber<void>): Fiber.Fiber<void> =>
+      fork(Effect.yieldNow.pipe(Effect.andThen(Effect.sync(() => owner.interruptUnsafe()))))
+
+    const interruptNow = (key: Key, reason?: Reason): Effect.Effect<boolean> =>
+      Effect.suspend(() => {
+        const execution = executions.get(key)
+        if (execution === undefined || execution.stopping) return Effect.succeed(false)
+        if (execution.owner === undefined) {
+          execution.pendingWake = undefined
+          return Effect.succeed(false)
+        }
+        const owner = execution.owner
+        execution.stopping = true
+        execution.pendingWake = undefined
+        execution.interruptionReason = reason
+        // Capture the exact old owner and fork the request in this same lazy
+        // transition so cancellation cannot leave stopping=true with no request.
+        // Initial yield breaks owner -> resumed caller -> owner reentrancy.
+        // Join the request fiber only; interruptUnsafe may run interruptible
+        // finalizers inline until they suspend. Do not await owner settlement.
+        const request = forkInterruptionRequest(owner)
+        execution.request = request
+        return Fiber.join(request).pipe(Effect.as(true))
+      })
+
+    const awaitIdle = (key: Key): Effect.Effect<void> =>
+      Effect.suspend(() => {
+        const execution = executions.get(key)
+        if (execution === undefined) return Effect.void
+        return awaitDone(execution.done).pipe(Effect.ignoreCause, Effect.andThen(awaitIdle(key)))
+      })
+
+    return {
+      active: Effect.sync(() => new Set(executions.keys())),
+      isActive: key => Effect.sync(() => executions.has(key)),
+      run: key =>
+        Effect.suspend(() => {
+          const execution = executions.get(key)
+          if (execution === undefined) return awaitDone(start(key, true, 'input').done)
+          if (!execution.stopping) return awaitDone(execution.done)
+          return awaitDone(execution.done).pipe(
+            Effect.ignoreCause,
+            Effect.andThen(
+              Effect.suspend(() => {
+                const next = executions.get(key)
+                return next === undefined
+                  ? awaitDone(start(key, true, 'input').done)
+                  : awaitDone(next.done)
+              })
+            )
+          )
+        }),
+      captureRun: key =>
+        Effect.sync(() => {
+          const execution = executions.get(key)
+          if (execution === undefined) {
+            const started = start(key, true, 'input')
+            return { _tag: 'Started' as const, join: awaitDone(started.done) }
+          }
+          if (!execution.stopping) {
+            return { _tag: 'Joined' as const, join: awaitDone(execution.done) }
+          }
+          return {
+            _tag: 'Stopping' as const,
+            awaitSettlement: awaitDone(execution.done).pipe(Effect.ignoreCause)
+          }
+        }),
+      wake: (key, scope = 'input') =>
+        Effect.sync(() => {
+          const execution = executions.get(key)
+          if (execution !== undefined) {
+            execution.pendingWake = widerScope(execution.pendingWake, scope)
+            return
+          }
+          start(key, false, scope)
+        }),
+      interrupt: (key, reason, options) =>
+        Effect.suspend(() => {
+          const execution = executions.get(key)
+          return interruptNow(key, reason).pipe(
+            Effect.tap(() =>
+              options?.awaitSettlement === true && execution !== undefined
+                ? awaitDone(execution.done).pipe(Effect.ignoreCause)
+                : Effect.void
+            )
+          )
+        }),
+      terminalStop: (key, reason) =>
+        Effect.suspend((): Effect.Effect<StopReceipt> => {
+          const execution = executions.get(key)
+          if (execution === undefined) return Effect.succeed({ _tag: 'Idle' } as const)
+          execution.pendingWake = undefined
+          if (execution.owner === undefined) {
+            execution.stopping = true
+            return Effect.succeed({ _tag: 'Settling' } as const)
+          }
+          execution.interruptionReason = reason
+          if (execution.stopping) {
+            const request = execution.request
+            return request === undefined
+              ? Effect.succeed({ _tag: 'LiveStopping' } as const)
+              : Fiber.join(request).pipe(Effect.as({ _tag: 'LiveStopping' } as const))
+          }
+          const owner = execution.owner
+          execution.stopping = true
+          const request = forkInterruptionRequest(owner)
+          execution.request = request
+          return Fiber.join(request).pipe(Effect.as({ _tag: 'Interrupted' } as const))
+        }),
+      awaitIdle
+    }
+  })