@yolk-sdk/agent 0.1.0-canary.21 → 0.1.0-canary.22

package/src/protocol/message.ts

@@ -87,6 +87,25 @@ export class ToolResultMessage extends Schema.TaggedClass<ToolResultMessage>()('
 export const AgentMessage = Schema.Union([UserMessage, AssistantAgentMessage, ToolResultMessage])
 export type AgentMessage = typeof AgentMessage.Type
 
+export type DanglingHostToolCall = {
+  readonly call: ToolCall
+  readonly assistantMessageIndex: number
+  readonly beforeMessageIndex?: number
+}
+
+export type TranscriptInvariantValidation =
+  | { readonly _tag: 'Valid' }
+  | {
+      readonly _tag: 'DanglingHostToolCalls'
+      readonly calls: ReadonlyArray<DanglingHostToolCall>
+      readonly message: string
+    }
+
+export type RepairDanglingHostToolCallsOptions = {
+  readonly content?: (call: ToolCall) => Content
+  readonly structuredContent?: (call: ToolCall) => unknown
+}
+
 export const assistantContent = (message: AssistantAgentMessage): Content => {
   const parts = message.parts.flatMap(part => (part._tag === 'Text' ? [part.content] : []))
   const first = parts[0]
@@ -108,6 +127,114 @@ export const assistantReasoningText = (message: AssistantAgentMessage) =>
 export const assistantHostToolCalls = (message: AssistantAgentMessage) =>
   message.parts.flatMap(part => (part._tag === 'HostToolCall' ? [part.call] : []))
 
+type PendingHostToolCall = {
+  readonly call: ToolCall
+  readonly assistantMessageIndex: number
+}
+
+const pendingHostToolCalls = (message: AgentMessage, messageIndex: number) =>
+  message._tag === 'Assistant'
+    ? assistantHostToolCalls(message).map(call => ({ call, assistantMessageIndex: messageIndex }))
+    : []
+
+const danglingHostToolCall = (
+  pending: PendingHostToolCall,
+  beforeMessageIndex: number | undefined
+): DanglingHostToolCall => ({
+  call: pending.call,
+  assistantMessageIndex: pending.assistantMessageIndex,
+  ...(beforeMessageIndex === undefined ? {} : { beforeMessageIndex })
+})
+
+const danglingHostToolCallSummary = (calls: ReadonlyArray<DanglingHostToolCall>) =>
+  calls.map(({ call }) => `${call.name} (${call.id})`).join(', ')
+
+const danglingHostToolResultContent = (call: ToolCall) =>
+  `Tool ${call.name} did not return a result before the transcript continued.`
+
+const danglingHostToolResultMessage = (
+  call: ToolCall,
+  options: RepairDanglingHostToolCallsOptions | undefined
+) => {
+  const structuredContent = options?.structuredContent?.(call)
+
+  return ToolResultMessage.make({
+    toolCallId: call.id,
+    content: options?.content?.(call) ?? danglingHostToolResultContent(call),
+    isError: true,
+    ...(structuredContent === undefined ? {} : { structuredContent })
+  })
+}
+
+export const danglingHostToolCalls = (
+  messages: ReadonlyArray<AgentMessage>
+): ReadonlyArray<DanglingHostToolCall> => {
+  const dangling: Array<DanglingHostToolCall> = []
+  let pending: ReadonlyArray<PendingHostToolCall> = []
+
+  for (const [messageIndex, message] of messages.entries()) {
+    if (message._tag !== 'ToolResult' && pending.length > 0) {
+      dangling.push(...pending.map(call => danglingHostToolCall(call, messageIndex)))
+      pending = []
+    }
+
+    pending = [...pending, ...pendingHostToolCalls(message, messageIndex)]
+
+    if (message._tag === 'ToolResult') {
+      pending = pending.filter(call => call.call.id !== message.toolCallId)
+    }
+  }
+
+  dangling.push(...pending.map(call => danglingHostToolCall(call, undefined)))
+
+  return dangling
+}
+
+export const validateNoDanglingHostToolCalls = (
+  messages: ReadonlyArray<AgentMessage>
+): TranscriptInvariantValidation => {
+  const dangling = danglingHostToolCalls(messages)
+
+  if (dangling.length === 0) {
+    return { _tag: 'Valid' }
+  }
+
+  return {
+    _tag: 'DanglingHostToolCalls',
+    calls: dangling,
+    message: `Transcript has host tool calls without tool results: ${danglingHostToolCallSummary(dangling)}`
+  }
+}
+
+export const repairDanglingHostToolCalls = (
+  messages: ReadonlyArray<AgentMessage>,
+  options?: RepairDanglingHostToolCallsOptions
+): ReadonlyArray<AgentMessage> => {
+  const repaired: Array<AgentMessage> = []
+  let pending: ReadonlyArray<ToolCall> = []
+
+  for (const message of messages) {
+    if (message._tag !== 'ToolResult' && pending.length > 0) {
+      repaired.push(...pending.map(call => danglingHostToolResultMessage(call, options)))
+      pending = []
+    }
+
+    repaired.push(message)
+
+    if (message._tag === 'Assistant') {
+      pending = [...pending, ...assistantHostToolCalls(message)]
+    }
+
+    if (message._tag === 'ToolResult') {
+      pending = pending.filter(call => call.id !== message.toolCallId)
+    }
+  }
+
+  repaired.push(...pending.map(call => danglingHostToolResultMessage(call, options)))
+
+  return repaired
+}
+
 const formatCreatedAtMs = (createdAtMs: number) =>
   Number.isFinite(createdAtMs) ? new Date(createdAtMs).toISOString() : String(createdAtMs)
 

package/src/providers/anthropic/claude-provider.ts

@@ -48,6 +48,7 @@ import {
   providerFailureCause,
   providerFailureRetryable
 } from '../provider-error.ts'
+import { validateProviderTranscript } from '../transcript.ts'
 
 export type AnthropicClaudeProviderConfig = {
   readonly token: OAuthAccessToken
@@ -802,6 +803,7 @@ export const toAnthropicClaudeRequestBody = (
   config?: { readonly maxTokens?: number; readonly stream?: boolean }
 ): Effect.Effect<AnthropicRequestBody, LLMError> =>
   Effect.gen(function* () {
+    yield* validateProviderTranscript(request.messages)
     const rawMessages = yield* Effect.forEach(request.messages, toAnthropicMessage)
     const billingSystemBlock = yield* makeAnthropicClaudeBillingSystemBlock(rawMessages)
     const messages = prependSystemPromptToFirstUserMessage(rawMessages, request.systemPrompt)

package/src/providers/openai/codex-provider.ts

@@ -43,6 +43,7 @@ import {
   providerFailureCause,
   providerFailureRetryable
 } from '../provider-error.ts'
+import { validateProviderTranscript } from '../transcript.ts'
 
 export type OpenAiCodexReasoningSummary = 'auto' | 'concise' | 'detailed'
 
@@ -377,6 +378,7 @@ export const toOpenAiCodexRequestBody = (
   }
 ): Effect.Effect<OpenAiCodexRequestBody, LLMError> =>
   Effect.gen(function* () {
+    yield* validateProviderTranscript(request.messages)
     const input = Arr.flatten(yield* Effect.forEach(request.messages, messageToCodexInput))
 
     const body: Omit<OpenAiCodexRequestBody, 'tools'> = {

package/src/providers/openai/provider.ts

@@ -40,6 +40,7 @@ import {
   providerFailureCause,
   providerFailureRetryable
 } from '../provider-error.ts'
+import { validateProviderTranscript } from '../transcript.ts'
 
 export type OpenAiProviderConfig = {
   readonly chatCompletionsUrl?: string
@@ -340,6 +341,7 @@ export const toOpenAiRequestBody = (
   config?: { readonly maxCompletionTokens?: number }
 ): Effect.Effect<OpenAiRequestBody, LLMError> =>
   Effect.gen(function* () {
+    yield* validateProviderTranscript(request.messages)
     const systemMessage: OpenAiMessage = { role: 'system', content: request.systemPrompt }
     const requestMessages = yield* Effect.forEach(request.messages, toOpenAiMessage)
     const messages = [systemMessage, ...requestMessages]

package/src/providers/transcript.ts

@@ -0,0 +1,24 @@
+import { Effect } from 'effect'
+import {
+  validateNoDanglingHostToolCalls,
+  type AgentMessage
+} from '@yolk-sdk/agent/protocol'
+import { LLMError } from '@yolk-sdk/agent/loop'
+
+export const validateProviderTranscript = (
+  messages: ReadonlyArray<AgentMessage>
+): Effect.Effect<void, LLMError> => {
+  const validation = validateNoDanglingHostToolCalls(messages)
+
+  if (validation._tag === 'Valid') {
+    return Effect.void
+  }
+
+  return Effect.fail(
+    new LLMError({
+      cause: 'validation_error',
+      message: validation.message,
+      retryable: false
+    })
+  )
+}

package/src/tools/README.md

@@ -41,8 +41,9 @@ return Effect.fail(modelVisibleToolError({
 }))
 ```
 
-Use `ToolError` for fatal runtime/tool infrastructure failures such as broken wiring, auth/config,
-storage outages, or implementation bugs.
+Thrown `ToolError`s become model-visible failed tool results plus `ToolExecutionError` events,
+so keep messages safe and non-secret. Reserve stream failure for provider/runtime defects,
+aborts, and implementation bugs outside typed tool execution.
 
 ## Task subagents