refactor(ai): name provider turn operations

Co-authored-by: Aiden Cline <rekram1-node@users.noreply.github.com>

packages/ai/AGENTS.md

@@ -10,7 +10,7 @@
 
 ## Conventions
 
-Per-type constructors live on the type, not as top-level re-exports. Use `Message.system(...)`, `Message.user(...)`, `Message.assistant(...)`, `Message.tool(...)`, `Model.make(...)`, `ToolDefinition.make(...)`, `ToolCallPart.make(...)`, `ToolResultPart.make(...)`, `ToolChoice.make(...)`, `ToolChoice.named(...)`, `SystemPart.make(...)`, and `GenerationOptions.make(...)` directly. The top-level `LLM` namespace is reserved for request-shaped call APIs: `LLM.request`, `LLM.generate`, `LLM.stream`, `LLM.updateRequest`, and `LLM.generateObject`. Two ways to construct the same thing is one too many.
+Per-type constructors live on the type, not as top-level re-exports. Use `Message.system(...)`, `Message.user(...)`, `Message.assistant(...)`, `Message.tool(...)`, `Model.make(...)`, `ToolDefinition.make(...)`, `ToolCallPart.make(...)`, `ToolResultPart.make(...)`, `ToolChoice.make(...)`, `ToolChoice.named(...)`, `SystemPart.make(...)`, and `GenerationOptions.make(...)` directly. The top-level `LLM` namespace is reserved for request-shaped call APIs: `LLM.request`, `LLM.generateTurn`, `LLM.streamTurn`, and `LLM.generateObject`. Two ways to construct the same thing is one too many.
 
 ## Tests
 
@@ -223,7 +223,7 @@ Routes lower these into provider-native assistant tool-call messages and tool-re
 
 ### Tool dispatch
 
-`LLM.stream(request)` and `LLM.generate(request)` each run exactly one provider turn. Add tool schemas to `request.tools` with `Tool.toDefinitions(tools)`. When a caller wants the package's typed one-call execution behavior, pass each canonical local `tool-call` event to `ToolRuntime.dispatch(tools, call)`.
+`LLM.streamTurn(request)` and `LLM.generateTurn(request)` each run exactly one provider turn. Add tool schemas to `request.tools` with `Tool.toDefinitions(tools)`. When a caller wants the package's typed one-call execution behavior, pass each canonical local `tool-call` event to `ToolRuntime.dispatch(tools, call)`.
 
 ```ts
 const get_weather = tool({
@@ -240,7 +240,7 @@ const get_weather = tool({
 })
 
 const tools = { get_weather, get_time, ... }
-const events = yield* LLM.stream(
+const events = yield* LLM.streamTurn(
   LLMRequest.update(request, { tools: Tool.toDefinitions(tools) }),
 ).pipe(Stream.runCollect)
 

packages/ai/DESIGN.md

@@ -175,8 +175,8 @@ const request = LLM.request({
   prompt: "Say hello.",
 })
 
-// Current API: this performs one provider turn, despite the broad name.
-const response = yield * LLM.generate(request)
+// Current API: this performs one provider turn.
+const response = yield * LLM.generateTurn(request)
 
 // Current API: execution also needs LLMClient.layer and RequestExecutor services.
 ```
@@ -432,7 +432,7 @@ const request = LLM.request({
   tools: Tool.toDefinitions(tools),
 })
 
-const events = yield * LLM.stream(request).pipe(Stream.runCollect)
+const events = yield * LLM.streamTurn(request).pipe(Stream.runCollect)
 const call = Array.from(events).find(LLMEvent.is.toolCall)
 
 if (call && !call.providerExecuted) {
@@ -1076,7 +1076,7 @@ The redesign intentionally removes or changes these current concepts:
 | Current                                 | Proposed                                                    |
 | --------------------------------------- | ----------------------------------------------------------- |
 | Mandatory `LLM.request({ model, ... })` | Inline calls or model-free portable requests                |
-| `LLM.generate` means one turn           | `LLM.generate` means complete run                           |
+| No complete-run API                     | Add `LLM.generate` / `LLM.stream`                           |
 | `LLMClient.generate/stream`             | `LLM.generateTurn/streamTurn` for one turn                  |
 | `LLMClient.layer` requirement           | Standard Effect requirements exposed directly               |
 | Public `Route` mental model             | Hidden behind executable `Model`                            |

packages/ai/README.md

@@ -176,7 +176,7 @@ Conversational image generation remains part of the LLM interaction. OpenAI Resp
 
 ```ts
 const program = Effect.gen(function* () {
-  const response = yield* LLM.generate(
+  const response = yield* LLM.generateTurn(
     LLM.request({
       model: OpenAI.configure({ apiKey }).responses("gpt-5"),
       prompt: "Design a solarpunk rooftop garden, then show me.",
@@ -193,7 +193,7 @@ The hosted result is represented as a provider-executed tool call and tool resul
 ## Public API
 
 - **`LLM.request({...})`** — build a provider-neutral `LLMRequest`. Accepts ergonomic inputs (`system: string`, `prompt: string`) that normalize into the canonical Schema classes.
-- **`LLM.generate` / `LLM.stream`** — re-exported from `LLMClient` for one-import use.
+- **`LLM.generateTurn` / `LLM.streamTurn`** — execute exactly one provider turn, re-exported from `LLMClient` for one-import use.
 - **`Message.user(...)` / `Message.assistant(...)` / `Message.tool(...)`** — message constructors from the canonical schema model.
 - **`Model.make(...)` / `ToolCallPart.make(...)` / `ToolResultPart.make(...)` / `ToolDefinition.make(...)`** — model and tool-related constructors from the canonical schema model.
 - **`LLMClient.prepare(request)`** — compile a request through protocol body construction, validation, and HTTP preparation without sending. Useful for inspection and testing.

packages/ai/example/call-sites.md

@@ -334,7 +334,7 @@ Final request call site stays boring:
 ```ts
 const response =
   yield *
-  LLM.generate(
+  LLM.generateTurn(
     LLM.request({
       model: DeepSeek.model("deepseek-chat"),
       prompt: "Hello.",

packages/ai/example/tutorial.ts

@@ -65,7 +65,7 @@ const rawOverlayExample = LLM.request({
 // 3. `generate` sends the request and collects the event stream into one
 // response object. `response.text` is the collected text output.
 const generateOnce = Effect.gen(function* () {
-  const response = yield* LLM.generate(request)
+  const response = yield* LLM.generateTurn(request)
 
   console.log("\n== generate ==")
   console.log("generated text:", response.text)
@@ -74,7 +74,7 @@ const generateOnce = Effect.gen(function* () {
 
 // 4. `stream` exposes provider output as common `LLMEvent`s for UIs that want
 // incremental text, reasoning, tool input, usage, or finish events.
-const streamText = LLM.stream(request).pipe(
+const streamText = LLM.streamTurn(request).pipe(
   Stream.tap((event) =>
     Effect.sync(() => {
       if (event.type === "text-delta") process.stdout.write(`\ntext: ${event.text}`)
@@ -106,7 +106,7 @@ const streamWithTools = Effect.gen(function* () {
     generation: { maxTokens: 80, temperature: 0 },
     tools: Tool.toDefinitions(tools),
   })
-  const events = Array.from(yield* LLM.stream(request).pipe(Stream.runCollect))
+  const events = Array.from(yield* LLM.streamTurn(request).pipe(Stream.runCollect))
   for (const event of events) {
     if (event.type === "tool-call") console.log("tool call", event.name, event.input)
     if (event.type === "text-delta") process.stdout.write(event.text)

packages/ai/src/llm.ts

@@ -31,9 +31,9 @@ export type RequestInput = Omit<
   readonly http?: HttpOptions.Input
 }
 
-export const generate = LLMClient.generate
+export const generateTurn = LLMClient.generate
 
-export const stream = LLMClient.stream
+export const streamTurn = LLMClient.stream
 
 export const request = (input: RequestInput) => {
   const {

packages/ai/src/route/client.ts

@@ -412,7 +412,7 @@ const streamRequestWith = (runtime: TransportRuntime) => (request: LLMRequest) =
   )
 
 const generateWith = (stream: Interface["stream"]) =>
-  Effect.fn("LLM.generate")(function* (request: LLMRequest) {
+  Effect.fn("LLM.generateTurn")(function* (request: LLMRequest) {
     const state = yield* stream(request).pipe(Stream.runFold(LLMResponse.empty, LLMResponse.reduce))
     const response = LLMResponse.complete(state)
     if (response) return response

packages/ai/test/exports.test.ts

@@ -23,6 +23,10 @@ import * as AnthropicMessages from "@opencode-ai/ai/protocols/anthropic-messages
 describe("public exports", () => {
   test("root exposes app-facing runtime APIs", () => {
     expect(LLM.request).toBeFunction()
+    expect(LLM.generateTurn).toBeFunction()
+    expect(LLM.streamTurn).toBeFunction()
+    expect(LLM).not.toHaveProperty("generate")
+    expect(LLM).not.toHaveProperty("stream")
     expect(LLMClient.Service).toBeFunction()
     expect(LLMClient.layer).toBeDefined()
     expect(ImageInput.bytes).toBeFunction()

packages/ai/test/provider/cloudflare.test.ts

@@ -47,7 +47,7 @@ describe("Cloudflare", () => {
 
   it.effect("posts to the derived gateway endpoint with bearer auth", () =>
     Effect.gen(function* () {
-      const response = yield* LLM.generate(
+      const response = yield* LLM.generateTurn(
         LLM.request({
           model: CloudflareAIGateway.configure({
             accountId: "test-account",
@@ -104,7 +104,7 @@ describe("Cloudflare", () => {
           index: 0,
         },
       ]
-      const response = yield* LLM.generate(LLM.request({ model, prompt: "Say hello." })).pipe(
+      const response = yield* LLM.generateTurn(LLM.request({ model, prompt: "Say hello." })).pipe(
         Effect.provide(
           dynamicResponse((input) =>
             Effect.succeed(
@@ -150,7 +150,7 @@ describe("Cloudflare", () => {
 
   it.effect("supports authenticated AI Gateway plus upstream provider auth", () =>
     Effect.gen(function* () {
-      yield* LLM.generate(
+      yield* LLM.generateTurn(
         LLM.request({
           model: CloudflareAIGateway.configure({
             accountId: "test-account",
@@ -221,7 +221,7 @@ describe("Cloudflare", () => {
 
   it.effect("posts direct Workers AI requests to the account endpoint with bearer auth", () =>
     Effect.gen(function* () {
-      const response = yield* LLM.generate(
+      const response = yield* LLM.generateTurn(
         LLM.request({
           model: CloudflareWorkersAI.configure({
             accountId: "test-account",
@@ -256,7 +256,7 @@ describe("Cloudflare", () => {
 
   it.effect("supports direct Workers AI token aliases through auth config", () =>
     Effect.gen(function* () {
-      yield* LLM.generate(
+      yield* LLM.generateTurn(
         LLM.request({
           model: CloudflareWorkersAI.configure({
             accountId: "test-account",

packages/ai/test/provider/openai-responses-images.recorded.test.ts

@@ -29,7 +29,7 @@ describe("OpenAI Responses image generation recorded", () => {
           partialImages: 0,
         }),
       ]
-      const response = yield* LLM.generate(
+      const response = yield* LLM.generateTurn(
         LLM.request({
           model: openai.responses("gpt-5-mini"),
           messages: [initial],
@@ -49,7 +49,7 @@ describe("OpenAI Responses image generation recorded", () => {
       expect(result.result.value[0].mime).toBe("image/jpeg")
       expect(result.result.value[0].uri.startsWith("data:image/jpeg;base64,")).toBe(true)
 
-      const edited = yield* LLM.generate(
+      const edited = yield* LLM.generateTurn(
         LLM.request({
           model: openai.responses("gpt-5-mini"),
           messages: [initial, response.message, Message.user("Now make the triangle blue.")],

packages/ai/test/tool.types.ts

@@ -32,9 +32,9 @@ Tool.make({
   ],
 })
 
-LLM.stream(request)
-LLM.generate(LLMRequest.update(request, { tools: toDefinitions({ schemaOnly }) }))
+LLM.streamTurn(request)
+LLM.generateTurn(LLMRequest.update(request, { tools: toDefinitions({ schemaOnly }) }))
 ToolRuntime.dispatch({ executable }, { type: "tool-call", id: "call_1", name: "executable", input: { city: "Paris" } })
 
 // @ts-expect-error High-level tool orchestration overloads are intentionally not supported.
-LLM.stream({ request, tools: { schemaOnly } })
+LLM.streamTurn({ request, tools: { schemaOnly } })

packages/core/src/session/execution/restart.ts

@@ -40,8 +40,7 @@ export const layer = Layer.effect(
               // Drain failures are already logged and durably recorded by the execution layer.
               yield* Effect.ignore(execution.resume(sessionID))
             }),
-          // Each suspension is consumed atomically right before its drain; at most four drains run at once.
-          { concurrency: 4, discard: true },
+          { concurrency: "unbounded", discard: true },
         )
       }),
     })

packages/core/src/session/runner/llm.ts

@@ -1,6 +1,6 @@
 export * as SessionRunnerLLM from "./llm"
 
-import { LLMClient, LLMError, LLMEvent, isContextOverflowFailure, type ProviderErrorEvent } from "@opencode-ai/ai"
+import { LLMClient, LLMError, LLMEvent, isContextOverflowFailure, type ProviderErrorEvent, type ToolCall } from "@opencode-ai/ai"
 import { Cause, Data, Effect, Exit, Fiber, FiberSet, Layer, Option, Pull, Schedule, Semaphore, Stream } from "effect"
 import { Database } from "../../database/database"
 import { EventV2 } from "../../event"
@@ -203,8 +203,9 @@ const layer = Layer.effect(
         context: loaded,
         step: currentStep,
       })
-      const toolFibers = yield* FiberSet.make<void, ToolOutputStore.Error>()
-      const ownedToolFibers: Array<Fiber.Fiber<void, ToolOutputStore.Error>> = []
+      // Every local tool call forked here is owned until it reaches one durable settlement.
+      const toolRuns: Array<{ readonly call: ToolCall; readonly fiber: Fiber.Fiber<void, ToolOutputStore.Error> }> = []
+      const interruptTools = Effect.suspend(() => Fiber.interruptAll(toolRuns.map((run) => run.fiber)))
       let needsContinuation = false
       const startSnapshot = yield* snapshots.capture()
       const publisher = createLLMEventPublisher(events, {
@@ -277,8 +278,9 @@ const layer = Layer.effect(
             // continuation depends only on remaining Step allowance.
             if (!prepared.stepLimitReached) needsContinuation = true
             const assistantMessageID = yield* publisher.assistantMessageID(event.id)
-            ownedToolFibers.push(
-              yield* Effect.uninterruptibleMask((restore) =>
+            toolRuns.push({
+              call: event,
+              fiber: yield* Effect.uninterruptibleMask((restore) =>
                 restore(
                   prepared.executeTool({
                     sessionID: session.id,
@@ -290,8 +292,8 @@ const layer = Layer.effect(
                 ).pipe(
                   Effect.flatMap((execution) => serialized(publisher.toolExecution(event.id, event.name, execution))),
                 ),
-              ).pipe(FiberSet.run(toolFibers)),
-            )
+              ).pipe(Effect.forkScoped),
+            })
           }),
         ),
         Effect.ensuring(serialized(publisher.flush())),
@@ -339,13 +341,13 @@ const layer = Layer.effect(
           // Provider error events only arrive from the stream, so the flag is final here.
           const providerFailed = publisher.hasProviderError()
 
-          // Settle every owned tool fiber. FiberSet.join returns on the first failure, so retain
-          // the individual fibers and await all exits before publishing the terminal step event.
-          if (streamInterrupted) yield* FiberSet.clear(toolFibers)
+          // Settle every owned tool run: await all exits, not just the first failure,
+          // before publishing the terminal step event.
+          if (streamInterrupted) yield* interruptTools
           const settled = yield* restore(
-            Effect.forEach(ownedToolFibers, Fiber.await, { concurrency: "unbounded" }),
+            Effect.forEach(toolRuns, (run) => Fiber.await(run.fiber), { concurrency: "unbounded" }),
           ).pipe(Effect.exit)
-          if (settled._tag === "Failure") yield* FiberSet.clear(toolFibers)
+          if (settled._tag === "Failure") yield* interruptTools
           const tools = classifyToolExits(settled)
 
           if (tools.declined || streamInterrupted || tools.interrupted) {
@@ -362,32 +364,17 @@ const layer = Layer.effect(
           // these sweeps only close calls that could not produce a truthful settlement.
           if (providerFailed)
             yield* serialized(publisher.failUnsettledTools({ type: "aborted", message: "Tool execution interrupted" }))
-          if (llmFailure && !providerFailed)
-            yield* serialized(
-              publisher.failUnsettledTools(
-                {
-                  type: "tool.result-missing",
-                  message: "Provider did not return a tool result",
-                },
-                true,
-              ),
-            )
-          const hostedResultMissing =
-            stream._tag === "Success" && !providerFailed
-              ? yield* serialized(
-                  publisher.failUnsettledTools(
-                    { type: "tool.result-missing", message: "Provider did not return a tool result" },
-                    true,
-                  ),
-                )
-              : false
-          if (hostedResultMissing && !publisher.stepSettlement())
-            yield* serialized(
-              publisher.failAssistant({
-                type: "tool.result-missing",
-                message: "Provider did not return a tool result",
-              }),
-            )
+          const resultMissing = {
+            type: "tool.result-missing",
+            message: "Provider did not return a tool result",
+          } as const
+          if (llmFailure && !providerFailed) yield* serialized(publisher.failUnsettledTools(resultMissing, "hosted"))
+          // A clean stream that still left hosted calls unresolved fails the step itself.
+          if (stream._tag === "Success" && !providerFailed) {
+            const hostedResultMissing = yield* serialized(publisher.failUnsettledTools(resultMissing, "hosted"))
+            if (hostedResultMissing && !publisher.stepSettlement())
+              yield* serialized(publisher.failAssistant(resultMissing))
+          }
 
           const stepFailure = publisher.stepFailure()
           const stepSettlement = publisher.stepSettlement()

packages/core/src/session/runner/publish-llm-event.ts

@@ -277,9 +277,9 @@ export const createLLMEventPublisher = (events: Pick<EventV2.Interface, "publish
 
   const failUnsettledTools = Effect.fn("SessionRunner.failUnsettledTools")(function* (
     error: SessionError.Error,
-    hostedOnly = false,
+    scope: "hosted" | "all" = "all",
   ) {
-    return yield* failTools(error, hostedOnly ? "hosted" : "all")
+    return yield* failTools(error, scope)
   })
 
   const assistantMessageIDForTool = (callID: string) => {

packages/core/test/npm.test.ts

@@ -64,29 +64,3 @@ describe("Npm.add", () => {
     expect(entries.fallback.entrypoint).toEndWith("/index.js")
   })
 })
-
-describe("Npm.install", () => {
-  test("respects omit from project .npmrc", async () => {
-    await using tmp = await tmpdir()
-
-    await writePackage(tmp.path, {
-      name: "fixture",
-      dependencies: {
-        "prod-pkg": "file:./prod-pkg",
-      },
-      devDependencies: {
-        "dev-pkg": "file:./dev-pkg",
-      },
-    })
-    await Bun.write(path.join(tmp.path, ".npmrc"), "omit=dev\n")
-    await fs.mkdir(path.join(tmp.path, "prod-pkg"))
-    await fs.mkdir(path.join(tmp.path, "dev-pkg"))
-    await writePackage(path.join(tmp.path, "prod-pkg"), { name: "prod-pkg" })
-    await writePackage(path.join(tmp.path, "dev-pkg"), { name: "dev-pkg" })
-
-    await Npm.install(tmp.path)
-
-    await expect(fs.stat(path.join(tmp.path, "node_modules", "prod-pkg"))).resolves.toBeDefined()
-    await expect(fs.stat(path.join(tmp.path, "node_modules", "dev-pkg"))).rejects.toThrow()
-  })
-})

packages/core/test/session-execution.test.ts

@@ -105,6 +105,31 @@ describe("SessionExecution lifecycle", () => {
     }),
   )
 
+  it.effect("starts every suspended execution without waiting for earlier drains to finish", () =>
+    Effect.gen(function* () {
+      const database = yield* Database.Service
+      const sessionIDs = Array.from({ length: 5 }, (_, index) => SessionV2.ID.make(`ses_resume_concurrent_${index}`))
+      yield* seedSessions(database, sessionIDs, { time_suspended: Date.now() })
+
+      const fourStarted = yield* Deferred.make<void>()
+      const started: SessionV2.ID[] = []
+      const scope = yield* Scope.make()
+      yield* Effect.addFinalizer(() => Scope.close(scope, Exit.void))
+      const context = yield* buildExecution(scope, ({ sessionID }) =>
+        Effect.sync(() => {
+          started.push(sessionID)
+          if (started.length === 4) Deferred.doneUnsafe(fourStarted, Effect.void)
+        }).pipe(Effect.andThen(Effect.never)),
+      )
+      const execution = Context.get(context, SessionExecution.Service)
+      const restart = Context.get(context, SessionRestart.Service)
+      yield* restart.resumeSuspendedSessions.pipe(Effect.forkIn(scope))
+      yield* Deferred.await(fourStarted)
+
+      expect([...(yield* execution.active)].toSorted()).toEqual(sessionIDs.toSorted())
+    }),
+  )
+
   it.effect("resumes each suspended Session at most once", () =>
     Effect.gen(function* () {
       const database = yield* Database.Service
@@ -115,9 +140,11 @@ describe("SessionExecution lifecycle", () => {
       const drained: string[] = []
       const scope = yield* Scope.make()
       const context = yield* buildExecution(scope, ({ sessionID }) => Effect.sync(() => void drained.push(sessionID)))
+      const execution = Context.get(context, SessionExecution.Service)
       const restart = Context.get(context, SessionRestart.Service)
 
       yield* restart.resumeSuspendedSessions
+      yield* Effect.forEach([first, second], execution.awaitIdle, { discard: true })
       expect(drained.toSorted()).toEqual([first, second])
       expect(yield* suspensions(database)).toEqual({ [first]: false, [second]: false })