clanka 0.0.28 → 0.1.0

package/src/Agent.ts

@@ -3,17 +3,16 @@
  */
 import {
   Array,
-  Deferred,
   Effect,
-  FileSystem,
   identity,
   Layer,
+  MutableRef,
   Option,
-  Path,
   pipe,
   Queue,
   Schema,
   Scope,
+  Semaphore,
   ServiceMap,
   Stream,
 } from "effect"
@@ -24,26 +23,62 @@ import {
   Tool,
   Toolkit,
 } from "effect/unstable/ai"
-import {
-  AgentToolHandlers,
-  AgentTools,
-  CurrentDirectory,
-  SubagentContext,
-  TaskCompleteDeferred,
-} from "./AgentTools.ts"
-import { Executor } from "./Executor.ts"
-import { ToolkitRenderer } from "./ToolkitRenderer.ts"
 import { ModelName, ProviderName } from "effect/unstable/ai/Model"
 import { type StreamPart } from "effect/unstable/ai/Response"
-import type { ChildProcessSpawner } from "effect/unstable/process"
-import type { HttpClient } from "effect/unstable/http"
+import * as AgentExecutor from "./AgentExecutor.ts"
+import type { Path } from "effect/Path"
+import type { ChildProcessSpawner } from "effect/unstable/process/ChildProcessSpawner"
+import type { HttpClient } from "effect/unstable/http/HttpClient"
+import type {
+  CurrentDirectory,
+  SubagentExecutor,
+  TaskCompleter,
+} from "./AgentTools.ts"
+import type { FileSystem } from "effect/FileSystem"
+
+/**
+ * @since 1.0.0
+ * @category Models
+ */
+export type TypeId = "~clanka/Agent"
+
+/**
+ * @since 1.0.0
+ * @category Models
+ */
+export const TypeId: TypeId = "~clanka/Agent"
 
 /**
  * @since 1.0.0
  * @category Models
  */
 export interface Agent {
-  readonly output: Stream.Stream<Output, AgentFinished | AiError.AiError>
+  readonly [TypeId]: TypeId
+
+  /**
+   * Send a prompt to the agent and receive a stream of output.
+   */
+  send(options: {
+    /**
+     * The prompt to send to the agent.
+     */
+    readonly prompt: Prompt.RawInput
+    /**
+     * Provide additional system instructions, or a function that generates
+     * system instructions based on the tool instructions
+     */
+    readonly system?:
+      | string
+      | ((options: {
+          readonly toolInstructions: string
+          readonly agentsMd: string
+        }) => string)
+      | undefined
+  }): Effect.Effect<
+    Stream.Stream<Output, AgentFinished | AiError.AiError>,
+    never,
+    Scope.Scope | LanguageModel.LanguageModel | ProviderName | ModelName
+  >
 
   /**
    * Send a message to the agent to steer its behavior. This is useful for
@@ -57,89 +92,26 @@ export interface Agent {
 }
 
 /**
- * Start an agent in the given directory with the given prompt and tools.
- *
+ * @since 1.0.0
+ * @category Service
+ */
+export const Agent = ServiceMap.Service<Agent>("clanka/Agent")
+
+/**
  * @since 1.0.0
  * @category Constructors
  */
-export const make: <
-  // oxlint-disable-next-line typescript/no-explicit-any
-  Toolkit extends Toolkit.Any = never,
-  SE = never,
-  SR = never,
->(options: {
-  /** The working directory to run the agent in */
-  readonly directory: string
-  /** The prompt to use for the agent */
-  readonly prompt: Prompt.RawInput
-  /**
-   * Provide additional system instructions, or a function that generates
-   * system instructions based on the tool instructions
-   */
-  readonly system?:
-    | string
-    | ((options: {
-        readonly toolInstructions: string
-        readonly agentsMd: string
-      }) => string)
-    | undefined
-  /** Additional tools to provide to the agent */
-  readonly tools?: Toolkit | undefined
-  /** Layer to use for subagents */
-  readonly subagentModel?:
-    | Layer.Layer<
-        LanguageModel.LanguageModel | ProviderName | ModelName,
-        SE,
-        SR
-      >
-    | undefined
-}) => Effect.Effect<
+export const make = Effect.gen(function* (): Effect.fn.Return<
   Agent,
   never,
-  | Scope.Scope
-  | FileSystem.FileSystem
-  | Path.Path
-  | Executor
-  | LanguageModel.LanguageModel
-  | ProviderName
-  | ModelName
-  | ToolkitRenderer
-  | (Toolkit extends Toolkit.Toolkit<infer T>
-      ? Tool.HandlersFor<T> | Tool.HandlerServices<T[keyof T]>
-      : never)
-  | Tool.HandlersFor<typeof AgentTools.tools>
-  | SR
-> = Effect.fnUntraced(function* (options: {
-  readonly directory: string
-  readonly prompt: Prompt.RawInput
-  readonly system?:
-    | string
-    | ((options: { readonly toolInstructions: string }) => string)
-    | undefined
-  readonly tools?: Toolkit.Toolkit<{}> | undefined
-  readonly subagentModel?:
-    | Layer.Layer<LanguageModel.LanguageModel | ProviderName | ModelName>
-    | undefined
-}) {
-  const fs = yield* FileSystem.FileSystem
-  const pathService = yield* Path.Path
-  const executor = yield* Executor
-  const renderer = yield* ToolkitRenderer
-  const generateSystem =
-    typeof options.system === "function" ? options.system : defaultSystem
-
-  const allTools = Toolkit.merge(AgentTools, options.tools ?? Toolkit.empty)
-  const allToolsDts = renderer.render(allTools)
-  const tools = yield* allTools
+  Scope.Scope | AgentExecutor.AgentExecutor
+> {
+  const executor = yield* AgentExecutor.AgentExecutor
+
   const singleTool = yield* SingleTools.asEffect().pipe(
     Effect.provide(SingleToolHandlers),
   )
-  const services = yield* Effect.services<
-    | Tool.HandlerServices<{}>
-    | LanguageModel.LanguageModel
-    | ProviderName
-    | ModelName
-  >()
+  const toolsDts = yield* executor.toolsDts
 
   const pendingMessages = new Set<{
     readonly message: string
@@ -147,9 +119,10 @@ export const make: <
   }>()
 
   const agentsMd = yield* pipe(
-    fs.readFileString(pathService.resolve(options.directory, "AGENTS.md")),
+    executor.agentsMd,
     Effect.map(
-      (content) => `# AGENTS.md
+      Option.map(
+        (content) => `# AGENTS.md
 
 The following instructions are from ./AGENTS.md in the current directory.
 You do not need to read this file again.
@@ -159,8 +132,8 @@ You do not need to read this file again.
 <!-- AGENTS.md start -->
 ${content}
 <!-- AGENTS.md end -->`,
+      ),
     ),
-    Effect.option,
   )
 
   let agentCounter = 0
@@ -168,27 +141,49 @@ ${content}
   const outputBuffer = new Map<number, Array<Output>>()
   let currentOutputAgent: number | null = null
 
-  const spawn: (
-    agentId: number,
-    prompt: Prompt.Prompt,
-  ) => Stream.Stream<
+  let history = MutableRef.make(Prompt.empty)
+
+  const spawn: (opts: {
+    readonly agentId: number
+    readonly prompt: Prompt.Prompt
+    readonly system?:
+      | string
+      | ((options: {
+          readonly toolInstructions: string
+          readonly agentsMd: string
+        }) => string)
+      | undefined
+    readonly disableHistory?: boolean | undefined
+  }) => Stream.Stream<
     Output,
     AgentFinished | AiError.AiError,
-    LanguageModel.LanguageModel | ProviderName
-  > = Effect.fnUntraced(function* (agentId, prompt) {
+    LanguageModel.LanguageModel | ProviderName | ModelName
+  > = Effect.fnUntraced(function* (opts) {
+    const agentId = opts.agentId
     const ai = yield* LanguageModel.LanguageModel
+    const subagentModel = yield* Effect.serviceOption(SubagentModel)
     const modelConfig = yield* AgentModelConfig
+    const services = yield* Effect.services<
+      LanguageModel.LanguageModel | ProviderName | ModelName
+    >()
+    let finalSummary = Option.none<string>()
+
     const singleToolMode = modelConfig.supportsNoTools !== true
-    const deferred = yield* Deferred.make<string>()
     const output = yield* Queue.make<Output, AgentFinished | AiError.AiError>()
+    const prompt = opts.disableHistory ? MutableRef.make(Prompt.empty) : history
+
+    MutableRef.update(prompt, Prompt.concat(opts.prompt))
+
+    const generateSystem =
+      typeof opts.system === "function" ? opts.system : defaultSystem
 
-    const toolInstructions = generateSystemTools(allToolsDts, !singleToolMode)
+    const toolInstructions = generateSystemTools(toolsDts, !singleToolMode)
     let system = generateSystem({
       toolInstructions,
       agentsMd: Option.getOrElse(agentsMd, () => ""),
     })
-    if (typeof options.system === "string") {
-      system += `\n${options.system}\n`
+    if (typeof opts.system === "string") {
+      system += `\n${opts.system}\n`
     }
 
     function maybeSend(options: {
@@ -197,10 +192,10 @@ ${content}
       readonly acquire?: boolean
       readonly release?: boolean
     }) {
-      if (currentOutputAgent === null || currentOutputAgent === agentId) {
+      if (currentOutputAgent === null || currentOutputAgent === opts.agentId) {
         Queue.offerUnsafe(output, options.part)
         if (options.acquire) {
-          currentOutputAgent = agentId
+          currentOutputAgent = opts.agentId
         }
         if (options.release) {
           currentOutputAgent = null
@@ -219,83 +214,88 @@ ${content}
         }
         return
       }
-      let state = outputBuffer.get(agentId)
+      let state = outputBuffer.get(opts.agentId)
       if (!state) {
         state = []
-        outputBuffer.set(agentId, state)
+        outputBuffer.set(opts.agentId, state)
       }
       state.push(options.part)
       return
     }
 
-    const taskServices = SubagentContext.serviceMap({
-      spawn: ({ prompt }) => {
+    const spawnSubagent = Effect.fnUntraced(
+      function* (prompt: string) {
         let id = agentCounter++
-        const stream = spawn(
-          id,
-          Prompt.make(`You have been asked using the "delegate" function to complete the following task. Avoid using the "delegate" function yourself unless strictly necessary:
+        const stream = spawn({
+          agentId: id,
+          prompt:
+            Prompt.make(`You have been asked using the "delegate" function to complete the following task. Try to avoid using the "delegate" function yourself unless strictly necessary:
 
 ${prompt}`),
-        )
-        return Effect.gen(function* () {
-          const provider = yield* ProviderName
-          const model = yield* ModelName
-          maybeSend({
-            agentId,
-            part: new SubagentStart({ id, prompt, model, provider }),
-            release: true,
-          })
-          return yield* stream.pipe(
-            Stream.runForEachArray((parts) => {
-              for (const part of parts) {
-                switch (part._tag) {
-                  case "SubagentStart":
-                  case "SubagentComplete":
-                  case "SubagentPart":
-                    Queue.offerUnsafe(output, part)
-                    break
+          system: opts.system,
+          disableHistory: true,
+        })
+        const provider = yield* ProviderName
+        const model = yield* ModelName
+        maybeSend({
+          agentId: opts.agentId,
+          part: new SubagentStart({ id, prompt, model, provider }),
+          release: true,
+        })
+        return yield* stream.pipe(
+          Stream.runForEachArray((parts) => {
+            for (const part of parts) {
+              switch (part._tag) {
+                case "AgentStart":
+                  break
+                case "SubagentStart":
+                case "SubagentComplete":
+                case "SubagentPart":
+                  Queue.offerUnsafe(output, part)
+                  break
 
-                  default:
-                    Queue.offerUnsafe(output, new SubagentPart({ id, part }))
-                    break
-                }
+                default:
+                  Queue.offerUnsafe(output, new SubagentPart({ id, part }))
+                  break
               }
-              return Effect.void
-            }),
-            Effect.as(""),
-            Effect.catchTag("AgentFinished", (finished) => {
-              Queue.offerUnsafe(
-                output,
-                new SubagentComplete({ id, summary: finished.summary }),
-              )
-              return Effect.succeed(finished.summary)
-            }),
-            Effect.orDie,
-          )
-        }).pipe(
-          options.subagentModel
-            ? Effect.provide(Layer.orDie(options.subagentModel))
-            : Effect.provideServices(services),
+            }
+            return Effect.void
+          }),
+          Effect.as(""),
+          Effect.catchTag("AgentFinished", (finished) => {
+            Queue.offerUnsafe(
+              output,
+              new SubagentComplete({ id, summary: finished.summary }),
+            )
+            return Effect.succeed(finished.summary)
+          }),
+          Effect.orDie,
         )
       },
-    }).pipe(
-      ServiceMap.add(CurrentDirectory, options.directory),
-      ServiceMap.add(TaskCompleteDeferred, deferred),
+      Option.isSome(subagentModel)
+        ? Effect.provideServices(subagentModel.value)
+        : Effect.provideServices(services),
     )
 
     const executeScript = Effect.fnUntraced(function* (script: string) {
       maybeSend({ agentId, part: new ScriptEnd(), release: true })
       const output = yield* pipe(
-        executor.execute({ tools, script }),
+        executor.execute({
+          script,
+          onSubagent: spawnSubagent,
+          onTaskComplete: (summary) =>
+            Effect.sync(() => {
+              finalSummary = Option.some(summary)
+            }),
+        }),
         Stream.mkString,
-        Effect.provideServices(taskServices),
       )
       maybeSend({ agentId, part: new ScriptOutput({ output }) })
       return output
     })
 
     if (!modelConfig.systemPromptTransform) {
-      prompt = Prompt.setSystem(prompt, system)
+      MutableRef.update(prompt, Prompt.setSystem(system))
     }
 
     let currentScript = ""
@@ -303,33 +303,40 @@ ${prompt}`),
       while (true) {
         if (!singleToolMode && currentScript.length > 0) {
           const result = yield* executeScript(currentScript)
-          prompt = Prompt.concat(prompt, [
-            {
-              role: modelConfig.supportsAssistantPrefill ? "assistant" : "user",
-              content: `Javascript output:\n\n${result}`,
-            },
-          ])
+          MutableRef.update(
+            prompt,
+            Prompt.concat([
+              {
+                role: modelConfig.supportsAssistantPrefill
+                  ? "assistant"
+                  : "user",
+                content: `Javascript output:\n\n${result}`,
+              },
+            ]),
+          )
           currentScript = ""
         }
 
-        if (Deferred.isDoneUnsafe(deferred)) {
+        if (Option.isSome(finalSummary)) {
           yield* Queue.fail(
             output,
-            new AgentFinished({ summary: yield* Deferred.await(deferred) }),
+            new AgentFinished({ summary: finalSummary.value }),
           )
           return
         }
 
         if (pendingMessages.size > 0) {
-          prompt = Prompt.concat(
+          MutableRef.update(
             prompt,
-            Array.Array.from(pendingMessages, ({ message, resume }) => {
-              resume(Effect.void)
-              return {
-                role: "user",
-                content: message,
-              }
-            }),
+            Prompt.concat(
+              Array.Array.from(pendingMessages, ({ message, resume }) => {
+                resume(Effect.void)
+                return {
+                  role: "user",
+                  content: message,
+                }
+              }),
+            ),
           )
           pendingMessages.clear()
         }
@@ -340,7 +347,9 @@ ${prompt}`),
         let hadReasoningDelta = false
         yield* pipe(
           ai.streamText(
-            singleToolMode ? { prompt, toolkit: singleTool } : { prompt },
+            singleToolMode
+              ? { prompt: prompt.current, toolkit: singleTool }
+              : { prompt: prompt.current },
           ),
           Stream.takeUntil((part) => {
             if (
@@ -461,35 +470,45 @@ ${prompt}`),
             ? (effect) => modelConfig.systemPromptTransform!(system, effect)
             : identity,
         )
-        prompt = Prompt.concat(prompt, Prompt.fromResponseParts(response))
+        MutableRef.update(
+          prompt,
+          Prompt.concat(Prompt.fromResponseParts(response)),
+        )
         currentScript = currentScript.trim()
       }
     }).pipe(
-      Effect.provideServices(
-        taskServices.pipe(
-          ServiceMap.add(ScriptExecutor, (script) => {
-            maybeSend({ agentId, part: new ScriptStart() })
-            maybeSend({ agentId, part: new ScriptDelta({ delta: script }) })
-            return executeScript(script)
-          }),
-        ),
-      ),
-      Effect.provideServices(services),
+      Effect.provideService(ScriptExecutor, (script) => {
+        maybeSend({ agentId, part: new ScriptStart() })
+        maybeSend({ agentId, part: new ScriptDelta({ delta: script }) })
+        return executeScript(script)
+      }),
       Effect.catchCause((cause) => Queue.failCause(output, cause)),
       Effect.forkScoped,
     )
 
+    yield* Queue.offer(
+      output,
+      new AgentStart({
+        id: opts.agentId,
+        prompt: opts.prompt,
+        provider: yield* ProviderName,
+        model: yield* ModelName,
+      }),
+    )
+
     return Stream.fromQueue(output)
   }, Stream.unwrap)
 
-  const output = yield* spawn(agentCounter++, Prompt.make(options.prompt)).pipe(
-    Stream.broadcast({
-      capacity: "unbounded",
-    }),
-  )
+  const sendLock = Semaphore.makeUnsafe(1)
 
-  return identity<Agent>({
-    output,
+  return Agent.of({
+    [TypeId]: TypeId,
+    send: (options) =>
+      spawn({
+        agentId: agentCounter++,
+        prompt: Prompt.make(options.prompt),
+        system: options.system,
+      }).pipe(Stream.broadcast({ capacity: "unbounded" }), sendLock.withPermit),
     steer: (message) =>
       Effect.callback((resume) => {
         const entry = { message, resume }
@@ -497,8 +516,7 @@ ${prompt}`),
         return Effect.sync(() => pendingMessages.delete(entry))
       }),
   })
-  // oxlint-disable-next-line typescript/no-explicit-any
-}) as any
+})
 
 const defaultSystem = (options: {
   readonly toolInstructions: string
@@ -561,6 +579,7 @@ You have the following functions available to you:
 \`\`\`ts
 ${toolsDts}
 
+/** The global Fetch API available for making HTTP requests. */
 declare const fetch: typeof globalThis.fetch
 \`\`\``
 }
@@ -578,6 +597,7 @@ You have the following functions available to you:
 \`\`\`ts
 ${toolsDts}
 
+// The global Fetch API available for making HTTP requests.
 declare const fetch: typeof globalThis.fetch
 \`\`\``
 }
@@ -604,6 +624,59 @@ const SingleToolHandlers = SingleTools.toLayer({
   }),
 })
 
+/**
+ * @since 1.0.0
+ * @category Layers
+ */
+export const layer: Layer.Layer<Agent, never, AgentExecutor.AgentExecutor> =
+  Layer.effect(Agent, make)
+
+/**
+ * Create an Agent layer that uses a local AgentExecutor.
+ *
+ * @since 1.0.0
+ * @category Layers
+ */
+export const layerLocal = <Toolkit extends Toolkit.Any = never>(options: {
+  readonly directory: string
+  readonly tools?: Toolkit | undefined
+}): Layer.Layer<
+  Agent,
+  never,
+  | FileSystem
+  | Path
+  | ChildProcessSpawner
+  | HttpClient
+  | Exclude<
+      Toolkit extends Toolkit.Toolkit<infer T>
+        ? Tool.HandlersFor<T> | Tool.HandlerServices<T[keyof T]>
+        : never,
+      CurrentDirectory | SubagentExecutor | TaskCompleter
+    >
+> => layer.pipe(Layer.provide(AgentExecutor.layerLocal(options)))
+
+/**
+ * @since 1.0.0
+ * @category Subagent model
+ */
+export class SubagentModel extends ServiceMap.Service<
+  SubagentModel,
+  ServiceMap.ServiceMap<LanguageModel.LanguageModel | ProviderName | ModelName>
+>()("clanka/Agent/SubagentModel") {}
+
+/**
+ * @since 1.0.0
+ * @category Subagent model
+ */
+export const layerSubagentModel = <E, R>(
+  layer: Layer.Layer<
+    LanguageModel.LanguageModel | ProviderName | ModelName,
+    E,
+    R
+  >,
+): Layer.Layer<SubagentModel, E, R> =>
+  Layer.effect(SubagentModel, Layer.build(layer))
+
 /**
  * @since 1.0.0
  * @category System prompts
@@ -623,19 +696,19 @@ export class AgentModelConfig extends ServiceMap.Reference<{
 }
 
 /**
- * A layer that provides most of the common services needed to run an agent.
- *
  * @since 1.0.0
- * @category Services
+ * @category Output
  */
-export const layerServices: Layer.Layer<
-  Tool.HandlersFor<typeof AgentTools.tools> | Executor | ToolkitRenderer,
-  never,
-  | FileSystem.FileSystem
-  | Path.Path
-  | ChildProcessSpawner.ChildProcessSpawner
-  | HttpClient.HttpClient
-> = Layer.mergeAll(AgentToolHandlers, Executor.layer, ToolkitRenderer.layer)
+export class AgentStart extends Schema.TaggedClass<AgentStart>()("AgentStart", {
+  id: Schema.Number,
+  prompt: Prompt.Prompt,
+  provider: Schema.String,
+  model: Schema.String,
+}) {
+  get modelAndProvider() {
+    return `${this.provider}/${this.model}`
+  }
+}
 
 /**
  * @since 1.0.0
@@ -706,17 +779,6 @@ export class ScriptOutput extends Schema.TaggedClass<ScriptOutput>()(
   },
 ) {}
 
-/**
- * @since 1.0.0
- * @category Output
- */
-export class AgentFinished extends Schema.TaggedErrorClass<AgentFinished>()(
-  "AgentFinished",
-  {
-    summary: Schema.String,
-  },
-) {}
-
 /**
  * @since 1.0.0
  * @category Output
@@ -783,6 +845,7 @@ export class SubagentPart extends Schema.TaggedClass<SubagentPart>()(
  * @category Output
  */
 export type Output =
+  | AgentStart
   | ContentPart
   | SubagentStart
   | SubagentComplete
@@ -793,6 +856,7 @@ export type Output =
  * @category Output
  */
 export const Output = Schema.Union([
+  AgentStart,
   ReasoningStart,
   ReasoningDelta,
   ReasoningEnd,
@@ -804,3 +868,14 @@ export const Output = Schema.Union([
   SubagentComplete,
   SubagentPart,
 ])
+
+/**
+ * @since 1.0.0
+ * @category Output
+ */
+export class AgentFinished extends Schema.TaggedErrorClass<AgentFinished>()(
+  "AgentFinished",
+  {
+    summary: Schema.String,
+  },
+) {}