@yolk-sdk/agent 0.0.1-canary.0

package/src/runtime/run-runtime.ts

@@ -0,0 +1,307 @@
+import { Effect, Ref, Stream } from 'effect'
+import type {
+  AgentEvent,
+  AgentMessage,
+  AgentModelCapabilities,
+  AgentReasoningEffort,
+  HitlResponse,
+  ToolDef
+} from '@yolk-sdk/agent/protocol'
+import {
+  run,
+  type AgentLoopError,
+  type ContextTransformer,
+  type LLMProvider,
+  type LoopConfig,
+  type ToolExecutor
+} from '@yolk-sdk/agent/loop'
+import { runtimeErrorToAgentError } from './error.ts'
+import {
+  HitlResponseAppended,
+  InputAppended,
+  replayRuntimeHitlResponses,
+  replayRuntimeSessionEvents,
+  RunAwaitingInput,
+  RunCompleted,
+  RunFailed,
+  RunStarted,
+  SessionEventStore,
+  type RuntimeSessionEventLog,
+  type SessionEventStoreApi,
+  type SessionRevision
+} from './session-event-store.ts'
+import type { RuntimeError } from './error.ts'
+
+export type RuntimeTranscript = readonly [AgentMessage, ...Array<AgentMessage>]
+
+export type RuntimeConfig = {
+  readonly systemPrompt: string
+  readonly tools: ReadonlyArray<ToolDef>
+  readonly hitlResponses?: ReadonlyArray<HitlResponse>
+  readonly model: string
+  readonly reasoningEffort?: AgentReasoningEffort
+  readonly capabilities?: AgentModelCapabilities
+}
+
+export type TranscriptRuntimeRequest = {
+  readonly _tag: 'Transcript'
+  readonly sessionId: string
+  readonly messages: RuntimeTranscript
+}
+
+export type AppendInputRuntimeRequest = {
+  readonly _tag: 'AppendInput'
+  readonly sessionId: string
+  readonly input: AgentMessage
+  readonly runId: string
+  readonly expectedRevision?: SessionRevision
+}
+
+export type AppendHitlResponseRuntimeRequest = {
+  readonly _tag: 'AppendHitlResponse'
+  readonly sessionId: string
+  readonly response: HitlResponse
+  readonly runId: string
+  readonly expectedRevision?: SessionRevision
+}
+
+export type RuntimeRequest =
+  | TranscriptRuntimeRequest
+  | AppendInputRuntimeRequest
+  | AppendHitlResponseRuntimeRequest
+
+type LoopRequirements = ContextTransformer | LLMProvider | LoopConfig | ToolExecutor
+type AppendRuntimeRequirements = LoopRequirements | SessionEventStore
+type RuntimeRequirements = LoopRequirements | AppendRuntimeRequirements
+type RuntimeErrorUnion = RuntimeError | AgentLoopError
+
+const extractNewMessages = (event: AgentEvent) => (event._tag === 'AgentEnd' ? event.messages : [])
+
+const runtimeRunConfig = (config: RuntimeConfig, messages: ReadonlyArray<AgentMessage>) => ({
+  messages,
+  systemPrompt: config.systemPrompt,
+  tools: config.tools,
+  hitlResponses: config.hitlResponses,
+  reasoningEffort: config.reasoningEffort,
+  capabilities: config.capabilities,
+  model: config.model
+})
+
+const runAndCollectMessages = (
+  config: RuntimeConfig,
+  messages: ReadonlyArray<AgentMessage>,
+  createdMessages: Ref.Ref<ReadonlyArray<AgentMessage>>
+) =>
+  run(runtimeRunConfig(config, messages)).pipe(
+    Stream.tap(event => {
+      const newMessages = extractNewMessages(event)
+
+      return newMessages.length === 0
+        ? Effect.void
+        : Ref.update(createdMessages, messages => [...messages, ...newMessages])
+    })
+  )
+
+const makeTranscriptRuntimeStream = (request: TranscriptRuntimeRequest, config: RuntimeConfig) =>
+  Stream.unwrap(
+    Ref.make<ReadonlyArray<AgentMessage>>([]).pipe(
+      Effect.map(createdMessages =>
+        runAndCollectMessages(config, request.messages, createdMessages)
+      )
+    )
+  )
+
+const emptyRuntimeSessionEventLog = (sessionId: string): RuntimeSessionEventLog => ({
+  sessionId,
+  revision: 0,
+  events: []
+})
+
+const loadAppendLogOrEmpty = (store: SessionEventStoreApi, sessionId: string) =>
+  store
+    .load(sessionId)
+    .pipe(
+      Effect.catchTag('SessionNotFoundError', () =>
+        Effect.succeed(emptyRuntimeSessionEventLog(sessionId))
+      )
+    )
+
+const appendRunFailed = (
+  store: SessionEventStoreApi,
+  request: AppendInputRuntimeRequest | AppendHitlResponseRuntimeRequest,
+  revision: SessionRevision,
+  error: AgentLoopError
+) =>
+  store.append({
+    sessionId: request.sessionId,
+    expectedRevision: revision,
+    events: [RunFailed.make({ runId: request.runId, error: runtimeErrorToAgentError(error) })]
+  })
+
+const makeAppendInputRuntimeStream = (request: AppendInputRuntimeRequest, config: RuntimeConfig) =>
+  Stream.unwrap(
+    Effect.gen(function* () {
+      const store = yield* SessionEventStore
+      const initialLog = yield* loadAppendLogOrEmpty(store, request.sessionId)
+      const startedLog = yield* store.append({
+        sessionId: request.sessionId,
+        expectedRevision: request.expectedRevision ?? initialLog.revision,
+        events: [
+          InputAppended.make({ message: request.input }),
+          RunStarted.make({ runId: request.runId })
+        ]
+      })
+      const messages = [...replayRuntimeSessionEvents(initialLog.events), request.input]
+      return run(runtimeRunConfig(config, messages)).pipe(
+        Stream.tap(event =>
+          event._tag === 'AgentEnd'
+            ? store
+                .append({
+                  sessionId: request.sessionId,
+                  expectedRevision: startedLog.revision,
+                  events: [RunCompleted.make({ runId: request.runId, messages: event.messages })]
+                })
+                .pipe(Effect.asVoid)
+            : event._tag === 'AgentAwaitingInput'
+              ? store
+                  .append({
+                    sessionId: request.sessionId,
+                    expectedRevision: startedLog.revision,
+                    events: [
+                      RunAwaitingInput.make({
+                        runId: request.runId,
+                        requests: event.requests,
+                        messages: event.messages
+                      })
+                    ]
+                  })
+                  .pipe(Effect.asVoid)
+              : Effect.void
+        ),
+        Stream.catchTags({
+          AbortError: error =>
+            Stream.fromEffect(appendRunFailed(store, request, startedLog.revision, error)).pipe(
+              Stream.flatMap(() => Stream.fail(error))
+            ),
+          ContextTransformError: error =>
+            Stream.fromEffect(appendRunFailed(store, request, startedLog.revision, error)).pipe(
+              Stream.flatMap(() => Stream.fail(error))
+            ),
+          FauxExhaustedError: error =>
+            Stream.fromEffect(appendRunFailed(store, request, startedLog.revision, error)).pipe(
+              Stream.flatMap(() => Stream.fail(error))
+            ),
+          LLMError: error =>
+            Stream.fromEffect(appendRunFailed(store, request, startedLog.revision, error)).pipe(
+              Stream.flatMap(() => Stream.fail(error))
+            ),
+          ToolError: error =>
+            Stream.fromEffect(appendRunFailed(store, request, startedLog.revision, error)).pipe(
+              Stream.flatMap(() => Stream.fail(error))
+            )
+        })
+      )
+    })
+  )
+
+const makeAppendHitlResponseRuntimeStream = (
+  request: AppendHitlResponseRuntimeRequest,
+  config: RuntimeConfig
+) =>
+  Stream.unwrap(
+    Effect.gen(function* () {
+      const store = yield* SessionEventStore
+      const initialLog = yield* loadAppendLogOrEmpty(store, request.sessionId)
+      const startedLog = yield* store.append({
+        sessionId: request.sessionId,
+        expectedRevision: request.expectedRevision ?? initialLog.revision,
+        events: [
+          HitlResponseAppended.make({ response: request.response }),
+          RunStarted.make({ runId: request.runId })
+        ]
+      })
+      const messages = replayRuntimeSessionEvents(initialLog.events)
+      const priorResponses = replayRuntimeHitlResponses(initialLog.events)
+      const hitlResponses = [...priorResponses, request.response]
+
+      return run(runtimeRunConfig({ ...config, hitlResponses }, messages)).pipe(
+        Stream.tap(event =>
+          event._tag === 'AgentEnd'
+            ? store
+                .append({
+                  sessionId: request.sessionId,
+                  expectedRevision: startedLog.revision,
+                  events: [RunCompleted.make({ runId: request.runId, messages: event.messages })]
+                })
+                .pipe(Effect.asVoid)
+            : event._tag === 'AgentAwaitingInput'
+              ? store
+                  .append({
+                    sessionId: request.sessionId,
+                    expectedRevision: startedLog.revision,
+                    events: [
+                      RunAwaitingInput.make({
+                        runId: request.runId,
+                        requests: event.requests,
+                        messages: event.messages
+                      })
+                    ]
+                  })
+                  .pipe(Effect.asVoid)
+              : Effect.void
+        ),
+        Stream.catchTags({
+          AbortError: error =>
+            Stream.fromEffect(appendRunFailed(store, request, startedLog.revision, error)).pipe(
+              Stream.flatMap(() => Stream.fail(error))
+            ),
+          ContextTransformError: error =>
+            Stream.fromEffect(appendRunFailed(store, request, startedLog.revision, error)).pipe(
+              Stream.flatMap(() => Stream.fail(error))
+            ),
+          FauxExhaustedError: error =>
+            Stream.fromEffect(appendRunFailed(store, request, startedLog.revision, error)).pipe(
+              Stream.flatMap(() => Stream.fail(error))
+            ),
+          LLMError: error =>
+            Stream.fromEffect(appendRunFailed(store, request, startedLog.revision, error)).pipe(
+              Stream.flatMap(() => Stream.fail(error))
+            ),
+          ToolError: error =>
+            Stream.fromEffect(appendRunFailed(store, request, startedLog.revision, error)).pipe(
+              Stream.flatMap(() => Stream.fail(error))
+            )
+        })
+      )
+    })
+  )
+
+export function runRuntime(
+  request: TranscriptRuntimeRequest,
+  config: RuntimeConfig
+): Stream.Stream<AgentEvent, AgentLoopError, LoopRequirements>
+export function runRuntime(
+  request: AppendInputRuntimeRequest,
+  config: RuntimeConfig
+): Stream.Stream<AgentEvent, RuntimeErrorUnion, AppendRuntimeRequirements>
+export function runRuntime(
+  request: AppendHitlResponseRuntimeRequest,
+  config: RuntimeConfig
+): Stream.Stream<AgentEvent, RuntimeErrorUnion, AppendRuntimeRequirements>
+export function runRuntime(
+  request: RuntimeRequest,
+  config: RuntimeConfig
+): Stream.Stream<AgentEvent, RuntimeErrorUnion, RuntimeRequirements>
+export function runRuntime(
+  request: RuntimeRequest,
+  config: RuntimeConfig
+): Stream.Stream<AgentEvent, RuntimeErrorUnion, RuntimeRequirements> {
+  switch (request._tag) {
+    case 'Transcript':
+      return makeTranscriptRuntimeStream(request, config)
+    case 'AppendInput':
+      return makeAppendInputRuntimeStream(request, config)
+    case 'AppendHitlResponse':
+      return makeAppendHitlResponseRuntimeStream(request, config)
+  }
+}

package/src/runtime/session-event-store.ts

@@ -0,0 +1,254 @@
+import { Context, Effect, Layer, Option, Ref } from 'effect'
+import * as Schema from 'effect/Schema'
+import { AgentError, AgentMessage, HitlRequest, HitlResponse } from '@yolk-sdk/agent/protocol'
+import { SessionConflictError, SessionNotFoundError } from './error.ts'
+import type { SessionLoadError, SessionSaveError } from './error.ts'
+
+export type SessionRevision = number
+
+export class InputAppended extends Schema.TaggedClass<InputAppended>()('InputAppended', {
+  message: AgentMessage
+}) {}
+
+export class HitlResponseAppended extends Schema.TaggedClass<HitlResponseAppended>()(
+  'HitlResponseAppended',
+  {
+    response: HitlResponse
+  }
+) {}
+
+export class RunStarted extends Schema.TaggedClass<RunStarted>()('RunStarted', {
+  runId: Schema.String
+}) {}
+
+export class RunCompleted extends Schema.TaggedClass<RunCompleted>()('RunCompleted', {
+  runId: Schema.String,
+  messages: Schema.Array(AgentMessage)
+}) {}
+
+export class RunAwaitingInput extends Schema.TaggedClass<RunAwaitingInput>()('RunAwaitingInput', {
+  runId: Schema.String,
+  requests: Schema.NonEmptyArray(HitlRequest),
+  messages: Schema.Array(AgentMessage)
+}) {}
+
+export class RunFailed extends Schema.TaggedClass<RunFailed>()('RunFailed', {
+  runId: Schema.String,
+  error: AgentError
+}) {}
+
+export class RunInterrupted extends Schema.TaggedClass<RunInterrupted>()('RunInterrupted', {
+  runId: Schema.String
+}) {}
+
+export const RuntimeSessionEvent = Schema.Union([
+  InputAppended,
+  HitlResponseAppended,
+  RunStarted,
+  RunCompleted,
+  RunAwaitingInput,
+  RunFailed,
+  RunInterrupted
+])
+export type RuntimeSessionEvent = typeof RuntimeSessionEvent.Type
+
+export type StoredRuntimeSessionEvent = {
+  readonly id: string
+  readonly sessionId: string
+  readonly revision: SessionRevision
+  readonly event: RuntimeSessionEvent
+}
+
+export type RuntimeSessionEventLog = {
+  readonly sessionId: string
+  readonly revision: SessionRevision
+  readonly events: ReadonlyArray<StoredRuntimeSessionEvent>
+}
+
+export type IncompleteRuntimeRun = {
+  readonly runId: string
+  readonly startedRevision: SessionRevision
+}
+
+export type AppendRuntimeSessionEventsInput = {
+  readonly sessionId: string
+  readonly expectedRevision?: SessionRevision
+  readonly events: ReadonlyArray<RuntimeSessionEvent>
+}
+
+export type SessionEventStoreApi = {
+  readonly load: (
+    sessionId: string
+  ) => Effect.Effect<RuntimeSessionEventLog, SessionNotFoundError | SessionLoadError>
+  readonly append: (
+    input: AppendRuntimeSessionEventsInput
+  ) => Effect.Effect<RuntimeSessionEventLog, SessionSaveError | SessionConflictError>
+}
+
+export class SessionEventStore extends Context.Service<SessionEventStore, SessionEventStoreApi>()(
+  '@yolk-sdk/agent/runtime/SessionEventStore'
+) {}
+
+export const replayRuntimeSessionEvents = (
+  events: ReadonlyArray<StoredRuntimeSessionEvent>
+): ReadonlyArray<AgentMessage> =>
+  events.flatMap(stored => {
+    switch (stored.event._tag) {
+      case 'InputAppended':
+        return [stored.event.message]
+      case 'RunCompleted':
+      case 'RunAwaitingInput':
+        return stored.event.messages
+      case 'HitlResponseAppended':
+      case 'RunFailed':
+      case 'RunInterrupted':
+      case 'RunStarted':
+        return []
+    }
+  })
+
+export const replayRuntimeHitlResponses = (
+  events: ReadonlyArray<StoredRuntimeSessionEvent>
+): ReadonlyArray<HitlResponse> =>
+  events.flatMap(stored =>
+    stored.event._tag === 'HitlResponseAppended' ? [stored.event.response] : []
+  )
+
+type IncompleteRunSearch =
+  | {
+      readonly _tag: 'Found'
+      readonly run: IncompleteRuntimeRun
+    }
+  | {
+      readonly _tag: 'Searching'
+      readonly terminalRunIds: ReadonlySet<string>
+    }
+
+const terminalRunId = (event: RuntimeSessionEvent): Option.Option<string> => {
+  switch (event._tag) {
+    case 'RunCompleted':
+    case 'RunAwaitingInput':
+    case 'RunFailed':
+    case 'RunInterrupted':
+      return Option.some(event.runId)
+    case 'HitlResponseAppended':
+    case 'InputAppended':
+    case 'RunStarted':
+      return Option.none()
+  }
+}
+
+export const latestIncompleteRuntimeRun = (
+  events: ReadonlyArray<StoredRuntimeSessionEvent>
+): Option.Option<IncompleteRuntimeRun> => {
+  const search = events.reduceRight<IncompleteRunSearch>(
+    (state, stored) => {
+      if (state._tag === 'Found') {
+        return state
+      }
+
+      const terminal = terminalRunId(stored.event)
+
+      if (Option.isSome(terminal)) {
+        return {
+          _tag: 'Searching',
+          terminalRunIds: new Set([...state.terminalRunIds, terminal.value])
+        }
+      }
+
+      if (stored.event._tag === 'RunStarted' && !state.terminalRunIds.has(stored.event.runId)) {
+        return {
+          _tag: 'Found',
+          run: {
+            runId: stored.event.runId,
+            startedRevision: stored.revision
+          }
+        }
+      }
+
+      return state
+    },
+    { _tag: 'Searching', terminalRunIds: new Set() }
+  )
+
+  return search._tag === 'Found' ? Option.some(search.run) : Option.none()
+}
+
+const emptyLog = (sessionId: string): RuntimeSessionEventLog => ({
+  sessionId,
+  revision: 0,
+  events: []
+})
+
+const makeStoredRuntimeSessionEvents = (
+  sessionId: string,
+  currentRevision: SessionRevision,
+  events: ReadonlyArray<RuntimeSessionEvent>
+): ReadonlyArray<StoredRuntimeSessionEvent> =>
+  events.map((event, index) => {
+    const revision = currentRevision + index + 1
+
+    return {
+      id: `${sessionId}:${revision}`,
+      sessionId,
+      revision,
+      event
+    }
+  })
+
+export const appendRuntimeSessionEventsToLog = (
+  current: RuntimeSessionEventLog,
+  input: AppendRuntimeSessionEventsInput
+): RuntimeSessionEventLog => {
+  const stored = makeStoredRuntimeSessionEvents(input.sessionId, current.revision, input.events)
+  const last = stored.at(-1)
+
+  return {
+    sessionId: input.sessionId,
+    revision: last?.revision ?? current.revision,
+    events: [...current.events, ...stored]
+  }
+}
+
+export const makeInMemorySessionEventStoreLayer = (
+  initial: ReadonlyArray<RuntimeSessionEventLog> = []
+) =>
+  Layer.effect(
+    SessionEventStore,
+    Effect.gen(function* () {
+      const logs = yield* Ref.make(new Map(initial.map(log => [log.sessionId, log])))
+
+      return SessionEventStore.of({
+        load: sessionId =>
+          Effect.gen(function* () {
+            const current = yield* Ref.get(logs)
+
+            return yield* Effect.fromNullishOr(current.get(sessionId)).pipe(
+              Effect.mapError(() => new SessionNotFoundError({ sessionId }))
+            )
+          }),
+        append: input =>
+          Effect.gen(function* () {
+            const current = yield* Ref.get(logs)
+            const currentLog = current.get(input.sessionId) ?? emptyLog(input.sessionId)
+
+            if (
+              input.expectedRevision !== undefined &&
+              input.expectedRevision !== currentLog.revision
+            ) {
+              return yield* Effect.fail(
+                new SessionConflictError({
+                  sessionId: input.sessionId,
+                  message: `Session revision conflict: expected ${input.expectedRevision}, got ${currentLog.revision}`
+                })
+              )
+            }
+
+            const nextLog = appendRuntimeSessionEventsToLog(currentLog, input)
+            yield* Ref.set(logs, new Map([...current, [input.sessionId, nextLog]]))
+
+            return nextLog
+          })
+      })
+    })
+  )

package/src/tools/README.md

@@ -0,0 +1,22 @@
+# @yolk-sdk/agent/tools
+
+Generic host tool registration and resolution.
+
+## What it provides
+
+- `ToolModule<Context>` and `ToolRegistration<Context>` types.
+- Tool resolution from host modules and context.
+- Duplicate tool name validation.
+- Adapter from resolved tools to `@yolk-sdk/agent/loop` `ToolExecutor`.
+- Package-owned `task` and `question` tool contracts.
+
+## Use it when
+
+- A host app wants declarative tool modules with generic context.
+- You need to filter/resolve tools before running the agent loop.
+
+## Boundaries
+
+- No app tool catalogs.
+- No provider SDKs.
+- Tool access/approval is metadata; host apps enforce product policy.

package/src/tools/index.ts

@@ -0,0 +1,29 @@
+export { EmptyToolParams, makeTool, makeToolExecutorLayer, resolveTools, ToolAccess, ToolRegistryError } from './registry.ts'
+export {
+  makeQuestionToolDef,
+  makeQuestionToolModule,
+  makeQuestionToolRegistration,
+  questionToolName
+} from './question.ts'
+export {
+  formatTaskResult,
+  makeTaskToolDef,
+  makeTaskToolModule,
+  makeTaskToolRegistration,
+  taskToolName
+} from './task.ts'
+export type {
+  ResolvedToolSet,
+  SchemaToolExecutionInput,
+  ToolExecutionInput,
+  ToolMetadata,
+  ToolModule,
+  ToolRegistration
+} from './registry.ts'
+export type { QuestionExecutionInput, QuestionToolOptions } from './question.ts'
+export type {
+  TaskExecutionInput,
+  TaskSubagentDefinition,
+  TaskToolOptions,
+  TaskToolParams
+} from './task.ts'

package/src/tools/question.ts

@@ -0,0 +1,58 @@
+import { Effect } from 'effect'
+import { ToolError } from '@yolk-sdk/agent/loop'
+import { QuestionToolParams, ToolResult, type ToolCall } from '@yolk-sdk/agent/protocol'
+import { makeTool, type ToolModule, type ToolRegistration } from './registry.ts'
+
+export const questionToolName = 'question'
+
+export type QuestionExecutionInput<Context> = {
+  readonly call: ToolCall
+  readonly context: Context
+  readonly params: QuestionToolParams
+}
+
+export type QuestionToolOptions<Context> = {
+  readonly execute: (input: QuestionExecutionInput<Context>) => Effect.Effect<ToolResult, ToolError>
+}
+
+const questionToolError = (message: string, cause: ToolError['cause']) =>
+  new ToolError({
+    tool: questionToolName,
+    message,
+    cause
+  })
+
+const questionToolDescription = [
+  'Ask the user one or more structured questions and wait for their response.',
+  'Use this when you need explicit user input before continuing.',
+  'Each question has a stable id, prompt, optional options, and optional custom-answer support.',
+  'Yolk returns user answers as structured tool output.'
+].join('\n\n')
+
+export const makeQuestionToolRegistration = <Context>(
+  options: QuestionToolOptions<Context>
+): ToolRegistration<Context> =>
+  makeTool({
+    name: questionToolName,
+    description: questionToolDescription,
+    parameters: QuestionToolParams,
+    access: 'read',
+    invalidParamsMessage: error =>
+      `Invalid question arguments: ${error instanceof Error ? error.message : String(error)}`,
+    execute: ({ call, context, params }) =>
+      call.name === questionToolName
+        ? options.execute({ call, context, params })
+        : Effect.fail(questionToolError(`Tool is not configured: ${call.name}`, 'not_found'))
+  })
+
+export const makeQuestionToolDef = () =>
+  makeQuestionToolRegistration({
+    execute: ({ call }) => Effect.succeed(ToolResult.make({ toolCallId: call.id, content: '' }))
+  }).def
+
+export const makeQuestionToolModule = <Context>(
+  options: QuestionToolOptions<Context>
+): ToolModule<Context> => ({
+  id: 'question',
+  tools: [makeQuestionToolRegistration(options)]
+})