@yolk-sdk/agent 0.0.1-canary.0

package/src/loop/services/context-transformer.ts

@@ -0,0 +1,24 @@
+import { Context, Effect, Layer } from 'effect'
+import type { AgentEvent, AgentMessage } from '@yolk-sdk/agent/protocol'
+import type { ContextTransformError } from '../error.ts'
+
+export type ContextTransformResult = {
+  readonly messages: ReadonlyArray<AgentMessage>
+  readonly events: ReadonlyArray<AgentEvent>
+}
+
+export class ContextTransformer extends Context.Service<
+  ContextTransformer,
+  {
+    readonly transform: (
+      messages: ReadonlyArray<AgentMessage>
+    ) => Effect.Effect<ContextTransformResult, ContextTransformError>
+  }
+>()('@yolk-sdk/agent/loop/ContextTransformer') {
+  static identity = Layer.succeed(
+    this,
+    this.of({
+      transform: messages => Effect.succeed({ messages, events: [] })
+    })
+  )
+}

package/src/loop/services/llm-provider.ts

@@ -0,0 +1,20 @@
+import { Context } from 'effect'
+import type { Stream } from 'effect'
+import type { AgentMessage, AgentReasoningEffort, ToolDef } from '@yolk-sdk/agent/protocol'
+import type { LLMProviderError } from '../error.ts'
+import type { LLMEvent } from '../llm-event.ts'
+
+export type LLMRequest = {
+  readonly messages: ReadonlyArray<AgentMessage>
+  readonly tools: ReadonlyArray<ToolDef>
+  readonly model: string
+  readonly systemPrompt: string
+  readonly reasoningEffort?: AgentReasoningEffort
+}
+
+export class LLMProvider extends Context.Service<
+  LLMProvider,
+  {
+    readonly stream: (request: LLMRequest) => Stream.Stream<LLMEvent, LLMProviderError>
+  }
+>()('@yolk-sdk/agent/loop/LLMProvider') {}

package/src/loop/services/loop-config.ts

@@ -0,0 +1,20 @@
+import { Context, Layer } from 'effect'
+
+export type LoopConfigShape = {
+  readonly maxTurns: number
+  readonly maxRetries: number
+  readonly retryBaseDelayMs: number
+  readonly toolConcurrency: number
+}
+
+export class LoopConfig extends Context.Service<LoopConfig, LoopConfigShape>()(
+  '@yolk-sdk/agent/loop/LoopConfig'
+) {
+  static layer = (config: LoopConfigShape) => Layer.succeed(this, config)
+  static defaultLayer = this.layer({
+    maxTurns: 500,
+    maxRetries: 2,
+    retryBaseDelayMs: 1000,
+    toolConcurrency: 4
+  })
+}

package/src/loop/services/tool-executor.ts

@@ -0,0 +1,11 @@
+import { Context } from 'effect'
+import type { Effect } from 'effect'
+import type { ToolCall, ToolResult } from '@yolk-sdk/agent/protocol'
+import type { ToolError } from '../error.ts'
+
+export class ToolExecutor extends Context.Service<
+  ToolExecutor,
+  {
+    readonly execute: (call: ToolCall) => Effect.Effect<ToolResult, ToolError>
+  }
+>()('@yolk-sdk/agent/loop/ToolExecutor') {}

package/src/loop/testing/faux-provider.ts

@@ -0,0 +1,94 @@
+import { Effect, Layer, Ref, Stream } from 'effect'
+import { AgentInputUsage, AgentOutputUsage, AgentUsage, ToolCall } from '@yolk-sdk/agent/protocol'
+import { FauxExhaustedError } from '../error.ts'
+import {
+  LLMDone,
+  LLMReasoningDelta,
+  LLMTextDelta,
+  LLMToolCall,
+  LLMUsage,
+  type LLMEvent
+} from '../llm-event.ts'
+import { LLMProvider, type LLMRequest } from '../services/llm-provider.ts'
+
+export type FauxResponse = {
+  readonly events: ReadonlyArray<LLMEvent>
+}
+
+export const Reply = {
+  text: (text: string): FauxResponse => ({
+    events: [
+      ...text.split('').map(character => LLMTextDelta.make({ text: character })),
+      LLMDone.make({ stopReason: 'stop' })
+    ]
+  }),
+  reasoningText: (reasoning: string, text: string): FauxResponse => ({
+    events: [
+      LLMReasoningDelta.make({ text: reasoning }),
+      ...text.split('').map(character => LLMTextDelta.make({ text: character })),
+      LLMDone.make({ stopReason: 'stop' })
+    ]
+  }),
+  toolCall: (input: {
+    readonly id: string
+    readonly name: string
+    readonly params: unknown
+  }): FauxResponse => ({
+    events: [
+      LLMToolCall.make({
+        call: ToolCall.make({ id: input.id, name: input.name, params: input.params })
+      }),
+      LLMDone.make({ stopReason: 'tool_use' })
+    ]
+  }),
+  usage: (input: { readonly input: number; readonly output: number }): FauxResponse => ({
+    events: [
+      LLMUsage.make({
+        usage: AgentUsage.make({
+          input: AgentInputUsage.make({ total: input.input }),
+          output: AgentOutputUsage.make({ total: input.output })
+        })
+      }),
+      LLMDone.make({ stopReason: 'stop' })
+    ]
+  })
+}
+
+const takeResponse = (responses: Ref.Ref<ReadonlyArray<FauxResponse>>) =>
+  Effect.gen(function* () {
+    const current = yield* Ref.get(responses)
+    const response = current[0]
+
+    if (response === undefined) {
+      return yield* Effect.fail(
+        new FauxExhaustedError({ message: 'No more faux responses queued' })
+      )
+    }
+
+    yield* Ref.set(responses, current.slice(1))
+    return response
+  })
+
+export const FauxProvider = {
+  layer: (...initialResponses: ReadonlyArray<FauxResponse>) =>
+    FauxProvider.layerWithRequests({ responses: initialResponses, requests: [] }),
+  layerWithRequests: (input: {
+    readonly responses: ReadonlyArray<FauxResponse>
+    readonly requests: Array<LLMRequest>
+  }) =>
+    Layer.effect(
+      LLMProvider,
+      Effect.gen(function* () {
+        const responses = yield* Ref.make(input.responses)
+
+        return LLMProvider.of({
+          stream: request => {
+            input.requests.push(request)
+            return Stream.fromEffect(takeResponse(responses)).pipe(
+              Stream.flatMap(response => Stream.fromIterable(response.events))
+            )
+          }
+        })
+      })
+    )
+}

package/src/loop/testing/index.ts

@@ -0,0 +1,3 @@
+export { FauxProvider, Reply } from './faux-provider.ts'
+export type { FauxResponse } from './faux-provider.ts'
+export { TestToolExecutor } from './test-tool-executor.ts'

package/src/loop/testing/test-tool-executor.ts

@@ -0,0 +1,28 @@
+import { Effect, Layer } from 'effect'
+import { ToolResult } from '@yolk-sdk/agent/protocol'
+import { ToolError } from '../error.ts'
+import { ToolExecutor } from '../services/tool-executor.ts'
+
+export const TestToolExecutor = {
+  layer: (resultsByName: Readonly<Record<string, string>>) =>
+    Layer.succeed(
+      ToolExecutor,
+      ToolExecutor.of({
+        execute: call => {
+          const content = resultsByName[call.name]
+
+          if (content === undefined) {
+            return Effect.fail(
+              new ToolError({
+                tool: call.name,
+                message: `No canned result for tool: ${call.name}`,
+                cause: 'execution'
+              })
+            )
+          }
+
+          return Effect.succeed(ToolResult.make({ toolCallId: call.id, content }))
+        }
+      })
+    )
+}

package/src/protocol/README.md

@@ -0,0 +1,24 @@
+# @yolk-sdk/agent/protocol
+
+Domain-free agent protocol types and helpers.
+
+## What it provides
+
+- Agent transcript message schemas.
+- Streamed agent event schemas.
+- Tool definition/call/result schemas.
+- HITL approval/question request and response schemas.
+- Text/image/audio content helpers.
+- Model capability and reasoning config types.
+
+## Use it when
+
+- Building providers, loops, clients, or transports that need the shared Yolk agent wire model.
+- Converting app state into protocol messages before an agent run.
+- Rendering or storing provider-produced agent events.
+
+## Boundaries
+
+- No provider SDKs.
+- No app auth, storage, routes, or product concepts.
+- No transport assumptions.

package/src/protocol/capability.ts

@@ -0,0 +1,29 @@
+import * as Schema from 'effect/Schema'
+
+export class AgentContentCapabilities extends Schema.Class<AgentContentCapabilities>(
+  'AgentContentCapabilities'
+)({
+  text: Schema.Boolean,
+  image: Schema.Boolean,
+  audio: Schema.Boolean
+}) {}
+
+export class AgentModelCapabilities extends Schema.Class<AgentModelCapabilities>(
+  'AgentModelCapabilities'
+)({
+  input: AgentContentCapabilities,
+  tools: Schema.Boolean,
+  reasoning: Schema.Boolean
+}) {}
+
+export const textOnlyModelCapabilities = AgentModelCapabilities.make({
+  input: AgentContentCapabilities.make({ text: true, image: false, audio: false }),
+  tools: true,
+  reasoning: true
+})
+
+export const textImageModelCapabilities = AgentModelCapabilities.make({
+  input: AgentContentCapabilities.make({ text: true, image: true, audio: false }),
+  tools: true,
+  reasoning: true
+})

package/src/protocol/content.ts

@@ -0,0 +1,76 @@
+import { Array as Arr, Option } from 'effect'
+import * as Schema from 'effect/Schema'
+
+export class TextPart extends Schema.TaggedClass<TextPart>()('Text', {
+  text: Schema.String
+}) {}
+
+export class ImagePart extends Schema.TaggedClass<ImagePart>()('Image', {
+  data: Schema.String,
+  mimeType: Schema.String
+}) {}
+
+export class AudioPart extends Schema.TaggedClass<AudioPart>()('Audio', {
+  data: Schema.String,
+  format: Schema.Literals(['pcm16', 'wav', 'mp3', 'opus'])
+}) {}
+
+export const ContentPart = Schema.Union([TextPart, ImagePart, AudioPart])
+export type ContentPart = typeof ContentPart.Type
+
+export const Content = Schema.Union([Schema.String, Schema.Array(ContentPart)])
+export type Content = typeof Content.Type
+
+export const contentPartText = (part: ContentPart) => {
+  switch (part._tag) {
+    case 'Text':
+      return part.text
+    case 'Image':
+    case 'Audio':
+      return ''
+  }
+}
+
+export const contentPartPreview = (part: ContentPart) => {
+  switch (part._tag) {
+    case 'Text':
+      return part.text
+    case 'Image':
+      return 'Image'
+    case 'Audio':
+      return 'Audio'
+  }
+}
+
+export const contentText = (content: Content) =>
+  typeof content === 'string' ? content : Arr.map(content, contentPartText).join('')
+
+export const contentPreview = (content: Content) =>
+  typeof content === 'string' ? content : Arr.map(content, contentPartPreview).join(', ')
+
+export const contentParts = (content: Content): ReadonlyArray<ContentPart> =>
+  typeof content === 'string' ? [TextPart.make({ text: content })] : content
+
+export const isContentEmpty = (content: Content) =>
+  typeof content === 'string'
+    ? content.length === 0
+    : content.length === 0 ||
+      Arr.every(content, part => part._tag === 'Text' && part.text.length === 0)
+
+export const appendTextToContent = (content: Content, text: string): Content => {
+  if (typeof content === 'string') {
+    return `${content}${text}`
+  }
+
+  return Option.match(Arr.last(content), {
+    onNone: () => [TextPart.make({ text })],
+    onSome: last =>
+      last._tag !== 'Text'
+        ? [...content, TextPart.make({ text })]
+        : Arr.map(content, (part, index) =>
+            index === content.length - 1 && part._tag === 'Text'
+              ? TextPart.make({ text: `${part.text}${text}` })
+              : part
+          )
+  })
+}

package/src/protocol/event.ts

@@ -0,0 +1,286 @@
+import * as Schema from 'effect/Schema'
+import { AssistantAgentMessage, AgentMessage } from './message.ts'
+import {
+  HitlRequest,
+  QuestionRequest,
+  QuestionResponse,
+  ToolApprovalRequest,
+  ToolApprovalResponse,
+  ToolCall,
+  ToolResult
+} from './tool.ts'
+import { AgentUsage } from './usage.ts'
+
+const NonEmptyTrimmedString = Schema.Trimmed.pipe(Schema.check(Schema.isNonEmpty()))
+
+const EventIdentity = {
+  eventId: Schema.optional(NonEmptyTrimmedString),
+  createdAtMs: Schema.optional(Schema.Number)
+}
+
+export const SubagentStatus = Schema.Literals(['running', 'completed', 'error'])
+export type SubagentStatus = typeof SubagentStatus.Type
+
+export const AgentErrorCode = Schema.Literals([
+  'validation_error',
+  'provider_error',
+  'rate_limit',
+  'context_overflow',
+  'invalid_response',
+  'tool_error',
+  'tool_denied',
+  'tool_timeout',
+  'store_error',
+  'aborted',
+  'session_not_found',
+  'conflict',
+  'unknown'
+])
+export type AgentErrorCode = typeof AgentErrorCode.Type
+
+export class AgentStart extends Schema.TaggedClass<AgentStart>()('AgentStart', {
+  ...EventIdentity
+}) {}
+
+export class AgentError extends Schema.TaggedClass<AgentError>()('AgentError', {
+  ...EventIdentity,
+  code: AgentErrorCode,
+  message: Schema.String,
+  retryable: Schema.Boolean
+}) {}
+
+export class AgentEnd extends Schema.TaggedClass<AgentEnd>()('AgentEnd', {
+  ...EventIdentity,
+  messages: Schema.Array(AgentMessage),
+  turns: Schema.Number,
+  usage: AgentUsage
+}) {}
+
+export class AgentAwaitingInput extends Schema.TaggedClass<AgentAwaitingInput>()(
+  'AgentAwaitingInput',
+  {
+    ...EventIdentity,
+    requests: Schema.NonEmptyArray(HitlRequest),
+    messages: Schema.Array(AgentMessage),
+    turns: Schema.Number,
+    usage: AgentUsage
+  }
+) {}
+
+export class UsageUpdate extends Schema.TaggedClass<UsageUpdate>()('UsageUpdate', {
+  ...EventIdentity,
+  usage: AgentUsage
+}) {}
+
+export class AgentRetry extends Schema.TaggedClass<AgentRetry>()('AgentRetry', {
+  ...EventIdentity,
+  attempt: Schema.Number,
+  reason: AgentErrorCode,
+  delayMs: Schema.Number,
+  message: Schema.String
+}) {}
+
+export class CompactionStart extends Schema.TaggedClass<CompactionStart>()('CompactionStart', {
+  ...EventIdentity,
+  strategy: Schema.String
+}) {}
+
+export class CompactionEnd extends Schema.TaggedClass<CompactionEnd>()('CompactionEnd', {
+  ...EventIdentity,
+  strategy: Schema.String,
+  beforeTokens: Schema.optional(Schema.Number),
+  afterTokens: Schema.optional(Schema.Number)
+}) {}
+
+export class TurnStart extends Schema.TaggedClass<TurnStart>()('TurnStart', {
+  ...EventIdentity,
+  turn: Schema.Number
+}) {}
+
+export class TurnEnd extends Schema.TaggedClass<TurnEnd>()('TurnEnd', {
+  ...EventIdentity,
+  turn: Schema.Number,
+  reason: Schema.Literals(['stop', 'tool_use'])
+}) {}
+
+export class LLMStreamStart extends Schema.TaggedClass<LLMStreamStart>()('LLMStreamStart', {
+  ...EventIdentity,
+  turn: Schema.Number
+}) {}
+
+export class LLMTextDelta extends Schema.TaggedClass<LLMTextDelta>()('LLMTextDelta', {
+  ...EventIdentity,
+  text: Schema.String
+}) {}
+
+export class LLMReasoningDelta extends Schema.TaggedClass<LLMReasoningDelta>()(
+  'LLMReasoningDelta',
+  {
+    ...EventIdentity,
+    text: Schema.String
+  }
+) {}
+
+export class ToolInputStart extends Schema.TaggedClass<ToolInputStart>()('ToolInputStart', {
+  ...EventIdentity,
+  id: Schema.String,
+  name: Schema.optional(Schema.String)
+}) {}
+
+export class ToolInputDelta extends Schema.TaggedClass<ToolInputDelta>()('ToolInputDelta', {
+  ...EventIdentity,
+  id: Schema.String,
+  delta: Schema.String
+}) {}
+
+export class ToolInputEnd extends Schema.TaggedClass<ToolInputEnd>()('ToolInputEnd', {
+  ...EventIdentity,
+  call: ToolCall
+}) {}
+
+export class ToolApprovalRequested extends Schema.TaggedClass<ToolApprovalRequested>()(
+  'ToolApprovalRequested',
+  {
+    ...EventIdentity,
+    call: ToolCall,
+    request: Schema.optional(ToolApprovalRequest)
+  }
+) {}
+
+export class ToolApprovalGranted extends Schema.TaggedClass<ToolApprovalGranted>()(
+  'ToolApprovalGranted',
+  {
+    ...EventIdentity,
+    toolCallId: Schema.String,
+    response: Schema.optional(ToolApprovalResponse)
+  }
+) {}
+
+export class ToolApprovalDenied extends Schema.TaggedClass<ToolApprovalDenied>()(
+  'ToolApprovalDenied',
+  {
+    ...EventIdentity,
+    toolCallId: Schema.String,
+    reason: Schema.String,
+    response: Schema.optional(ToolApprovalResponse)
+  }
+) {}
+
+export class QuestionRequested extends Schema.TaggedClass<QuestionRequested>()('QuestionRequested', {
+  ...EventIdentity,
+  request: QuestionRequest
+}) {}
+
+export class QuestionAnswered extends Schema.TaggedClass<QuestionAnswered>()('QuestionAnswered', {
+  ...EventIdentity,
+  response: QuestionResponse
+}) {}
+
+export class QuestionCancelled extends Schema.TaggedClass<QuestionCancelled>()('QuestionCancelled', {
+  ...EventIdentity,
+  response: QuestionResponse
+}) {}
+
+export class LLMStreamEnd extends Schema.TaggedClass<LLMStreamEnd>()('LLMStreamEnd', {
+  ...EventIdentity,
+  turn: Schema.Number
+}) {}
+
+export class AssistantMessageEvent extends Schema.TaggedClass<AssistantMessageEvent>()(
+  'AssistantMessage',
+  {
+    ...EventIdentity,
+    message: AssistantAgentMessage
+  }
+) {}
+
+export class ToolExecutionStarted extends Schema.TaggedClass<ToolExecutionStarted>()(
+  'ToolExecutionStarted',
+  {
+    ...EventIdentity,
+    call: ToolCall
+  }
+) {}
+
+export class ToolExecutionCompleted extends Schema.TaggedClass<ToolExecutionCompleted>()(
+  'ToolExecutionCompleted',
+  {
+    ...EventIdentity,
+    call: ToolCall,
+    result: ToolResult
+  }
+) {}
+
+export class ToolExecutionError extends Schema.TaggedClass<ToolExecutionError>()(
+  'ToolExecutionError',
+  {
+    ...EventIdentity,
+    call: ToolCall,
+    message: Schema.String,
+    code: AgentErrorCode
+  }
+) {}
+
+export class ProviderToolResult extends Schema.TaggedClass<ProviderToolResult>()(
+  'ProviderToolResult',
+  {
+    ...EventIdentity,
+    call: ToolCall,
+    result: ToolResult
+  }
+) {}
+
+export class SubagentStarted extends Schema.TaggedClass<SubagentStarted>()('SubagentStarted', {
+  ...EventIdentity,
+  parentToolCallId: NonEmptyTrimmedString,
+  subagentRunId: NonEmptyTrimmedString,
+  subagentType: NonEmptyTrimmedString,
+  description: Schema.String,
+  model: Schema.String
+}) {}
+
+export class SubagentCompleted extends Schema.TaggedClass<SubagentCompleted>()('SubagentCompleted', {
+  ...EventIdentity,
+  parentToolCallId: NonEmptyTrimmedString,
+  subagentRunId: NonEmptyTrimmedString,
+  subagentType: NonEmptyTrimmedString,
+  description: Schema.String,
+  model: Schema.String,
+  status: SubagentStatus,
+  durationMs: Schema.Number,
+  summary: Schema.optional(Schema.String)
+}) {}
+
+export const AgentEvent = Schema.Union([
+  AgentStart,
+  AgentError,
+  AgentEnd,
+  AgentAwaitingInput,
+  UsageUpdate,
+  AgentRetry,
+  CompactionStart,
+  CompactionEnd,
+  TurnStart,
+  TurnEnd,
+  LLMStreamStart,
+  LLMTextDelta,
+  LLMReasoningDelta,
+  ToolInputStart,
+  ToolInputDelta,
+  ToolInputEnd,
+  LLMStreamEnd,
+  AssistantMessageEvent,
+  ToolApprovalRequested,
+  ToolApprovalGranted,
+  ToolApprovalDenied,
+  QuestionRequested,
+  QuestionAnswered,
+  QuestionCancelled,
+  ToolExecutionStarted,
+  ToolExecutionCompleted,
+  ToolExecutionError,
+  ProviderToolResult,
+  SubagentStarted,
+  SubagentCompleted
+])
+export type AgentEvent = typeof AgentEvent.Type