clanka 0.4.0 → 0.5.1

package/src/AgentExecutor.ts

@@ -10,6 +10,7 @@ import {
   AgentTools,
   AgentToolsWithSearch,
   CurrentDirectory,
+  DirectoryChanger,
   SubagentExecutor,
   TaskCompleter,
 } from "./AgentTools.ts"
@@ -100,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(
@@ -142,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, {}),
@@ -165,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) => {
@@ -213,6 +225,7 @@ export const makeLocal = Effect.fnUntraced(function* <
       const skills = yield* AgentSkills.discover({
         directory: options.directory,
         homeDirectory: homeDirectory(),
+        hermesHome: Option.fromNullishOr(process.env.HERMES_HOME),
       }).pipe(
         Effect.provideService(FileSystem.FileSystem, fs),
         Effect.provideService(Path.Path, pathService),
@@ -225,33 +238,38 @@ export const makeLocal = Effect.fnUntraced(function* <
       })
     }),
     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>
+      }),
   })
 })
 
@@ -319,7 +337,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(
@@ -359,7 +377,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, {

package/src/AgentSkills.test.ts

@@ -40,6 +40,7 @@ const withRoots = <A, E, R>(
   f: (roots: {
     readonly project: string
     readonly home: string
+    readonly hermes: string
   }) => Effect.Effect<A, E, R>,
 ) =>
   Effect.scoped(
@@ -49,9 +50,11 @@ const withRoots = <A, E, R>(
       const base = yield* fs.makeTempDirectoryScoped()
       const project = path.join(base, "project")
       const home = path.join(base, "home")
+      const hermes = path.join(base, "hermes-home")
+      yield* fs.makeDirectory(hermes)
       yield* fs.makeDirectory(project)
       yield* fs.makeDirectory(home)
-      return yield* f({ project, home })
+      return yield* f({ project, home, hermes })
     }),
   )
 
@@ -61,7 +64,291 @@ const discover = (roots: { readonly project: string; readonly home: string }) =>
     homeDirectory: Option.some(roots.home),
   })
 
+const writeHermesSkill = Effect.fnUntraced(function* (
+  root: string,
+  dir: string,
+  content: string,
+) {
+  const fs = yield* FileSystem.FileSystem
+  const path = yield* Path.Path
+  const skillDir = path.join(root, "skills", dir)
+  yield* fs.makeDirectory(skillDir, { recursive: true })
+  const location = path.join(skillDir, "SKILL.md")
+  yield* fs.writeFileString(location, content)
+  return location
+})
+
+const discoverWithHermes = (
+  roots: {
+    readonly project: string
+    readonly home: string
+    readonly hermes: string
+  },
+  hermesHome: Option.Option<string> = Option.some(roots.hermes),
+) =>
+  AgentSkills.discover({
+    directory: roots.project,
+    homeDirectory: Option.some(roots.home),
+    hermesHome,
+  })
+
+const withLocalExecutor = <A, E, R>(
+  roots: { readonly project: string; readonly home: string },
+  hermesHome: string | undefined,
+  effect: Effect.Effect<A, E, R>,
+) =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      yield* Effect.acquireRelease(
+        Effect.sync(() => {
+          const previous = {
+            HOME: process.env.HOME,
+            HERMES_HOME: process.env.HERMES_HOME,
+          }
+          process.env.HOME = roots.home
+          if (hermesHome === undefined) delete process.env.HERMES_HOME
+          else process.env.HERMES_HOME = hermesHome
+          return previous
+        }),
+        (previous) =>
+          Effect.sync(() => {
+            for (const key of ["HOME", "HERMES_HOME"] as const) {
+              if (previous[key] === undefined) delete process.env[key]
+              else process.env[key] = previous[key]
+            }
+          }),
+      )
+      return yield* effect.pipe(
+        Effect.provide(
+          AgentExecutor.layerLocal({ directory: roots.project }).pipe(
+            Layer.provide(NodeHttpClient.layerUndici),
+          ),
+        ),
+      )
+    }),
+  )
+
 describe("AgentSkills", () => {
+  it.effect("catalogs a flat HERMES_HOME skill with an absolute location", () =>
+    withRoots(
+      Effect.fnUntraced(function* (roots) {
+        const path = yield* Path.Path
+        const location = yield* writeHermesSkill(
+          roots.hermes,
+          "bound",
+          skillFile("bound", "Workspace skill"),
+        )
+        const skills = yield* discoverWithHermes(roots)
+        assert.deepStrictEqual(
+          skills.map(({ name, description, location }) => [
+            name,
+            description,
+            location,
+          ]),
+          [["bound", "Workspace skill", location]],
+        )
+        assert.isTrue(path.isAbsolute(skills[0]!.location))
+      }),
+    ).pipe(Effect.provide(NodeServices.layer)),
+  )
+
+  for (const projectWins of [true, false]) {
+    it.effect(
+      projectWins
+        ? "project skill overrides Hermes and user skills"
+        : "Hermes skill overrides a user skill",
+      () =>
+        withRoots(
+          Effect.fnUntraced(function* (roots) {
+            yield* writeSkill(roots.home, "shared", skillFile("shared", "User"))
+            const hermesLocation = yield* writeHermesSkill(
+              roots.hermes,
+              "shared",
+              skillFile("shared", "Hermes"),
+            )
+            const location = projectWins
+              ? yield* writeSkill(
+                  roots.project,
+                  "shared",
+                  skillFile("shared", "Project"),
+                )
+              : hermesLocation
+            const skills = yield* discoverWithHermes(roots)
+            assert.deepStrictEqual(
+              skills.map((skill) => [skill.description, skill.location]),
+              [[projectWins ? "Project" : "Hermes", location]],
+            )
+          }),
+        ).pipe(Effect.provide(NodeServices.layer)),
+    )
+  }
+
+  for (const mode of ["unset", "empty", "missing skills"] as const) {
+    it.effect(`preserves existing discovery with ${mode} HERMES_HOME`, () =>
+      withRoots(
+        Effect.fnUntraced(function* (roots) {
+          const fs = yield* FileSystem.FileSystem
+          const path = yield* Path.Path
+          yield* writeSkill(roots.project, "proj", skillFile("proj", "Project"))
+          yield* writeSkill(roots.home, "usr", skillFile("usr", "User"))
+          // An unset input must not fall back to ~/.hermes.
+          yield* writeHermesSkill(
+            path.join(roots.home, ".hermes"),
+            "ignored",
+            skillFile("ignored", "Ignored"),
+          )
+          const reads: Array<string> = []
+          const skills = yield* discoverWithHermes(
+            roots,
+            mode === "unset"
+              ? Option.none()
+              : Option.some(mode === "empty" ? "" : roots.hermes),
+          ).pipe(
+            Effect.provideService(
+              FileSystem.FileSystem,
+              FileSystem.FileSystem.of({
+                ...fs,
+                readDirectory: (directory) => {
+                  reads.push(directory)
+                  return fs.readDirectory(directory)
+                },
+              }),
+            ),
+          )
+          assert.deepStrictEqual(skills, yield* discover(roots))
+          if (mode !== "missing skills")
+            assert.deepStrictEqual(reads, [
+              path.join(roots.project, ".agents", "skills"),
+              path.join(roots.home, ".agents", "skills"),
+            ])
+        }),
+      ).pipe(Effect.provide(NodeServices.layer)),
+    )
+  }
+
+  it.effect("only reads HERMES_HOME/skills/<dir>/SKILL.md", () =>
+    withRoots(
+      Effect.fnUntraced(function* (roots) {
+        yield* writeHermesSkill(
+          roots.hermes,
+          "outer/inner",
+          skillFile("nested", "Ignored"),
+        )
+        yield* writeHermesSkill(roots.hermes, "", skillFile("bare", "Ignored"))
+        yield* writeSkill(
+          roots.hermes,
+          "agents",
+          skillFile("agents", "Ignored"),
+        )
+        const location = yield* writeHermesSkill(
+          roots.hermes,
+          "real",
+          skillFile("real", "Found"),
+        )
+        const skills = yield* discoverWithHermes(roots)
+        assert.deepStrictEqual(
+          skills.map((skill) => [skill.name, skill.location]),
+          [["real", location]],
+        )
+      }),
+    ).pipe(Effect.provide(NodeServices.layer)),
+  )
+
+  it.effect(
+    "makeLocal exposes HERMES_HOME skills and reads their relative references",
+    () =>
+      withRoots(
+        Effect.fnUntraced(function* (roots) {
+          const fs = yield* FileSystem.FileSystem
+          const path = yield* Path.Path
+          const content =
+            skillFile("bound", "Workspace skill") +
+            "Read references/guide.md.\n"
+          const location = yield* writeHermesSkill(
+            roots.hermes,
+            "bound",
+            content,
+          )
+          const reference = path.join(
+            path.dirname(location),
+            "references",
+            "guide.md",
+          )
+          yield* fs.makeDirectory(path.dirname(reference))
+          yield* fs.writeFileString(
+            reference,
+            "Workspace reference instructions.",
+          )
+          yield* withLocalExecutor(
+            roots,
+            roots.hermes,
+            Effect.gen(function* () {
+              const executor = yield* AgentExecutor.AgentExecutor
+              const capabilities = yield* executor.capabilities
+              assert.deepStrictEqual(
+                capabilities.skills.map((skill) => [
+                  skill.name,
+                  skill.location,
+                ]),
+                [["bound", location]],
+              )
+              const discovered = capabilities.skills[0]!.location
+              const body = yield* executor.executeUnsafe({
+                tool: "readFile",
+                params: { path: discovered },
+              })
+              assert.include(String(body), "Read references/guide.md.")
+              const guide = yield* executor.executeUnsafe({
+                tool: "readFile",
+                params: {
+                  path: path.resolve(
+                    path.dirname(discovered),
+                    "references/guide.md",
+                  ),
+                },
+              })
+              assert.include(String(guide), "Workspace reference instructions.")
+            }),
+          )
+        }),
+      ).pipe(Effect.provide(NodeServices.layer)),
+  )
+
+  for (const hermesHome of [undefined, ""]) {
+    it.effect(
+      hermesHome === undefined
+        ? "makeLocal leaves unset HERMES_HOME disabled"
+        : "makeLocal treats empty HERMES_HOME as unset",
+      () =>
+        withRoots(
+          Effect.fnUntraced(function* (roots) {
+            const path = yield* Path.Path
+            yield* writeHermesSkill(
+              path.join(roots.home, ".hermes"),
+              "ignored",
+              skillFile("ignored", "Ignored"),
+            )
+            const location = yield* writeSkill(
+              roots.project,
+              "proj",
+              skillFile("proj", "Project"),
+            )
+            const capabilities = yield* withLocalExecutor(
+              roots,
+              hermesHome,
+              AgentExecutor.AgentExecutor.pipe(
+                Effect.flatMap((executor) => executor.capabilities),
+              ),
+            )
+            assert.deepStrictEqual(
+              capabilities.skills.map((skill) => skill.location),
+              [location],
+            )
+          }),
+        ).pipe(Effect.provide(NodeServices.layer)),
+    )
+  }
+
   for (const type of ["FIFO", "Socket", "Directory"] as const) {
     it.effect(`skips a ${type} SKILL.md without attempting to read it`, () =>
       withRoots(
@@ -456,7 +743,7 @@ body`,
   it.effect("returns an empty catalog when nothing exists", () =>
     withRoots(
       Effect.fnUntraced(function* (roots) {
-        const skills = yield* discover(roots)
+        const skills = yield* discoverWithHermes(roots, Option.none())
         assert.deepStrictEqual(skills, [])
         assert.isTrue(Option.isNone(AgentSkills.renderCatalog(skills)))
       }),
@@ -478,19 +765,11 @@ body`,
         )
         yield* writeSkill(roots.project, "broken", "---\nnope\n---")
 
-        const previousHome = process.env.HOME
-        process.env.HOME = roots.home
-        const capabilities = yield* AgentExecutor.AgentExecutor.pipe(
-          Effect.flatMap((executor) => executor.capabilities),
-          Effect.provide(
-            AgentExecutor.layerLocal({ directory: roots.project }).pipe(
-              Layer.provide(NodeHttpClient.layerUndici),
-            ),
-          ),
-          Effect.ensuring(
-            Effect.sync(() => {
-              process.env.HOME = previousHome
-            }),
+        const capabilities = yield* withLocalExecutor(
+          roots,
+          undefined,
+          AgentExecutor.AgentExecutor.pipe(
+            Effect.flatMap((executor) => executor.capabilities),
           ),
         )
         assert.deepStrictEqual(
@@ -567,6 +846,48 @@ const systemPromptFor = (skills: ReadonlyArray<AgentSkills.Skill>) =>
   )
 
 describe("Agent skills catalog", () => {
+  it.effect(
+    "renders a Hermes skill in the system prompt with its absolute location",
+    () =>
+      withRoots(
+        Effect.fnUntraced(function* (roots) {
+          const location = yield* writeHermesSkill(
+            roots.hermes,
+            "bound",
+            skillFile("bound", "Workspace skill"),
+          )
+          const system = yield* systemPromptFor(
+            yield* discoverWithHermes(roots),
+          )
+          assert.include(system, "# Skills")
+          assert.include(system, "- bound: Workspace skill")
+          assert.include(system, "location: " + location)
+          assert.notInclude(system, "Instructions for bound.")
+        }),
+      ).pipe(Effect.provide(NodeServices.layer)),
+  )
+
+  it.effect(
+    "omits the catalog with HERMES_HOME pointing at an empty directory",
+    () =>
+      withRoots(
+        Effect.fnUntraced(function* (roots) {
+          const capabilities = yield* withLocalExecutor(
+            roots,
+            roots.hermes,
+            AgentExecutor.AgentExecutor.pipe(
+              Effect.flatMap((executor) => executor.capabilities),
+            ),
+          )
+          assert.deepStrictEqual(capabilities.skills, [])
+          assert.notInclude(
+            yield* systemPromptFor(capabilities.skills),
+            "# Skills",
+          )
+        }),
+      ).pipe(Effect.provide(NodeServices.layer)),
+  )
+
   it.effect(
     "escapes a newline in a catalog location without changing the filesystem path",
     () =>

package/src/AgentSkills.ts

@@ -37,9 +37,11 @@ export class Skill extends Schema.Class<Skill>("Skill")({
 }) {}
 
 /**
- * Scan project and user `.agents/skills/<dir>/SKILL.md` files.
+ * Scan project and user `.agents/skills/<dir>/SKILL.md` files, plus
+ * `<hermesHome>/skills/<dir>/SKILL.md` when explicitly configured.
  *
- * Project names override user names; the first name wins within each scope.
+ * Project names override Hermes names, which override user names.
+ * The first name wins within each scope; an empty Hermes home is ignored.
  * Skip unreadable files, invalid frontmatter and missing or empty descriptions.
  *
  * @since 1.0.0
@@ -48,6 +50,7 @@ export class Skill extends Schema.Class<Skill>("Skill")({
 export const discover: (options: {
   readonly directory: string
   readonly homeDirectory: Option.Option<string>
+  readonly hermesHome?: Option.Option<string>
 }) => Effect.Effect<
   ReadonlyArray<Skill>,
   never,
@@ -57,14 +60,31 @@ export const discover: (options: {
   const path = yield* Path.Path
 
   const roots: Array<{ readonly root: string; readonly source: SkillSource }> =
-    [{ root: options.directory, source: "project" }]
+    [
+      {
+        root: path.resolve(options.directory, ".agents", "skills"),
+        source: "project",
+      },
+    ]
+  if (
+    options.hermesHome &&
+    Option.isSome(options.hermesHome) &&
+    options.hermesHome.value !== ""
+  ) {
+    roots.push({
+      root: path.resolve(options.hermesHome.value, "skills"),
+      source: "user",
+    })
+  }
   if (Option.isSome(options.homeDirectory)) {
-    roots.push({ root: options.homeDirectory.value, source: "user" })
+    roots.push({
+      root: path.resolve(options.homeDirectory.value, ".agents", "skills"),
+      source: "user",
+    })
   }
 
   const byName = new Map<string, Skill>()
-  for (const { root, source } of roots) {
-    const skillsDir = path.resolve(root, ".agents", "skills")
+  for (const { root: skillsDir, source } of roots) {
     const entries = yield* fs
       .readDirectory(skillsDir)
       .pipe(Effect.orElseSucceed(() => []))