clanka 0.3.1 → 0.5.0

package/src/Agent.ts

@@ -4,12 +4,14 @@
 import * as Model from "effect/unstable/ai/Model"
 import type * as Response from "effect/unstable/ai/Response"
 import * as AgentExecutor from "./AgentExecutor.ts"
+import * as AgentSkills from "./AgentSkills.ts"
 import { stripWrappingCodeFence } from "./ScriptExtraction.ts"
 import type * as Path from "effect/Path"
 import type * as ChildProcessSpawner from "effect/unstable/process/ChildProcessSpawner"
 import type * as HttpClient from "effect/unstable/http/HttpClient"
 import type {
   CurrentDirectory,
+  DirectoryChanger,
   SubagentExecutor,
   TaskCompleter,
 } from "./AgentTools.ts"
@@ -36,6 +38,8 @@ import * as Duration from "effect/Duration"
 import * as Cause from "effect/Cause"
 import * as Latch from "effect/Latch"
 import * as Clock from "effect/Clock"
+import * as Exit from "effect/Exit"
+import * as Compaction from "./Compaction.ts"
 import {
   ScriptEnd,
   ScriptOutput,
@@ -52,6 +56,9 @@ import {
   ScriptStart,
   ScriptDelta,
   AgentStart,
+  ExecuteOutputCapped,
+  CompactionStarted,
+  CompactionEnded,
 } from "./AgentOutput.ts"
 
 /**
@@ -187,6 +194,9 @@ ${content}
     const conversationMode = yield* ConversationMode
     const turnTimeout = yield* TurnTimeout
     let finalSummary = Option.none<string>()
+    // `inputTokens.total` from the most recent finish part; undefined until
+    // the first response and after every compaction.
+    let lastContextTokens: number | undefined = undefined
 
     const output = yield* Queue.make<Output, AgentFinished | AiError.AiError>()
     let inputTokens = 0
@@ -319,6 +329,50 @@ ${content}
       }
     })
 
+    // Compaction. `compactWithEvents` applies a successful rewrite and closes
+    // the progress event on every exit: success, failure, timeout, interrupt.
+    let compactionStarted = false
+    const onCompactionStart = (reason: Compaction.CompactionReason) =>
+      Effect.sync(() => {
+        compactionStarted = true
+        maybeSend({ agentId, part: new CompactionStarted({ reason }) })
+      })
+    const compactWithEvents = <E, R>(
+      reason: Compaction.CompactionReason,
+      compaction: Effect.Effect<
+        Option.Option<Compaction.CompactionResult>,
+        E,
+        R
+      >,
+    ) =>
+      Effect.suspend(() => {
+        compactionStarted = false
+        return compaction
+      }).pipe(
+        Effect.onExit((exit) =>
+          Effect.sync(() => {
+            if (!compactionStarted) return
+            const result = Exit.isSuccess(exit) ? exit.value : Option.none()
+            let tokensBefore: number
+            let tokensAfter: number
+            if (Option.isSome(result)) {
+              MutableRef.set(prompt, result.value.prompt)
+              lastContextTokens = undefined
+              tokensBefore = result.value.tokensBefore
+              tokensAfter = result.value.tokensAfter
+            } else {
+              tokensBefore = tokensAfter = Compaction.estimateTokens(
+                prompt.current,
+              )
+            }
+            maybeSend({
+              agentId,
+              part: new CompactionEnded({ reason, tokensBefore, tokensAfter }),
+            })
+          }),
+        ),
+      )
+
     // Script execution
     const executeScript = Effect.fnUntraced(function* (script: string) {
       yield* toolLatchAcquire
@@ -335,8 +389,20 @@ ${content}
         }),
         Stream.mkString,
       )
+      // Always-on cap on what enters the Prompt. The ScriptOutput event keeps
+      // the full output for display; the formatter applies its own truncation.
+      const capped = Compaction.capOutput(output)
+      if (capped.capped) {
+        maybeSend({
+          agentId,
+          part: new ExecuteOutputCapped({
+            charsBefore: capped.charsBefore,
+            charsAfter: capped.charsAfter,
+          }),
+        })
+      }
       maybeSend({ agentId, part: new ScriptOutput({ output }) })
-      return output
+      return capped.output
     }, Effect.ensuring(toolLatchRelease))
 
     if (!modelConfig.systemPromptTransform) {
@@ -369,12 +435,29 @@ ${content}
           pendingMessages.clear()
         }
 
+        // Threshold compaction before the next model call
+        yield* compactWithEvents(
+          "threshold",
+          Compaction.compactIfNeeded({
+            prompt: prompt.current,
+            contextTokens: lastContextTokens,
+            onStart: onCompactionStart,
+          }).pipe(Effect.timeout(turnTimeout)),
+        ).pipe(
+          Effect.catchTag("TimeoutError", (error) =>
+            Effect.logWarning(
+              "Compaction timed out, continuing with the uncompacted prompt",
+              error,
+            ),
+          ),
+        )
+
         // oxlint-disable-next-line typescript/no-explicit-any
         let response = Array.empty<Response.StreamPart<any>>()
         let reasoningStarted = false
         let hadReasoningDelta = false
         let hadToolCall = false
-        yield* pipe(
+        const runModel = pipe(
           Stream.suspend(() =>
             ai.streamText({ prompt: prompt.current, toolkit: singleTool }),
           ),
@@ -431,6 +514,7 @@ ${content}
                     outputTokens += usage.outputTokens.total
                   }
                   if (usage.inputTokens.total !== undefined) {
+                    lastContextTokens = usage.inputTokens.total
                     inputTokens += usage.inputTokens.total
                     maybeSend({
                       agentId,
@@ -449,6 +533,12 @@ ${content}
             }
             return Effect.void
           }),
+          modelConfig.systemPromptTransform
+            ? (effect) => modelConfig.systemPromptTransform!(system, effect)
+            : identity,
+        )
+        const attempt = pipe(
+          runModel,
           Effect.raceFirst(turnTimeoutEffect),
           Effect.retry({
             while: (err) => {
@@ -468,6 +558,9 @@ ${content}
                 response = []
                 return true
               }
+              // Never retry a context-length error as is: the overflow
+              // handler below compacts first.
+              if (Compaction.isContextLengthError(err)) return false
               if (err.isRetryable) {
                 maybeSend({ agentId, part: new ErrorRetry({ error: err }) })
                 switch (err.reason._tag) {
@@ -488,9 +581,33 @@ ${content}
             schedule: retryPolicy,
           }),
           Effect.catchTag("TimeoutError", Effect.die),
-          modelConfig.systemPromptTransform
-            ? (effect) => modelConfig.systemPromptTransform!(system, effect)
-            : identity,
+        )
+        // Overflow: compact once, retry the attempt once, then fail.
+        yield* attempt.pipe(
+          Effect.catchIf(
+            (err): err is AiError.AiError =>
+              Compaction.isContextLengthError(err),
+            (err) =>
+              Effect.gen(function* () {
+                response = []
+                const compacted = yield* compactWithEvents(
+                  "overflow",
+                  Compaction.compact({
+                    prompt: prompt.current,
+                    reason: "overflow",
+                    onStart: onCompactionStart,
+                  }).pipe(
+                    Effect.timeout(turnTimeout),
+                    Effect.retry({
+                      while: (error) => error._tag === "TimeoutError",
+                      times: 1,
+                    }),
+                    Effect.catchTag("TimeoutError", Effect.die),
+                  ),
+                )
+                return Option.isSome(compacted) ? yield* attempt : yield* err
+              }),
+          ),
         )
         MutableRef.update(
           prompt,
@@ -620,7 +737,12 @@ ${capabilities.toolsDts}
 
 /** The global Fetch API available for making HTTP requests. */
 declare const fetch: typeof globalThis.fetch
-\`\`\``
+\`\`\`${Option.match(AgentSkills.renderCatalog(capabilities.skills), {
+  onNone: () => "",
+  onSome: (catalog) => `
+
+${catalog}`,
+})}`
 
 class ScriptExecutor extends Context.Service<
   ScriptExecutor,
@@ -671,7 +793,7 @@ export const layerLocal = <Toolkit extends Toolkit.Any = never>(options: {
       Toolkit extends Toolkit.Toolkit<infer T>
         ? Tool.HandlersFor<T> | Tool.HandlerServices<T[keyof T]>
         : never,
-      CurrentDirectory | SubagentExecutor | TaskCompleter
+      CurrentDirectory | DirectoryChanger | SubagentExecutor | TaskCompleter
     >
 > => layer.pipe(Layer.provide(AgentExecutor.layerLocal(options)))
 

package/src/AgentExecutor.ts

@@ -2,6 +2,7 @@
  * @since 1.0.0
  */
 import * as NodeConsole from "node:console"
+import * as NodeOs from "node:os"
 import * as NodeVm from "node:vm"
 import { Writable } from "node:stream"
 import {
@@ -9,10 +10,12 @@ import {
   AgentTools,
   AgentToolsWithSearch,
   CurrentDirectory,
+  DirectoryChanger,
   SubagentExecutor,
   TaskCompleter,
 } from "./AgentTools.ts"
 import { ToolkitRenderer } from "./ToolkitRenderer.ts"
+import * as AgentSkills from "./AgentSkills.ts"
 import type * as ChildProcessSpawner from "effect/unstable/process/ChildProcessSpawner"
 import type * as HttpClient from "effect/unstable/http/HttpClient"
 import * as Context from "effect/Context"
@@ -69,6 +72,13 @@ export class Capabilities extends Schema.Class<Capabilities>("Capabilities")({
   toolsDts: Schema.String,
   agentsMd: Schema.Option(Schema.String),
   supportsSearch: Schema.Boolean,
+  /**
+   * Skills available on the executor filesystem.
+   */
+  skills: Schema.Array(AgentSkills.Skill).pipe(
+    Schema.withDecodingDefaultKey(Effect.succeed([])),
+    Schema.withConstructorDefault(Effect.succeed([])),
+  ),
 }) {}
 
 /**
@@ -91,12 +101,22 @@ export const makeLocal = Effect.fnUntraced(function* <
       Toolkit extends Toolkit.Toolkit<infer T>
         ? Tool.HandlersFor<T> | Tool.HandlerServices<T[keyof T]>
         : never,
-      CurrentDirectory | SubagentExecutor | TaskCompleter
+      CurrentDirectory | DirectoryChanger | SubagentExecutor | TaskCompleter
     >
 > {
   const fs = yield* FileSystem.FileSystem
   const pathService = yield* Path.Path
   const renderer = yield* ToolkitRenderer
+  let currentDirectory = pathService.resolve(options.directory)
+  const changeDirectory = Effect.fnUntraced(function* (directory: string) {
+    const target = pathService.resolve(currentDirectory, directory)
+    const info = yield* fs.stat(target)
+    if (info.type !== "Directory") {
+      return yield* Effect.die(new Error(`Not a directory: ${target}`))
+    }
+    currentDirectory = target
+    return target
+  }, Effect.orDie)
   const search = yield* Effect.serviceOption(SemanticSearch)
   const hasSearch = Option.isSome(search)
   const AllTools = Toolkit.merge(
@@ -133,7 +153,7 @@ export const makeLocal = Effect.fnUntraced(function* <
 
     const taskServices = Context.empty().pipe(
       Context.add(TaskCompleter, opts.onTaskComplete),
-      Context.add(CurrentDirectory, options.directory),
+      Context.add(DirectoryChanger, changeDirectory),
       Context.add(SubagentExecutor, opts.onSubagent),
       Context.add(Console.Console, console),
       Context.add(References.CurrentLogAnnotations, {}),
@@ -156,12 +176,13 @@ export const makeLocal = Effect.fnUntraced(function* <
 
       for (let i = 0; i < toolEntries.length; i++) {
         const { name, handler, services } = toolEntries[i]!
-        const runFork = Effect.runForkWith(
-          Context.merge(services, taskServices),
-        )
+        const toolServices = Context.merge(services, taskServices)
 
         // oxlint-disable-next-line typescript/no-explicit-any
         sandbox[name] = function (params: any) {
+          const runFork = Effect.runForkWith(
+            Context.add(toolServices, CurrentDirectory, currentDirectory),
+          )
           running++
           const fiber = trackFiber(runFork(handler(params, {})))
           return new Promise((resolve, reject) => {
@@ -201,40 +222,53 @@ export const makeLocal = Effect.fnUntraced(function* <
       const agentsMd = yield* Effect.option(
         fs.readFileString(pathService.join(options.directory, "AGENTS.md")),
       )
+      const skills = yield* AgentSkills.discover({
+        directory: options.directory,
+        homeDirectory: homeDirectory(),
+      }).pipe(
+        Effect.provideService(FileSystem.FileSystem, fs),
+        Effect.provideService(Path.Path, pathService),
+      )
       return new Capabilities({
         toolsDts,
         agentsMd,
         supportsSearch: hasSearch,
+        skills,
       })
     }),
     execute,
-    executeUnsafe: (opts) => {
-      const tool = tools.tools[opts.tool as keyof typeof tools.tools]
-      const handler = services.mapUnsafe.get(tool.id) as Tool.Handler<string>
-      if (!handler || !tool) {
-        return Effect.die(new Error(`Unknown tool: ${opts.tool}`))
-      }
+    executeUnsafe: (opts) =>
+      Effect.suspend(() => {
+        const tool = tools.tools[opts.tool as keyof typeof tools.tools]
+        if (!tool) {
+          return Effect.die(new Error(`Unknown tool: ${opts.tool}`))
+        }
+        const handler = services.mapUnsafe.get(tool.id) as Tool.Handler<string>
+        if (!handler) {
+          return Effect.die(new Error(`Unknown tool: ${opts.tool}`))
+        }
 
-      const taskServices = handler.context.pipe(
-        Context.add(TaskCompleter, () => Effect.void),
-        Context.add(CurrentDirectory, options.directory),
-        Context.add(SubagentExecutor, () => Effect.succeed("")),
-        Context.add(References.CurrentLogAnnotations, {}),
-        Option.isSome(search)
-          ? Context.add(SemanticSearch, search.value)
-          : identity,
-      )
+        const taskServices = handler.context.pipe(
+          Context.add(TaskCompleter, () => Effect.void),
+          Context.add(CurrentDirectory, currentDirectory),
+          Context.add(DirectoryChanger, changeDirectory),
+          Context.add(SubagentExecutor, () => Effect.succeed("")),
+          Context.add(References.CurrentLogAnnotations, {}),
+          Option.isSome(search)
+            ? Context.add(SemanticSearch, search.value)
+            : identity,
+        )
 
-      const encodeSuccess = Schema.encodeUnknownEffect(
-        Schema.toCodecJson(tool.successSchema as Schema.Top),
-      )
-      return pipe(
-        handler.handler(opts.params, {}),
-        Effect.flatMap(encodeSuccess),
-        Effect.provideContext(taskServices),
-        Effect.orDie,
-      ) as Effect.Effect<Schema.Json>
-    },
+        const encodeSuccess = Schema.encodeUnknownEffect(
+          Schema.toCodecJson(tool.successSchema as Schema.Top),
+        )
+        return pipe(
+          handler.handler(opts.params, {}),
+          Effect.flatMap(encodeSuccess),
+          Effect.provideContext(taskServices),
+          Effect.orDie,
+        ) as Effect.Effect<Schema.Json>
+      }),
   })
 })
 
@@ -302,7 +336,7 @@ export const layerLocal = <Toolkit extends Toolkit.Any = never>(options: {
       Toolkit extends Toolkit.Toolkit<infer T>
         ? Tool.HandlersFor<T> | Tool.HandlerServices<T[keyof T]>
         : never,
-      CurrentDirectory | SubagentExecutor | TaskCompleter
+      CurrentDirectory | DirectoryChanger | SubagentExecutor | TaskCompleter
     >
 > =>
   Layer.effect(AgentExecutor, makeLocal(options)).pipe(
@@ -342,7 +376,7 @@ export const layerRpcServer = <Toolkit extends Toolkit.Any = never>(options: {
       Toolkit extends Toolkit.Toolkit<infer T>
         ? Tool.HandlersFor<T> | Tool.HandlerServices<T[keyof T]>
         : never,
-      CurrentDirectory | SubagentExecutor | TaskCompleter
+      CurrentDirectory | DirectoryChanger | SubagentExecutor | TaskCompleter
     >
 > =>
   RpcServer.layer(Rpcs, {
@@ -500,6 +534,16 @@ const compileScript = (script: string): NodeVm.Script => {
 
 const defaultMain = () => Promise.resolve()
 
+const homeDirectory = (): Option.Option<string> => {
+  const fromEnv = process.env.HOME
+  if (fromEnv) return Option.some(fromEnv)
+  try {
+    return Option.some(NodeOs.homedir())
+  } catch {
+    return Option.none()
+  }
+}
+
 const makeConsole = Effect.fn(function* (
   queue: Queue.Queue<string, Cause.Done>,
 ) {

package/src/AgentOutput.ts

@@ -138,6 +138,58 @@ export class SubagentComplete extends Schema.TaggedClass<SubagentComplete>()(
   },
 ) {}
 
+/**
+ * Emitted when an `execute` result exceeded the always-on output cap and was
+ * shortened before being appended to the Prompt.
+ *
+ * @since 1.0.0
+ * @category Output
+ */
+export class ExecuteOutputCapped extends Schema.TaggedClass<ExecuteOutputCapped>()(
+  "ExecuteOutputCapped",
+  {
+    charsBefore: Schema.Number,
+    charsAfter: Schema.Number,
+  },
+) {}
+
+/**
+ * @since 1.0.0
+ * @category Output
+ */
+export const CompactionReason = Schema.Literals(["threshold", "overflow"])
+
+/**
+ * Emitted when auto-compaction begins. `reason` is `threshold` when the
+ * context token count crossed the configured limit before a model call, and
+ * `overflow` when a context-length error from the provider triggered it.
+ *
+ * @since 1.0.0
+ * @category Output
+ */
+export class CompactionStarted extends Schema.TaggedClass<CompactionStarted>()(
+  "CompactionStarted",
+  {
+    reason: CompactionReason,
+  },
+) {}
+
+/**
+ * Emitted when auto-compaction finished and the Prompt was rewritten.
+ * `tokensBefore` / `tokensAfter` are estimates.
+ *
+ * @since 1.0.0
+ * @category Output
+ */
+export class CompactionEnded extends Schema.TaggedClass<CompactionEnded>()(
+  "CompactionEnded",
+  {
+    reason: CompactionReason,
+    tokensBefore: Schema.Number,
+    tokensAfter: Schema.Number,
+  },
+) {}
+
 export type ContentPart =
   | ReasoningStart
   | ReasoningDelta
@@ -148,6 +200,9 @@ export type ContentPart =
   | ScriptOutput
   | Usage
   | ErrorRetry
+  | ExecuteOutputCapped
+  | CompactionStarted
+  | CompactionEnded
 
 export const ContentPart = Schema.Union([
   ReasoningStart,
@@ -159,6 +214,9 @@ export const ContentPart = Schema.Union([
   ScriptOutput,
   Usage,
   ErrorRetry,
+  ExecuteOutputCapped,
+  CompactionStarted,
+  CompactionEnded,
 ])
 
 /**