@yolk-sdk/agent 0.0.1-canary.0

package/src/protocol/index.ts

@@ -0,0 +1,109 @@
+export {
+  AgentContentCapabilities,
+  AgentModelCapabilities,
+  textImageModelCapabilities,
+  textOnlyModelCapabilities
+} from './capability.ts'
+export {
+  appendTextToContent,
+  AudioPart,
+  Content,
+  ContentPart,
+  contentParts,
+  contentPartPreview,
+  contentPartText,
+  contentPreview,
+  contentText,
+  ImagePart,
+  isContentEmpty,
+  TextPart
+} from './content.ts'
+export {
+  AgentAwaitingInput,
+  AgentEnd,
+  AgentError,
+  AgentErrorCode,
+  AgentEvent,
+  AgentRetry,
+  AgentStart,
+  AssistantMessageEvent,
+  CompactionEnd,
+  CompactionStart,
+  LLMReasoningDelta,
+  LLMStreamEnd,
+  LLMStreamStart,
+  LLMTextDelta,
+  ProviderToolResult,
+  QuestionAnswered,
+  QuestionCancelled,
+  QuestionRequested,
+  SubagentCompleted,
+  SubagentStarted,
+  SubagentStatus,
+  ToolApprovalDenied,
+  ToolApprovalGranted,
+  ToolApprovalRequested,
+  ToolExecutionCompleted,
+  ToolExecutionError,
+  ToolExecutionStarted,
+  ToolInputDelta,
+  ToolInputEnd,
+  ToolInputStart,
+  TurnEnd,
+  TurnStart,
+  UsageUpdate
+} from './event.ts'
+export {
+  AgentMessage,
+  AssistantAgentMessage,
+  AssistantPart,
+  AssistantReasoningPart,
+  AssistantTextPart,
+  HostToolCallPart,
+  ProviderToolCallPart,
+  ProviderToolResultPart,
+  ToolResultMessage,
+  UserMessage,
+  assistantContent,
+  assistantHostToolCalls,
+  assistantReasoningText
+} from './message.ts'
+export { AgentReasoningEffort } from './reasoning.ts'
+export {
+  AgentWebSocketClientMessage,
+  AgentWebSocketServerMessage,
+  SessionSnapshot,
+  QuestionResponseInput,
+  ToolApprovalResponseInput,
+  UserInput
+} from './session.ts'
+export {
+  HitlRequest,
+  HitlResponse,
+  HitlResponseSource,
+  QuestionAnswer,
+  QuestionOption,
+  QuestionPrompt,
+  QuestionRequest,
+  QuestionResponse,
+  QuestionResponseOutcome,
+  QuestionToolParams,
+  formatQuestionResponseContent,
+  ToolApprovalDecision,
+  ToolApprovalMode,
+  ToolApprovalPolicy,
+  ToolApprovalRequest,
+  ToolApprovalResponse,
+  ToolCall,
+  ToolDef,
+  ToolResult
+} from './tool.ts'
+export {
+  addAgentUsage,
+  AgentInputUsage,
+  AgentOutputUsage,
+  AgentUsage,
+  zeroAgentUsage
+} from './usage.ts'
+
+export type MessageId = string

package/src/protocol/message.ts

@@ -0,0 +1,86 @@
+import * as Schema from 'effect/Schema'
+import { Content, contentParts } from './content.ts'
+import { ToolCall, ToolResult } from './tool.ts'
+
+export class UserMessage extends Schema.TaggedClass<UserMessage>()('User', {
+  content: Content
+}) {}
+
+export class AssistantTextPart extends Schema.TaggedClass<AssistantTextPart>()('Text', {
+  content: Content
+}) {}
+
+export class AssistantReasoningPart extends Schema.TaggedClass<AssistantReasoningPart>()(
+  'Reasoning',
+  {
+    text: Schema.String
+  }
+) {}
+
+export class HostToolCallPart extends Schema.TaggedClass<HostToolCallPart>()('HostToolCall', {
+  call: ToolCall
+}) {}
+
+export class ProviderToolCallPart extends Schema.TaggedClass<ProviderToolCallPart>()(
+  'ProviderToolCall',
+  {
+    call: ToolCall,
+    providerMetadata: Schema.optional(Schema.Unknown)
+  }
+) {}
+
+export class ProviderToolResultPart extends Schema.TaggedClass<ProviderToolResultPart>()(
+  'ProviderToolResult',
+  {
+    toolCallId: Schema.String,
+    result: ToolResult,
+    providerMetadata: Schema.optional(Schema.Unknown)
+  }
+) {}
+
+export const AssistantPart = Schema.Union([
+  AssistantTextPart,
+  AssistantReasoningPart,
+  HostToolCallPart,
+  ProviderToolCallPart,
+  ProviderToolResultPart
+])
+export type AssistantPart = typeof AssistantPart.Type
+
+export class AssistantAgentMessage extends Schema.TaggedClass<AssistantAgentMessage>()(
+  'Assistant',
+  {
+    parts: Schema.Array(AssistantPart)
+  }
+) {}
+
+export class ToolResultMessage extends Schema.TaggedClass<ToolResultMessage>()('ToolResult', {
+  toolCallId: Schema.String,
+  content: Content,
+  isError: Schema.optional(Schema.Boolean),
+  structuredContent: Schema.optional(Schema.Unknown)
+}) {}
+
+export const AgentMessage = Schema.Union([UserMessage, AssistantAgentMessage, ToolResultMessage])
+export type AgentMessage = typeof AgentMessage.Type
+
+export const assistantContent = (message: AssistantAgentMessage): Content => {
+  const parts = message.parts.flatMap(part => (part._tag === 'Text' ? [part.content] : []))
+  const first = parts[0]
+
+  if (parts.length === 0) {
+    return ''
+  }
+
+  if (parts.length === 1 && first !== undefined) {
+    return first
+  }
+
+  return parts.flatMap(contentParts)
+}
+
+export const assistantReasoningText = (message: AssistantAgentMessage) =>
+  message.parts.flatMap(part => (part._tag === 'Reasoning' ? [part.text] : [])).join('')
+
+export const assistantHostToolCalls = (message: AssistantAgentMessage) =>
+  message.parts.flatMap(part => (part._tag === 'HostToolCall' ? [part.call] : []))

package/src/protocol/reasoning.ts

@@ -0,0 +1,4 @@
+import * as Schema from 'effect/Schema'
+
+export const AgentReasoningEffort = Schema.Literals(['minimal', 'low', 'medium', 'high', 'xhigh'])
+export type AgentReasoningEffort = typeof AgentReasoningEffort.Type

package/src/protocol/session.ts

@@ -0,0 +1,47 @@
+import * as Schema from 'effect/Schema'
+import { AgentEvent } from './event.ts'
+import { AgentMessage, UserMessage } from './message.ts'
+import { AgentReasoningEffort } from './reasoning.ts'
+import { QuestionResponse, ToolApprovalResponse } from './tool.ts'
+
+export class SessionSnapshot extends Schema.TaggedClass<SessionSnapshot>()('SessionSnapshot', {
+  revision: Schema.Number,
+  messages: Schema.Array(AgentMessage)
+}) {}
+
+export class UserInput extends Schema.TaggedClass<UserInput>()('UserInput', {
+  message: UserMessage,
+  expectedRevision: Schema.optional(Schema.Number),
+  model: Schema.optional(Schema.String),
+  reasoningEffort: Schema.optional(AgentReasoningEffort)
+}) {}
+
+export class ToolApprovalResponseInput extends Schema.TaggedClass<ToolApprovalResponseInput>()(
+  'ToolApprovalResponseInput',
+  {
+    response: ToolApprovalResponse,
+    expectedRevision: Schema.optional(Schema.Number),
+    model: Schema.optional(Schema.String),
+    reasoningEffort: Schema.optional(AgentReasoningEffort)
+  }
+) {}
+
+export class QuestionResponseInput extends Schema.TaggedClass<QuestionResponseInput>()(
+  'QuestionResponseInput',
+  {
+    response: QuestionResponse,
+    expectedRevision: Schema.optional(Schema.Number),
+    model: Schema.optional(Schema.String),
+    reasoningEffort: Schema.optional(AgentReasoningEffort)
+  }
+) {}
+
+export const AgentWebSocketClientMessage = Schema.Union([
+  UserInput,
+  ToolApprovalResponseInput,
+  QuestionResponseInput
+])
+export type AgentWebSocketClientMessage = typeof AgentWebSocketClientMessage.Type
+
+export const AgentWebSocketServerMessage = Schema.Union([SessionSnapshot, AgentEvent])
+export type AgentWebSocketServerMessage = typeof AgentWebSocketServerMessage.Type

package/src/protocol/tool.ts

@@ -0,0 +1,154 @@
+import * as Schema from 'effect/Schema'
+import { Content } from './content.ts'
+
+const NonEmptyTrimmedString = Schema.Trimmed.pipe(Schema.check(Schema.isNonEmpty()))
+
+export const HitlResponseSource = Schema.Literals(['user', 'policy', 'replay'])
+export type HitlResponseSource = typeof HitlResponseSource.Type
+
+export const ToolApprovalDecision = Schema.Literals(['approved', 'denied'])
+export type ToolApprovalDecision = typeof ToolApprovalDecision.Type
+
+export const ToolApprovalMode = Schema.Literals(['manual'])
+export type ToolApprovalMode = typeof ToolApprovalMode.Type
+
+export class ToolApprovalPolicy extends Schema.Class<ToolApprovalPolicy>('ToolApprovalPolicy')({
+  mode: ToolApprovalMode,
+  reason: Schema.optional(Schema.String)
+}) {}
+
+export class ToolCall extends Schema.Class<ToolCall>('ToolCall')({
+  id: NonEmptyTrimmedString,
+  name: NonEmptyTrimmedString,
+  params: Schema.Unknown
+}) {}
+
+export class ToolDef extends Schema.Class<ToolDef>('ToolDef')({
+  name: NonEmptyTrimmedString,
+  description: Schema.String,
+  parameters: Schema.Unknown,
+  approval: Schema.optional(ToolApprovalPolicy)
+}) {}
+
+export class ToolResult extends Schema.Class<ToolResult>('ToolResult')({
+  toolCallId: NonEmptyTrimmedString,
+  content: Content,
+  isError: Schema.optional(Schema.Boolean),
+  structuredContent: Schema.optional(Schema.Unknown)
+}) {}
+
+export class ToolApprovalRequest extends Schema.TaggedClass<ToolApprovalRequest>()(
+  'ToolApprovalRequest',
+  {
+    requestId: NonEmptyTrimmedString,
+    toolCallId: NonEmptyTrimmedString,
+    call: ToolCall,
+    policy: Schema.optional(ToolApprovalPolicy)
+  }
+) {}
+
+export class ToolApprovalResponse extends Schema.TaggedClass<ToolApprovalResponse>()(
+  'ToolApprovalResponse',
+  {
+    requestId: NonEmptyTrimmedString,
+    toolCallId: NonEmptyTrimmedString,
+    decision: ToolApprovalDecision,
+    source: HitlResponseSource,
+    reason: Schema.optional(Schema.String)
+  }
+) {}
+
+export class QuestionOption extends Schema.Class<QuestionOption>('QuestionOption')({
+  id: NonEmptyTrimmedString,
+  label: NonEmptyTrimmedString,
+  description: Schema.optional(Schema.String)
+}) {}
+
+export class QuestionPrompt extends Schema.Class<QuestionPrompt>('QuestionPrompt')({
+  id: NonEmptyTrimmedString,
+  prompt: NonEmptyTrimmedString,
+  options: Schema.optional(Schema.Array(QuestionOption)),
+  multiple: Schema.optional(Schema.Boolean),
+  allowCustom: Schema.optional(Schema.Boolean),
+  required: Schema.optional(Schema.Boolean)
+}) {}
+
+export class QuestionToolParams extends Schema.Class<QuestionToolParams>('QuestionToolParams')({
+  questions: Schema.NonEmptyArray(QuestionPrompt)
+}) {}
+
+export class QuestionRequest extends Schema.TaggedClass<QuestionRequest>()('QuestionRequest', {
+  requestId: NonEmptyTrimmedString,
+  toolCallId: NonEmptyTrimmedString,
+  call: ToolCall,
+  questions: Schema.NonEmptyArray(QuestionPrompt)
+}) {}
+
+export class QuestionAnswer extends Schema.Class<QuestionAnswer>('QuestionAnswer')({
+  questionId: NonEmptyTrimmedString,
+  optionIds: Schema.optional(Schema.Array(NonEmptyTrimmedString)),
+  customAnswer: Schema.optional(Schema.String)
+}) {}
+
+export const QuestionResponseOutcome = Schema.Literals(['answered', 'cancelled'])
+export type QuestionResponseOutcome = typeof QuestionResponseOutcome.Type
+
+export class QuestionResponse extends Schema.TaggedClass<QuestionResponse>()('QuestionResponse', {
+  requestId: NonEmptyTrimmedString,
+  toolCallId: NonEmptyTrimmedString,
+  outcome: QuestionResponseOutcome,
+  source: HitlResponseSource,
+  answers: Schema.optional(Schema.Array(QuestionAnswer)),
+  reason: Schema.optional(Schema.String)
+}) {}
+
+const optionLabel = (question: QuestionPrompt, optionId: string) =>
+  question.options?.find(option => option.id === optionId)?.label ?? optionId
+
+const questionForAnswer = (
+  questions: ReadonlyArray<QuestionPrompt>,
+  answer: QuestionAnswer
+) => questions.find(question => question.id === answer.questionId)
+
+const formatQuestionAnswer = (
+  answer: QuestionAnswer,
+  questions: ReadonlyArray<QuestionPrompt>
+) => {
+  const question = questionForAnswer(questions, answer)
+  const prompt = question?.prompt ?? answer.questionId
+  const selected = answer.optionIds?.map(optionId =>
+    question === undefined ? optionId : optionLabel(question, optionId)
+  ) ?? []
+  const custom = answer.customAnswer?.trim()
+  const values = custom === undefined || custom.length === 0 ? selected : [...selected, custom]
+
+  return values.length === 0 ? `- ${prompt}: answered` : `- ${prompt}: ${values.join(', ')}`
+}
+
+export const formatQuestionResponseContent = (
+  response: QuestionResponse,
+  questions: ReadonlyArray<QuestionPrompt> = []
+) => {
+  if (response.outcome === 'cancelled') {
+    return `Question cancelled: ${response.reason ?? 'Question cancelled'}`
+  }
+
+  const answers = response.answers ?? []
+
+  if (answers.length === 0) {
+    return 'User answered the question, but no answer values were provided. Continue with this in mind.'
+  }
+
+  const formatted = answers
+    .map(answer => formatQuestionAnswer(answer, questions).slice('- '.length))
+    .join('; ')
+  const label = answers.length === 1 ? 'question' : 'questions'
+
+  return `User has answered your ${label}: ${formatted}. Continue with the user's answers in mind.`
+}
+
+export const HitlRequest = Schema.Union([ToolApprovalRequest, QuestionRequest])
+export type HitlRequest = typeof HitlRequest.Type
+
+export const HitlResponse = Schema.Union([ToolApprovalResponse, QuestionResponse])
+export type HitlResponse = typeof HitlResponse.Type

package/src/protocol/usage.ts

@@ -0,0 +1,48 @@
+import { Array as Arr, Option } from 'effect'
+import * as Schema from 'effect/Schema'
+
+export class AgentInputUsage extends Schema.Class<AgentInputUsage>('AgentInputUsage')({
+  total: Schema.Number,
+  uncached: Schema.optional(Schema.Number),
+  cacheRead: Schema.optional(Schema.Number),
+  cacheWrite: Schema.optional(Schema.Number)
+}) {}
+
+export class AgentOutputUsage extends Schema.Class<AgentOutputUsage>('AgentOutputUsage')({
+  total: Schema.Number,
+  text: Schema.optional(Schema.Number),
+  reasoning: Schema.optional(Schema.Number)
+}) {}
+
+export class AgentUsage extends Schema.Class<AgentUsage>('AgentUsage')({
+  input: AgentInputUsage,
+  output: AgentOutputUsage
+}) {}
+
+export const zeroAgentUsage = AgentUsage.make({
+  input: AgentInputUsage.make({ total: 0 }),
+  output: AgentOutputUsage.make({ total: 0 })
+})
+
+const sumOptional = (left: number | undefined, right: number | undefined) =>
+  Option.getOrUndefined(
+    Option.liftPredicate(
+      Arr.getSomes([Option.fromNullishOr(left), Option.fromNullishOr(right)]),
+      values => values.length > 0
+    ).pipe(Option.map(values => Arr.reduce(values, 0, (sum, value) => sum + value)))
+  )
+
+export const addAgentUsage = (left: AgentUsage, right: AgentUsage) =>
+  AgentUsage.make({
+    input: AgentInputUsage.make({
+      total: left.input.total + right.input.total,
+      uncached: sumOptional(left.input.uncached, right.input.uncached),
+      cacheRead: sumOptional(left.input.cacheRead, right.input.cacheRead),
+      cacheWrite: sumOptional(left.input.cacheWrite, right.input.cacheWrite)
+    }),
+    output: AgentOutputUsage.make({
+      total: left.output.total + right.output.total,
+      text: sumOptional(left.output.text, right.output.text),
+      reasoning: sumOptional(left.output.reasoning, right.output.reasoning)
+    })
+  })

package/src/runtime/README.md

@@ -0,0 +1,44 @@
+# @yolk-sdk/agent/runtime
+
+Generic session orchestration for `@yolk-sdk/agent/loop`.
+
+## What it provides
+
+- `runRuntime` for stateless transcript runs or append-backed durable runs.
+- `SessionEventStore` service contract for append-only runtime session events.
+- In-memory session event store layer for tests/simple hosts.
+- Runtime-specific errors.
+- Pending HITL state and response replay for durable sessions.
+
+## Request modes
+
+### `Transcript`
+
+Use `Transcript` when the caller owns replay state. The caller passes a complete protocol transcript and runtime does not load or persist session state.
+
+### `AppendInput`
+
+Use `AppendInput` when the host wants durable runtime persistence. Runtime:
+
+1. loads the prior `SessionEventStore` log,
+2. replays protocol `AgentMessage` values from `InputAppended` and `RunCompleted`,
+3. appends `InputAppended` and `RunStarted`,
+4. runs the loop,
+5. appends `RunCompleted`, `RunAwaitingInput`, or `RunFailed`.
+
+### `AppendHitlResponse`
+
+Use `AppendHitlResponse` to persist one approval/question response and resume a paused append-backed run.
+
+Hosts own physical storage, auth/tenancy, reconnect/fanout, and cleanup policy. Use numeric `expectedRevision` to reject stale writes. Use `latestIncompleteRuntimeRun` to decide when a host should append `RunInterrupted`.
+
+## Use it when
+
+- You need reusable lifecycle around the stateless loop.
+- Your app owns storage and wants to inject it through an Effect service.
+
+## Boundaries
+
+- No database implementation.
+- No HTTP/WebSocket routes.
+- No app auth or tenancy logic.

package/src/runtime/error.ts

@@ -0,0 +1,70 @@
+import * as Schema from 'effect/Schema'
+import { agentLoopErrorToAgentError, type AgentLoopError } from '@yolk-sdk/agent/loop'
+import { AgentError } from '@yolk-sdk/agent/protocol'
+
+export class SessionNotFoundError extends Schema.TaggedErrorClass<SessionNotFoundError>()(
+  'SessionNotFoundError',
+  {
+    sessionId: Schema.String
+  }
+) {}
+
+export class SessionLoadError extends Schema.TaggedErrorClass<SessionLoadError>()(
+  'SessionLoadError',
+  {
+    sessionId: Schema.String,
+    message: Schema.String
+  }
+) {}
+
+export class SessionSaveError extends Schema.TaggedErrorClass<SessionSaveError>()(
+  'SessionSaveError',
+  {
+    sessionId: Schema.String,
+    message: Schema.String
+  }
+) {}
+
+export class SessionConflictError extends Schema.TaggedErrorClass<SessionConflictError>()(
+  'SessionConflictError',
+  {
+    sessionId: Schema.String,
+    message: Schema.String
+  }
+) {}
+
+export type RuntimeError =
+  | SessionNotFoundError
+  | SessionLoadError
+  | SessionSaveError
+  | SessionConflictError
+
+export const runtimeErrorToAgentError = (error: RuntimeError | AgentLoopError): AgentError => {
+  switch (error._tag) {
+    case 'SessionNotFoundError':
+      return AgentError.make({
+        code: 'session_not_found',
+        message: `Session not found: ${error.sessionId}`,
+        retryable: false
+      })
+    case 'SessionLoadError':
+    case 'SessionSaveError':
+      return AgentError.make({
+        code: 'store_error',
+        message: error.message,
+        retryable: true
+      })
+    case 'SessionConflictError':
+      return AgentError.make({
+        code: 'conflict',
+        message: error.message,
+        retryable: false
+      })
+    case 'LLMError':
+    case 'ToolError':
+    case 'ContextTransformError':
+    case 'AbortError':
+    case 'FauxExhaustedError':
+      return agentLoopErrorToAgentError(error)
+  }
+}

package/src/runtime/index.ts

@@ -0,0 +1,43 @@
+export {
+  runtimeErrorToAgentError,
+  SessionConflictError,
+  SessionLoadError,
+  SessionNotFoundError,
+  SessionSaveError
+} from './error.ts'
+export type { RuntimeError } from './error.ts'
+export { runRuntime } from './run-runtime.ts'
+export type {
+  AppendInputRuntimeRequest,
+  AppendHitlResponseRuntimeRequest,
+  RuntimeConfig,
+  RuntimeRequest,
+  RuntimeTranscript,
+  TranscriptRuntimeRequest
+} from './run-runtime.ts'
+export {
+  appendRuntimeSessionEventsToLog,
+  HitlResponseAppended,
+  InputAppended,
+  makeInMemorySessionEventStoreLayer,
+  latestIncompleteRuntimeRun,
+  replayRuntimeHitlResponses,
+  replayRuntimeSessionEvents,
+  RunAwaitingInput,
+  RunCompleted,
+  RunFailed,
+  RunInterrupted,
+  RunStarted,
+  RuntimeSessionEvent,
+  SessionEventStore
+} from './session-event-store.ts'
+export type {
+  AppendRuntimeSessionEventsInput,
+  IncompleteRuntimeRun,
+  RuntimeSessionEventLog,
+  SessionEventStoreApi,
+  SessionRevision,
+  StoredRuntimeSessionEvent
+} from './session-event-store.ts'
+
+export type RuntimeSessionId = string