From 0e4ef427719449c221e8f7ee074a5527899e9aa2 Mon Sep 17 00:00:00 2001 From: eust-w Date: Wed, 4 Nov 2026 12:37:36 +0800 Subject: [PATCH] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20Unify=20project=20lessons?= =?UTF-8?q?=20into=20self-evolving=20project=20skills?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Lessons become skills with a category (workflow / pitfall / convention): one model, one prompt section, one permission rule. A repaired failure records or updates a pitfall skill deduplicated by failure signature; harvest sees every skill and may merge into an existing one; corroborated skills auto-activate per project (skillAutoActivation, default on). Runs given a skill are counted (skill_usage); platform-maintained skills retire after 3 failing runs in a row or 90 days unused. Skills can be imported from SKILL.md / zip, copied between projects and searched across projects. Migration 004 converts existing lesson rows to skills. Co-Authored-By: Claude Opus 5.5 (1M context) --- .../db/migrations/004_lessons_to_skills.sql | 32 + apps/api/src/domain/control-plane.ts | 9 +- apps/api/src/domain/lessons.ts | 90 --- apps/api/src/domain/releases.ts | 4 +- apps/api/src/domain/skill-files.ts | 282 ++++++++ apps/api/src/domain/skills.ts | 640 +++++++++++++++--- apps/api/src/http.ts | 37 +- apps/api/src/main.ts | 2 + apps/worker/src/common.ts | 3 +- apps/worker/src/executor.ts | 1 - packages/agent/src/prompt.ts | 37 +- packages/agent/test/prompt.test.ts | 26 +- packages/contracts/src/index.ts | 59 +- scripts/cluster-poc-projects.ts | 1 + tests/local-loop.test.ts | 105 ++- tests/migrations.test.ts | 6 + tests/skills.test.ts | 473 +++++++++++++ 17 files changed, 1504 insertions(+), 303 deletions(-) create mode 100644 apps/api/src/db/migrations/004_lessons_to_skills.sql delete mode 100644 apps/api/src/domain/lessons.ts create mode 100644 apps/api/src/domain/skill-files.ts create mode 100644 tests/skills.test.ts diff --git a/apps/api/src/db/migrations/004_lessons_to_skills.sql b/apps/api/src/db/migrations/004_lessons_to_skills.sql new file mode 100644 index 0000000..936ab29 --- /dev/null +++ b/apps/api/src/db/migrations/004_lessons_to_skills.sql @@ -0,0 +1,32 @@ +-- Project lessons become project skills: one kind of project know-how, one prompt section. +-- Data changes below must see every tenant: fail instead of silently skipping rows under RLS. +SET LOCAL row_security = off; + +-- A lesson recorded from a repaired failure becomes a pitfall skill, a convention one a convention +-- skill. Each keeps its id, project, status, author and source run; its name is made unique from +-- its id, its summary is both its description (shortened) and its content. +INSERT INTO entities(tenant_id, kind, id, version, data, created_at) +SELECT l.tenant_id, 'skill', l.id, 1, + jsonb_strip_nulls(jsonb_build_object( + 'id', l.id, + 'tenantId', l.tenant_id, + 'createdAt', l.data->>'createdAt', + 'updatedAt', coalesce(l.data->>'updatedAt', l.data->>'createdAt'), + 'version', 1, + 'projectId', l.data->>'projectId', + 'name', CASE WHEN l.data->>'kind' = 'convention' THEN 'convention-' ELSE 'pitfall-' END + || substr(regexp_replace(lower(l.id), '[^a-z0-9]', '', 'g'), 1, 12), + 'description', left(regexp_replace(btrim(l.data->>'summary'), '\s+', ' ', 'g'), 300), + 'content', btrim(l.data->>'summary'), + 'category', CASE WHEN l.data->>'kind' = 'convention' THEN 'convention' ELSE 'pitfall' END, + 'status', CASE WHEN l.data->>'status' = 'disabled' THEN 'disabled' ELSE 'active' END, + 'sourceRunIds', CASE WHEN l.data ? 'sourceRunId' THEN jsonb_build_array(l.data->>'sourceRunId') + ELSE '[]'::jsonb END, + 'createdBy', coalesce(l.data->>'createdBy', 'wishforge') + )), + l.created_at + FROM entities l + WHERE l.kind = 'lesson' AND coalesce(btrim(l.data->>'summary'), '') <> '' +ON CONFLICT (tenant_id, kind, id) DO NOTHING; + +DELETE FROM entities WHERE kind = 'lesson'; diff --git a/apps/api/src/domain/control-plane.ts b/apps/api/src/domain/control-plane.ts index f78077e..207e53a 100644 --- a/apps/api/src/domain/control-plane.ts +++ b/apps/api/src/domain/control-plane.ts @@ -52,8 +52,7 @@ import { Artifacts } from './artifacts.js'; import { providerProxyConfigured } from './provider-proxy.js'; import { assertVerificationProfile, verificationPolicyDigest } from './verification-policy.js'; import { IntegrationLeases } from './integration-lease.js'; -import { captureLesson, projectLessons } from './lessons.js'; -import { projectSkills } from './skills.js'; +import { learnFromRun, projectSkills, recordSkillUse } from './skills.js'; import { describeProviderEvent } from './provider-events.js'; import { backendDefined, personWishScope, requirePermission, wishScopeOf } from './permissions.js'; @@ -1135,6 +1134,9 @@ export class ControlPlane { } if (run.status === 'running') run.lastActiveAt = now(); else run.lastActiveAt = undefined; + // The executor starts an implementation round with the project's skills in its prompt. + if (actor.kind === 'worker' && run.stage === 'implement' && run.status === 'running') + await recordSkillUse(tx, run); await tx.put('run', run); await tx.event(id, 'run.transition', redact(data.message), { stage: run.stage, @@ -1356,7 +1358,7 @@ export class ControlPlane { clearWaiting(run); if (run.lease) run.lease.expiresAt = now(); if (!run.providerProxyActiveRequest) run.reservedTokens = 0; - await captureLesson(tx, run); + await learnFromRun(tx, run); await tx.event( run.id, 'run.succeeded', @@ -1405,7 +1407,6 @@ export class ControlPlane { verificationProfileRequired: isProduction(this.env), connectionId: connection?.id ?? null, bundleConfig: await resolveBundle(tx, run.bundleVersion), - lessons: await projectLessons(tx, run.projectId), skills: await projectSkills(tx, run.projectId), delivery: { release, diff --git a/apps/api/src/domain/lessons.ts b/apps/api/src/domain/lessons.ts deleted file mode 100644 index 6c40335..0000000 --- a/apps/api/src/domain/lessons.ts +++ /dev/null @@ -1,90 +0,0 @@ -import { z } from 'zod'; -import { lessonInput, type Actor, type Lesson, type Run } from '@wishforge/contracts'; -import { LESSON_LIMIT, repairLesson } from '@wishforge/agent'; -import type { Store, Transaction } from '../db/store.js'; -import { must, projectAccess, record, touch } from './control-plane.js'; -import { redact, requireHuman, requireRole } from './policy.js'; - -const statusInput = z.object({ status: z.enum(['active', 'disabled']) }).strict(); -const newestFirst = (a: Lesson, b: Lesson) => b.createdAt.localeCompare(a.createdAt); - -/** Active lessons of a project, most recent first, as they are injected into prompts. */ -export async function projectLessons(tx: Transaction, projectId: string): Promise { - return (await tx.list('lesson', { projectId, status: 'active' })) - .sort(newestFirst) - .slice(0, LESSON_LIMIT) - .map(lesson => lesson.summary); -} - -/** A run that needed a repair round before it succeeded leaves a lesson for later runs of its project. */ -export async function captureLesson(tx: Transaction, run: Run) { - if (!run.repairCount || !run.lastFailure) return; - const lessons = await tx.list('lesson', { projectId: run.projectId }); - if (lessons.some(lesson => lesson.sourceRunId === run.id && lesson.kind === 'repair')) return; - const lesson: Lesson = { - ...record(run.tenantId), - projectId: run.projectId, - kind: 'repair', - summary: redact(repairLesson(run.lastFailure, run.implementationSummary)), - sourceRunId: run.id, - status: 'active', - createdBy: 'wishforge', - }; - await tx.put('lesson', lesson); - await tx.event(run.id, 'lesson.recorded', 'Recorded a project lesson from the repaired failure.', { - lessonId: lesson.id, - }); -} - -/** Owners and admins review what later runs will be told. */ -export class Lessons { - constructor(private readonly store: Store) {} - async list(actor: Actor, projectId: string) { - return this.store.read(actor.tenantId, async tx => { - await projectAccess(tx, actor, projectId); - return (await tx.list('lesson', { projectId })).sort(newestFirst); - }); - } - async create(actor: Actor, projectId: string, input: unknown) { - this.authorize(actor); - const { summary } = lessonInput.parse(input); - return this.store.transaction(actor.tenantId, async tx => { - await projectAccess(tx, actor, projectId); - const lesson: Lesson = { - ...record(actor.tenantId), - projectId, - kind: 'convention', - summary: redact(summary), - status: 'active', - createdBy: actor.userId, - }; - await tx.put('lesson', lesson); - return lesson; - }); - } - async setStatus(actor: Actor, id: string, input: unknown) { - this.authorize(actor); - const { status } = statusInput.parse(input); - return this.store.transaction(actor.tenantId, async tx => { - const lesson = await must(tx, 'lesson', id); - await projectAccess(tx, actor, lesson.projectId); - if (lesson.status === status) return lesson; - const next = { ...touch(lesson), status }; - await tx.put('lesson', next); - return next; - }); - } - async remove(actor: Actor, id: string) { - this.authorize(actor); - return this.store.transaction(actor.tenantId, async tx => { - const lesson = await must(tx, 'lesson', id); - await projectAccess(tx, actor, lesson.projectId); - await tx.remove('lesson', id); - return { deleted: true }; - }); - } - private authorize(actor: Actor) { - requireRole(actor, ['owner', 'admin']); - requireHuman(actor); - } -} diff --git a/apps/api/src/domain/releases.ts b/apps/api/src/domain/releases.ts index 8b12e70..c3df496 100644 --- a/apps/api/src/domain/releases.ts +++ b/apps/api/src/domain/releases.ts @@ -32,7 +32,7 @@ import { setWaiting, clearWaiting, } from './control-plane.js'; -import { captureLesson } from './lessons.js'; +import { learnFromRun } from './skills.js'; import { digest, releaseRisk, requireRole, requireHuman } from './policy.js'; import { requirePermission } from './permissions.js'; @@ -542,7 +542,7 @@ export class Releases { run.stage = 'accept'; clearWaiting(run); run.reservedTokens = 0; - await captureLesson(tx, run); + await learnFromRun(tx, run); run.lastActiveAt = undefined; if (run.lease) run.lease.expiresAt = now(); await tx.put('release', touch(release)); diff --git a/apps/api/src/domain/skill-files.ts b/apps/api/src/domain/skill-files.ts new file mode 100644 index 0000000..5f53c0b --- /dev/null +++ b/apps/api/src/domain/skill-files.ts @@ -0,0 +1,282 @@ +import { crc32, inflateRawSync } from 'node:zlib'; +import { + DomainError, + SKILL_CONTENT_LIMIT, + skillCategories, + skillName, + type Skill, + type SkillCategory, +} from '@wishforge/contracts'; + +/** + * Skills as files: SKILL.md with its name and purpose up front, one directory per skill in a zip, + * as Claude Code's .claude/skills/ expects. Export writes them; import reads them back, from this + * platform's exports or from skills written elsewhere. + */ + +/** What an import may hold. Larger archives and files are refused rather than read partly. */ +export const SKILL_IMPORT_LIMITS = { + /** A zip as uploaded (before base64). */ + archiveBytes: 512 * 1024, + /** Entries a zip's directory may list, skills or not. */ + entries: 500, + /** Skills one import may add. */ + skills: 50, + /** One SKILL.md, uncompressed. */ + fileBytes: 64 * 1024, + /** Every SKILL.md of an archive together, uncompressed. */ + totalBytes: 2 * 1024 * 1024, +} as const; + +/** One skill read from a file, before it joins a project. */ +export interface SkillFile { + name: string; + description: string; + content: string; + category: SkillCategory; + /** Where it came from: the file name or the path inside the archive. */ + source: string; +} + +/** A skill as Claude Code and other agents read it: SKILL.md with its name and purpose up front. */ +export function skillMarkdown(skill: Pick) { + const description = skill.description.replace(/\s+/g, ' ').trim(); + // Other tools ignore metadata; an import here restores what kind of skill it was. + const metadata = + skill.category && skill.category !== 'workflow' ? `metadata:\n wishforge-category: ${skill.category}\n` : ''; + return `---\nname: ${skill.name}\ndescription: ${JSON.stringify(description)}\n${metadata}---\n\n${skill.content.trim()}\n`; +} + +const invalid = (source: string, reason: string) => new DomainError('INVALID_SKILL_FILE', `${source}: ${reason}`, 400); + +/** A YAML scalar as SKILL.md front matter writes it: plain, single- or double-quoted. */ +function scalar(raw: string, source: string): string { + const value = raw.trim(); + if (value.startsWith('"')) { + try { + const parsed: unknown = JSON.parse(value); + if (typeof parsed === 'string') return parsed; + } catch {} + throw invalid(source, 'a quoted value in the front matter is not closed'); + } + if (value.startsWith("'")) { + if (!value.endsWith("'") || value.length < 2) + throw invalid(source, 'a quoted value in the front matter is not closed'); + return value.slice(1, -1).replaceAll("''", "'"); + } + // A comment after a plain value is not part of it. + return value.replace(/\s+#.*$/, ''); +} + +/** + * The front matter keys SKILL.md uses: top-level scalars, block scalars (`|`, `>`) and one level + * of nesting (`metadata:`). Anything richer is ignored rather than misread. + */ +function frontMatter(lines: string[], source: string) { + const fields: Record = {}; + const nested: Record = {}; + for (let i = 0; i < lines.length; i++) { + const line = lines[i]!; + if (!line.trim() || line.trimStart().startsWith('#')) continue; + const match = /^([A-Za-z0-9_-]+):(.*)$/.exec(line); + if (!match) continue; + const [, key, rest] = match as unknown as [string, string, string]; + const indented: string[] = []; + while (i + 1 < lines.length && (/^\s+\S/.test(lines[i + 1]!) || !lines[i + 1]!.trim())) indented.push(lines[++i]!); + const marker = rest.trim(); + if (/^[|>][+-]?$/.test(marker)) { + const body = indented.map(item => item.trim()); + fields[key] = (marker.startsWith('>') ? body.join(' ') : body.join('\n')).trim(); + } else if (marker) { + fields[key] = [scalar(marker, source), ...indented.map(item => item.trim())].join(' ').trim(); + } else + for (const item of indented) { + const child = /^\s+([A-Za-z0-9_-]+):(.*)$/.exec(item); + if (child?.[2]?.trim()) nested[`${key}.${child[1]}`] = scalar(child[2], source); + } + } + return { ...nested, ...fields }; +} + +/** Lowercase words joined by hyphens, from whatever a file or directory was called. */ +export function skillSlug(value: string) { + return value + .normalize('NFKD') + .toLowerCase() + .replace(/[^a-z0-9]+/g, '-') + .replace(/^-+|-+$/g, '') + .slice(0, 64) + .replace(/-+$/, ''); +} + +/** The skill a path names when its front matter does not: `name/SKILL.md`, `name.SKILL.md` or `name.md`. */ +function nameFromPath(source: string) { + const parts = source.split('/').filter(Boolean); + const file = parts.at(-1) ?? ''; + if (/^skill\.md$/i.test(file)) return parts.at(-2) ?? ''; + return file.replace(/(\.skill)?\.md$/i, ''); +} + +/** Reads one SKILL.md; `source` names it in errors and supplies the name when the file has none. */ +export function parseSkillMarkdown(text: string, source: string): SkillFile { + const normalized = text.replace(/^\uFEFF/, '').replace(/\r\n?/g, '\n'); + if (Buffer.byteLength(normalized, 'utf8') > SKILL_IMPORT_LIMITS.fileBytes) + throw invalid(source, `larger than ${SKILL_IMPORT_LIMITS.fileBytes / 1024} KiB`); + let fields: Record = {}; + let body = normalized; + if (normalized.startsWith('---\n')) { + const end = normalized.indexOf('\n---', 4); + if (end === -1) throw invalid(source, 'the front matter is not closed with ---'); + fields = frontMatter(normalized.slice(4, end).split('\n'), source); + body = normalized.slice(end + 4).replace(/^[^\n]*\n?/, ''); + } + const content = body.trim(); + if (!content) throw invalid(source, 'the skill has no instructions after its front matter'); + if (content.length > SKILL_CONTENT_LIMIT) + throw invalid(source, `the instructions are longer than ${SKILL_CONTENT_LIMIT} characters`); + const rawName = fields.name?.trim() || nameFromPath(source); + const name = skillName.safeParse(rawName).success ? rawName : skillSlug(rawName); + if (!name) throw invalid(source, 'the skill has no usable name'); + // Skills written elsewhere sometimes leave the description out; their first line says what they are for. + const description = (fields.description || content.split('\n').find(line => line.trim()) || '') + .replace(/^#+\s*/, '') + .replace(/\s+/g, ' ') + .trim() + .slice(0, 500); + if (!description) throw invalid(source, 'the skill has no description'); + const category = fields['metadata.wishforge-category'] ?? fields.category; + return { + name, + description, + content, + category: (skillCategories as readonly string[]).includes(category ?? '') + ? (category as SkillCategory) + : 'workflow', + source, + }; +} + +/** A zip archive of text files, stored without compression: the format every system opens. */ +export function zipFiles(files: { path: string; content: string }[], at = new Date()): Buffer { + const time = ((at.getHours() << 11) | (at.getMinutes() << 5) | (at.getSeconds() >> 1)) & 0xffff; + const date = (((at.getFullYear() - 1980) << 9) | ((at.getMonth() + 1) << 5) | at.getDate()) & 0xffff; + const locals: Buffer[] = []; + const centrals: Buffer[] = []; + let offset = 0; + for (const file of files) { + const name = Buffer.from(file.path, 'utf8'); + const data = Buffer.from(file.content, 'utf8'); + const checksum = crc32(data); + const local = Buffer.alloc(30); + local.writeUInt32LE(0x04034b50, 0); + local.writeUInt16LE(20, 4); + local.writeUInt16LE(0x0800, 6); // UTF-8 names + local.writeUInt16LE(0, 8); + local.writeUInt16LE(time, 10); + local.writeUInt16LE(date, 12); + local.writeUInt32LE(checksum, 14); + local.writeUInt32LE(data.length, 18); + local.writeUInt32LE(data.length, 22); + local.writeUInt16LE(name.length, 26); + local.writeUInt16LE(0, 28); + const central = Buffer.alloc(46); + central.writeUInt32LE(0x02014b50, 0); + central.writeUInt16LE(20, 4); + central.writeUInt16LE(20, 6); + central.writeUInt16LE(0x0800, 8); + central.writeUInt16LE(0, 10); + central.writeUInt16LE(time, 12); + central.writeUInt16LE(date, 14); + central.writeUInt32LE(checksum, 16); + central.writeUInt32LE(data.length, 20); + central.writeUInt32LE(data.length, 24); + central.writeUInt16LE(name.length, 28); + central.writeUInt32LE(offset, 42); + locals.push(local, name, data); + centrals.push(central, name); + offset += local.length + name.length + data.length; + } + const directory = Buffer.concat(centrals); + const end = Buffer.alloc(22); + end.writeUInt32LE(0x06054b50, 0); + end.writeUInt16LE(files.length, 8); + end.writeUInt16LE(files.length, 10); + end.writeUInt32LE(directory.length, 12); + end.writeUInt32LE(offset, 16); + return Buffer.concat([...locals, directory, end]); +} + +const isSkillFile = (path: string) => /(^|\/)skill\.md$/i.test(path) || /\.skill\.md$/i.test(path); + +/** + * The SKILL.md files of a zip, stored or deflated, as this platform and common tools write them. + * Other files (scripts, references) are counted, not read: a skill here is its instructions. + * Encrypted, multi-disk and ZIP64 archives, and anything beyond the limits, are refused. + */ +export function readSkillArchive(archive: Buffer): { files: { path: string; content: string }[]; ignored: number } { + const bad = (reason: string) => new DomainError('INVALID_SKILL_ARCHIVE', `The zip archive ${reason}`, 400); + if (archive.length > SKILL_IMPORT_LIMITS.archiveBytes) + throw bad(`is larger than ${SKILL_IMPORT_LIMITS.archiveBytes / 1024} KiB`); + let end = -1; + for (let i = archive.length - 22; i >= Math.max(0, archive.length - 22 - 0xffff); i--) + if (archive.readUInt32LE(i) === 0x06054b50) { + end = i; + break; + } + if (end === -1) throw bad('cannot be read: it is not a zip file'); + const count = archive.readUInt16LE(end + 10); + const size = archive.readUInt32LE(end + 12); + const start = archive.readUInt32LE(end + 16); + if (archive.readUInt16LE(end + 4) !== 0 || count === 0xffff || start === 0xffffffff) + throw bad('uses multiple disks or ZIP64, which is not supported'); + if (count > SKILL_IMPORT_LIMITS.entries) throw bad(`has more than ${SKILL_IMPORT_LIMITS.entries} entries`); + if (start + size > end) throw bad('is damaged'); + const files: { path: string; content: string }[] = []; + let ignored = 0; + let total = 0; + let at = start; + for (let n = 0; n < count; n++) { + if (at + 46 > end || archive.readUInt32LE(at) !== 0x02014b50) throw bad('is damaged'); + const flags = archive.readUInt16LE(at + 8); + const method = archive.readUInt16LE(at + 10); + const checksum = archive.readUInt32LE(at + 16); + const compressed = archive.readUInt32LE(at + 20); + const uncompressed = archive.readUInt32LE(at + 24); + const nameLength = archive.readUInt16LE(at + 28); + const extraLength = archive.readUInt16LE(at + 30); + const commentLength = archive.readUInt16LE(at + 32); + const local = archive.readUInt32LE(at + 42); + const path = archive.subarray(at + 46, at + 46 + nameLength).toString('utf8'); + at += 46 + nameLength + extraLength + commentLength; + if (path.endsWith('/')) continue; + // macOS adds resource forks under __MACOSX/; they are not skills. + if (!isSkillFile(path) || path.startsWith('__MACOSX/')) { + ignored++; + continue; + } + if (flags & 1) throw bad(`is encrypted (${path})`); + if (uncompressed > SKILL_IMPORT_LIMITS.fileBytes) + throw bad(`holds ${path}, larger than ${SKILL_IMPORT_LIMITS.fileBytes / 1024} KiB`); + total += uncompressed; + if (total > SKILL_IMPORT_LIMITS.totalBytes) + throw bad(`holds more than ${SKILL_IMPORT_LIMITS.totalBytes / 1024 / 1024} MiB of skills`); + if (local + 30 > end || archive.readUInt32LE(local) !== 0x04034b50) throw bad('is damaged'); + const dataStart = local + 30 + archive.readUInt16LE(local + 26) + archive.readUInt16LE(local + 28); + if (dataStart + compressed > end) throw bad('is damaged'); + const raw = archive.subarray(dataStart, dataStart + compressed); + let data: Buffer; + if (method === 0) data = raw; + else if (method === 8) + try { + data = inflateRawSync(raw, { maxOutputLength: SKILL_IMPORT_LIMITS.fileBytes }); + } catch { + throw bad(`holds ${path}, which cannot be decompressed`); + } + else throw bad(`compresses ${path} in a way that is not supported`); + if (data.length !== uncompressed || crc32(data) !== checksum) throw bad(`holds ${path}, which is damaged`); + files.push({ path, content: data.toString('utf8') }); + if (files.length > SKILL_IMPORT_LIMITS.skills) + throw bad(`holds more than ${SKILL_IMPORT_LIMITS.skills} skills; import them in parts`); + } + return { files, ignored }; +} diff --git a/apps/api/src/domain/skills.ts b/apps/api/src/domain/skills.ts index e2c7b73..7deec1e 100644 --- a/apps/api/src/domain/skills.ts +++ b/apps/api/src/domain/skills.ts @@ -1,103 +1,273 @@ -import { crc32 } from 'node:zlib'; import { z } from 'zod'; import { askClaude } from '@wishforge/runtime'; -import { SKILL_LIMIT, type PromptSkill } from '@wishforge/agent'; +import { repairLesson, selectSkills, type PromptSkill } from '@wishforge/agent'; import { DomainError, SKILL_CONTENT_LIMIT, + skillCategories, skillInput, skillName, skillUpdateInput, type Actor, type CodeReview, + type FailureSummary, type Project, type Run, type Skill, type SkillHarvest, + type SkillUsage, } from '@wishforge/contracts'; import type { Store, Transaction } from '../db/store.js'; -import { must, projectAccess, record, touch } from './control-plane.js'; +import { idempotent, must, now, projectAccess, record, terminal, touch } from './control-plane.js'; import { nativeClaudeEnabled } from './local-execution.js'; import { wishScopeOf } from './permissions.js'; import { redact, requireHuman } from './policy.js'; +import { + SKILL_IMPORT_LIMITS, + parseSkillMarkdown, + readSkillArchive, + skillMarkdown, + skillSlug, + zipFiles, + type SkillFile, +} from './skill-files.js'; +import { dispatchTenants } from '../tenants.js'; + +export { skillMarkdown, zipFiles } from './skill-files.js'; const recentlyChanged = (a: Skill, b: Skill) => b.updatedAt.localeCompare(a.updatedAt); -/** Active skills of a project, most recently changed first, as they enter prompts. */ +/** A pitfall records at most this many repaired failures, most recent first. */ +const PITFALL_ENTRIES = 8; +/** A skill remembers at most this many runs it was learned from. */ +const SOURCE_RUNS = 20; +/** A platform-maintained skill is retired after this many settled runs in a row that used it failed. */ +export const RETIRE_AFTER_FAILURES = 3; +/** A platform-maintained skill no run was given for this long, while the project kept running, is retired. */ +export const RETIRE_UNUSED_DAYS = 90; + +/** Whether the project lets the platform activate corroborated skills itself (absent: yes). */ +export const autoActivation = (project: Pick) => project.skillAutoActivation !== false; +/** Learned by the platform and not since written by a person: the platform may rewrite or retire it. */ +export const platformMaintained = (skill: Skill) => skill.createdBy === 'wishforge' && !skill.updatedBy; +/** A change to a skill's bookkeeping only: it keeps its place among the most recently changed. */ +const counted = (skill: Skill, changes: Partial): Skill => ({ + ...skill, + ...changes, + version: skill.version + 1, +}); +const lastRuns = (ids: string[], runId: string) => [...ids.filter(id => id !== runId), runId].slice(-SOURCE_RUNS); + +/** Active skills of a project as they enter prompts: most recently changed first, within the limits. */ +async function promptSkillsOf(tx: Transaction, projectId: string): Promise { + return selectSkills((await tx.list('skill', { projectId, status: 'active' })).sort(recentlyChanged)); +} export async function projectSkills(tx: Transaction, projectId: string): Promise { - return (await tx.list('skill', { projectId, status: 'active' })) - .sort(recentlyChanged) - .slice(0, SKILL_LIMIT) - .map(({ name, description, content }) => ({ name, description, content })); + return (await promptSkillsOf(tx, projectId)).map(({ name, description, content }) => ({ + name, + description, + content, + })); } -/** A skill as Claude Code and other agents read it: SKILL.md with its name and purpose up front. */ -export function skillMarkdown(skill: Pick) { - const description = skill.description.replace(/\s+/g, ' ').trim(); - return `---\nname: ${skill.name}\ndescription: ${JSON.stringify(description)}\n---\n\n${skill.content.trim()}\n`; +/** + * Notes which skills a run's implementation is given, once per run and skill: called when an + * executor takes the run at its implementation stage, just before it reads them. + */ +export async function recordSkillUse(tx: Transaction, run: Run) { + const skills = await promptSkillsOf(tx, run.projectId); + const usage = await tx.get('skill_usage', run.id); + const known = new Set(usage?.skillIds ?? []); + const fresh = skills.filter(skill => !known.has(skill.id)); + if (!fresh.length) return; + const time = now(); + for (const skill of fresh) + await tx.put('skill', counted(skill, { useCount: (skill.useCount ?? 0) + 1, lastUsedAt: time })); + const next: SkillUsage = { + ...(usage ? touch(usage) : { ...record(run.tenantId), id: run.id }), + runId: run.id, + projectId: run.projectId, + skillIds: [...known, ...fresh.map(skill => skill.id)], + }; + await tx.put('skill_usage', next); } -/** A zip archive of text files, stored without compression: the format every system opens. */ -export function zipFiles(files: { path: string; content: string }[], at = new Date()): Buffer { - const time = ((at.getHours() << 11) | (at.getMinutes() << 5) | (at.getSeconds() >> 1)) & 0xffff; - const date = (((at.getFullYear() - 1980) << 9) | ((at.getMonth() + 1) << 5) | at.getDate()) & 0xffff; - const locals: Buffer[] = []; - const centrals: Buffer[] = []; - let offset = 0; - for (const file of files) { - const name = Buffer.from(file.path, 'utf8'); - const data = Buffer.from(file.content, 'utf8'); - const checksum = crc32(data); - const local = Buffer.alloc(30); - local.writeUInt32LE(0x04034b50, 0); - local.writeUInt16LE(20, 4); - local.writeUInt16LE(0x0800, 6); // UTF-8 names - local.writeUInt16LE(0, 8); - local.writeUInt16LE(time, 10); - local.writeUInt16LE(date, 12); - local.writeUInt32LE(checksum, 14); - local.writeUInt32LE(data.length, 18); - local.writeUInt32LE(data.length, 22); - local.writeUInt16LE(name.length, 26); - local.writeUInt16LE(0, 28); - const central = Buffer.alloc(46); - central.writeUInt32LE(0x02014b50, 0); - central.writeUInt16LE(20, 4); - central.writeUInt16LE(20, 6); - central.writeUInt16LE(0x0800, 8); - central.writeUInt16LE(0, 10); - central.writeUInt16LE(time, 12); - central.writeUInt16LE(date, 14); - central.writeUInt32LE(checksum, 16); - central.writeUInt32LE(data.length, 20); - central.writeUInt32LE(data.length, 24); - central.writeUInt16LE(name.length, 28); - central.writeUInt32LE(offset, 42); - locals.push(local, name, data); - centrals.push(central, name); - offset += local.length + name.length + data.length; +/** + * Counts how a finished run that was given skills ended. A success resets each skill's failure + * streak; a failure (or a cancel after a failed check) extends it, and a platform-maintained skill + * whose streak reaches RETIRE_AFTER_FAILURES is disabled. A cancel without a failure counts for + * neither: the person changed their mind, not the skill. + */ +export async function settleSkillUsage(tx: Transaction, run: Run) { + const usage = await tx.get('skill_usage', run.id); + if (!usage || usage.outcome || !terminal(run)) return; + const outcome: NonNullable = + run.status === 'succeeded' + ? 'succeeded' + : run.status === 'failed' || run.repairCount > 0 || run.lastFailure + ? 'failed' + : 'neutral'; + await tx.put('skill_usage', { ...touch(usage), outcome }); + if (outcome === 'neutral') return; + const retired: Skill[] = []; + for (const id of usage.skillIds) { + const skill = await tx.get('skill', id); + if (!skill) continue; + let next = + outcome === 'succeeded' + ? counted(skill, { successCount: (skill.successCount ?? 0) + 1, failureStreak: 0 }) + : counted(skill, { + failureCount: (skill.failureCount ?? 0) + 1, + failureStreak: (skill.failureStreak ?? 0) + 1, + }); + if ( + outcome === 'failed' && + next.status === 'active' && + platformMaintained(next) && + (next.failureStreak ?? 0) >= RETIRE_AFTER_FAILURES + ) { + next = { ...touch(next), status: 'disabled', retiredAt: now(), retiredReason: 'failing' }; + retired.push(next); + } + await tx.put('skill', next); } - const directory = Buffer.concat(centrals); - const end = Buffer.alloc(22); - end.writeUInt32LE(0x06054b50, 0); - end.writeUInt16LE(files.length, 8); - end.writeUInt16LE(files.length, 10); - end.writeUInt32LE(directory.length, 12); - end.writeUInt32LE(offset, 16); - return Buffer.concat([...locals, directory, end]); + if (retired.length) + await tx.event( + run.id, + 'skill.retired', + `Disabled ${retired.map(skill => skill.name).join(', ')}: the last ${RETIRE_AFTER_FAILURES} runs that used ${retired.length > 1 ? 'them' : 'it'} failed.`, + { skillIds: retired.map(skill => skill.id), reason: 'failing' }, + ); } -export const HARVEST_RULES = `你是一名资深工程师,负责为一个软件项目沉淀"技能"(skill):以后在这个项目里做类似工作时,编码 Agent 可以直接照做的、可复用的做法。你会拿到一次已完成的工作记录(需求、验收标准、实现总结、改动的文件、遇到的失败和审核意见)以及项目里已有的技能。 +/** + * What identifies a failure across runs: the failing command, or the conflicting or out-of-scope + * files. The same failure in a later run updates the same pitfall instead of adding another. + */ +export function failureSignature(failure: FailureSummary): string { + const words = (text: string) => text.toLowerCase().split(/\s+/).filter(Boolean); + if (failure.kind === 'integration_conflict' || failure.kind === 'scope') + return `${failure.kind}:${[...new Set(words(failure.outputTail))].sort().join(' ')}`.slice(0, 500); + return `${failure.kind}:${words((failure.argv ?? []).join(' ')).join(' ')}`.slice(0, 500); +} + +const PITFALL_HEADER = 'Earlier runs of this project failed here, and a repair round fixed it. Most recent first:'; + +/** The name and purpose of a pitfall about a failure. */ +function pitfallOf(failure: FailureSummary): { name: string; description: string } { + const command = `\`${failure.argv?.join(' ') ?? 'verification'}\``; + const files = failure.outputTail.split(/\s+/).filter(Boolean); + const subject = + failure.kind === 'integration_conflict' + ? `merge-conflict ${files[0] ?? ''}` + : failure.kind === 'scope' + ? 'frontend-scope' + : // Executables by name, not by where they are installed. + `${failure.kind === 'install' ? 'install ' : ''}${failure.argv?.map(word => word.split('/').pop()).join(' ') ?? 'verification'}`; + const description = + failure.kind === 'integration_conflict' + ? `When changing ${files.slice(0, 5).join(', ')}: merging into the target branch conflicted there before; how it was resolved.` + : failure.kind === 'scope' + ? 'For frontend-only wishes: backend files were changed by mistake before; how the change stayed in the frontend.' + : failure.kind === 'install' + ? `Before changing dependency manifests: installing with ${command} failed in earlier runs; what fixed it.` + : `Before finishing a change that ${command} checks: how it failed in earlier runs and what fixed it.`; + return { + name: `pitfall-${skillSlug(subject)}`.slice(0, 64).replace(/-+$/, ''), + description: description.slice(0, 500), + }; +} + +/** A pitfall's content with a new entry first: rebuilt when the platform keeps it, else prepended. */ +function withEntry(skill: Skill | undefined, entry: string) { + const line = `- ${entry}`; + if (!skill) return `${PITFALL_HEADER}\n\n${line}`; + if (!platformMaintained(skill)) return `${line}\n\n${skill.content}`.slice(0, SKILL_CONTENT_LIMIT); + const entries = skill.content.split('\n').filter(item => item.startsWith('- ')); + return `${PITFALL_HEADER}\n\n${[line, ...entries].slice(0, PITFALL_ENTRIES).join('\n')}`.slice( + 0, + SKILL_CONTENT_LIMIT, + ); +} + +/** A name the project does not use yet: the name itself, or with the next free number. */ +function freeName(name: string, taken: Set) { + if (!taken.has(name)) return name; + for (let n = 2; ; n++) { + const suffix = `-${n}`; + const candidate = `${name.slice(0, 64 - suffix.length).replace(/-+$/, '')}${suffix}`; + if (!taken.has(candidate)) return candidate; + } +} + +/** + * What a run that ended well teaches the project: its skills' counts include it, and when a + * repair round fixed a failure on the way, that failure becomes (or updates) a pitfall skill. + * The pitfall is active right away where the project lets the platform activate skills, since + * it is drawn from a verified failure and a verified fix; otherwise it waits for a person. + */ +export async function learnFromRun(tx: Transaction, run: Run) { + await settleSkillUsage(tx, run); + if (!run.repairCount || !run.lastFailure) return; + const project = await must(tx, 'project', run.projectId); + const skills = await tx.list('skill', { projectId: run.projectId }); + const signature = failureSignature(run.lastFailure); + const entry = redact(repairLesson(run.lastFailure, run.implementationSummary)); + const existing = skills.find(skill => skill.category === 'pitfall' && skill.signature === signature); + if (existing?.sourceRunIds.includes(run.id)) return; + const auto = autoActivation(project); + if (existing) { + const activate = existing.status === 'proposed' && auto; + const next: Skill = { + ...touch(existing), + content: withEntry(existing, entry), + sourceRunIds: lastRuns(existing.sourceRunIds, run.id), + ...(activate ? { status: 'active' as const } : {}), + }; + await tx.put('skill', next); + await tx.event( + run.id, + activate ? 'skill.activated' : 'skill.updated', + `${activate ? 'Activated' : 'Updated'} the pitfall skill ${next.name} with the repaired failure${next.status === 'disabled' ? '; it stays disabled' : ''}.`, + { skillId: next.id }, + ); + return; + } + const pitfall = pitfallOf(run.lastFailure); + const skill: Skill = { + ...record(run.tenantId), + projectId: run.projectId, + name: freeName(pitfall.name, new Set(skills.map(item => item.name))), + description: redact(pitfall.description), + content: withEntry(undefined, entry), + category: 'pitfall', + signature, + status: auto ? 'active' : 'proposed', + sourceRunIds: [run.id], + createdBy: 'wishforge', + }; + await tx.put('skill', skill); + await tx.event( + run.id, + auto ? 'skill.activated' : 'skill.proposed', + `Recorded the repaired failure as the pitfall skill ${skill.name}${auto ? '; later runs are told about it' : ', waiting for confirmation'}.`, + { skillId: skill.id, skillIds: [skill.id] }, + ); +} + +export const HARVEST_RULES = `你是一名资深工程师,负责为一个软件项目沉淀"技能"(skill):以后在这个项目里做类似工作时,编码 Agent 可以直接照做的、可复用的做法。你会拿到一次已完成的工作记录(需求、验收标准、实现总结、改动的文件、遇到的失败和审核意见)以及项目里已有的技能(category 为 workflow 是做法,pitfall 是踩过的坑和修法,convention 是项目约定;status 为 disabled 的是被停用的)。 1. 只提炼以后还会用到的、对这个项目具体有用的做法:例如这个项目里某类改动该改哪些地方、按什么步骤、要注意什么坑、怎么验证。不要把这一次的具体改动本身写成技能。 -2. 通用常识(写测试、读代码、遵守代码风格之类)不算技能。已有技能已经覆盖的不要重复。没有值得沉淀的就返回空数组,这完全正常。 -3. 最多返回 2 个。name 用小写英文单词和连字符,例如 lazy-load-page-css;description 用一两句话写"什么时候用它";content 用 Markdown 写做法:适用场景、步骤、注意事项、如何验证,具体到这个项目的目录、文件和命令,不超过 3000 字。 -4. 只写工作记录里有依据的内容,不要编造文件、命令或结论。 -5. 用和需求相同的语言写 description 和 content。`; +2. 通用常识(写测试、读代码、遵守代码风格之类)不算技能。已有技能已经覆盖的不要重复,被停用的也不要再提。没有值得沉淀的就返回空数组,这完全正常。 +3. 这次的工作让某个已有技能需要补充或修正时,不要新建:把 updates 设为那个技能的 name,name 也用它,content 写合并后的完整做法(保留原有仍然成立的内容)。全新的技能不要填 updates。 +4. 最多返回 2 个。name 用小写英文单词和连字符,例如 lazy-load-page-css;description 用一两句话写"什么时候用它";content 用 Markdown 写做法:适用场景、步骤、注意事项、如何验证,具体到这个项目的目录、文件和命令,不超过 3000 字。 +5. 只写工作记录里有依据的内容,不要编造文件、命令或结论。 +6. 用和需求相同的语言写 description 和 content。`; const proposal = z .object({ name: skillName, description: z.string().trim().min(1).max(500), content: z.string().trim().min(1).max(8000), + updates: z.string().trim().max(64).optional(), }) .strip(); const harvestSchema = { @@ -113,6 +283,7 @@ const harvestSchema = { name: { type: 'string', description: '小写英文单词和连字符' }, description: { type: 'string', description: '什么时候用它,一两句话' }, content: { type: 'string', description: 'Markdown 写的做法:适用场景、步骤、注意事项、如何验证' }, + updates: { type: 'string', description: '补充已有技能时填它的 name;新技能不填' }, }, required: ['name', 'description', 'content'], additionalProperties: false, @@ -134,13 +305,51 @@ function changedFiles(events: { type: string; message: string }[]) { return [...files].slice(0, 100); } +const listQuery = z + .object({ + projectId: z.string().min(1).max(128).optional(), + status: z.enum(['proposed', 'active', 'disabled']).optional(), + category: z.enum(skillCategories).optional(), + q: z.string().trim().max(200).optional(), + }) + .strict(); +const copyInput = z + .object({ skillIds: z.array(z.string().min(1).max(128)).min(1).max(100), projectId: z.string().min(1).max(128) }) + .strict(); +const importInput = z + .object({ + /** SKILL.md files as text, each with its file name. */ + files: z + .array(z.object({ path: z.string().min(1).max(300), content: z.string().max(SKILL_IMPORT_LIMITS.fileBytes) })) + .min(1) + .max(SKILL_IMPORT_LIMITS.skills) + .optional(), + /** A zip, base64-encoded, as the project export writes it. */ + archive: z + .string() + .max(Math.ceil((SKILL_IMPORT_LIMITS.archiveBytes * 4) / 3) + 4) + .optional(), + /** Imported skills are active unless they should wait for a confirmation first. */ + status: z.enum(['active', 'proposed']).default('active'), + }) + .strict() + .refine(value => Boolean(value.files) !== Boolean(value.archive), 'Provide either SKILL.md files or a zip archive'); +/** What adding skills to a project did: added (perhaps under another name), or left out and why. */ +export interface SkillTransfer { + created: Skill[]; + skipped: { name: string; source: string; reason: 'identical' | 'invalid'; detail?: string }[]; + /** Files in an archive that were not SKILL.md. */ + ignored: number; +} + /** At most this many proposals are worked out at once on the deployment's Claude account. */ const CONCURRENCY = 1; let running = 0; /** - * A project's skills: proposed by the platform from finished runs, confirmed, edited, disabled, - * deleted and exported by the people who wish for the project. + * Project skills, the one place a project's know-how lives: workflows the platform proposes from + * finished runs, pitfalls it records from repaired failures, conventions people write. Whoever may + * wish for a project confirms, edits, disables, deletes, copies, imports and exports them. */ export class Skills { constructor( @@ -154,6 +363,32 @@ export class Skills { return (await tx.list('skill', { projectId })).sort(recentlyChanged); }); } + /** Skills of every project the person may see, filtered as the knowledge base page asks. */ + async search(actor: Actor, query: unknown) { + const filter = listQuery.parse(query); + return this.store.read(actor.tenantId, async tx => { + if (filter.projectId) await projectAccess(tx, actor, filter.projectId); + const visible = new Set( + (await tx.list('project')) + .filter(p => ['owner', 'admin'].includes(actor.role) || p.memberIds.includes(actor.userId)) + .map(p => p.id), + ); + const words = filter.q?.toLowerCase(); + return ( + await tx.list('skill', { + ...(filter.projectId ? { projectId: filter.projectId } : {}), + ...(filter.status ? { status: filter.status } : {}), + }) + ) + .filter( + skill => + visible.has(skill.projectId) && + (!filter.category || (skill.category ?? 'workflow') === filter.category) && + (!words || [skill.name, skill.description, skill.content].some(text => text.toLowerCase().includes(words))), + ) + .sort(recentlyChanged); + }); + } async create(actor: Actor, projectId: string, input: unknown) { const data = skillInput.parse(input); return this.store.transaction(actor.tenantId, async tx => { @@ -166,6 +401,7 @@ export class Skills { name: data.name, description: redact(data.description), content: redact(data.content), + category: data.category, status: 'active', sourceRunIds: [], createdBy: actor.userId, @@ -174,21 +410,32 @@ export class Skills { return skill; }); } - /** Edits a skill; confirming a proposal is setting it active. */ + /** + * Edits a skill; confirming a proposal is setting it active. Changing what it says makes it a + * person's: the platform no longer rewrites or retires it. Enabling it again starts its failure + * streak afresh. + */ async update(actor: Actor, id: string, input: unknown) { const data = skillUpdateInput.parse(input); return this.store.transaction(actor.tenantId, async tx => { const skill = await must(tx, 'skill', id); this.authorize(actor, await projectAccess(tx, actor, skill.projectId)); if (data.name && data.name !== skill.name) await this.uniqueName(tx, skill.projectId, data.name, id); + const edited = Boolean(data.name || data.description || data.content || data.category); const next: Skill = { ...touch(skill), ...(data.name ? { name: data.name } : {}), ...(data.description ? { description: redact(data.description) } : {}), ...(data.content ? { content: redact(data.content) } : {}), + ...(data.category ? { category: data.category } : {}), ...(data.status ? { status: data.status } : {}), - updatedBy: actor.userId, + ...(edited ? { updatedBy: actor.userId } : {}), }; + if (data.status === 'active' && skill.status !== 'active') { + delete next.retiredAt; + delete next.retiredReason; + next.failureStreak = 0; + } await tx.put('skill', next); return next; }); @@ -211,7 +458,7 @@ export class Skills { } /** * The project's skills, proposals left out unless asked for, as a zip with a directory per skill - * holding its SKILL.md: what .claude/skills/ expects. + * holding its SKILL.md: what .claude/skills/ expects, and what import reads back. */ async exportAll(actor: Actor, projectId: string, includeProposed = false) { return this.store.read(actor.tenantId, async tx => { @@ -220,17 +467,125 @@ export class Skills { .filter(skill => skill.status === 'active' || (includeProposed && skill.status === 'proposed')) .sort((a, b) => a.name.localeCompare(b.name)); if (!skills.length) throw new DomainError('NO_SKILLS', 'This project has no skills to export', 404); - const slug = project.name - .normalize('NFKD') - .replace(/[^A-Za-z0-9]+/g, '-') - .replace(/^-|-$/g, '') - .toLowerCase(); return { - filename: `${slug || 'project'}-skills.zip`, + filename: `${skillSlug(project.name) || 'project'}-skills.zip`, content: zipFiles(skills.map(skill => ({ path: `${skill.name}/SKILL.md`, content: skillMarkdown(skill) }))), }; }); } + /** + * Adds skills from SKILL.md files or a zip of them (as export writes it) to a project. A skill + * the project already has word for word (description and content) is skipped, so importing the + * same files twice adds nothing; one whose name a different skill holds is added with the next + * free number. + */ + async importFiles(actor: Actor, projectId: string, input: unknown, key?: string): Promise { + const data = importInput.parse(input); + let sources: { path: string; content: string }[]; + let ignored = 0; + if (data.archive) { + const archive = Buffer.from(data.archive, 'base64'); + ({ files: sources, ignored } = readSkillArchive(archive)); + } else sources = data.files!; + const skipped: SkillTransfer['skipped'] = []; + const parsed: SkillFile[] = []; + for (const source of sources) + try { + parsed.push(parseSkillMarkdown(source.content, source.path)); + } catch (error) { + skipped.push({ + name: source.path, + source: source.path, + reason: 'invalid', + detail: error instanceof Error ? error.message : 'unreadable', + }); + } + if (!parsed.length) + throw new DomainError( + 'NO_SKILLS', + skipped.length ? `No skill could be read: ${skipped[0]!.detail}` : 'The archive holds no SKILL.md files', + 400, + ); + return this.store.transaction(actor.tenantId, async tx => { + this.authorize(actor, await projectAccess(tx, actor, projectId)); + return idempotent(tx, key && `skills-import:${actor.userId}:${projectId}:${key}`, data, async () => { + const result = await this.addSkills(tx, actor, projectId, parsed, () => data.status); + return { ...result, skipped: [...skipped, ...result.skipped], ignored }; + }); + }); + } + /** + * Copies skills to another project the person may shape, keeping what they say and whether they + * are active, but not their counts or the runs they came from. Collisions as for an import. + */ + async copy(actor: Actor, input: unknown, key?: string): Promise { + const data = copyInput.parse(input); + return this.store.transaction(actor.tenantId, async tx => { + this.authorize(actor, await projectAccess(tx, actor, data.projectId)); + return idempotent(tx, key && `skills-copy:${actor.userId}:${key}`, data, async () => { + const originals: Skill[] = []; + for (const id of new Set(data.skillIds)) { + const skill = await must(tx, 'skill', id); + await projectAccess(tx, actor, skill.projectId); + originals.push(skill); + } + const files = originals.map(skill => ({ + name: skill.name, + description: skill.description, + content: skill.content, + category: skill.category ?? 'workflow', + source: skill.id, + signature: skill.signature, + })); + const status = new Map(originals.map(skill => [skill.id, skill.status])); + return { + ...(await this.addSkills(tx, actor, data.projectId, files, file => status.get(file.source)!)), + ignored: 0, + }; + }); + }); + } + private async addSkills( + tx: Transaction, + actor: Actor, + projectId: string, + files: (SkillFile & { signature?: string })[], + status: (file: SkillFile) => Skill['status'], + ): Promise> { + const existing = await tx.list('skill', { projectId }); + const taken = new Set(existing.map(skill => skill.name)); + const created: Skill[] = []; + const skipped: SkillTransfer['skipped'] = []; + for (const file of files) { + const description = redact(file.description); + const content = redact(file.content); + // Saying exactly the same under whatever name: already there. + const same = [...existing, ...created].find( + skill => skill.description === description && skill.content === content, + ); + if (same) { + skipped.push({ name: file.name, source: file.source, reason: 'identical' }); + continue; + } + const name = freeName(file.name, taken); + taken.add(name); + const skill: Skill = { + ...record(actor.tenantId), + projectId, + name, + description, + content, + category: file.category, + ...(file.signature ? { signature: file.signature } : {}), + status: status(file), + sourceRunIds: [], + createdBy: actor.userId, + }; + await tx.put('skill', skill); + created.push(skill); + } + return { created, skipped }; + } available(tenantId: string) { return nativeClaudeEnabled(this.env, tenantId); } @@ -254,8 +609,12 @@ export class Skills { return this.harvest(actor.tenantId, runId); } /** - * Looks for skills in one run and stores what it finds as proposals; records that it looked, so - * the background harvest does not ask again. + * Looks for skills in one run. A proposal that names an existing skill (or is called like one) + * updates it instead of adding another: a proposal is rewritten, as is an active skill only the + * platform maintains where the project lets it activate skills; a skill a person wrote or + * disabled just records the run. A proposal seen in two succeeded runs becomes active where the + * project allows it. Records that it looked, so the background harvest does not ask again. + * Returns the skills it added or changed. */ async harvest(tenantId: string, runId: string): Promise { running++; @@ -285,9 +644,13 @@ export class Skills { ? { kind: run.lastFailure.kind, outputTail: run.lastFailure.outputTail.slice(-2000) } : undefined, reviewComments: reviews.flatMap(review => (review.comment ? [review.comment] : [])).slice(0, 5), - existingSkills: existing - .filter(skill => skill.status !== 'disabled') - .map(skill => ({ name: skill.name, description: skill.description, content: skill.content.slice(0, 1500) })), + existingSkills: existing.sort(recentlyChanged).map(skill => ({ + name: skill.name, + category: skill.category ?? 'workflow', + status: skill.status, + description: skill.description, + ...(skill.status === 'disabled' ? {} : { content: skill.content.slice(0, 1500) }), + })), }; const output = await this.ask({ binary: this.env.WF_CLAUDE_BIN!, @@ -307,35 +670,76 @@ export class Skills { }) .slice(0, 2); return await this.store.transaction(tenantId, async tx => { - const names = new Set((await tx.list('skill', { projectId: run.projectId })).map(skill => skill.name)); + const project = await must(tx, 'project', run.projectId); + const auto = autoActivation(project); + const skills = await tx.list('skill', { projectId: run.projectId }); + const byName = new Map(skills.map(skill => [skill.name, skill])); + const succeeded = async (ids: string[]) => { + let count = 0; + for (const id of ids) if ((await tx.get('run', id))?.status === 'succeeded') count++; + return count; + }; const created: Skill[] = []; + const updated: Skill[] = []; + const activated: Skill[] = []; for (const item of proposals) { - // A name the project uses already gets the next free number. - let name = item.name; - for (let n = 2; names.has(name); n++) name = `${item.name}-${n}`; - names.add(name); + const description = redact(item.description); + const content = redact(item.content).slice(0, SKILL_CONTENT_LIMIT); + const target = (item.updates && byName.get(item.updates)) || byName.get(item.name); + if (target) { + const rewrite = + target.status === 'proposed' || (target.status === 'active' && auto && platformMaintained(target)); + // Asked about the same run again: only new words are news. + const unchanged = !rewrite || (target.content === content && target.description === description); + if (target.sourceRunIds.includes(run.id) && unchanged) continue; + const sourceRunIds = lastRuns(target.sourceRunIds, run.id); + const activate = target.status === 'proposed' && auto && (await succeeded(sourceRunIds)) >= 2; + const next: Skill = rewrite + ? { ...touch(target), description, content, sourceRunIds } + : counted(target, { sourceRunIds }); + if (activate) next.status = 'active'; + await tx.put('skill', next); + byName.set(next.name, next); + (activate ? activated : updated).push(next); + continue; + } const skill: Skill = { ...record(tenantId), projectId: run.projectId, - name, - description: redact(item.description), - content: redact(item.content).slice(0, SKILL_CONTENT_LIMIT), + name: freeName(item.name, new Set(byName.keys())), + description, + content, + category: 'workflow', status: 'proposed', sourceRunIds: [run.id], createdBy: 'wishforge', }; await tx.put('skill', skill); + byName.set(skill.name, skill); created.push(skill); } - await this.recordHarvest(tx, run, { status: 'done', skillIds: created.map(skill => skill.id) }); + const changed = [...created, ...updated, ...activated]; + await this.recordHarvest(tx, run, { status: 'done', skillIds: changed.map(skill => skill.id) }); + const names = (list: Skill[]) => list.map(skill => skill.name).join(', '); if (created.length) await tx.event( run.id, 'skill.proposed', - `Proposed ${created.length} project skill${created.length > 1 ? 's' : ''}: ${created.map(skill => skill.name).join(', ')}`, + `Proposed ${created.length} project skill${created.length > 1 ? 's' : ''}: ${names(created)}`, { skillIds: created.map(skill => skill.id) }, ); - return created; + if (updated.length) + await tx.event(run.id, 'skill.updated', `Updated project skills with this run: ${names(updated)}`, { + skillIds: updated.map(skill => skill.id), + }); + if (activated.length) + await tx.event( + run.id, + 'skill.activated', + `Activated ${names(activated)}: proposed again by a second succeeded run.`, + { skillIds: activated.map(skill => skill.id) }, + ); + return changed; }); } catch (error) { await this.store @@ -387,6 +791,38 @@ export class Skills { await this.harvest(tenantId, next.id); return next.id; } + /** + * Keeps the skills honest: counts the outcome of every finished run that was given skills (a + * success counts when it happens; failures and cancels are found here), and retires + * platform-maintained skills no run was given for RETIRE_UNUSED_DAYS while their project kept + * running, crowded out by newer ones. Returns the skills it retired. + */ + async maintain(tenantId: string, at = new Date()): Promise { + return this.store.transaction(tenantId, async tx => { + const usages = await tx.list('skill_usage'); + // Oldest first, so a failure streak ends on the run that completed it. + for (const usage of usages.filter(item => !item.outcome).reverse()) { + const run = await tx.get('run', usage.runId); + if (!run) await tx.put('skill_usage', { ...touch(usage), outcome: 'neutral' }); + else await settleSkillUsage(tx, run); + } + const cutoff = new Date(at.getTime() - RETIRE_UNUSED_DAYS * 86_400_000).toISOString(); + const live = new Set(usages.filter(usage => usage.createdAt >= cutoff).map(usage => usage.projectId)); + const retired: Skill[] = []; + for (const skill of await tx.list('skill', { status: 'active' })) + if (platformMaintained(skill) && live.has(skill.projectId) && (skill.lastUsedAt ?? skill.updatedAt) < cutoff) { + const next: Skill = { + ...touch(skill), + status: 'disabled', + retiredAt: at.toISOString(), + retiredReason: 'stale', + }; + await tx.put('skill', next); + retired.push(next); + } + return retired; + }); + } /** * Every run that succeeded is looked at once, oldest first, one at a time; a failed look is tried * again a few times. Runs only where the deployment's Claude account serves its tenant. @@ -410,6 +846,28 @@ export class Skills { timer.unref(); return () => clearInterval(timer); } + /** Counts finished runs and retires stale skills for every tenant this deployment serves. */ + startMaintenance(intervalMs = 10 * 60_000) { + const tenants = [ + ...new Set([...(this.env.WF_TENANT_ID ? [this.env.WF_TENANT_ID] : []), ...dispatchTenants(this.env)]), + ]; + if (!tenants.length) return () => undefined; + let busy = false; + const tick = async () => { + if (busy) return; + busy = true; + try { + for (const tenantId of tenants) await this.maintain(tenantId); + } catch (error) { + console.error(`[skills] ${error instanceof Error ? error.message : 'maintenance failed'}`); + } finally { + busy = false; + } + }; + const timer = setInterval(() => void tick(), intervalMs); + timer.unref(); + return () => clearInterval(timer); + } /** Whoever may wish for the project may shape the skills its later wishes follow. */ private authorize(actor: Actor, project: Project) { requireHuman(actor); diff --git a/apps/api/src/http.ts b/apps/api/src/http.ts index 5b52b5a..dc40d60 100644 --- a/apps/api/src/http.ts +++ b/apps/api/src/http.ts @@ -35,7 +35,6 @@ import { Authenticator, localUser } from './auth.js'; import { ControlPlane, must, projectAccess, record, touch } from './domain/control-plane.js'; import { Releases } from './domain/releases.js'; import { AgentBundles } from './domain/agent-bundles.js'; -import { Lessons } from './domain/lessons.js'; import { Skills } from './domain/skills.js'; import { WishReports } from './domain/wish-report.js'; import { Connections } from './domain/connections.js'; @@ -58,7 +57,6 @@ export class Services { auth: Authenticator; releases: Releases; bundles: AgentBundles; - lessons: Lessons; skills: Skills; reports: WishReports; connections: Connections; @@ -71,7 +69,6 @@ export class Services { this.auth = new Authenticator(control.store, control.env); this.releases = new Releases(control.store, control.env); this.bundles = new AgentBundles(control.store); - this.lessons = new Lessons(control.store); this.skills = new Skills(control.store, control.env); this.reports = new WishReports(control.store); this.connections = new Connections(control.store, control.env); @@ -311,6 +308,7 @@ export class ApiController { codeReview: codeReviewPolicyInput.nullable().optional(), wishRules: wishRulesInput.optional(), models: projectModelsInput.nullable().optional(), + skillAutoActivation: z.boolean().optional(), deliveryConfig: z .object({ imageRepository: z.string().min(1), @@ -350,24 +348,33 @@ export class ApiController { }), ); } - @Get('projects/:id/lessons') async lessons(@Req() r: AuthRequest, @Param('id') id: string) { - return ok(await this.s.lessons.list(r.actor, id)); - } - @Post('projects/:id/lessons') async createLesson(@Req() r: AuthRequest, @Param('id') id: string, @Body() b: unknown) { - return ok(await this.s.lessons.create(r.actor, id, b)); - } - @Patch('lessons/:id') async updateLesson(@Req() r: AuthRequest, @Param('id') id: string, @Body() b: unknown) { - return ok(await this.s.lessons.setStatus(r.actor, id, b)); - } - @Delete('lessons/:id') async deleteLesson(@Req() r: AuthRequest, @Param('id') id: string) { - return ok(await this.s.lessons.remove(r.actor, id)); - } @Get('projects/:id/skills') async skills(@Req() r: AuthRequest, @Param('id') id: string) { return ok(await this.s.skills.list(r.actor, id)); } @Post('projects/:id/skills') async createSkill(@Req() r: AuthRequest, @Param('id') id: string, @Body() b: unknown) { return ok(await this.s.skills.create(r.actor, id, b)); } + /** SKILL.md files, or a zip of them as the export writes it, added to the project. */ + @Post('projects/:id/skills/import') async importSkills( + @Req() r: AuthRequest, + @Param('id') id: string, + @Body() b: unknown, + ) { + return ok(await this.s.skills.importFiles(r.actor, id, b, key(r))); + } + /** The knowledge base: skills of every project the person may see. */ + @Get('skills') async allSkills( + @Req() r: AuthRequest, + @Query('project') projectId?: string, + @Query('status') status?: string, + @Query('category') category?: string, + @Query('q') q?: string, + ) { + return ok(await this.s.skills.search(r.actor, { projectId, status, category, q })); + } + @Post('skills/copy') async copySkills(@Req() r: AuthRequest, @Body() b: unknown) { + return ok(await this.s.skills.copy(r.actor, b, key(r))); + } /** Every active skill (and with ?proposed=1 the proposals) as a zip, one directory per skill. */ @Get('projects/:id/skills/export') async exportSkills( @Req() r: AuthRequest, diff --git a/apps/api/src/main.ts b/apps/api/src/main.ts index 2b4abb0..009d042 100644 --- a/apps/api/src/main.ts +++ b/apps/api/src/main.ts @@ -37,6 +37,8 @@ export async function bootstrap() { const service = new Services(new ControlPlane(store)); // Succeeded runs are looked at for skills worth keeping, one at a time, in the background. service.skills.startHarvesting(); + // Finished runs count for the skills they were given; skills that keep failing or go unused retire. + service.skills.startMaintenance(); const telemetry = await observability(); @Module({ controllers: [ApiController, InternalController, WorkspaceLifecycleController, WorkspaceLaunchController], diff --git a/apps/worker/src/common.ts b/apps/worker/src/common.ts index 13ad55e..a4b942b 100644 --- a/apps/worker/src/common.ts +++ b/apps/worker/src/common.ts @@ -49,8 +49,7 @@ export interface RunContext { verificationProfileDigest?: string; verificationProfileRequired?: boolean; bundleConfig?: AgentBundleConfig; - lessons?: string[]; - /** The project's active skills, most recently changed first. */ + /** The project's active skills (workflows, pitfalls, conventions), most recently changed first. */ skills?: PromptSkill[]; delivery?: { release?: { id: string; status: string }; diff --git a/apps/worker/src/executor.ts b/apps/worker/src/executor.ts index 7cbe246..6120da6 100644 --- a/apps/worker/src/executor.ts +++ b/apps/worker/src/executor.ts @@ -342,7 +342,6 @@ export async function executeRun(config: WorkerConfig, input: RunInput): Promise acceptanceCriteria: run.acceptanceCriteria, repairCount: run.repairCount, lastFailure, - lessons: context.lessons, skills: context.skills, sourceBranch: run.sourceBranch, ...(revert ? { revert } : {}), diff --git a/packages/agent/src/prompt.ts b/packages/agent/src/prompt.ts index 82b8496..56422d9 100644 --- a/packages/agent/src/prompt.ts +++ b/packages/agent/src/prompt.ts @@ -6,13 +6,14 @@ export const QUESTIONS_MARKER = 'QUESTIONS:'; export const QUESTION_LIMIT = 5; const QUESTION_MAX_LENGTH = 300; -/** At most this many lessons, and this many characters of them, enter a prompt. */ -export const LESSON_LIMIT = 5; -export const LESSON_CHARS = 4096; +/** The longest account of one repaired failure a pitfall skill records. */ export const LESSON_MAX_LENGTH = 1000; -/** At most this many skills, and this many characters of them, enter a prompt. */ -export const SKILL_LIMIT = 8; -export const SKILL_CHARS = 16000; +/** + * At most this many skills, and this many characters of them, enter a prompt; pitfalls and + * conventions (once lessons) share the budget with workflows. + */ +export const SKILL_LIMIT = 12; +export const SKILL_CHARS = 20000; /** A project skill as a prompt carries it. */ export interface PromptSkill { @@ -27,8 +28,6 @@ export interface PromptInput { repairCount: number; /** The failure this repair round must fix. */ lastFailure?: FailureSummary; - /** Active project lessons, most recent first. */ - lessons?: string[]; /** Active project skills, most recently changed first. */ skills?: PromptSkill[]; /** The branch the workspace started from instead of the target branch. */ @@ -45,21 +44,9 @@ export interface PromptInput { frontendOnly?: { backend: string[]; except: string[] }; } -/** Keeps the most recent lessons that fit the count and size limits. */ -export function selectLessons(summaries: string[]): string[] { - const chosen: string[] = []; - let used = 0; - for (const summary of summaries.slice(0, LESSON_LIMIT)) { - if (used + summary.length > LESSON_CHARS) break; - chosen.push(summary); - used += summary.length; - } - return chosen; -} - /** Keeps the most recently changed skills that fit the count and size limits. */ -export function selectSkills(skills: PromptSkill[]): PromptSkill[] { - const chosen: PromptSkill[] = []; +export function selectSkills(skills: T[]): T[] { + const chosen: T[] = []; let used = 0; for (const skill of skills.slice(0, SKILL_LIMIT)) { const size = skill.name.length + skill.description.length + skill.content.length; @@ -135,15 +122,11 @@ export function bundlePrompt(config: AgentBundleConfig, input: PromptInput) { ] .filter(Boolean) .join('\n\n'); - const lessons = selectLessons(input.lessons ?? []); const skills = selectSkills(input.skills ?? []); return [ instructions, input.goal, `Acceptance criteria:\n${input.acceptanceCriteria.map((criterion, i) => `${i + 1}. ${criterion}`).join('\n')}`, - lessons.length - ? `Lessons from earlier work on this project (apply them when relevant):\n${lessons.map(lesson => `- ${lesson}`).join('\n')}` - : '', skills.length ? skillsSection(skills) : '', input.sourceBranch ? `The workspace starts from branch ${input.sourceBranch}, which holds changes people made themselves (for example in the IDE). Keep those changes and build on them; this run verifies and merges them into the target branch together with your work.` @@ -196,7 +179,7 @@ function failureLine(output: string) { return line ? singleLine(line).slice(0, 300) : 'no output'; } -/** A lesson learned when a repair round turned a recorded failure into a pass. */ +/** What a repair round that turned a recorded failure into a pass teaches: one entry of a pitfall skill. */ export function repairLesson(failure: FailureSummary, summary?: string): string { const trigger = failure.kind === 'integration_conflict' diff --git a/packages/agent/test/prompt.test.ts b/packages/agent/test/prompt.test.ts index b163591..b1eae19 100644 --- a/packages/agent/test/prompt.test.ts +++ b/packages/agent/test/prompt.test.ts @@ -1,14 +1,5 @@ import { describe, expect, it } from 'vitest'; -import { - BASELINE_BUNDLE, - LESSON_CHARS, - LESSON_LIMIT, - LESSON_MAX_LENGTH, - bundlePrompt, - questionsIn, - repairLesson, - selectLessons, -} from '../src/index.js'; +import { BASELINE_BUNDLE, LESSON_MAX_LENGTH, bundlePrompt, questionsIn, repairLesson } from '../src/index.js'; const failure = { kind: 'verification' as const, @@ -123,21 +114,6 @@ describe('agent prompt', () => { 'A frontend-only wish changed backend files go.mod server/main.go. What fixed it: Moved the style into src/', ); }); - it('injects at most the configured number and size of lessons', () => { - const lessons = Array.from({ length: 8 }, (_, i) => `lesson ${i}`); - const prompt = bundlePrompt(BASELINE_BUNDLE, { - goal: 'Goal', - acceptanceCriteria: ['Criterion'], - repairCount: 0, - lessons, - }); - expect(prompt).toContain('- lesson 0'); - expect(prompt).toContain(`- lesson ${LESSON_LIMIT - 1}`); - expect(prompt).not.toContain(`- lesson ${LESSON_LIMIT}`); - const large = selectLessons(['x'.repeat(LESSON_CHARS - 10), 'y'.repeat(20), 'z']); - expect(large).toHaveLength(1); - }); - it('turns a repaired failure into a bounded lesson', () => { const lesson = repairLesson(failure, 'Built the project before running the tests.\nAdded a missing fixture.'); expect(lesson).toContain('`npm test` failed (exit code 1): FAIL b.test.ts'); diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.ts index 5d60781..1b2f3f0 100644 --- a/packages/contracts/src/index.ts +++ b/packages/contracts/src/index.ts @@ -57,7 +57,6 @@ export type EntityKind = | 'workspace' | 'provider_connection' | 'bundle' - | 'lesson' | 'runner_task' | 'runner' | 'policy' @@ -69,7 +68,8 @@ export type EntityKind = | 'local_account' | 'notification' | 'skill' - | 'skill_harvest'; + | 'skill_harvest' + | 'skill_usage'; export interface Entity { id: string; tenantId: string; @@ -123,6 +123,11 @@ export interface Project extends Entity { wishRules?: string; /** Models a wish of this project may run with; flash when offered, else the first; absent: the executor's default. */ models?: string[]; + /** + * Whether the platform activates the skills it learns once they are corroborated: a pitfall + * from a repaired failure, or a proposal seen in two succeeded runs. Absent: on. + */ + skillAutoActivation?: boolean; } /** A run that takes back what another run integrated into the target branch. */ export interface RevertSource { @@ -264,11 +269,14 @@ export interface FailureSummary { /** For a conflict: the target-branch commit the repair round must merge. */ targetCommit?: string; } -/** Knowledge reused by later runs of the same project (docs/requirements.md FR-I2). */ +/** What a skill is: a way of working, a known pitfall and its fix, or a project convention. */ +export const skillCategories = ['workflow', 'pitfall', 'convention'] as const; +export type SkillCategory = (typeof skillCategories)[number]; /** - * Know-how a project's later wishes can reuse: when it applies and how to do it. The platform - * proposes skills from finished runs; people confirm, edit and export them. Active skills enter - * the prompts of the project's later runs. + * Know-how a project's later wishes can reuse: when it applies and how to do it (docs/requirements.md + * FR-I2). The platform proposes skills from finished runs and records pitfalls from repaired + * failures; people confirm, edit, copy, import and export them. Active skills enter the prompts of + * the project's later runs. */ export interface Skill extends Entity { projectId: string; @@ -278,13 +286,27 @@ export interface Skill extends Entity { description: string; /** How to do it, in Markdown. */ content: string; + /** Absent: `workflow` (skills stored before categories existed). */ + category?: SkillCategory; /** `proposed`: suggested by the platform, waiting for a person; only `active` skills are used. */ status: 'proposed' | 'active' | 'disabled'; - /** The runs it was learned from. */ + /** The runs it was learned from, oldest first. */ sourceRunIds: string[]; - /** `wishforge` for proposals, else the person who wrote it. */ + /** For a pitfall: the failure it is about, so the same failure in later runs updates it. */ + signature?: string; + /** `wishforge` for what the platform learned, else the person who wrote it. */ createdBy: string; updatedBy?: string; + /** How often runs were given the skill, and how the settled ones ended. */ + useCount?: number; + successCount?: number; + failureCount?: number; + /** Settled runs that used it and failed since the last one that succeeded. */ + failureStreak?: number; + lastUsedAt?: string; + /** Set when the platform disabled it: its runs kept failing, or it went unused too long. */ + retiredAt?: string; + retiredReason?: 'failing' | 'stale'; } /** Whether the platform has looked for skills in a finished run; its id is the run's. */ export interface SkillHarvest extends Entity { @@ -295,13 +317,13 @@ export interface SkillHarvest extends Entity { skillIds: string[]; error?: string; } -export interface Lesson extends Entity { +/** Which skills a run's prompts carried, and whether that run's outcome was counted; its id is the run's. */ +export interface SkillUsage extends Entity { + runId: string; projectId: string; - kind: 'repair' | 'convention'; - summary: string; - sourceRunId?: string; - status: 'active' | 'disabled'; - createdBy: string; + skillIds: string[]; + /** Set once the run ended and the skills' counts include it; `neutral` counts for neither. */ + outcome?: 'succeeded' | 'failed' | 'neutral'; } export interface RunEvent { id: string; @@ -497,7 +519,6 @@ export const projectInput = z installCommands: commandList.default([]), }) .strict(); -export const lessonInput = z.object({ summary: text.max(1000) }).strict(); export const skillName = z .string() .trim() @@ -505,13 +526,19 @@ export const skillName = z .max(64); export const SKILL_CONTENT_LIMIT = 20000; export const skillInput = z - .object({ name: skillName, description: text.max(500), content: text.max(SKILL_CONTENT_LIMIT) }) + .object({ + name: skillName, + description: text.max(500), + content: text.max(SKILL_CONTENT_LIMIT), + category: z.enum(skillCategories).default('workflow'), + }) .strict(); export const skillUpdateInput = z .object({ name: skillName.optional(), description: text.max(500).optional(), content: text.max(SKILL_CONTENT_LIMIT).optional(), + category: z.enum(skillCategories).optional(), status: z.enum(['active', 'disabled']).optional(), }) .strict() diff --git a/scripts/cluster-poc-projects.ts b/scripts/cluster-poc-projects.ts index d9ed565..e128109 100644 --- a/scripts/cluster-poc-projects.ts +++ b/scripts/cluster-poc-projects.ts @@ -40,6 +40,7 @@ export const PROJECT_KINDS = [ 'bundle', 'skill', 'skill_harvest', + 'skill_usage', ]; /** Where the containers keep POC state; a rehearsal of this script names another directory. */ const POC_STATE = process.env.WF_CLUSTER_POC_STATE ?? '/var/lib/wishforge/poc-state'; diff --git a/tests/local-loop.test.ts b/tests/local-loop.test.ts index 19f243d..acc5591 100644 --- a/tests/local-loop.test.ts +++ b/tests/local-loop.test.ts @@ -1,6 +1,6 @@ /** * The main loop end to end with real Git: wish → executor → independent verification - * → repair with failure feedback → integration → success, plus lessons and merge + * → repair with failure feedback → integration → success, plus pitfall skills and merge * conflicts, and a change pushed from the IDE workspace. The control plane runs in process * behind its real internal routes; only the agent is scripted. */ @@ -21,11 +21,11 @@ import { type CheckpointRecord, type Environment, type Evidence, - type Lesson, type Project, type Release, type Role, type Run, + type Skill, } from '@wishforge/contracts'; import { executeCommand, type CommandExecutor, type HostCheckSandbox, type ProviderStart } from '@wishforge/runtime'; import { ManagedProvider } from '../packages/runtime/src/providers/base.js'; @@ -471,18 +471,24 @@ describe('local main loop', () => { expect(await drive(session)).toEqual({ status: 'complete' }); await release(runId, session.generation); - // The background harvest looks at the run once; the model proposes two skills, one named - // like a skill the project has. + // The background harvest looks at the run once; the model proposes a new skill, an update + // of one the project has, and one it cannot use. const asked: string[] = []; const skills = new Skills(store, { ...env, WF_TENANT_ID: TENANT }, async input => { asked.push(input.prompt); return { skills: [ { - name: 'greeting-check', + name: 'greeting-check-flow', description: 'When changing greeting.txt', content: '1. Edit greeting.txt.\n2. Run `node check.mjs`.', }, + { + name: 'greeting-check', + updates: 'greeting-check', + description: 'An older skill', + content: 'Keep greetings lowercase, and run node check.mjs.', + }, { name: 'Not A Name', description: 'x', content: 'y' }, ], }; @@ -497,13 +503,25 @@ describe('local main loop', () => { expect(JSON.parse(asked[0]!)).toMatchObject({ goal: 'Make the greeting say hello world', changedFiles: ['greeting.txt'], - existingSkills: [{ name: 'greeting-check' }], }); + // The harvest sees every skill, the pitfall from the repair included. + expect( + JSON.parse(asked[0]!) + .existingSkills.map((skill: { name: string; category: string }) => `${skill.category}:${skill.name}`) + .sort(), + ).toEqual(['pitfall:pitfall-node-check-mjs', 'workflow:greeting-check']); const listed = await skills.list(owner, project.id); const proposed = listed.find(skill => skill.status === 'proposed')!; - expect(listed).toHaveLength(2); - expect(proposed).toMatchObject({ name: 'greeting-check-2', createdBy: 'wishforge', sourceRunIds: [runId] }); - expect((await services.control.events(owner, runId)).map(event => event.type)).toContain('skill.proposed'); + expect(listed).toHaveLength(3); + expect(proposed).toMatchObject({ name: 'greeting-check-flow', createdBy: 'wishforge', sourceRunIds: [runId] }); + // A person's skill keeps what it says; it records the run that confirmed it. + expect(listed.find(skill => skill.name === 'greeting-check')).toMatchObject({ + content: 'Keep greetings lowercase.', + sourceRunIds: [runId], + }); + expect((await services.control.events(owner, runId)).map(event => event.type)).toEqual( + expect.arrayContaining(['skill.activated', 'skill.proposed', 'skill.updated']), + ); // Someone who may not wish for the project may not shape its skills; anyone who may can. const viewer = await person(project.id, 'li', { wish: 'none', manage: false, releases: false, reviewCode: false }); @@ -525,20 +543,29 @@ describe('local main loop', () => { return writeGreeting('hello world', 'Nothing to change.')(start); }); await second.executor.executeRun(second.input); - expect(prompt).toContain('### greeting-check-2'); + expect(prompt).toContain('### greeting-check-flow'); expect(prompt).toContain('Edit greeting.txt, then run node check.mjs.'); expect(prompt).toContain('### greeting-check'); // Exports: one SKILL.md, or a zip with a directory per active skill. const one = await skills.exportOne(owner, proposed.id); - expect(one.content).toMatch(/^---\nname: greeting-check-2\ndescription: "When changing greeting.txt"\n---\n\nEdit/); + expect(one.content).toMatch( + /^---\nname: greeting-check-flow\ndescription: "When changing greeting.txt"\n---\n\nEdit/, + ); const zip = await skills.exportAll(owner, project.id); expect(zip.content.subarray(0, 4).toString('hex')).toBe('504b0304'); const unzipped = path.join(root, 'skills.zip'); await writeFile(unzipped, zip.content); const listing = await run('unzip', ['-Z1', unzipped]).then(result => result.stdout.trim().split('\n')); - expect(listing.sort()).toEqual(['greeting-check-2/SKILL.md', 'greeting-check/SKILL.md']); - expect((await run('unzip', ['-p', unzipped, 'greeting-check-2/SKILL.md'])).stdout).toBe(one.content); + expect(listing.sort()).toEqual([ + 'greeting-check-flow/SKILL.md', + 'greeting-check/SKILL.md', + 'pitfall-node-check-mjs/SKILL.md', + ]); + expect((await run('unzip', ['-p', unzipped, 'greeting-check-flow/SKILL.md'])).stdout).toBe(one.content); + expect((await run('unzip', ['-p', unzipped, 'pitfall-node-check-mjs/SKILL.md'])).stdout).toContain( + 'wishforge-category: pitfall', + ); // The wish's report carries every stage, the agent's work, the change and the checks. const report = await new WishReports(store).markdown(owner, (await services.control.run(owner, runId)).wishId); @@ -604,27 +631,42 @@ describe('local main loop', () => { expect(events.find(e => e.type === 'provider.output')?.message).toContain('Updated the greeting'); expect(events.find(e => e.type === 'provider.command')?.message).toBe('$ node edit.mjs (exit 0)'); - // The repair became a project lesson that the next run is told about (FR-I2). - const lessons = await services.lessons.list(owner, project.id); - expect(lessons).toHaveLength(1); - expect(lessons[0]).toMatchObject({ kind: 'repair', status: 'active', sourceRunId: runId }); - expect(lessons[0]!.summary).toContain('check.mjs'); - expect(lessons[0]!.summary).toContain('Fixed the typo'); + // The repair became an active pitfall skill that the next run is told about (FR-I2). + const skills = await services.skills.list(owner, project.id); + expect(skills).toHaveLength(1); + const pitfall = skills[0]!; + expect(pitfall).toMatchObject({ + name: 'pitfall-node-check-mjs', + category: 'pitfall', + status: 'active', + sourceRunIds: [runId], + createdBy: 'wishforge', + }); + expect(pitfall.content).toContain('check.mjs'); + expect(pitfall.content).toContain('Fixed the typo'); + expect((await services.control.events(owner, runId)).map(event => event.type)).toContain('skill.activated'); await release(runId, session.generation); const next = await submit(project.id, 'Make the greeting say hello world again', 'wish-lesson-0002'); const second = await provision(next, writeGreeting('hello world!', 'Added an exclamation mark.')); expect(await drive(second)).toEqual({ status: 'complete' }); - expect(prompts[2]).toContain('Lessons from earlier work on this project'); - expect(prompts[2]).toContain(lessons[0]!.summary); + expect(prompts[2]).toContain('### pitfall-node-check-mjs'); + expect(prompts[2]).toContain('Fixed the typo'); + expect(prompts[2]).not.toContain('Lessons from earlier work'); await release(next, second.generation); + // The run that was given it succeeded: the skill counts it. + expect((await services.skills.list(owner, project.id))[0]).toMatchObject({ + useCount: 1, + successCount: 1, + failureStreak: 0, + }); - // A disabled lesson is no longer injected. - await services.lessons.setStatus(owner, lessons[0]!.id, { status: 'disabled' }); + // A disabled skill is no longer injected. + await services.skills.update(owner, pitfall.id, { status: 'disabled' }); const third = await submit(project.id, 'Keep the greeting', 'wish-lesson-0003'); const thirdSession = await provision(third, writeGreeting('hello world!!', 'More emphasis.')); expect(await drive(thirdSession)).toEqual({ status: 'complete' }); - expect(prompts[3]).not.toContain('Lessons from earlier work'); + expect(prompts[3]).not.toContain('pitfall-node-check-mjs'); }); it('waits instead of repairing when the repair budget is used up, and continues on request', async () => { @@ -685,8 +727,9 @@ describe('local main loop', () => { // The resolved change contains A's commit; nothing was overwritten (FR-F1). const integratedA = (await services.control.run(owner, first)).integratedCommit!; await git(remote, 'merge-base', '--is-ancestor', integratedA, 'main'); - const lessons: Lesson[] = await services.lessons.list(owner, project.id); - expect(lessons[0]?.summary).toContain('Merging into the target branch conflicted in greeting.txt'); + const pitfalls: Skill[] = await services.skills.list(owner, project.id); + expect(pitfalls[0]).toMatchObject({ category: 'pitfall', name: 'pitfall-merge-conflict-greeting-txt' }); + expect(pitfalls[0]?.content).toContain('Merging into the target branch conflicted in greeting.txt'); }); it('merges a change onto a target that moved meanwhile, and checks the merge', async () => { @@ -1132,10 +1175,12 @@ describe('local main loop', () => { expect((await evidenceOf(runId)).find(evidence => evidence.installFailure)?.changedManifests).toEqual([ 'package.json', ]); - const lessons = await store.transaction(TENANT, tx => tx.list('lesson', { projectId: project.id })); - expect(lessons.map(lesson => lesson.summary)).toEqual([ - expect.stringMatching(/^Installing dependencies with `.+` failed \(exit code 1\): .*left-pad-typo/), - ]); + const pitfalls = await store.transaction(TENANT, tx => tx.list('skill', { projectId: project.id })); + expect(pitfalls).toHaveLength(1); + expect(pitfalls[0]).toMatchObject({ category: 'pitfall', status: 'active' }); + expect(pitfalls[0]!.content).toMatch( + /\n- Installing dependencies with `.+` failed \(exit code 1\): .*left-pad-typo/, + ); // The same manifest change failing on the network is the environment's: no repair round is spent. const second = await submit(project.id, 'Greet again', 'wish-install-0002'); diff --git a/tests/migrations.test.ts b/tests/migrations.test.ts index d46a350..dbd8c32 100644 --- a/tests/migrations.test.ts +++ b/tests/migrations.test.ts @@ -31,6 +31,12 @@ describe('versioned database migrations (requirements FR-K2)', () => { expect(new Set(versions.map(v => v.slice(0, 3))).size).toBe(versions.length); // Data migrations must not run silently restricted by row-level security. expect(migrations[1]!.sql).toContain('SET LOCAL row_security = off'); + // Lessons became skills: every lesson row is converted, keeping its id, then removed. + const lessons = migrations.find(m => m.version === '004_lessons_to_skills')!; + expect(lessons.sql).toContain('SET LOCAL row_security = off'); + expect(lessons.sql).toContain("WHERE l.kind = 'lesson'"); + expect(lessons.sql).toContain('ON CONFLICT (tenant_id, kind, id) DO NOTHING'); + expect(lessons.sql).toContain("DELETE FROM entities WHERE kind = 'lesson'"); }); it('applies only what has not run, in order, and never repeats a migration', async () => { const db = database(); diff --git a/tests/skills.test.ts b/tests/skills.test.ts new file mode 100644 index 0000000..48323e3 --- /dev/null +++ b/tests/skills.test.ts @@ -0,0 +1,473 @@ +/** + * Project skills as the one home of a project's know-how (requirements FR-I2): pitfalls learned + * from repaired failures, harvested proposals merged and activated, effectiveness counted and + * retired, and skills moved between projects as SKILL.md files, zips or copies. + */ +import { describe, expect, it } from 'vitest'; +import { crc32, deflateRawSync } from 'node:zlib'; +import type { Actor, FailureSummary, Project, Run, Skill } from '@wishforge/contracts'; +import { + RETIRE_AFTER_FAILURES, + RETIRE_UNUSED_DAYS, + Skills, + failureSignature, + learnFromRun, + projectSkills, + recordSkillUse, + settleSkillUsage, +} from '../apps/api/src/domain/skills.js'; +import { parseSkillMarkdown, readSkillArchive, skillMarkdown, zipFiles } from '../apps/api/src/domain/skill-files.js'; +import { MemoryStore } from './helpers/memory-store.js'; + +const TENANT = 'demo'; +const owner: Actor = { tenantId: TENANT, userId: 'owner', role: 'owner', kind: 'human' }; +const viewer: Actor = { tenantId: TENANT, userId: 'viewer', role: 'viewer', kind: 'human' }; +const stamp = (id: string) => { + const time = new Date().toISOString(); + return { id, tenantId: TENANT, version: 1, createdAt: time, updatedAt: time }; +}; +const failure = (argv = ['npm', 'test'], tail = 'Error: expected 2 to equal 3'): FailureSummary => ({ + kind: 'verification', + evidenceId: 'evidence', + sourceCommit: 'a'.repeat(40), + argv, + exitCode: 1, + outputTail: tail, +}); + +function setup() { + const store = new MemoryStore(); + store.seed(TENANT); + const answers: unknown[] = []; + const asked: string[] = []; + const skills = new Skills(store, { WF_TENANT_ID: TENANT } as NodeJS.ProcessEnv, async input => { + asked.push(input.prompt); + return answers.shift() ?? { skills: [] }; + }); + const project = async (id: string, extra: Partial = {}) => { + const value = { + ...stamp(id), + name: `Project ${id}`, + repositoryStorage: 'platform', + repositoryStatus: 'ready', + targetBranch: 'main', + memberIds: ['viewer'], + verificationCommands: [], + autoDeploy: false, + ...extra, + } as Project; + await store.transaction(TENANT, tx => tx.put('project', value)); + return value; + }; + const run = async (id: string, projectId: string, extra: Partial = {}) => { + const value = { + ...stamp(id), + projectId, + wishId: `wish-${id}`, + goal: 'Change the greeting', + acceptanceCriteria: ['check passes'], + status: 'running', + stage: 'implement', + repairCount: 0, + ...extra, + } as unknown as Run; + await store.transaction(TENANT, tx => tx.put('run', value)); + return value; + }; + /** The run ends: its status changes and, for a success, the control plane learns from it. */ + const finish = (value: Run, status: Run['status'], extra: Partial = {}) => + store.transaction(TENANT, async tx => { + const next = { ...value, ...extra, status }; + await tx.put('run', next); + if (status === 'succeeded') await learnFromRun(tx, next); + return next; + }); + const use = (value: Run) => store.transaction(TENANT, tx => recordSkillUse(tx, value)); + const all = (projectId: string) => skills.list(owner, projectId); + return { store, skills, answers, asked, project, run, finish, use, all }; +} + +describe('pitfall skills from repaired failures', () => { + it('turns the same failure in several runs into one pitfall, active right away', async () => { + const { project, run, finish, all, store } = setup(); + await project('p1'); + const first = await run('r1', 'p1'); + await finish(first, 'succeeded', { + repairCount: 1, + lastFailure: failure(), + implementationSummary: 'Built before testing.', + }); + const second = await run('r2', 'p1'); + await finish(second, 'succeeded', { + repairCount: 1, + lastFailure: failure(['npm', ' test'], 'FAIL other.test.ts'), + implementationSummary: 'Added a fixture.', + }); + // Learning from the same run again changes nothing. + await finish(second, 'succeeded', { repairCount: 1, lastFailure: failure(), implementationSummary: 'x' }); + const skills = await all('p1'); + expect(skills).toHaveLength(1); + const pitfall = skills[0]!; + expect(pitfall).toMatchObject({ + name: 'pitfall-npm-test', + category: 'pitfall', + status: 'active', + signature: 'verification:npm test', + sourceRunIds: ['r1', 'r2'], + createdBy: 'wishforge', + }); + // Most recent first. + expect(pitfall.content.indexOf('Added a fixture')).toBeLessThan(pitfall.content.indexOf('Built before testing')); + const events = await store.read(TENANT, tx => tx.events('r2')); + expect(events.map(event => event.type)).toEqual(['skill.updated']); + // A different command is a different pitfall; a conflict is identified by its files. + expect(failureSignature(failure(['npm', 'run', 'lint']))).toBe('verification:npm run lint'); + expect( + failureSignature({ ...failure(), kind: 'integration_conflict', argv: undefined, outputTail: 'b.ts\na.ts' }), + ).toBe('integration_conflict:a.ts b.ts'); + }); + it('waits for a person where the project does not activate skills itself, and is not shown before', async () => { + const { project, run, finish, all, store } = setup(); + await project('p1', { skillAutoActivation: false }); + await finish(await run('r1', 'p1'), 'succeeded', { repairCount: 1, lastFailure: failure() }); + expect((await all('p1'))[0]).toMatchObject({ status: 'proposed', category: 'pitfall' }); + expect(await store.read(TENANT, tx => projectSkills(tx, 'p1'))).toEqual([]); + // A run that needed no repair teaches nothing. + await finish(await run('r2', 'p1'), 'succeeded'); + expect(await all('p1')).toHaveLength(1); + }); +}); + +describe('harvested skills', () => { + it('merges a proposal into the skill it updates, and activates one two succeeded runs proposed', async () => { + const { project, run, skills, answers, asked, all } = setup(); + await project('p1'); + await run('r1', 'p1', { status: 'succeeded' }); + await run('r2', 'p1', { status: 'succeeded' }); + const written = await skills.create(owner, 'p1', { + name: 'house-style', + description: 'Any change', + content: 'Use tabs.', + category: 'convention', + }); + answers.push({ + skills: [ + { name: 'add-page', description: 'When adding a page', content: 'Register it in routes.ts.' }, + { name: 'house-style', updates: 'house-style', description: 'Any change', content: 'Use spaces.' }, + ], + }); + expect((await skills.harvest(TENANT, 'r1')).map(skill => skill.name).sort()).toEqual(['add-page', 'house-style']); + expect(JSON.parse(asked[0]!).existingSkills).toEqual([ + expect.objectContaining({ name: 'house-style', category: 'convention', status: 'active' }), + ]); + let listed = await all('p1'); + expect(listed.find(skill => skill.name === 'add-page')).toMatchObject({ status: 'proposed', sourceRunIds: ['r1'] }); + // A person's skill keeps its words. + expect(listed.find(skill => skill.id === written.id)).toMatchObject({ content: 'Use tabs.', sourceRunIds: ['r1'] }); + + // A second succeeded run proposes the same skill again (by name): it is rewritten and activated. + answers.push({ + skills: [ + { name: 'add-page', description: 'When adding a page', content: 'Register it in routes.ts; add a test.' }, + ], + }); + await skills.harvest(TENANT, 'r2'); + listed = await all('p1'); + expect(listed.filter(skill => skill.name.startsWith('add-page'))).toEqual([ + expect.objectContaining({ + status: 'active', + content: 'Register it in routes.ts; add a test.', + sourceRunIds: ['r1', 'r2'], + }), + ]); + }); + it('leaves corroborated proposals for a person where the project says so', async () => { + const { project, run, skills, answers, all } = setup(); + await project('p1', { skillAutoActivation: false }); + for (const id of ['r1', 'r2']) { + await run(id, 'p1', { status: 'succeeded' }); + answers.push({ skills: [{ name: 'add-page', description: 'When adding a page', content: `Do it (${id}).` }] }); + await skills.harvest(TENANT, id); + } + expect(await all('p1')).toEqual([ + expect.objectContaining({ status: 'proposed', content: 'Do it (r2).', sourceRunIds: ['r1', 'r2'] }), + ]); + }); +}); + +describe('how well skills work', () => { + it('counts the runs given a skill and retires a platform skill whose runs keep failing', async () => { + const { project, run, finish, use, all, store, skills } = setup(); + await project('p1'); + await finish(await run('r0', 'p1'), 'succeeded', { repairCount: 1, lastFailure: failure() }); + const mine = await skills.create(owner, 'p1', { name: 'mine', description: 'Always', content: 'Be careful.' }); + const good = await run('good', 'p1'); + await use(good); + await use(good); // a repair round does not count twice + await finish(good, 'succeeded'); + let [pitfall, written] = [ + (await all('p1')).find(skill => skill.category === 'pitfall')!, + (await all('p1')).find(skill => skill.id === mine.id)!, + ]; + expect(pitfall).toMatchObject({ useCount: 1, successCount: 1, failureStreak: 0 }); + expect(written).toMatchObject({ useCount: 1, successCount: 1 }); + + // Canceled without a failed check: neither success nor failure. + const changedMind = await run('cancel', 'p1'); + await use(changedMind); + await store.transaction(TENANT, async tx => { + await tx.put('run', { ...changedMind, status: 'canceled' }); + await settleSkillUsage(tx, { ...changedMind, status: 'canceled' }); + }); + for (let n = 1; n <= RETIRE_AFTER_FAILURES; n++) { + const failing = await run(`fail-${n}`, 'p1', { repairCount: 2 }); + await use(failing); + await store.transaction(TENANT, tx => tx.put('run', { ...failing, status: 'canceled' })); + } + // Failures are found by the background maintenance. + await skills.maintain(TENANT); + [pitfall, written] = [ + (await all('p1')).find(skill => skill.category === 'pitfall')!, + (await all('p1')).find(skill => skill.id === mine.id)!, + ]; + expect(pitfall).toMatchObject({ + status: 'disabled', + retiredReason: 'failing', + useCount: 2 + RETIRE_AFTER_FAILURES, + failureCount: RETIRE_AFTER_FAILURES, + }); + // A person's skill is only flagged by its counts; theirs to decide. + expect(written).toMatchObject({ status: 'active', failureStreak: RETIRE_AFTER_FAILURES }); + const retiredOn = await store.read(TENANT, tx => tx.events(`fail-${RETIRE_AFTER_FAILURES}`)); + expect(retiredOn.map(event => event.type)).toEqual(['skill.retired']); + + // Enabling it again starts afresh. + const again = await skills.update(owner, pitfall.id, { status: 'active' }); + expect(again).toMatchObject({ status: 'active', failureStreak: 0 }); + expect(again.retiredReason).toBeUndefined(); + expect(again.updatedBy).toBeUndefined(); + }); + it('retires a platform skill no run was given for a long time while its project kept running', async () => { + const { project, run, finish, all, skills, store } = setup(); + await project('p1'); + await finish(await run('r0', 'p1'), 'succeeded', { repairCount: 1, lastFailure: failure() }); + // Long ago it was used; today's run has only newer skills in its prompt. + const old = new Date(Date.now() - (RETIRE_UNUSED_DAYS + 1) * 86_400_000).toISOString(); + await store.transaction(TENANT, async tx => { + const [skill] = await tx.list('skill', { projectId: 'p1' }); + await tx.put('skill', { ...skill!, lastUsedAt: old, updatedAt: old }); + await tx.put('skill', { + ...stamp('fresh'), + projectId: 'p1', + name: 'fresh', + description: 'd', + content: 'c', + status: 'active', + sourceRunIds: [], + createdBy: 'owner', + } as Skill); + }); + // A project that did not run keeps its skills. + expect(await skills.maintain(TENANT)).toEqual([]); + const today = await run('today', 'p1'); + await store.transaction(TENANT, tx => + tx.put('skill_usage', { ...stamp('today'), runId: today.id, projectId: 'p1', skillIds: ['fresh'] }), + ); + const retired = await skills.maintain(TENANT); + expect(retired.map(skill => skill.category)).toEqual(['pitfall']); + expect((await all('p1')).find(skill => skill.category === 'pitfall')).toMatchObject({ + status: 'disabled', + retiredReason: 'stale', + }); + }); +}); + +/** A zip whose entries are deflated, as zip tools write them. */ +function deflatedZip(files: { path: string; content: string }[]) { + const locals: Buffer[] = []; + const centrals: Buffer[] = []; + let offset = 0; + for (const file of files) { + const name = Buffer.from(file.path); + const data = Buffer.from(file.content); + const packed = deflateRawSync(data); + const local = Buffer.alloc(30); + local.writeUInt32LE(0x04034b50, 0); + local.writeUInt16LE(20, 4); + local.writeUInt16LE(8, 8); + local.writeUInt32LE(crc32(data), 14); + local.writeUInt32LE(packed.length, 18); + local.writeUInt32LE(data.length, 22); + local.writeUInt16LE(name.length, 26); + const central = Buffer.alloc(46); + central.writeUInt32LE(0x02014b50, 0); + central.writeUInt16LE(20, 4); + central.writeUInt16LE(20, 6); + central.writeUInt16LE(8, 10); + central.writeUInt32LE(crc32(data), 16); + central.writeUInt32LE(packed.length, 20); + central.writeUInt32LE(data.length, 24); + central.writeUInt16LE(name.length, 28); + central.writeUInt32LE(offset, 42); + locals.push(local, name, packed); + centrals.push(central, name); + offset += 30 + name.length + packed.length; + } + const directory = Buffer.concat(centrals); + const end = Buffer.alloc(22); + end.writeUInt32LE(0x06054b50, 0); + end.writeUInt16LE(files.length, 8); + end.writeUInt16LE(files.length, 10); + end.writeUInt32LE(directory.length, 12); + end.writeUInt32LE(offset, 16); + return Buffer.concat([...locals, directory, end]); +} + +describe('skills as files', () => { + it('reads back what export writes, and SKILL.md written elsewhere', () => { + const skill = { + name: 'pitfall-npm-test', + description: 'Before "npm test"', + content: '- It fails.', + category: 'pitfall' as const, + }; + expect(parseSkillMarkdown(skillMarkdown(skill), 'x/SKILL.md')).toEqual({ ...skill, source: 'x/SKILL.md' }); + expect( + parseSkillMarkdown( + "---\r\nname: 'Lazy Load'\r\ndescription: >\r\n When a page\r\n is slow\r\nallowed-tools: Read\r\n---\r\n# Steps\r\nDo it.\r\n", + 'lazy/SKILL.md', + ), + ).toMatchObject({ + name: 'lazy-load', + description: 'When a page is slow', + content: '# Steps\nDo it.', + category: 'workflow', + }); + // No front matter: the name comes from the file, the description from the first line. + expect(parseSkillMarkdown('# Run the e2e suite first\n\nnpm run e2e', 'e2e-first.SKILL.md')).toMatchObject({ + name: 'e2e-first', + description: 'Run the e2e suite first', + }); + expect(() => parseSkillMarkdown('---\nname: x\n', 'a.md')).toThrow(/not closed/); + expect(() => parseSkillMarkdown('---\nname: x\ndescription: y\n---\n', 'a.md')).toThrow(/no instructions/); + expect(() => parseSkillMarkdown('x'.repeat(70 * 1024), 'big.md')).toThrow(/larger than/); + }); + it('reads stored and deflated zips, skipping what is not a skill and refusing what is too large', () => { + const files = [ + { path: 'a/SKILL.md', content: '---\nname: a\ndescription: A\n---\n\nDo A.' }, + { path: 'a/scripts/run.sh', content: 'echo' }, + { path: '__MACOSX/a/._SKILL.md', content: 'junk' }, + ]; + for (const archive of [zipFiles(files), deflatedZip(files)]) + expect(readSkillArchive(archive)).toEqual({ files: [files[0]], ignored: 2 }); + expect(() => readSkillArchive(Buffer.from('not a zip'))).toThrow(/not a zip/); + expect(() => readSkillArchive(Buffer.alloc(600 * 1024))).toThrow(/larger than/); + const bomb = deflatedZip([{ path: 'b/SKILL.md', content: 'x'.repeat(100 * 1024) }]); + expect(() => readSkillArchive(bomb)).toThrow(/larger than 64 KiB/); + const damaged = zipFiles([files[0]!]); + damaged[40] ^= 0xff; // a byte of the file's content + expect(() => readSkillArchive(damaged)).toThrow(/damaged/); + }); +}); + +describe('moving skills between projects', () => { + it('imports an export into another project once, numbering names a different skill holds', async () => { + const { project, skills, all } = setup(); + await project('p1'); + await project('p2'); + await skills.create(owner, 'p1', { name: 'add-page', description: 'Pages', content: 'Register it.' }); + await skills.create(owner, 'p1', { + name: 'house-style', + description: 'Always', + content: 'Tabs.', + category: 'convention', + }); + await skills.create(owner, 'p2', { name: 'add-page', description: 'Pages', content: 'Something else.' }); + const exported = await skills.exportAll(owner, 'p1'); + const archive = exported.content.toString('base64'); + const result = await skills.importFiles(owner, 'p2', { archive }, 'import-key-0001'); + expect(result.created.map(skill => [skill.name, skill.category, skill.status])).toEqual([ + ['add-page-2', 'workflow', 'active'], + ['house-style', 'convention', 'active'], + ]); + // The same request again answers the same; the same files again add nothing. + expect(await skills.importFiles(owner, 'p2', { archive }, 'import-key-0001')).toEqual(result); + const again = await skills.importFiles(owner, 'p2', { archive, status: 'proposed' }, 'import-key-0002'); + expect(again.created).toEqual([]); + expect(again.skipped.map(item => item.reason)).toEqual(['identical', 'identical']); + expect(await all('p2')).toHaveLength(3); + // Loose files; one unreadable file is reported, the rest imported. + const loose = await skills.importFiles( + owner, + 'p2', + { + files: [ + { path: 'review.SKILL.md', content: '---\ndescription: Before review\n---\nCheck it.' }, + { path: 'broken.md', content: '---\nname: x' }, + ], + status: 'proposed', + }, + 'import-key-0003', + ); + expect(loose.created).toEqual([expect.objectContaining({ name: 'review', status: 'proposed' })]); + expect(loose.skipped).toEqual([expect.objectContaining({ source: 'broken.md', reason: 'invalid' })]); + await expect( + skills.importFiles(owner, 'p2', { files: [{ path: 'broken.md', content: '---\nname: x' }] }, 'import-key-0004'), + ).rejects.toMatchObject({ code: 'NO_SKILLS' }); + await expect(skills.importFiles(viewer, 'p2', { archive }, 'import-key-0005')).rejects.toMatchObject({ + code: 'FORBIDDEN', + }); + await expect(skills.importFiles(owner, 'p2', { archive })).rejects.toMatchObject({ code: 'IDEMPOTENCY_REQUIRED' }); + }); + it('copies skills to a project the person may shape, keeping their kind and state but not their history', async () => { + const { project, run, finish, skills, all } = setup(); + await project('p1'); + await project('p2'); + await project('hidden', { memberIds: [] }); + await finish(await run('r1', 'p1'), 'succeeded', { repairCount: 1, lastFailure: failure() }); + const [pitfall] = await all('p1'); + const copied = await skills.copy(owner, { skillIds: [pitfall!.id], projectId: 'p2' }, 'copy-key-0001'); + expect(copied.created).toEqual([ + expect.objectContaining({ + projectId: 'p2', + name: 'pitfall-npm-test', + category: 'pitfall', + signature: 'verification:npm test', + status: 'active', + sourceRunIds: [], + createdBy: 'owner', + }), + ]); + expect((await skills.copy(owner, { skillIds: [pitfall!.id], projectId: 'p2' }, 'copy-key-0002')).skipped).toEqual([ + expect.objectContaining({ reason: 'identical' }), + ]); + // The copy keeps learning in its new project: the same failure there updates it. + await finish(await run('r2', 'p2'), 'succeeded', { repairCount: 1, lastFailure: failure() }); + expect(await all('p2')).toEqual([expect.objectContaining({ id: copied.created[0]!.id, sourceRunIds: ['r2'] })]); + // Someone who may not wish for the target may not copy into it, nor see a project they are not in. + await expect( + skills.copy(viewer, { skillIds: [pitfall!.id], projectId: 'p2' }, 'copy-key-0003'), + ).rejects.toMatchObject({ + code: 'FORBIDDEN', + }); + await expect( + skills.copy(viewer, { skillIds: [pitfall!.id], projectId: 'hidden' }, 'copy-key-0004'), + ).rejects.toMatchObject({ + code: 'NOT_FOUND', + }); + }); + it('lists the skills of every project a person may see, filtered', async () => { + const { project, skills } = setup(); + await project('p1'); + await project('hidden', { memberIds: [] }); + await skills.create(owner, 'p1', { name: 'one', description: 'Pages', content: 'Register routes.' }); + await skills.create(owner, 'p1', { name: 'two', description: 'Style', content: 'Tabs.', category: 'convention' }); + await skills.create(owner, 'hidden', { name: 'secret', description: 'Hidden', content: 'x' }); + expect((await skills.search(owner, {})).map(skill => skill.name).sort()).toEqual(['one', 'secret', 'two']); + expect((await skills.search(viewer, {})).map(skill => skill.name).sort()).toEqual(['one', 'two']); + expect((await skills.search(viewer, { category: 'convention' })).map(skill => skill.name)).toEqual(['two']); + expect((await skills.search(viewer, { q: 'ROUTES' })).map(skill => skill.name)).toEqual(['one']); + expect(await skills.search(viewer, { status: 'proposed' })).toEqual([]); + await expect(skills.search(viewer, { projectId: 'hidden' })).rejects.toMatchObject({ code: 'NOT_FOUND' }); + }); +});