clanka 0.3.1 → 0.4.0

package/src/Agent.ts

@@ -4,6 +4,7 @@
 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"
@@ -36,6 +37,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 +55,9 @@ import {
   ScriptStart,
   ScriptDelta,
   AgentStart,
+  ExecuteOutputCapped,
+  CompactionStarted,
+  CompactionEnded,
 } from "./AgentOutput.ts"
 
 /**
@@ -187,6 +193,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 +328,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 +388,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 +434,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 +513,7 @@ ${content}
                     outputTokens += usage.outputTokens.total
                   }
                   if (usage.inputTokens.total !== undefined) {
+                    lastContextTokens = usage.inputTokens.total
                     inputTokens += usage.inputTokens.total
                     maybeSend({
                       agentId,
@@ -449,6 +532,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 +557,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 +580,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 +736,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,

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 {
@@ -13,6 +14,7 @@ import {
   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 +71,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([])),
+  ),
 }) {}
 
 /**
@@ -201,10 +210,18 @@ 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,
@@ -500,6 +517,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,
 ])
 
 /**