@adecore/agents 0.39.0 → 0.40.0

package/src/skills.ts

@@ -3,7 +3,8 @@ import { open, readdir, readFile, realpath, stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join, parse } from 'node:path';
 import type { AgentKind, ChatSkill, ChatSkillSource } from '@adecore/agent-contracts';
-import { isNotFound } from './fs.ts';
+import { wait } from './async.ts';
+import { hasErrorCode, isNotFound } from './fs.ts';
 
 export interface SkillRoot {
     dir: string;
@@ -62,7 +63,6 @@ const HEAD_BYTES = 64 * 1024;
 const MAX_DESCRIPTION = 1024;
 
 export interface SkillRootOptions {
-    // The person's home directory; a test points it at a temporary tree.
     home?: string;
     // Where Claude Code keeps its own configuration, when it is not `<home>/.claude`.
     claudeConfigDir?: string;
@@ -72,6 +72,7 @@ const NAME = /^[A-Za-z][A-Za-z0-9_:-]*$/;
 
 function unquote(value: string): string {
     const quoted = /^(['"])([\s\S]*)\1$/.exec(value);
+
     return quoted ? quoted[2]! : value;
 }
 
@@ -81,28 +82,38 @@ function unquote(value: string): string {
  */
 export function parseFrontmatter(text: string): Record<string, string> {
     const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+
     if (!match) {
         return {};
     }
+
     const fields: Record<string, string> = {};
     const lines = match[1]!.split(/\r?\n/);
+
     for (let i = 0; i < lines.length; i++) {
         const pair = /^([A-Za-z0-9_-]+):[ \t]*(.*)$/.exec(lines[i]!);
+
         if (!pair) {
             continue;
         }
+
         let value = pair[2]!.trim();
+
         if (value === '' || value === '>' || value === '>-' || value === '|' || value === '|-') {
             // A block scalar puts the value on the indented lines under it; `|` keeps the newlines.
             const keepNewlines = value.startsWith('|');
             const parts: string[] = [];
+
             while (i + 1 < lines.length && /^[ \t]+\S/.test(lines[i + 1]!)) {
                 parts.push(lines[++i]!.trim());
             }
+
             value = parts.join(keepNewlines ? '\n' : ' ');
         }
+
         fields[pair[1]!] = unquote(value);
     }
+
     return fields;
 }
 
@@ -113,58 +124,76 @@ export function parseFrontmatter(text: string): Record<string, string> {
 function projectDirs(cwd: string, home: string): string[] {
     const dirs: string[] = [];
     let current = cwd;
+
     while (current !== '' && current !== parse(current).root && current !== home && current !== dirname(home) && dirs.length < 8) {
         dirs.push(current);
+
         // Anything above a repository root belongs to another project, so the walk ends there.
         if (existsSync(join(current, '.git'))) {
             break;
         }
+
         const parent = dirname(current);
+
         if (parent === current) {
             break;
         }
+
         current = parent;
     }
+
     return dirs;
 }
 
 /* The plugin folders Claude Code installed, each named the way its skills are addressed. */
 export async function pluginSkillRoots(configDir: string): Promise<SkillRoot[]> {
     let raw: string;
+
     try {
         raw = await readFile(join(configDir, 'plugins', 'installed_plugins.json'), 'utf8');
     } catch (e) {
         if (isNotFound(e)) {
             return [];
         }
+
         throw e;
     }
+
     let parsed: unknown;
+
     try {
         parsed = JSON.parse(raw);
     } catch {
         return [];
     }
+
     const plugins = typeof parsed === 'object' && parsed !== null ? (parsed as { plugins?: unknown }).plugins : undefined;
+
     if (typeof plugins !== 'object' || plugins === null) {
         return [];
     }
+
     const roots: SkillRoot[] = [];
+
     for (const [key, installs] of Object.entries(plugins as Record<string, unknown>)) {
         const name = key.split('@')[0] ?? key;
+
         for (const install of Array.isArray(installs) ? installs : []) {
             const path = typeof install === 'object' && install !== null ? (install as { installPath?: unknown }).installPath : undefined;
+
             if (typeof path === 'string' && path !== '') {
                 roots.push({ dir: join(path, 'skills'), source: 'plugin', prefix: name });
             }
         }
     }
+
     return roots;
 }
 
 /* Where a provider's CLI looks for skills, in the order a name clash is decided. */
 export async function skillRootsFor(kind: AgentKind, cwd: string, options: SkillRootOptions = {}): Promise<SkillRoot[]> {
     const home = options.home ?? homedir();
+
     if (kind === 'codex') {
         return [
             { dir: join(home, '.agents', 'skills'), source: 'user', depth: CODEX_SKILL_DEPTH },
@@ -172,7 +201,9 @@ export async function skillRootsFor(kind: AgentKind, cwd: string, options: Skill
             ...projectDirs(cwd, home).map((dir): SkillRoot => ({ dir: join(dir, '.agents', 'skills'), source: 'project', depth: CODEX_SKILL_DEPTH }))
         ];
     }
+
     const configDir = options.claudeConfigDir ?? join(home, '.claude');
+
     return [
         { dir: join(configDir, 'skills'), source: 'user' },
         ...projectDirs(cwd, home).map((dir): SkillRoot => ({ dir: join(dir, '.claude', 'skills'), source: 'project' })),
@@ -182,15 +213,11 @@ export async function skillRootsFor(kind: AgentKind, cwd: string, options: Skill
 
 /* Too many files open, in this process or on the system: it says nothing about the path that was asked for. */
 function isBusy(e: unknown): boolean {
-    return typeof e === 'object' && e !== null && 'code' in e && (e.code === 'EMFILE' || e.code === 'ENFILE');
-}
-
-function sleep(ms: number): Promise<void> {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+    return hasErrorCode(e, 'EMFILE', 'ENFILE');
 }
 
 /* Runs `operation` again a few times while the process is short of file handles, and throws if it still is. */
-export async function whileBusy<T>(operation: () => Promise<T>, wait: (ms: number) => Promise<void> = sleep): Promise<T> {
+export async function whileBusy<T>(operation: () => Promise<T>, sleep: (ms: number) => Promise<void> = wait): Promise<T> {
     for (let attempt = 1; ; attempt++) {
         try {
             return await operation();
@@ -198,7 +225,8 @@ export async function whileBusy<T>(operation: () => Promise<T>, wait: (ms: numbe
             if (!isBusy(e) || attempt > BUSY_RETRIES) {
                 throw e;
             }
-            await wait(BUSY_RETRY_MS * attempt);
+
+            await sleep(BUSY_RETRY_MS * attempt);
         }
     }
 }
@@ -207,33 +235,41 @@ export async function whileBusy<T>(operation: () => Promise<T>, wait: (ms: numbe
 export async function mapLimited<T, R>(items: readonly T[], limit: number, work: (item: T) => Promise<R>): Promise<R[]> {
     const results = new Array<R>(items.length);
     let next = 0;
+
     const worker = async (): Promise<void> => {
         while (next < items.length) {
             const index = next++;
             results[index] = await work(items[index]!);
         }
     };
+
     await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+
     return results;
 }
 
 /* The top of a folder's SKILL.md, or null when it has none. A process short of file handles throws instead of finding none. */
 async function skillHead(folder: string): Promise<string | null> {
     let handle;
+
     try {
         handle = await whileBusy(() => open(join(folder, 'SKILL.md'), 'r'));
     } catch (e) {
         if (isBusy(e)) {
             throw e;
         }
+
         return null;
     }
+
     try {
         if (!(await handle.stat()).isFile()) {
             return null;
         }
+
         const buffer = Buffer.alloc(HEAD_BYTES);
         const { bytesRead } = await handle.read(buffer, 0, HEAD_BYTES, 0);
+
         return buffer.subarray(0, bytesRead).toString('utf8');
     } catch {
         return null;
@@ -246,9 +282,11 @@ function skillOf(root: SkillRoot, folder: string, text: string): ChatSkill | nul
     const fields = parseFrontmatter(text);
     const own = fields.name && NAME.test(fields.name) ? fields.name : folder;
     const name = root.prefix ? `${root.prefix}:${own}` : own;
+
     if (!NAME.test(name)) {
         return null;
     }
+
     return { name, description: (fields.description ?? '').slice(0, MAX_DESCRIPTION), source: root.source };
 }
 
@@ -256,11 +294,13 @@ function skillOf(root: SkillRoot, folder: string, text: string): ChatSkill | nul
 async function realFolder(path: string): Promise<string | null> {
     try {
         const real = await whileBusy(() => realpath(path));
+
         return (await whileBusy(() => stat(real))).isDirectory() ? real : null;
     } catch (e) {
         if (isBusy(e)) {
             throw e;
         }
+
         return null;
     }
 }
@@ -272,52 +312,68 @@ async function realFolder(path: string): Promise<string | null> {
  */
 async function scanRoot(root: SkillRoot, limits: SkillScanLimits): Promise<ChatSkill[]> {
     const start = await realFolder(root.dir);
+
     if (start === null) {
         return [];
     }
+
     const visited = new Set([start]);
     const depth = root.depth ?? 1;
     const entriesPerFolder = limits.entries ?? ENTRIES_PER_FOLDER;
     const skills: ChatSkill[] = [];
     let level = [root.dir];
     let listed = 0;
+
     for (let below = 1; below <= depth && level.length > 0; below++) {
         const next: string[] = [];
+
         for (const folder of level) {
             if (listed >= limits.directories || skills.length >= limits.skills) {
                 return skills;
             }
+
             listed++;
             let entries: Dirent[];
+
             try {
                 entries = await whileBusy(() => readdir(folder, { withFileTypes: true }));
             } catch (e) {
                 if (isBusy(e)) {
                     throw e;
                 }
+
                 continue;
             }
+
             // A skill manager links each skill in from a shared folder, so a link counts as much as a folder.
             const candidates = entries
                 .filter((entry) => (entry.isDirectory() || entry.isSymbolicLink()) && !entry.name.startsWith('.'))
                 .map((entry) => ({ name: entry.name, path: join(folder, entry.name) }))
                 .sort((a, b) => a.name.localeCompare(b.name))
                 .slice(0, entriesPerFolder);
+
             const reals = await mapLimited(candidates, SCAN_CONCURRENCY, (candidate) => realFolder(candidate.path));
+
             const fresh = candidates.flatMap((candidate, index) => {
                 const real = reals[index];
+
                 return real === null || real === undefined || visited.has(real) ? [] : [{ ...candidate, real }];
             });
+
             const heads = await mapLimited(fresh, SCAN_CONCURRENCY, (candidate) => skillHead(candidate.path));
+
             for (const [index, candidate] of fresh.entries()) {
                 // Two links in one folder can lead to the same place; the first one read it.
                 if (visited.has(candidate.real)) {
                     continue;
                 }
+
                 const head = heads[index];
+
                 if (head !== null && head !== undefined) {
                     visited.add(candidate.real);
                     const skill = skillOf(root, candidate.name, head);
+
                     if (skill !== null && skills.length < limits.skills) {
                         skills.push(skill);
                     }
@@ -327,24 +383,29 @@ async function scanRoot(root: SkillRoot, limits: SkillScanLimits): Promise<ChatS
                 }
             }
         }
+
         level = next;
     }
+
     return skills;
 }
 
 /* Every skill under these roots, sorted by name; the first root that carries a name wins. */
 export async function scanSkillRoots(roots: SkillRoot[], limits: SkillScanLimits = SCAN_LIMITS): Promise<ChatSkill[]> {
     const found = new Map<string, ChatSkill>();
+
     for (const root of roots) {
         if (found.size >= limits.skills) {
             break;
         }
+
         for (const skill of await scanRoot(root, limits)) {
             if (!found.has(skill.name) && found.size < limits.skills) {
                 found.set(skill.name, skill);
             }
         }
     }
+
     return [...found.values()].sort((a, b) => a.name.localeCompare(b.name));
 }
 
@@ -352,7 +413,6 @@ export async function discoverSkills(kind: AgentKind, cwd: string, options: Skil
     return scanSkillRoots(await skillRootsFor(kind, cwd, options));
 }
 
-// How long a scan stays good; a skill written mid-session shows up on the next look.
 const CACHE_TTL_MS = 30_000;
 
 /* The skills of one CLI in one folder, scanned at most once per half minute. There is no watcher. */
@@ -367,11 +427,14 @@ export class SkillIndex {
     async list(kind: AgentKind, cwd: string): Promise<ChatSkill[]> {
         const key = `${kind}:${cwd}`;
         const cached = this.cache.get(key);
+
         if (cached && Date.now() - cached.at < CACHE_TTL_MS) {
             return cached.skills;
         }
+
         const skills = await discoverSkills(kind, cwd, this.options);
         this.cache.set(key, { at: Date.now(), skills });
+
         return skills;
     }
 

package/src/tasks/background-limit.ts

@@ -21,16 +21,21 @@ export function backgroundLimitHandler(deps: BackgroundLimitDeps) {
         if (deps.tasks.get(entry.payload.taskId)?.status !== 'open') {
             return;
         }
+
         const chat = await loadChat(deps, entry.target);
+
         if (chat === null) {
             return;
         }
+
         if (chat.info.activeTurnId !== null) {
             return 'wait';
         }
+
         if (runningInBackground(chat.thread.list()).length > 0) {
             return;
         }
+
         // A child whose process went since the limit started runs nothing any more; what it ran then is what the parent is told.
         const running = (chat.info.background ?? []).map(commandLabel);
         await deps.coordinator.outlasted(entry.target, running.length > 0 ? running : entry.payload.commands, entry.payload.restarted ? 'restart' : 'limit');
@@ -57,13 +62,15 @@ export async function restartBackgroundLimits(outbox: RestartedOutbox, now: numb
 
 /* The `background-limit` entries of a host's outbox, one per task at most, as the coordinator owes and drops them. */
 export function backgroundLimits(outbox: Pick<TaskOutbox, 'list' | 'enqueue' | 'remove'>): TaskCoordinatorDeps['limit'] {
+    const limitOf = (entry: AnyOutboxEntry, taskId: string): boolean => isBackgroundLimit(entry) && entry.payload.taskId === taskId;
+
     return {
-        owed: (taskId) => outbox.list().some((entry) => isBackgroundLimit(entry) && entry.payload.taskId === taskId),
+        owed: (taskId) => outbox.list().some((entry) => limitOf(entry, taskId)),
         owe: (task, commands, at) =>
             outbox.enqueue(task.projectId, task.childId, { kind: 'background-limit', payload: { taskId: task.id, commands: [...commands] } }, at),
         lapse: async (taskId) => {
             for (const entry of outbox.list()) {
-                if (isBackgroundLimit(entry) && entry.payload.taskId === taskId) {
+                if (limitOf(entry, taskId)) {
                     await outbox.remove(entry.id);
                 }
             }

package/src/tasks/end-children.ts

@@ -65,19 +65,24 @@ export function endChildren(deps: EndChildrenDeps): EndChildren {
     const end = async (nodeIds: readonly string[], reason: string): Promise<void> => {
         await lineage.markEnded(nodeIds);
         const ended = new Set(nodeIds);
+
         for (const owed of outbox.list()) {
             if (reviving.has(owed.kind) && ended.has(owed.target)) {
                 await outbox.remove(owed.id);
             }
         }
+
         await tasks.cancelOpen(ended, reason, now());
+
         // A stopped chat that gave tasks of its own is not woken about them either.
         for (const nodeId of nodeIds) {
             await tasks.dropWake(nodeId);
         }
+
         for (const nodeId of [...nodeIds].reverse()) {
             await deps.stop(nodeId, reason);
         }
+
         await deps.ended?.(nodeIds);
     };
 
@@ -85,13 +90,17 @@ export function endChildren(deps: EndChildrenDeps): EndChildren {
         owe: async (target, named) => {
             const nodeIds = named === undefined ? lineage.descendants(target) : [...named];
             const projectId = nodeIds.map((id) => lineage.projectOf(id)).find((id) => id !== null) ?? null;
+
             if (nodeIds.length === 0 || projectId === null) {
                 return 0;
             }
+
             const owed = outbox.list().some((entry) => entry.kind === 'end-children' && entry.target === target);
+
             if (!owed) {
                 await outbox.enqueue(projectId, target, { kind: 'end-children', payload: { nodeIds } });
             }
+
             return nodeIds.length;
         },
         handler: (entry) => end([...new Set([...entry.payload.nodeIds, ...lineage.descendants(entry.target)])], deps.reason),

package/src/tasks/give-task.ts

@@ -29,24 +29,32 @@ export interface GiveTaskDeps {
 export function giveTaskHandler(deps: GiveTaskDeps) {
     return async (entry: GiveTaskEntry): Promise<OutboxOutcome> => {
         const task = deps.tasks.get(entry.payload.taskId);
+
         // Settled or cancelled before the turn could open, or a node the project no longer places.
         if (!task || task.status !== 'open' || !deps.placed(task.childId)) {
             return;
         }
+
         const chat = await deps.chat(task.childId);
+
         if (chat === null) {
             throw new Error(`${task.childId} has no chat to open a turn in`);
         }
+
         // The turn names the task, so a restart between opening it and dropping this entry gives it once.
         if (chat.items().some((item) => item.kind === 'turn' && (item.taskIds ?? []).includes(task.id))) {
             await chat.persist?.();
+
             return;
         }
+
         const from = deps.titleFor(task.parentId) ?? task.parentId;
         const text = deps.assignment?.(task) ?? task.prompt;
+
         if (!chat.wake({ text, label: task.title, note: taskNote(from), taskIds: [task.id] })) {
             return 'wait';
         }
+
         await chat.persist?.();
     };
 }