@yolk-sdk/harness 0.1.0-canary.100

package/src/outcome.ts

@@ -0,0 +1,377 @@
+import { Effect, Match, Predicate, Stream, type Data } from 'effect'
+import {
+  HitlMatch as hitlMatch,
+  OverflowCompactionResult as overflowCompactionResult,
+  StepOutcome as stepOutcome
+} from './outcome-constructors-internal.ts'
+import {
+  addAgentUsage,
+  zeroAgentUsage,
+  type AgentEvent,
+  type AgentMessage,
+  type AgentUsage,
+  type HitlRequest,
+  type HitlResponse
+} from '@yolk-sdk/agent/protocol'
+import {
+  collectModelTurnAttempt,
+  LLMError,
+  runModelTurn,
+  runToolBatch,
+  type AgentLoopError,
+  type ContextTransformer,
+  type LLMProvider,
+  type LoopConfig,
+  type ModelTurnConfig,
+  type ModelTurnResult,
+  type ToolBatchConfig,
+  type ToolExecutor
+} from '@yolk-sdk/agent/loop'
+import {
+  applyOverflowCompaction,
+  isOverflowCompactionAttemptCount
+} from '@yolk-sdk/agent/compaction'
+
+export type OverflowCompactionResult =
+  | { readonly _tag: 'Compacted'; readonly messages: ReadonlyArray<AgentMessage> }
+  | { readonly _tag: 'Skipped' }
+
+export const OverflowCompactionResult = overflowCompactionResult
+
+export type StepOutcome = Data.TaggedEnum<{
+  Completed: {
+    readonly needsContinuation: boolean
+    readonly assistantMessage: ModelTurnResult['assistantMessage']
+    readonly toolCalls: ModelTurnResult['toolCalls']
+    readonly usage: ModelTurnResult['usage']
+    readonly stopReason: ModelTurnResult['stopReason']
+  }
+  Retry: {
+    readonly error: AgentLoopError
+  }
+  Continue: {
+    readonly error: AgentLoopError
+    readonly assistantMessage: ModelTurnResult['assistantMessage']
+    readonly toolCalls: ModelTurnResult['toolCalls']
+    readonly usage: ModelTurnResult['usage']
+    readonly stopReason: ModelTurnResult['stopReason']
+  }
+  RecoverFull: {
+    readonly error: AgentLoopError
+  }
+  Compacted: {
+    readonly messages: ReadonlyArray<AgentMessage>
+    readonly overflowCompactionAttempt: number
+  }
+  AwaitingInput: {
+    readonly requests: ReadonlyArray<HitlRequest>
+    readonly usage: AgentUsage
+  }
+}>
+
+export const StepOutcome = stepOutcome
+
+export type CompletedTurn = Extract<StepOutcome, { readonly _tag: 'Completed' }>
+
+export type ModelTurnOutcome = Exclude<StepOutcome, { readonly _tag: 'AwaitingInput' }>
+
+export type ToolBatchOutcome = Extract<
+  StepOutcome,
+  { readonly _tag: 'Completed' | 'AwaitingInput' }
+>
+
+const completedOutcome = (result: ModelTurnResult): CompletedTurn =>
+  StepOutcome.Completed({
+    needsContinuation: result.stopReason === 'tool_use',
+    assistantMessage: result.assistantMessage,
+    toolCalls: result.toolCalls,
+    usage: result.usage,
+    stopReason: result.stopReason
+  })
+
+const modelTurnResult = (result: ModelTurnResult): ModelTurnResult => ({
+  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: unknown): error is AgentLoopError => {
+  if (!Predicate.isObjectOrArray(error) || !('_tag' in error)) {
+    return false
+  }
+
+  const tag = error._tag
+
+  return (
+    tag === 'LLMError' ||
+    tag === 'FauxExhaustedError' ||
+    tag === 'ToolError' ||
+    tag === 'ContextTransformError' ||
+    tag === 'AbortError'
+  )
+}
+
+const isOverflow = (error: AgentLoopError) =>
+  Match.value(error).pipe(
+    Match.tag('LLMError', 'ContextTransformError', current => current.cause === 'context_overflow'),
+    Match.orElse(() => false)
+  )
+
+const isMissingDone = (error: AgentLoopError) =>
+  Match.value(error).pipe(
+    Match.tag('LLMError', current => current.responseIssue === 'missing_done'),
+    Match.orElse(() => false)
+  )
+
+const isRetryableLlm = (
+  error: AgentLoopError
+): error is Extract<AgentLoopError, { _tag: 'LLMError' }> =>
+  Predicate.isTagged(error, 'LLMError') && error.retryable
+
+const classifyModelTurnFailure = <E2, R2>(input: {
+  readonly error: AgentLoopError
+  readonly collected: ModelTurnResult
+  readonly outputStarted: boolean
+  readonly messages: ReadonlyArray<AgentMessage>
+  readonly overflowCompactionAttempt: number
+  readonly compact?: (
+    messages: ReadonlyArray<AgentMessage>
+  ) => Effect.Effect<OverflowCompactionResult, E2, R2>
+}): Effect.Effect<ModelTurnOutcome, AgentLoopError | E2, R2> => {
+  if (isOverflow(input.error)) {
+    if (input.compact === undefined) {
+      return Effect.fail(input.error)
+    }
+
+    return applyOverflowCompaction({
+      compact: input.compact,
+      messages: input.messages,
+      attempt: input.overflowCompactionAttempt,
+      outputStarted: input.outputStarted
+    }).pipe(
+      Effect.flatMap(result =>
+        Match.value(result).pipe(
+          Match.tag('Compacted', current =>
+            Effect.succeed(
+              StepOutcome.Compacted({
+                messages: current.messages,
+                overflowCompactionAttempt: input.overflowCompactionAttempt + 1
+              })
+            )
+          ),
+          Match.orElse(() => Effect.fail(input.error))
+        )
+      )
+    )
+  }
+
+  if (isMissingDone(input.error) && !input.outputStarted) {
+    return Effect.succeed(StepOutcome.RecoverFull({ error: input.error }))
+  }
+
+  if (isMissingDone(input.error) && input.outputStarted) {
+    return Effect.succeed(
+      StepOutcome.Continue({
+        error: input.error,
+        ...modelTurnResult(input.collected)
+      })
+    )
+  }
+
+  if (isRetryableLlm(input.error) && !input.outputStarted) {
+    if (input.error.cause === 'invalid_response') {
+      return Effect.succeed(StepOutcome.RecoverFull({ error: input.error }))
+    }
+
+    return Effect.succeed(StepOutcome.Retry({ error: input.error }))
+  }
+
+  if (isRetryableLlm(input.error) && input.outputStarted) {
+    return Effect.succeed(
+      StepOutcome.Continue({
+        error: input.error,
+        ...modelTurnResult(input.collected)
+      })
+    )
+  }
+
+  return Effect.fail(input.error)
+}
+
+export const attemptModelTurn = <E2 = never, R2 = never>(
+  config: ModelTurnConfig,
+  options?: {
+    readonly onEvent?: (event: AgentEvent) => Effect.Effect<void, E2, R2>
+    readonly initialUsage?: AgentUsage
+    readonly overflowCompactionAttempt?: number
+    readonly compact?: (
+      messages: ReadonlyArray<AgentMessage>
+    ) => Effect.Effect<OverflowCompactionResult, E2, R2>
+  }
+): Effect.Effect<
+  ModelTurnOutcome,
+  AgentLoopError | E2,
+  ContextTransformer | LLMProvider | LoopConfig | R2
+> =>
+  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
+    })
+
+    return yield* Match.value(outcome).pipe(
+      Match.tag('Collected', current => Effect.succeed(completedOutcome(current.collection))),
+      Match.tag('SinkFailed', current => Effect.fail(current.error)),
+      Match.tag('StreamFailed', current => {
+        if (!isAgentLoopError(current.error)) {
+          return Effect.fail(current.error)
+        }
+
+        return classifyModelTurnFailure({
+          error: current.error,
+          collected: {
+            assistantMessage:
+              current.collection.assistantMessage ?? current.collection.partialAssistantMessage,
+            toolCalls: current.collection.toolCalls,
+            usage: current.collection.usage,
+            stopReason: current.collection.stopReason
+          },
+          outputStarted: current.collection.outputStarted,
+          messages: config.messages,
+          overflowCompactionAttempt,
+          compact: options?.compact
+        })
+      }),
+      Match.exhaustive
+    )
+  })
+
+type AttemptToolBatchFoldState = {
+  requests: ReadonlyArray<HitlRequest>
+  usage: AgentUsage
+  toolCalls: ModelTurnResult['toolCalls']
+}
+
+export const attemptToolBatch = <E2 = never, R2 = never>(
+  config: ToolBatchConfig,
+  options?: {
+    readonly onEvent?: (event: AgentEvent) => Effect.Effect<void, E2, R2>
+  }
+): Effect.Effect<ToolBatchOutcome, AgentLoopError | E2, LoopConfig | ToolExecutor | R2> => {
+  const onEvent = options?.onEvent
+
+  return runToolBatch(config).pipe(
+    Stream.runFoldEffect(
+      (): AttemptToolBatchFoldState => ({
+        requests: [],
+        usage: config.usage ?? zeroAgentUsage,
+        toolCalls: []
+      }),
+      (acc, event) => {
+        const next = Predicate.isTagged(event, 'AgentAwaitingInput')
+          ? { ...acc, requests: event.requests, usage: event.usage }
+          : Predicate.isTagged(event, 'UsageUpdate')
+            ? { ...acc, usage: addAgentUsage(acc.usage, event.usage) }
+            : Predicate.isTagged(event, 'ToolExecutionCompleted') ||
+                Predicate.isTagged(event, 'ToolExecutionAccepted')
+              ? { ...acc, toolCalls: [...acc.toolCalls, event.call] }
+              : acc
+
+        return onEvent === undefined ? Effect.succeed(next) : onEvent(event).pipe(Effect.as(next))
+      }
+    ),
+    Effect.map((result): ToolBatchOutcome => {
+      if (result.requests.length === 0) {
+        const needsContinuation = result.toolCalls.length > 0
+
+        return StepOutcome.Completed({
+          needsContinuation,
+          assistantMessage: undefined,
+          toolCalls: result.toolCalls,
+          usage: result.usage,
+          stopReason: needsContinuation ? 'tool_use' : 'stop'
+        })
+      }
+
+      return StepOutcome.AwaitingInput({ requests: result.requests, usage: result.usage })
+    })
+  )
+}
+
+export type HitlMatch =
+  | { readonly _tag: 'Match'; readonly requestId: string }
+  | { readonly _tag: 'Mismatch' }
+
+export const HitlMatch = hitlMatch
+
+const hitlResponseMatchesRequest = (response: HitlResponse, request: HitlRequest) =>
+  Match.value(response).pipe(
+    Match.tag(
+      'ToolApprovalResponse',
+      current =>
+        Predicate.isTagged(request, 'ToolApprovalRequest') &&
+        current.requestId === request.requestId &&
+        current.toolCallId === request.toolCallId
+    ),
+    Match.tag(
+      'QuestionResponse',
+      current =>
+        Predicate.isTagged(request, 'QuestionRequest') &&
+        current.requestId === request.requestId &&
+        current.toolCallId === request.toolCallId
+    ),
+    Match.tag(
+      'InputResponse',
+      current =>
+        Predicate.isTagged(request, 'InputRequest') &&
+        current.requestId === request.requestId &&
+        current.toolCallId === request.toolCallId
+    ),
+    Match.tag(
+      'InteractionResponse',
+      current =>
+        Predicate.isTagged(request, 'InteractionRequest') &&
+        current.requestId === request.requestId &&
+        current.toolCallId === request.toolCallId
+    ),
+    Match.exhaustive
+  )
+
+export const matchHitlResponse = (
+  pending: ReadonlyArray<HitlRequest>,
+  response: HitlResponse
+): HitlMatch => {
+  const matched = pending.find(request => hitlResponseMatchesRequest(response, request))
+
+  return matched === undefined
+    ? HitlMatch.Mismatch()
+    : HitlMatch.Match({ requestId: matched.requestId })
+}
+
+export const resumeHitlIfMatched = <A, E, R>(input: {
+  readonly pending: ReadonlyArray<HitlRequest>
+  readonly response: HitlResponse
+  readonly resume: (requestId: string) => Effect.Effect<A, E, R>
+}): Effect.Effect<A | Extract<HitlMatch, { readonly _tag: 'Mismatch' }>, E, R> => {
+  const matched = matchHitlResponse(input.pending, input.response)
+
+  return Match.value(matched).pipe(
+    Match.tag('Mismatch', current => Effect.succeed(current)),
+    Match.tag('Match', current => input.resume(current.requestId)),
+    Match.exhaustive
+  )
+}

package/src/store.ts

@@ -0,0 +1,161 @@
+import { Context, Effect, Layer, Ref, Semaphore } from 'effect'
+
+export type RunStoreApi = {
+  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>
+}
+
+export type SnapshotRunStoreOptions = {
+  readonly load: Effect.Effect<DurableRunStoreSnapshot | undefined>
+  readonly save: (snapshot: DurableRunStoreSnapshot) => Effect.Effect<void>
+}
+
+export type DurableRunStoreSnapshot = {
+  readonly claimed: ReadonlyArray<string>
+  readonly resumes: ReadonlyArray<readonly [string, number]>
+}
+
+type MemorySnapshot = {
+  readonly claimed: ReadonlySet<string>
+  readonly resumes: ReadonlyMap<string, number>
+}
+
+const emptySnapshot: DurableRunStoreSnapshot = {
+  claimed: [],
+  resumes: []
+}
+
+const snapshotFromMemory = (memory: MemorySnapshot): DurableRunStoreSnapshot => ({
+  claimed: [...memory.claimed],
+  resumes: [...memory.resumes.entries()]
+})
+
+const memoryFromSnapshot = (snapshot: DurableRunStoreSnapshot): MemorySnapshot => ({
+  claimed: new Set(snapshot.claimed),
+  resumes: new Map(snapshot.resumes)
+})
+
+export class RunStore extends Context.Service<RunStore, RunStoreApi>()(
+  '@yolk-sdk/harness/RunStore'
+) {
+  /**
+   * Canonical owning layer for snapshot-backed claims. Each call builds a fresh layer so
+   * composed harnesses never share `Ref` state or the snapshot lock across factory calls.
+   */
+  static snapshotLayer = (options: SnapshotRunStoreOptions): Layer.Layer<RunStore> =>
+    Layer.effect(
+      this,
+      Effect.gen(function* () {
+        const loaded = yield* options.load
+        const memory = yield* Ref.make(memoryFromSnapshot(loaded ?? emptySnapshot))
+        const lock = yield* Semaphore.make(1)
+
+        const mutate = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+          Effect.uninterruptibleMask(restore =>
+            restore(lock.take(1)).pipe(
+              Effect.flatMap(() => effect.pipe(Effect.ensuring(lock.release(1))))
+            )
+          )
+
+        const commit = (next: MemorySnapshot) =>
+          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))
+        })
+      })
+    )
+
+  /**
+   * Canonical owning layer for process-local claims. Each call builds a fresh layer so
+   * composed harnesses never share `Ref` state across factory calls.
+   */
+  static inMemoryLayer = (): Layer.Layer<RunStore> =>
+    Layer.effect(
+      this,
+      Effect.gen(function* () {
+        const claimed = yield* Ref.make(new Set<string>())
+        const resumes = yield* Ref.make(new Map<string, number>())
+
+        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] as const
+            }),
+          resumeCount: runId =>
+            Ref.get(resumes).pipe(Effect.map(current => current.get(runId) ?? 0))
+        })
+      })
+    )
+}
+
+/** Backward-compatible delegation to {@link RunStore.snapshotLayer}. */
+export const makeSnapshotRunStoreLayer = (
+  options: SnapshotRunStoreOptions
+): Layer.Layer<RunStore> => RunStore.snapshotLayer(options)
+
+/** Backward-compatible delegation to {@link RunStore.inMemoryLayer}. */
+export const makeInMemoryRunStoreLayer = (): Layer.Layer<RunStore> => RunStore.inMemoryLayer()