clanka 0.3.1 → 0.5.0

package/src/AgentSkills.ts

@@ -0,0 +1,155 @@
+/**
+ * Discover Agent Skills (https://agentskills.io/specification) on the executor.
+ *
+ * @since 1.0.0
+ */
+import * as Effect from "effect/Effect"
+import * as FileSystem from "effect/FileSystem"
+import * as Option from "effect/Option"
+import * as Path from "effect/Path"
+import * as Predicate from "effect/Predicate"
+import * as Schema from "effect/Schema"
+import * as Yaml from "effect/unstable/encoding/Yaml"
+
+/**
+ * @since 1.0.0
+ * @category Models
+ */
+export const SkillSource = Schema.Literals(["project", "user"])
+
+/**
+ * @since 1.0.0
+ * @category Models
+ */
+export type SkillSource = typeof SkillSource.Type
+
+/**
+ * Skill metadata with an absolute executor-side `SKILL.md` path.
+ *
+ * @since 1.0.0
+ * @category Models
+ */
+export class Skill extends Schema.Class<Skill>("Skill")({
+  name: Schema.String,
+  description: Schema.String,
+  location: Schema.String,
+  source: SkillSource,
+}) {}
+
+/**
+ * Scan project and user `.agents/skills/<dir>/SKILL.md` files.
+ *
+ * Project names override user names; the first name wins within each scope.
+ * Skip unreadable files, invalid frontmatter and missing or empty descriptions.
+ *
+ * @since 1.0.0
+ * @category Discovery
+ */
+export const discover: (options: {
+  readonly directory: string
+  readonly homeDirectory: Option.Option<string>
+}) => Effect.Effect<
+  ReadonlyArray<Skill>,
+  never,
+  FileSystem.FileSystem | Path.Path
+> = Effect.fnUntraced(function* (options) {
+  const fs = yield* FileSystem.FileSystem
+  const path = yield* Path.Path
+
+  const roots: Array<{ readonly root: string; readonly source: SkillSource }> =
+    [{ root: options.directory, source: "project" }]
+  if (Option.isSome(options.homeDirectory)) {
+    roots.push({ root: options.homeDirectory.value, source: "user" })
+  }
+
+  const byName = new Map<string, Skill>()
+  for (const { root, source } of roots) {
+    const skillsDir = path.resolve(root, ".agents", "skills")
+    const entries = yield* fs
+      .readDirectory(skillsDir)
+      .pipe(Effect.orElseSucceed(() => []))
+    entries.sort()
+    for (const entry of entries) {
+      const location = path.join(skillsDir, entry, "SKILL.md")
+      const content = yield* Effect.option(
+        fs.stat(location).pipe(
+          Effect.filterOrFail((info) => info.type === "File"),
+          Effect.andThen(() => fs.readFileString(location)),
+        ),
+      )
+      if (Option.isNone(content)) continue
+      const frontmatter = parseFrontmatter(content.value)
+      if (Option.isNone(frontmatter)) continue
+      const description = singleLine(frontmatter.value.description)
+      if (description === "") continue
+      const name = Predicate.isString(frontmatter.value.name)
+        ? singleLine(frontmatter.value.name) || singleLine(entry)
+        : singleLine(entry)
+      if (byName.has(name)) continue
+      byName.set(name, new Skill({ name, description, location, source }))
+    }
+  }
+
+  return Array.from(byName.values())
+})
+
+/**
+ * Render the skills prompt section, or `None` for an empty catalog.
+ *
+ * @since 1.0.0
+ * @category Rendering
+ */
+export const renderCatalog = (
+  skills: ReadonlyArray<Skill>,
+): Option.Option<string> => {
+  if (skills.length === 0) return Option.none()
+  const entries = skills
+    .map(
+      (skill) => `- ${skill.name}: ${skill.description}
+  location: ${renderLocation(skill.location)}`,
+    )
+    .join("\n")
+  return Option.some(`# Skills
+
+The following skills are available. Each one is a folder with instructions for
+a specific kind of task.
+
+When a task matches a skill's description, use "readFile" to read the file at
+its location BEFORE proceeding, then follow the instructions it contains.
+Double-quoted locations are JSON strings; decode them to get the exact file
+path. Unquoted locations are literal paths.
+Relative paths mentioned inside a skill (such as "scripts/" or "references/")
+are relative to the skill's directory (the parent of SKILL.md); use absolute
+paths when accessing them.
+
+${entries}`)
+}
+
+const Frontmatter = Schema.Struct({
+  name: Schema.optional(Schema.Unknown),
+  description: Schema.String,
+})
+
+const decodeFrontmatter = Schema.decodeUnknownOption(Frontmatter)
+
+const frontmatterPattern = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/
+
+// Validate all frontmatter, including fields omitted from the catalog.
+const parseFrontmatter = (
+  content: string,
+): Option.Option<typeof Frontmatter.Type> => {
+  const match = frontmatterPattern.exec(content)
+  if (match === null) return Option.none()
+  try {
+    return decodeFrontmatter(Yaml.parse(match[1]!))
+  } catch {
+    return Option.none()
+  }
+}
+
+const singleLine = (value: string): string => value.replace(/\s+/g, " ").trim()
+
+const renderLocation = (location: string): string => {
+  const encoded = JSON.stringify(location)
+  return encoded.slice(1, -1) === location ? location : encoded
+}

package/src/AgentTools.ts

@@ -32,6 +32,15 @@ export class CurrentDirectory extends Context.Service<
   string
 >()("clanka/AgentTools/CurrentDirectory") {}
 
+/**
+ * @since 1.0.0
+ * @category Context
+ */
+export class DirectoryChanger extends Context.Service<
+  DirectoryChanger,
+  (directory: string) => Effect.Effect<string>
+>()("clanka/AgentTools/DirectoryChanger") {}
+
 /**
  * @since 1.0.0
  * @category Context
@@ -57,6 +66,7 @@ export class SubagentExecutor extends Context.Service<
 export const makeContextNoop = (cwd?: string) =>
   SubagentExecutor.context(() => Effect.die("Not implemented")).pipe(
     Context.add(CurrentDirectory, cwd ?? "/"),
+    Context.add(DirectoryChanger, () => Effect.die("Not implemented")),
     Context.add(TaskCompleter, () => Effect.void),
   )
 
@@ -73,6 +83,13 @@ class TodoItem extends Schema.Opaque<TodoItem>()(
  * @category Toolkit
  */
 export const AgentTools = Toolkit.make(
+  Tool.make("changeDirectory", {
+    description:
+      "Change the executor's working directory to an existing directory and return its absolute path. Relative paths resolve from the current directory without shell expansion. Await this before dependent tools. The change persists across scripts and is shared with delegates using this executor. Startup AGENTS.md, skills, and the semantic-search index root remain fixed. Navigation does not survive a session reload.",
+    parameters: Schema.String.annotate({ identifier: "directory" }),
+    success: Schema.String,
+    dependencies: [DirectoryChanger],
+  }),
   Tool.make("readFile", {
     description:
       "Read a file and optionally filter the lines to return. Returns null if the file doesn't exist.",
@@ -284,6 +301,15 @@ export const AgentToolHandlersNoDeps = AgentToolsWithSearch.toLayer(
     }, Effect.scoped)
 
     return AgentToolsWithSearch.of({
+      changeDirectory: Effect.fn("AgentTools.changeDirectory")(
+        function* (directory) {
+          yield* Effect.logInfo(`Calling "changeDirectory"`).pipe(
+            Effect.annotateLogs({ directory }),
+          )
+          const changeDirectory = yield* DirectoryChanger
+          return yield* changeDirectory(directory)
+        },
+      ),
       readFile: Effect.fn("AgentTools.readFile")(function* (options) {
         yield* Effect.logInfo(`Calling "readFile"`).pipe(
           Effect.annotateLogs(options),
@@ -321,7 +347,7 @@ export const AgentToolHandlersNoDeps = AgentToolsWithSearch.toLayer(
           recursive: true,
         })
         yield* fs.writeFileString(path, options.content)
-        yield* SemanticSearch.maybeUpdateFile(pathService.relative(cwd, path))
+        yield* SemanticSearch.maybeUpdateFile(path)
       }, Effect.orDie),
       removeFile: Effect.fn("AgentTools.removeFile")(function* (path) {
         yield* Effect.logInfo(`Calling "removeFile"`).pipe(
@@ -330,9 +356,7 @@ export const AgentToolHandlersNoDeps = AgentToolsWithSearch.toLayer(
         const cwd = yield* CurrentDirectory
         const absolutePath = pathService.resolve(cwd, path)
         yield* fs.remove(absolutePath, { force: true })
-        yield* SemanticSearch.maybeRemoveFile(
-          pathService.relative(cwd, absolutePath),
-        )
+        yield* SemanticSearch.maybeRemoveFile(absolutePath)
       }, Effect.orDie),
       renameFile: Effect.fn("AgentTools.renameFile")(function* (options) {
         yield* Effect.logInfo(`Calling "renameFile"`).pipe(
@@ -345,8 +369,8 @@ export const AgentToolHandlersNoDeps = AgentToolsWithSearch.toLayer(
           recursive: true,
         })
         yield* fs.rename(from, to)
-        yield* SemanticSearch.maybeRemoveFile(pathService.relative(cwd, from))
-        yield* SemanticSearch.maybeUpdateFile(pathService.relative(cwd, to))
+        yield* SemanticSearch.maybeRemoveFile(from)
+        yield* SemanticSearch.maybeUpdateFile(to)
       }, Effect.orDie),
       ls: Effect.fn("AgentTools.ls")(function* (directory) {
         yield* Effect.logInfo(`Calling "ls"`).pipe(
@@ -597,7 +621,7 @@ export const AgentToolHandlersNoDeps = AgentToolsWithSearch.toLayer(
                 recursive: true,
               })
               yield* fs.writeFileString(step.path, step.next)
-              yield* SemanticSearch.maybeUpdateFile(rel(step.path))
+              yield* SemanticSearch.maybeUpdateFile(step.path)
               break
             }
             case "move": {
@@ -606,13 +630,13 @@ export const AgentToolHandlersNoDeps = AgentToolsWithSearch.toLayer(
               })
               yield* fs.writeFileString(step.movePath, step.next)
               yield* fs.remove(step.path)
-              yield* SemanticSearch.maybeRemoveFile(rel(step.path))
-              yield* SemanticSearch.maybeUpdateFile(rel(step.movePath))
+              yield* SemanticSearch.maybeRemoveFile(step.path)
+              yield* SemanticSearch.maybeUpdateFile(step.movePath)
               break
             }
             case "delete": {
               yield* fs.remove(step.path)
-              yield* SemanticSearch.maybeRemoveFile(rel(step.path))
+              yield* SemanticSearch.maybeRemoveFile(step.path)
               break
             }
           }

package/src/Codex.ts

@@ -67,7 +67,7 @@ const layerModel = (
   OpenAiLanguageModel.layer({
     model,
     config: {
-      ...Struct.omit(options ?? {}, ["reasoning"]),
+      ...Struct.omit(options ?? {}, ["reasoning", "systemPromptTransform"]),
       store: false,
       reasoning: {
         effort: "medium",
@@ -83,5 +83,7 @@ const layerModel = (
             instructions: system,
           }),
       }),
+      // No Compaction.SummarizerTransform: Codex rejects max_output_tokens,
+      // so compaction summaries have no configured output-token cap.
     ),
   )