@llm4ts/core 2.35.4 → 2.36.0

package/src/providers/AnthropicProvider.ts

@@ -1,5 +1,6 @@
 import * as Effect from "effect/Effect"
 import * as Redacted from "effect/Redacted"
+import * as Ref from "effect/Ref"
 import * as Schema from "effect/Schema"
 import * as Stream from "effect/Stream"
 import { makeApiConnector, type ApiConnectorShape } from "../Connector.ts"
@@ -7,8 +8,10 @@ import { AuthenticationError, ConfigError, ParseError, type LlmError } from "../
 import type { HttpClientShape } from "../HttpClient.ts"
 import type { StructuredResult } from "../LlmService.ts"
 import {
+  ConnectorCapabilities,
   ConnectorIds,
   LlmChunk,
+  TokenUsage,
   ToolCall,
   ToolCallResponse,
   type JsonSchema,
@@ -20,14 +23,18 @@ import { collect } from "../Streaming.ts"
 import { parseFromText } from "../StructuredOutput.ts"
 import type { AnthropicContentBlockFull } from "./AnthropicModels.ts"
 import {
+  AnthropicCacheControl,
   AnthropicMessage,
+  AnthropicOutputConfig,
   AnthropicRequest,
   AnthropicRequestWithTools,
   AnthropicResponse,
   AnthropicResponseWithTools,
   AnthropicStreamChunk,
+  AnthropicTextBlock,
   AnthropicTool,
-  AnthropicToolInputSchema
+  AnthropicToolInputSchema,
+  AnthropicUsage
 } from "./AnthropicModels.ts"
 
 interface AnthropicRequiredConfig {
@@ -84,20 +91,76 @@ export const anthropicHistory = (messages: ReadonlyArray<Message>): AnthropicHis
     )
 })
 
+const ephemeral = AnthropicCacheControl.make({ type: "ephemeral" })
+
+const cachedBlock = (text: string): AnthropicTextBlock =>
+  AnthropicTextBlock.make({ type: "text", text, cache_control: ephemeral })
+
+/**
+ * Prompt-cache breakpoints (ADR 0029): one on the system block, one on the
+ * last message. The API caches the prefix up to each marker and looks the
+ * next request up at earlier markers too, so a chat whose history only
+ * grows at the end reads every earlier turn from the cache.
+ */
+export const withCacheMarkers = (
+  messages: ReadonlyArray<AnthropicMessage>,
+  system: string | undefined
+): {
+  readonly messages: ReadonlyArray<AnthropicMessage>
+  readonly system: string | ReadonlyArray<AnthropicTextBlock> | undefined
+} => {
+  const last = messages[messages.length - 1]
+  const marked =
+    last === undefined || typeof last.content !== "string"
+      ? messages
+      : [
+          ...messages.slice(0, -1),
+          AnthropicMessage.make({ role: last.role, content: [cachedBlock(last.content)] })
+        ]
+  return {
+    messages: marked,
+    system: system === undefined || system.length === 0 ? system : [cachedBlock(system)]
+  }
+}
+
 export const buildAnthropicRequest = (
   config: LlmConfig,
   messages: ReadonlyArray<AnthropicMessage>,
   stream: boolean,
   system?: string
-): AnthropicRequest =>
-  AnthropicRequest.make({
+): AnthropicRequest => {
+  const cached =
+    config.promptCache === false ? { messages, system } : withCacheMarkers(messages, system)
+  return AnthropicRequest.make({
     model: config.model,
     max_tokens: config.maxTokens ?? 4096,
-    messages,
+    messages: cached.messages,
     stream,
     ...(config.temperature === undefined ? {} : { temperature: config.temperature }),
-    ...(system === undefined ? {} : { system })
+    ...(cached.system === undefined ? {} : { system: cached.system }),
+    ...(config.effort === undefined
+      ? {}
+      : { output_config: AnthropicOutputConfig.make({ effort: config.effort }) })
+  })
+}
+
+/**
+ * The API's usage as llm4ts counts it: cache reads and writes are prompt
+ * tokens the request paid for (at their own rates), `cached` is what was
+ * read from the cache.
+ */
+export const anthropicTokenUsage = (usage: AnthropicUsage): TokenUsage => {
+  const read = usage.cache_read_input_tokens ?? 0
+  const written = usage.cache_creation_input_tokens ?? 0
+  const prompt = (usage.input_tokens ?? 0) + read + written
+  const completion = usage.output_tokens ?? 0
+  return TokenUsage.make({
+    prompt,
+    completion,
+    total: prompt + completion,
+    ...(read > 0 ? { cached: read } : {})
   })
+}
 
 export const buildAnthropicToolRequest = (
   config: LlmConfig,
@@ -123,7 +186,10 @@ export const buildAnthropicToolRequest = (
         })
       })
     ),
-    ...(config.temperature === undefined ? {} : { temperature: config.temperature })
+    ...(config.temperature === undefined ? {} : { temperature: config.temperature }),
+    ...(config.effort === undefined
+      ? {}
+      : { output_config: AnthropicOutputConfig.make({ effort: config.effort }) })
   })
 
 const contentFromResponse = (
@@ -195,46 +261,76 @@ export const makeAnthropicProvider = (
     Stream.unwrap(
       Effect.map(requiredConfig, ({ apiKey, baseUrl }) => {
         const request = buildAnthropicRequest(config, messages, true, system)
-        return httpClient
-          .postJsonStreamSSE(
-            `${baseUrl}/messages`,
-            JSON.stringify(request),
-            authHeaders(apiKey),
-            config.timeout
-          )
-          .pipe(
-            Stream.mapEffect(decodeStreamChunk),
-            Stream.flatMap((chunk) => {
-              if (chunk.type === "content_block_delta") {
-                const delta = chunk.delta?.text ?? ""
-                return delta.length === 0
-                  ? Stream.empty
-                  : Stream.succeed(
-                      LlmChunk.make({
-                        delta,
+        // Usage arrives in two events: `message_start` carries the input
+        // (and cache) counts, `message_delta` the output so far. The final
+        // chunk carries them together, so the seat is measured, not estimated.
+        const usage = Stream.unwrap(
+          Effect.map(Ref.make<AnthropicUsage | undefined>(undefined), (started) =>
+            httpClient
+              .postJsonStreamSSE(
+                `${baseUrl}/messages`,
+                JSON.stringify(request),
+                authHeaders(apiKey),
+                config.timeout
+              )
+              .pipe(
+                Stream.mapEffect(decodeStreamChunk),
+                Stream.mapEffect((chunk) =>
+                  chunk.type === "message_start" && chunk.message?.usage !== undefined
+                    ? Effect.as(Ref.set(started, chunk.message.usage), chunk)
+                    : Effect.succeed(chunk)
+                ),
+                Stream.flatMap((chunk) => {
+                  if (chunk.type === "content_block_delta") {
+                    const delta = chunk.delta?.text ?? ""
+                    return delta.length === 0
+                      ? Stream.empty
+                      : Stream.succeed(
+                          LlmChunk.make({
+                            delta,
+                            metadata: {
+                              provider: "anthropic",
+                              model: config.model
+                            }
+                          })
+                        )
+                  }
+                  const finishReason =
+                    chunk.type === "message_delta"
+                      ? (chunk.delta?.stop_reason ?? undefined)
+                      : undefined
+                  if (finishReason === undefined) {
+                    return Stream.empty
+                  }
+                  return Stream.fromEffect(
+                    Effect.map(Ref.get(started), (input) => {
+                      const combined =
+                        input === undefined && chunk.usage === undefined
+                          ? undefined
+                          : anthropicTokenUsage(
+                              AnthropicUsage.make({
+                                ...(input ?? {}),
+                                ...(chunk.usage?.output_tokens === undefined
+                                  ? {}
+                                  : { output_tokens: chunk.usage.output_tokens })
+                              })
+                            )
+                      return LlmChunk.make({
+                        delta: "",
+                        finishReason,
+                        ...(combined === undefined ? {} : { usage: combined }),
                         metadata: {
                           provider: "anthropic",
                           model: config.model
                         }
                       })
-                    )
-              }
-              const finishReason =
-                chunk.type === "message_delta" ? (chunk.delta?.stop_reason ?? undefined) : undefined
-              return finishReason === undefined
-                ? Stream.empty
-                : Stream.succeed(
-                    LlmChunk.make({
-                      delta: "",
-                      finishReason,
-                      metadata: {
-                        provider: "anthropic",
-                        model: config.model
-                      }
                     })
                   )
-            })
+                })
+              )
           )
+        )
+        return usage
       })
     )
 
@@ -315,6 +411,7 @@ export const makeAnthropicProvider = (
     },
     executeWithTools,
     executeStructuredWithUsage,
-    isAvailable
+    isAvailable,
+    capabilities: ConnectorCapabilities.make({ readOnlyEnforcement: "enforced", effort: "mapped" })
   })
 }

package/src/providers/ClaudeCliConnector.ts

@@ -30,7 +30,8 @@ import {
   toolResultChunk,
   toolResultText,
   usageEventChunk,
-  type JsonValue
+  type JsonValue,
+  effortWord
 } from "./CliSupport.ts"
 
 /**
@@ -51,7 +52,16 @@ export const claudeCliExtraArgs = (config: CliConnectorConfig): ReadonlyArray<st
         ...config.flags
       }
     : config.flags
-  return [...optionalModelArgs(config.model), ...sortedFlagArgs(effectiveFlags)]
+  return [
+    ...optionalModelArgs(config.model),
+    // `--effort` is Claude Code's own vocabulary: low, medium, high, max.
+    ...(config.effort === undefined ? [] : ["--effort", effortWord(config.effort)]),
+    // `--bare` (Claude Code 2.1.81+) skips hooks, skills, plugins, MCP,
+    // auto memory and CLAUDE.md discovery: the documented headless mode for
+    // a repository the run does not trust (ADR 0029).
+    ...(config.isolated ? ["--bare"] : []),
+    ...sortedFlagArgs(effectiveFlags)
+  ]
 }
 
 export const claudeCliInitModel = (line: string): string | undefined => {
@@ -256,7 +266,9 @@ export const makeClaudeCliConnector = (
       askUser: true,
       approval: true,
       resumableSessions: true,
-      readOnlyEnforcement: "enforced"
+      readOnlyEnforcement: "enforced",
+      effort: "mapped",
+      isolatedHeadless: "enforced"
     }),
     buildArgv: (prompt, _context) => ["claude", "--print", ...extraArgs, prompt],
     buildInteractiveArgv: (_context) => ["claude", ...extraArgs],

package/src/providers/CliSupport.ts

@@ -5,7 +5,7 @@ import * as Ref from "effect/Ref"
 import * as Schema from "effect/Schema"
 import * as Stream from "effect/Stream"
 import { ProviderError, type LlmError } from "../Errors.ts"
-import { LlmChunk, TokenUsage } from "../Models.ts"
+import { LlmChunk, TokenUsage, type Effort } from "../Models.ts"
 import { classifyUsageLimit } from "../UsageLimits.ts"
 
 export type JsonValue = typeof Schema.Json.Type
@@ -68,6 +68,13 @@ export const sortedFlagArgs = (flags: Readonly<Record<string, string>>): Readonl
 export const optionalModelArgs = (model: string | undefined): ReadonlyArray<string> =>
   model === undefined ? [] : ["--model", model]
 
+/**
+ * The harness's word for an llm4ts effort (ADR 0029): the same four words,
+ * except `max` on a harness whose top level is `xhigh`.
+ */
+export const effortWord = (effort: Effort, top: "max" | "xhigh" = "max"): string =>
+  effort === "max" ? top : effort
+
 export const toolEventChunk = (name: string, input: JsonValue | undefined, id?: string): LlmChunk =>
   LlmChunk.make({
     delta: "",

package/src/providers/CodexConnector.ts

@@ -17,6 +17,7 @@ import { collect } from "../Streaming.ts"
 import type { TemporaryFilesShape } from "../TemporaryFiles.ts"
 import { parseFromText, withSchemaHint } from "../StructuredOutput.ts"
 import {
+  effortWord,
   failClassifiedCliError,
   isJsonRecord,
   jsonField,
@@ -39,7 +40,19 @@ export const codexExtraArgs = (config: CliConnectorConfig): ReadonlyArray<string
         sandbox: "read-only"
       }
     : config.flags
-  return [...optionalModelArgs(config.model), ...sortedFlagArgs(effectiveFlags)]
+  return [
+    ...optionalModelArgs(config.model),
+    // Codex reads its effort from config: `-c model_reasoning_effort="…"`,
+    // top level `xhigh`.
+    ...(config.effort === undefined
+      ? []
+      : ["-c", `model_reasoning_effort="${effortWord(config.effort, "xhigh")}"`]),
+    // Isolation is partial (ADR 0029): the project's `.codex/config.toml`
+    // is skipped unless the user trusted that path, and this turns off the
+    // project's AGENTS.md; MCP servers from the user's own config still load.
+    ...(config.isolated ? ["-c", "project_doc_max_bytes=0"] : []),
+    ...sortedFlagArgs(effectiveFlags)
+  ]
 }
 
 export const codexSchemaEnforceable = (schema: JsonSchema): boolean => {
@@ -224,7 +237,9 @@ export const makeCodexConnector = (
     // `sandbox: read-only` is an OS-level sandbox — a real capability gate.
     capabilities: ConnectorCapabilities.make({
       interactiveSessions: true,
-      readOnlyEnforcement: "enforced"
+      readOnlyEnforcement: "enforced",
+      effort: "mapped",
+      isolatedHeadless: "partial"
     }),
     buildArgv: (prompt, _context) => ["codex", "exec", ...extraArgs, prompt],
     buildInteractiveArgv: (_context) => ["codex", ...extraArgs],

package/src/providers/GeminiCliProvider.ts

@@ -122,6 +122,8 @@ export class GeminiCliExecutionContext extends Schema.Class<GeminiCliExecutionCo
   sandbox: Schema.optionalKey(GeminiSandbox),
   turnLimit: Schema.optionalKey(Schema.Int),
   readOnly: Schema.Boolean.pipe(Schema.withConstructorDefault(Effect.succeed(false))),
+  /** No project extensions (`-e none`); settings and GEMINI.md are still read (ADR 0029). */
+  isolated: Schema.Boolean.pipe(Schema.withConstructorDefault(Effect.succeed(false))),
   /** The seat's own environment (a roster `env`), under llm4ts's own keys. */
   envVars: Schema.Record(Schema.String, Schema.String).pipe(
     Schema.withConstructorDefault(Effect.succeed<Readonly<Record<string, string>>>({}))
@@ -135,6 +137,7 @@ export const geminiCliExecutionContextFrom = (
     ...(config.workingDir === undefined ? {} : { cwd: config.workingDir }),
     ...(config.turnLimit === undefined ? {} : { turnLimit: config.turnLimit }),
     readOnly: config.readOnly,
+    isolated: config.isolated,
     envVars: config.envVars,
     ...(config.sandbox === undefined
       ? {}
@@ -226,7 +229,11 @@ export const buildGeminiArgs = (
     outputFormat,
     ...directories,
     ...(adminPolicyPath === undefined ? [] : ["--admin-policy", adminPolicyPath]),
-    ...(context.sandbox === undefined ? [] : ["-s"])
+    ...(context.sandbox === undefined ? [] : ["-s"]),
+    // Partial isolation: no extensions; `.gemini/settings.json` and
+    // GEMINI.md have no off switch, and the ADR 0027 harness policy above
+    // already keeps the model out of llm4ts's own packages.
+    ...(context.isolated ? ["-e", "none"] : [])
   ]
 }
 
@@ -964,7 +971,8 @@ export const makeGeminiCliProvider = (
     // every seat that runs.
     capabilities: ConnectorCapabilities.make({
       interactiveSessions: true,
-      readOnlyEnforcement: "enforced"
+      readOnlyEnforcement: "enforced",
+      isolatedHeadless: "partial"
     })
   })
 

package/src/providers/OpenAIModels.ts

@@ -44,6 +44,8 @@ export class OpenAIChatCompletionRequest extends Schema.Class<OpenAIChatCompleti
   stream: Schema.optionalKey(Schema.Boolean),
   response_format: Schema.optionalKey(OpenAIResponseFormat),
   chat_template_kwargs: Schema.optionalKey(OpenAIChatTemplateKwargs),
+  /** Reasoning effort (ADR 0029): low, medium, high, xhigh; sent only when asked. */
+  reasoning_effort: Schema.optionalKey(Schema.String),
   logprobs: Schema.optionalKey(Schema.Boolean),
   top_logprobs: Schema.optionalKey(Schema.Int)
 }) {}

package/src/providers/OpenAIProvider.ts

@@ -7,6 +7,7 @@ import { AuthenticationError, ConfigError, ParseError, type LlmError } from "../
 import type { HttpClientShape } from "../HttpClient.ts"
 import type { StructuredResult } from "../LlmService.ts"
 import {
+  ConnectorCapabilities,
   ConnectorIds,
   LlmChunk,
   ToolCall,
@@ -18,6 +19,7 @@ import {
   type ToolDefinition
 } from "../Models.ts"
 import { parseFromText } from "../StructuredOutput.ts"
+import { effortWord } from "./CliSupport.ts"
 import {
   OpenAIChatChunk,
   OpenAIChatCompletionRequest,
@@ -74,7 +76,8 @@ export const buildOpenAIChatRequest = (
     temperature: config.temperature ?? 0.7,
     stream,
     ...(config.maxTokens === undefined ? {} : { max_tokens: config.maxTokens }),
-    ...(responseFormat === undefined ? {} : { response_format: responseFormat })
+    ...(responseFormat === undefined ? {} : { response_format: responseFormat }),
+    ...(config.effort === undefined ? {} : { reasoning_effort: effortWord(config.effort, "xhigh") })
   })
 
 export const buildOpenAIToolRequest = (
@@ -326,6 +329,7 @@ export const makeOpenAIProvider = (
     executeStreamWithHistory: (messages) => executeStreamRequest(openAIHistoryMessages(messages)),
     executeWithTools,
     executeStructuredWithUsage,
-    isAvailable
+    isAvailable,
+    capabilities: ConnectorCapabilities.make({ readOnlyEnforcement: "enforced", effort: "mapped" })
   })
 }

package/src/providers/PiConnector.ts

@@ -6,6 +6,7 @@ import { ProviderError } from "../Errors.ts"
 import { ConnectorCapabilities, ConnectorIds, LlmChunk, TokenUsage } from "../Models.ts"
 import type { ProcessExecutorShape } from "../ProcessExecutor.ts"
 import {
+  effortWord,
   cumulativeUsage,
   failClassifiedCliError,
   jsonBooleanField,
@@ -29,6 +30,11 @@ export const piExtraArgs = (config: CliConnectorConfig): ReadonlyArray<string> =
   // session, unsafe for a one-shot complete() call with no tool-loop
   // continuation (see the field's doc comment on CliConnectorConfig).
   ...(config.noTools ? ["--no-tools"] : config.readOnly ? ["--tools", "read"] : []),
+  // `--thinking` is pi's effort flag (off, minimal, low, medium, high, xhigh).
+  ...(config.effort === undefined ? [] : ["--thinking", effortWord(config.effort, "xhigh")]),
+  // Isolation is partial (ADR 0029): project extensions and skills stay
+  // out; pi still reads AGENTS.md from the working directory and its parents.
+  ...(config.isolated ? ["--no-extensions", "--no-skills"] : []),
   ...sortedFlagArgs(config.flags)
 ]
 
@@ -182,7 +188,9 @@ export const makePiConnector = (
     // capability removal, the same mechanism class as claude's `--tools`.
     capabilities: ConnectorCapabilities.make({
       interactiveSessions: true,
-      readOnlyEnforcement: "enforced"
+      readOnlyEnforcement: "enforced",
+      effort: "mapped",
+      isolatedHeadless: "partial"
     }),
     buildArgv: (prompt, _context) => ["pi", "-p", ...extraArgs, prompt],
     buildInteractiveArgv: (_context) => ["pi", ...extraArgs],