diff --git a/docs/user/providers-kiro.md b/docs/user/providers-kiro.md index 6b94ca14f2e5..2b217688edbb 100644 --- a/docs/user/providers-kiro.md +++ b/docs/user/providers-kiro.md @@ -38,6 +38,14 @@ not listed yet. Refresh the Kiro provider after adding or removing an agent. The thread's model still applies when an agent sets its own `model`. An agent that was removed leaves the thread on Kiro's current agent. +## Skills + +The `/` and `$` menus list the Kiro skills in `~/.kiro/skills` and in `.kiro/skills` of the folder +the thread runs in, and your Kiro account's cloud skills as Kiro last synced them to this machine. +As in Kiro, a parent folder's `.kiro/skills` is not read, a skill needs a valid `name` and a +`description` in its `SKILL.md`, and a project skill replaces a `~/.kiro/skills` skill of the same +name, which replaces a cloud skill of the same name. + ## Permission Modes Kiro asks before tool calls such as writes and commands, and T3 Code answers by the permission mode: diff --git a/packages/provider-kiro/package.json b/packages/provider-kiro/package.json index be2781eacfce..2c24dd80abee 100644 --- a/packages/provider-kiro/package.json +++ b/packages/provider-kiro/package.json @@ -29,7 +29,8 @@ "@t3tools/provider-acp": "workspace:*", "@t3tools/provider-core": "workspace:*", "@t3tools/shared": "workspace:*", - "effect": "catalog:" + "effect": "catalog:", + "yaml": "catalog:" }, "devDependencies": { "@effect/platform-node": "catalog:", diff --git a/packages/provider-kiro/src/server/driver.ts b/packages/provider-kiro/src/server/driver.ts index 0a4e9b85fa28..bc822c65bf6e 100644 --- a/packages/provider-kiro/src/server/driver.ts +++ b/packages/provider-kiro/src/server/driver.ts @@ -3,6 +3,8 @@ import { KiroSettings } from "../settings.ts"; import * as HostProcess from "@t3tools/shared/HostProcess"; import * as SecureRandom from "effect/crypto/SecureRandom"; import * as Effect from "effect/Effect"; +import * as FileSystem from "effect/FileSystem"; +import * as Path from "effect/Path"; import * as Schema from "effect/Schema"; import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner"; @@ -25,6 +27,7 @@ import { } from "@t3tools/provider-core/server/snapshotSettings"; import type { ProviderTextGeneration } from "@t3tools/provider-core/server/textGeneration"; import { type KiroAdapterV2DriverEnv, makeKiroAdapterV2Driver } from "./adapter.ts"; +import { discoverKiroSkills } from "./skills.ts"; import { buildInitialKiroProviderSnapshot, checkKiroProviderStatus, @@ -82,6 +85,8 @@ export const KiroDriver: ProviderDriver = { }) { const spawner = yield* ChildProcessSpawner.ChildProcessSpawner; const crypto = yield* SecureRandom.SecureRandom; + const fileSystem = yield* FileSystem.FileSystem; + const path = yield* Path.Path; const processEnv = yield* mergeProviderInstanceEnvironment( environment, yield* HostProcess.Environment, @@ -160,6 +165,16 @@ export const KiroDriver: ProviderDriver = { accentColor, enabled, snapshot, + snapshotForCwd: (cwd) => + !effectiveConfig.enabled + ? snapshot.getSnapshot + : Effect.all([ + snapshot.getSnapshot, + discoverKiroSkills({ cwd, environment: processEnv }).pipe( + Effect.provideService(FileSystem.FileSystem, fileSystem), + Effect.provideService(Path.Path, path), + ), + ]).pipe(Effect.map(([machineSnapshot, skills]) => ({ ...machineSnapshot, skills }))), orchestrationAdapter, textGeneration: unsupportedTextGeneration, } satisfies ProviderInstance; diff --git a/packages/provider-kiro/src/server/skills.test.ts b/packages/provider-kiro/src/server/skills.test.ts new file mode 100644 index 000000000000..870ec9c96dbc --- /dev/null +++ b/packages/provider-kiro/src/server/skills.test.ts @@ -0,0 +1,92 @@ +import * as NodeServices from "@effect/platform-node/NodeServices"; +import { assert, describe, it } from "@effect/vitest"; +import * as Effect from "effect/Effect"; +import * as FileSystem from "effect/FileSystem"; +import * as Path from "effect/Path"; + +import { discoverKiroSkills } from "./skills.ts"; + +describe("discoverKiroSkills", () => { + // Each case is what a kiro-cli 3.1.0 session advertised in + // `available_commands_update` for the same folders. + it.effect("lists the user and workspace skills a Kiro session loads", () => + Effect.gen(function* () { + const fileSystem = yield* FileSystem.FileSystem; + const path = yield* Path.Path; + const home = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-kiro-skills-home-" }); + const repo = path.join(home, "repo"); + const workspace = path.join(repo, "packages", "app"); + const userRoot = path.join(home, ".kiro", "skills"); + const workspaceRoot = path.join(workspace, ".kiro", "skills"); + const cloudSkills = (kiroHome: string) => + path.join(kiroHome, "cloud-cache", "resolved", "config", "user", "skills"); + const cloudRoot = cloudSkills(path.join(home, ".kiro")); + const write = (root: string, folder: string, contents: string) => + fileSystem + .makeDirectory(path.join(root, folder), { recursive: true }) + .pipe( + Effect.andThen( + fileSystem.writeFileString(path.join(root, folder, "SKILL.md"), contents), + ), + ); + const skill = (name: string, description: string) => + `---\nname: ${name}\ndescription: ${description}\n---\n\nBody.\n`; + + yield* write(cloudRoot, "cloud-only", skill("cloud-only", "from the account")); + yield* write(cloudRoot, "user-only", skill("user-only", "cloud copy")); + yield* write(userRoot, "shared", skill("shared", "user copy")); + yield* write(userRoot, "user-only", skill("user-only", "from the home folder")); + yield* write(workspaceRoot, "block", "---\nname: block\ndescription: >\n one\n two\n---\n"); + yield* write(workspaceRoot, "crlf", "---\r\nname: crlf\r\ndescription: windows\r\n---\r\n"); + yield* write(workspaceRoot, "folder-a", skill("renamed", "named by its front matter")); + yield* write(workspaceRoot, "open", "---\nname: open\ndescription: no closing fence\n"); + yield* write(workspaceRoot, "shared", skill("shared", "workspace copy")); + // Kiro loads none of these. + yield* write(workspaceRoot, "bad-yaml", "---\nname: bad-yaml\ndescription: [unclosed\n---\n"); + yield* write(workspaceRoot, "capitals", skill("Capitals", "invalid name")); + yield* write(workspaceRoot, "long-name", skill("a".repeat(65), "name over 64 characters")); + yield* write(workspaceRoot, "no-description", "---\nname: no-description\n---\n"); + yield* write(workspaceRoot, "no-frontmatter", "Just a body.\n"); + yield* write(workspaceRoot, "numeric", skill("123", "YAML reads the name as a number")); + yield* write(workspaceRoot, "snake", skill("snake_case", "invalid name")); + yield* write(workspaceRoot, "wordy", skill("wordy", "x".repeat(1_025))); + yield* write(path.join(workspaceRoot, "group"), "nested", skill("nested", "too deep")); + yield* write(path.join(repo, ".kiro", "skills"), "parent", skill("parent", "above cwd")); + yield* fileSystem.writeFileString(path.join(workspaceRoot, "loose.md"), skill("loose", "x")); + + const skills = yield* discoverKiroSkills({ cwd: workspace, environment: { HOME: home } }); + + assert.deepEqual( + skills.map(({ name, description, scope }) => ({ name, description, scope })), + [ + { name: "cloud-only", description: "from the account", scope: "user" }, + { name: "user-only", description: "from the home folder", scope: "user" }, + { name: "shared", description: "workspace copy", scope: "project" }, + { name: "block", description: "one two", scope: "project" }, + { name: "crlf", description: "windows", scope: "project" }, + { name: "renamed", description: "named by its front matter", scope: "project" }, + { name: "open", description: "no closing fence", scope: "project" }, + ], + ); + assert.equal(skills[2]?.path, path.join(workspaceRoot, "shared", "SKILL.md")); + assert.isTrue(skills.every((entry) => entry.enabled)); + + // With KIRO_HOME set, Kiro reads that folder and nothing under `~/.kiro`. + const kiroHome = path.join(home, "other-account"); + yield* write(cloudSkills(kiroHome), "relocated-cloud", skill("relocated-cloud", "cloud")); + yield* write(path.join(kiroHome, "skills"), "relocated", skill("relocated", "in KIRO_HOME")); + const relocated = yield* discoverKiroSkills({ + cwd: repo, + environment: { HOME: home, KIRO_HOME: kiroHome }, + }); + assert.deepEqual( + relocated.map(({ name, scope }) => ({ name, scope })), + [ + { name: "relocated-cloud", scope: "user" }, + { name: "relocated", scope: "user" }, + { name: "parent", scope: "project" }, + ], + ); + }).pipe(Effect.provide(NodeServices.layer)), + ); +}); diff --git a/packages/provider-kiro/src/server/skills.ts b/packages/provider-kiro/src/server/skills.ts new file mode 100644 index 000000000000..736f5d01eb1f --- /dev/null +++ b/packages/provider-kiro/src/server/skills.ts @@ -0,0 +1,104 @@ +/** + * Lists Kiro skills for the `/` and `$` menus from the SKILL.md folders Kiro + * reads. Kiro reports skills only to a running session, and a session starts + * the user's MCP servers, so none is opened for a composer menu. + * + * @module provider-kiro/server/skills + */ +import type { ServerProviderSkill } from "@t3tools/contracts"; +import * as HostProcess from "@t3tools/shared/HostProcess"; +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 Schema from "effect/Schema"; +import { parse as parseYamlDocument } from "yaml"; + +const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/; +const MAX_NAME_LENGTH = 64; +const MAX_DESCRIPTION_LENGTH = 1_024; + +const decodeSkillFrontmatter = Schema.decodeUnknownOption( + Schema.Struct({ name: Schema.String, description: Schema.String }), +); + +/** + * Reads SKILL.md as Kiro CLI 3.1.0 does: the file opens with `---`, the YAML + * runs to the closing `---` or the end of the file, and a skill without a + * valid `name` and a `description` is not loaded. + */ +function parseKiroSkill( + contents: string, +): { readonly name: string; readonly description: string } | undefined { + const opening = /^---[ \t]*\r?\n/.exec(contents); + if (opening === null) return undefined; + const rest = contents.slice(opening[0].length); + const closing = /^---[ \t]*\r?$/m.exec(rest); + let parsed: unknown; + try { + parsed = parseYamlDocument(closing === null ? rest : rest.slice(0, closing.index)); + } catch { + return undefined; + } + const frontmatter = Option.getOrUndefined(decodeSkillFrontmatter(parsed)); + if (frontmatter === undefined) return undefined; + const { name } = frontmatter; + // Kiro shows a block description on one line. + const description = frontmatter.description.replace(/\s+/g, " ").trim(); + return SKILL_NAME.test(name) && + name.length <= MAX_NAME_LENGTH && + description.length > 0 && + description.length <= MAX_DESCRIPTION_LENGTH + ? { name, description } + : undefined; +} + +const readSkillsRoot = Effect.fn("KiroSkills.readSkillsRoot")(function* ( + directory: string, + scope: "user" | "project", +): Effect.fn.Return, never, FileSystem.FileSystem | Path.Path> { + const fileSystem = yield* FileSystem.FileSystem; + const path = yield* Path.Path; + // A missing root, a stray file and an unreadable SKILL.md are all "no skill here". + const folders = yield* fileSystem + .readDirectory(directory) + .pipe(Effect.orElseSucceed((): Array => [])); + const skills: Array = []; + for (const folder of folders.toSorted()) { + const skillPath = path.join(directory, folder, "SKILL.md"); + const contents = yield* Effect.option(fileSystem.readFileString(skillPath)); + const skill = Option.isSome(contents) ? parseKiroSkill(contents.value) : undefined; + if (skill !== undefined) skills.push({ ...skill, path: skillPath, scope, enabled: true }); + } + return skills; +}); + +/** + * The skills a Kiro session in `cwd` loads: the account's cloud skills, then + * `~/.kiro/skills` (`KIRO_HOME` replaces `~/.kiro`), then the workspace's own + * `.kiro/skills` (Kiro reads no parent folder). A later skill replaces a + * same-named earlier one in its place, as in Kiro's list. + */ +export const discoverKiroSkills = Effect.fn("discoverKiroSkills")(function* (input: { + readonly cwd: string; + readonly environment: NodeJS.ProcessEnv; +}): Effect.fn.Return, never, FileSystem.FileSystem | Path.Path> { + const path = yield* Path.Path; + const home = + input.environment.HOME?.trim() || + input.environment.USERPROFILE?.trim() || + (yield* HostProcess.HomeDirectory); + const kiroHome = input.environment.KIRO_HOME?.trim() || path.join(home, ".kiro"); + const skills = new Map(); + for (const [kiroFolder, scope] of [ + // Kiro's own copy of the account's cloud skills, synced when a session starts. + [path.join(kiroHome, "cloud-cache", "resolved", "config", "user"), "user"], + [kiroHome, "user"], + [path.join(input.cwd, ".kiro"), "project"], + ] as const) { + for (const skill of yield* readSkillsRoot(path.join(kiroFolder, "skills"), scope)) { + skills.set(skill.name, skill); + } + } + return [...skills.values()]; +}); diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 744838ebefa9..319373bf9603 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1858,6 +1858,9 @@ importers: effect: specifier: 4.1.3 version: 4.1.3 + yaml: + specifier: ^2.9.0 + version: 2.9.0 devDependencies: '@effect/platform-node': specifier: 4.1.2