@llm4ts/core 0.1.0

package/src/providers/ClaudeAgentSession.ts

@@ -0,0 +1,226 @@
+import * as Deferred from "effect/Deferred"
+import * as Effect from "effect/Effect"
+import * as PubSub from "effect/PubSub"
+import * as Queue from "effect/Queue"
+import * as Ref from "effect/Ref"
+import type * as Scope from "effect/Scope"
+import * as Stream from "effect/Stream"
+import {
+  SessionDone,
+  SessionResult,
+  SessionTextDelta,
+  SessionToolResult,
+  SessionToolUse,
+  SessionUsage,
+  type AgentSessionShape,
+  type SessionEvent
+} from "../AgentSession.ts"
+import { ProviderError, type LlmError } from "../Errors.ts"
+import { TokenUsage } from "../Models.ts"
+import type { ProcessExecutorShape } from "../ProcessExecutor.ts"
+import {
+  jsonArray,
+  jsonBooleanField,
+  jsonField,
+  jsonIntField,
+  jsonStringField,
+  jsonText,
+  parseJsonLine,
+  type JsonValue
+} from "./CliSupport.ts"
+
+export const claudeSessionArgv = (
+  model: string | undefined,
+  extraFlags: ReadonlyArray<string>
+): ReadonlyArray<string> => [
+  "claude",
+  "--print",
+  "--input-format",
+  "stream-json",
+  "--output-format",
+  "stream-json",
+  "--verbose",
+  ...(model === undefined ? [] : ["--model", model]),
+  ...extraFlags
+]
+
+export const claudeUserMessageJson = (text: string): string =>
+  JSON.stringify({
+    type: "user",
+    message: {
+      role: "user",
+      content: text
+    }
+  })
+
+const contentBlocks = (json: JsonValue): ReadonlyArray<JsonValue> =>
+  jsonArray(jsonField(jsonField(json, "message"), "content"))
+
+const assistantEvents = (json: JsonValue): ReadonlyArray<SessionEvent> =>
+  contentBlocks(json).flatMap((block): ReadonlyArray<SessionEvent> => {
+    switch (jsonStringField(block, "type")) {
+      case "text": {
+        const text = jsonStringField(block, "text")
+        return text === undefined || text.length === 0 ? [] : [SessionTextDelta.make({ text })]
+      }
+      case "tool_use":
+        return [
+          SessionToolUse.make({
+            tool: jsonStringField(block, "name") ?? "",
+            rawInput: jsonText(jsonField(block, "input") ?? {}),
+            id: jsonStringField(block, "id") ?? ""
+          })
+        ]
+      default:
+        return []
+    }
+  })
+
+const toolResultEvents = (json: JsonValue): ReadonlyArray<SessionEvent> =>
+  contentBlocks(json).flatMap((block): ReadonlyArray<SessionEvent> => {
+    if (jsonStringField(block, "type") !== "tool_result") {
+      return []
+    }
+    const content = jsonField(block, "content")
+    return [
+      SessionToolResult.make({
+        id: jsonStringField(block, "tool_use_id") ?? "",
+        status: jsonBooleanField(block, "is_error") === true ? "error" : "success",
+        content: content === undefined ? "" : jsonText(content)
+      })
+    ]
+  })
+
+const resultEvents = (json: JsonValue): ReadonlyArray<SessionEvent> => {
+  const usage = jsonField(json, "usage")
+  const usageEvents: ReadonlyArray<SessionEvent> =
+    usage === undefined
+      ? []
+      : [
+          SessionUsage.make({
+            usage: TokenUsage.make({
+              prompt: jsonIntField(usage, "input_tokens") ?? 0,
+              completion: jsonIntField(usage, "output_tokens") ?? 0,
+              total:
+                (jsonIntField(usage, "input_tokens") ?? 0) +
+                (jsonIntField(usage, "output_tokens") ?? 0),
+              ...(jsonIntField(usage, "cache_read_input_tokens") === undefined
+                ? {}
+                : {
+                    cached: jsonIntField(usage, "cache_read_input_tokens") ?? 0
+                  })
+            })
+          })
+        ]
+
+  return [
+    ...usageEvents,
+    SessionDone.make({
+      result: jsonStringField(json, "result") ?? ""
+    })
+  ]
+}
+
+export const parseClaudeSessionLine = (line: string): ReadonlyArray<SessionEvent> => {
+  const json = parseJsonLine(line)
+  if (json === undefined) {
+    return []
+  }
+  switch (jsonStringField(json, "type")) {
+    case "assistant":
+      return assistantEvents(json)
+    case "user":
+      return toolResultEvents(json)
+    case "result":
+      return resultEvents(json)
+    default:
+      return []
+  }
+}
+
+export const claudeSessionInitModel = (line: string): string | undefined => {
+  const json = parseJsonLine(line)
+  return json !== undefined && jsonStringField(json, "type") === "system"
+    ? jsonStringField(json, "model")
+    : undefined
+}
+
+export const openClaudeAgentSession = Effect.fn("@llm4ts/core/providers/ClaudeAgentSession.open")(
+  function* (
+    executor: ProcessExecutorShape,
+    argv: ReadonlyArray<string>,
+    cwd: string,
+    envVars: Readonly<Record<string, string>> = {}
+  ): Effect.fn.Return<AgentSessionShape, LlmError, Scope.Scope> {
+    const [stdin, stdout] = yield* executor.runBidirectional(argv, cwd, envVars)
+    const events = yield* PubSub.unbounded<SessionEvent>()
+    const done = yield* Deferred.make<SessionResult, LlmError>()
+    const model = yield* Ref.make<string | undefined>(undefined)
+    const text = yield* Ref.make("")
+    const usage = yield* Ref.make<TokenUsage | undefined>(undefined)
+
+    const trackEvent = Effect.fn("@llm4ts/core/providers/ClaudeAgentSession.trackEvent")(function* (
+      event: SessionEvent
+    ) {
+      switch (event._tag) {
+        case "TextDelta":
+          yield* Ref.update(text, (current) => current + event.text)
+          break
+        case "Usage":
+          yield* Ref.set(usage, event.usage)
+          break
+        case "Done": {
+          const accumulated = yield* Ref.get(text)
+          const finalUsage = yield* Ref.get(usage)
+          const finalModel = yield* Ref.get(model)
+          yield* Deferred.succeed(
+            done,
+            SessionResult.make({
+              text: event.result.length === 0 ? accumulated : event.result,
+              ...(finalUsage === undefined ? {} : { usage: finalUsage }),
+              ...(finalModel === undefined ? {} : { model: finalModel })
+            })
+          )
+          break
+        }
+        default:
+          break
+      }
+      yield* PubSub.publish(events, event)
+    })
+
+    yield* stdout.pipe(
+      Stream.mapEffect((line) => {
+        const initializedModel = claudeSessionInitModel(line)
+        return initializedModel === undefined
+          ? Effect.succeed(line)
+          : Ref.set(model, initializedModel).pipe(Effect.as(line))
+      }),
+      Stream.flatMap((line) => Stream.fromIterable(parseClaudeSessionLine(line))),
+      Stream.mapEffect(trackEvent),
+      Stream.runDrain,
+      Effect.catch((error) => Deferred.fail(done, error).pipe(Effect.asVoid)),
+      Effect.ensuring(
+        Deferred.fail(
+          done,
+          ProviderError.make({
+            message: "claude session ended before a result"
+          })
+        ).pipe(Effect.asVoid)
+      ),
+      Effect.forkScoped
+    )
+
+    const sendUserMessage = (message: string): Effect.Effect<void, LlmError> =>
+      Queue.offer(stdin, claudeUserMessageJson(message)).pipe(Effect.asVoid)
+
+    return {
+      events: Stream.fromPubSub(events),
+      sendUserMessage,
+      respondToAsk: sendUserMessage,
+      respondToApproval: (_id, _approved) => Effect.void,
+      awaitResult: Deferred.await(done),
+      cancel: Queue.shutdown(stdin)
+    }
+  }
+)

package/src/providers/ClaudeCliConnector.ts

@@ -0,0 +1,201 @@
+import * as Effect from "effect/Effect"
+import * as Ref from "effect/Ref"
+import type * as Schema from "effect/Schema"
+import * as Stream from "effect/Stream"
+import { makeCliConnector, type CliConnectorShape } from "../Connector.ts"
+import type { CliConnectorConfig } from "../ConnectorConfig.ts"
+import type { LlmError } from "../Errors.ts"
+import type { StructuredResult } from "../LlmService.ts"
+import {
+  ConnectorCapabilities,
+  ConnectorIds,
+  LlmChunk,
+  TokenUsage,
+  type JsonSchema
+} from "../Models.ts"
+import type { ProcessExecutorShape } from "../ProcessExecutor.ts"
+import { collect } from "../Streaming.ts"
+import { parseFromText, withSchemaHint } from "../StructuredOutput.ts"
+import {
+  failClassifiedCliError,
+  jsonArray,
+  jsonField,
+  jsonIntField,
+  jsonStringField,
+  optionalModelArgs,
+  parseJsonLine,
+  sortedFlagArgs,
+  toolEventChunk,
+  usageEventChunk
+} from "./CliSupport.ts"
+
+export const claudeCliExtraArgs = (config: CliConnectorConfig): ReadonlyArray<string> => {
+  const effectiveFlags = config.readOnly
+    ? {
+        ...config.flags,
+        "permission-mode": "default",
+        "disallowed-tools": "Write,Edit,NotebookEdit"
+      }
+    : config.flags
+  return [...optionalModelArgs(config.model), ...sortedFlagArgs(effectiveFlags)]
+}
+
+export const claudeCliInitModel = (line: string): string | undefined => {
+  const json = parseJsonLine(line)
+  return json !== undefined && jsonStringField(json, "type") === "system"
+    ? jsonStringField(json, "model")
+    : undefined
+}
+
+export const parseClaudeCliStreamLine = (line: string): ReadonlyArray<LlmChunk> => {
+  const json = parseJsonLine(line)
+  if (json === undefined) {
+    return []
+  }
+
+  switch (jsonStringField(json, "type")) {
+    case "assistant":
+      return jsonArray(jsonField(jsonField(json, "message"), "content")).flatMap(
+        (block): ReadonlyArray<LlmChunk> => {
+          switch (jsonStringField(block, "type")) {
+            case "text": {
+              const text = jsonStringField(block, "text")
+              return text === undefined || text.length === 0 ? [] : [LlmChunk.make({ delta: text })]
+            }
+            case "tool_use":
+              return [
+                toolEventChunk(jsonStringField(block, "name") ?? "", jsonField(block, "input"))
+              ]
+            default:
+              return []
+          }
+        }
+      )
+    case "result": {
+      const usage = jsonField(json, "usage")
+      if (usage === undefined) {
+        return []
+      }
+      const prompt = jsonIntField(usage, "input_tokens") ?? 0
+      const completion = jsonIntField(usage, "output_tokens") ?? 0
+      const cached = jsonIntField(usage, "cache_read_input_tokens")
+      return [
+        usageEventChunk(
+          undefined,
+          TokenUsage.make({
+            prompt,
+            completion,
+            total: prompt + completion,
+            ...(cached === undefined ? {} : { cached })
+          })
+        )
+      ]
+    }
+    default:
+      return []
+  }
+}
+
+export const makeClaudeCliConnector = (
+  config: CliConnectorConfig,
+  executor: ProcessExecutorShape
+): CliConnectorShape => {
+  const cwd = config.workingDir ?? "."
+  const extraArgs = claudeCliExtraArgs(config)
+
+  const complete = Effect.fn("@llm4ts/core/providers/ClaudeCliConnector.complete")(function* (
+    prompt: string
+  ) {
+    const result = yield* executor.runWithStdin(
+      ["claude", "--print", ...extraArgs],
+      cwd,
+      config.envVars,
+      prompt
+    )
+    if (result.exitCode !== 0) {
+      const raw = result.stdout.join("\n")
+      return yield* failClassifiedCliError(
+        "claude",
+        `claude exited with code ${result.exitCode}`,
+        raw
+      )
+    }
+    return result.stdout.join("\n")
+  })
+
+  const completeStream = (prompt: string) =>
+    Stream.unwrap(
+      Effect.map(Ref.make<string | undefined>(undefined), (model) =>
+        executor
+          .runStreamingWithStdin(
+            ["claude", "--print", "--output-format", "stream-json", "--verbose", ...extraArgs],
+            cwd,
+            config.envVars,
+            prompt
+          )
+          .pipe(
+            Stream.mapEffect((line) => {
+              const initializedModel = claudeCliInitModel(line)
+              return initializedModel === undefined
+                ? Effect.succeed(line)
+                : Ref.set(model, initializedModel).pipe(Effect.as(line))
+            }),
+            Stream.flatMap((line) => Stream.fromIterable(parseClaudeCliStreamLine(line))),
+            Stream.mapEffect((chunk) =>
+              chunk.usage === undefined
+                ? Effect.succeed(chunk)
+                : Effect.map(Ref.get(model), (servedModel) =>
+                    servedModel === undefined
+                      ? chunk
+                      : LlmChunk.make({
+                          ...chunk,
+                          metadata: {
+                            ...chunk.metadata,
+                            model: servedModel
+                          }
+                        })
+                  )
+            )
+          )
+      )
+    )
+
+  const base = makeCliConnector({
+    id: ConnectorIds.ClaudeCli,
+    interactionSupport: "InteractiveStdin",
+    capabilities: ConnectorCapabilities.make({
+      interactiveSessions: true,
+      askUser: true,
+      approval: true,
+      resumableSessions: true
+    }),
+    buildArgv: (prompt, _context) => ["claude", "--print", ...extraArgs, prompt],
+    buildInteractiveArgv: (_context) => ["claude", ...extraArgs],
+    complete,
+    completeStream,
+    versionProbe: { executor, binary: "claude", cwd }
+  })
+
+  const executeStructuredWithUsage = <A, E, RD, RE>(
+    prompt: string,
+    schema: Schema.ConstraintCodec<A, E, RD, RE>,
+    jsonSchema: JsonSchema
+  ): Effect.Effect<StructuredResult<A>, LlmError, RD> =>
+    Effect.gen(function* () {
+      const reply = yield* collect(completeStream(withSchemaHint(prompt, jsonSchema)))
+      const value = yield* parseFromText(reply.content, schema, jsonSchema)
+      const result: StructuredResult<A> = [value, reply.usage, reply.metadata.model]
+      return result
+    })
+
+  return {
+    ...base,
+    executeStructured: <A, E, RD, RE>(
+      prompt: string,
+      schema: Schema.ConstraintCodec<A, E, RD, RE>,
+      jsonSchema: JsonSchema
+    ): Effect.Effect<A, LlmError, RD> =>
+      Effect.map(executeStructuredWithUsage(prompt, schema, jsonSchema), ([value]) => value),
+    executeStructuredWithUsage
+  }
+}

package/src/providers/CliSupport.ts

@@ -0,0 +1,100 @@
+import * as DateTime from "effect/DateTime"
+import * as Effect from "effect/Effect"
+import * as Option from "effect/Option"
+import * as Schema from "effect/Schema"
+import { ProviderError, type LlmError } from "../Errors.ts"
+import { LlmChunk, type TokenUsage } from "../Models.ts"
+import { classifyUsageLimit } from "../UsageLimits.ts"
+
+export type JsonValue = typeof Schema.Json.Type
+export type JsonRecord = Readonly<Record<string, JsonValue>>
+
+export const isJsonRecord = (value: JsonValue): value is JsonRecord =>
+  value !== null && typeof value === "object" && !Array.isArray(value)
+
+export const parseJsonLine = (line: string): JsonValue | undefined => {
+  const trimmed = line.trim()
+  if (trimmed.length === 0 || !trimmed.startsWith("{")) {
+    return undefined
+  }
+  return Option.getOrUndefined(
+    Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Json))(trimmed)
+  )
+}
+
+export const jsonField = (value: JsonValue | undefined, name: string): JsonValue | undefined =>
+  value !== undefined && isJsonRecord(value) ? value[name] : undefined
+
+export const jsonStringField = (value: JsonValue | undefined, name: string): string | undefined => {
+  const field = jsonField(value, name)
+  return typeof field === "string" ? field : undefined
+}
+
+export const jsonIntField = (value: JsonValue | undefined, name: string): number | undefined => {
+  const field = jsonField(value, name)
+  return typeof field === "number" && Number.isFinite(field) ? Math.trunc(field) : undefined
+}
+
+export const jsonBooleanField = (
+  value: JsonValue | undefined,
+  name: string
+): boolean | undefined => {
+  const field = jsonField(value, name)
+  return typeof field === "boolean" ? field : undefined
+}
+
+export const jsonArray = (value: JsonValue | undefined): ReadonlyArray<JsonValue> =>
+  Array.isArray(value) ? value : []
+
+export const jsonObjectEntries = (
+  value: JsonValue | undefined
+): ReadonlyArray<readonly [string, JsonValue]> =>
+  value !== undefined && isJsonRecord(value) ? Object.entries(value) : []
+
+export const jsonText = (value: JsonValue): string => JSON.stringify(value) ?? "{}"
+
+export const sortedFlagArgs = (flags: Readonly<Record<string, string>>): ReadonlyArray<string> =>
+  Object.entries(flags)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .flatMap(([key, value]) => (value.length === 0 ? [`--${key}`] : [`--${key}`, value]))
+
+export const optionalModelArgs = (model: string | undefined): ReadonlyArray<string> =>
+  model === undefined ? [] : ["--model", model]
+
+export const toolEventChunk = (name: string, input: JsonValue | undefined): LlmChunk =>
+  LlmChunk.make({
+    delta: "",
+    metadata: {
+      event: "tool_use",
+      tool_name: name,
+      tool_input: input === undefined ? "{}" : jsonText(input)
+    }
+  })
+
+export const usageEventChunk = (model: string | undefined, usage: TokenUsage): LlmChunk =>
+  LlmChunk.make({
+    delta: "",
+    finishReason: "stop",
+    usage,
+    metadata:
+      model === undefined
+        ? {}
+        : {
+            model
+          }
+  })
+
+export const failClassifiedCliError = Effect.fn(
+  "@llm4ts/core/providers/CliSupport.failClassifiedCliError"
+)(function* (
+  provider: string,
+  fallbackPrefix: string,
+  raw: string
+): Effect.fn.Return<never, LlmError> {
+  const now = yield* DateTime.now
+  const timeZone = yield* Effect.sync(() => Intl.DateTimeFormat().resolvedOptions().timeZone)
+  return yield* classifyUsageLimit(provider, raw, now, timeZone) ??
+    ProviderError.make({
+      message: `${fallbackPrefix}: ${raw}`
+    })
+})