@adecore/agents 0.38.0 → 0.40.0

package/src/context/verb.ts

@@ -145,6 +145,7 @@ function usageWithFlags(usage: string, detail: readonly string[]): string {
         .map((line) => line.split('\t'))
         .filter(([, syntax]) => !flagSpelled(usage, syntax!.split(' ')[0]!))
         .map(([, syntax, need]) => (need === 'required' ? syntax! : `[${syntax}]`));
+
     return [usage, ...missing].filter((part) => part !== '').join(' ');
 }
 
@@ -182,9 +183,6 @@ export function createVerbRegistry<Call extends VerbCallBase>(options: { cli: st
      */
     const dryRunVerbs: string[] = [];
 
-    /* What a refusal over arguments points at; for an action `name` is both words, which is what `help` takes. */
-    const usageLinesOf = (name: string, usage: string): string[] => [`usage\t${name}\t${usage}`, `detail\t${cli} help ${name}`];
-
     /* One set of arguments parsed and run. `name` is what a refusal calls it, so `view new` refuses under both its words. */
     const runArgs = async <Positionals extends z.ZodType, Flags extends z.ZodObject>(
         name: string,
@@ -193,11 +191,13 @@ export function createVerbRegistry<Call extends VerbCallBase>(options: { cli: st
         argv: readonly string[],
         call: Call
     ): Promise<string[]> => {
-        const usageLines = usageLinesOf(name, usage);
+        const usageLines = [`usage\t${name}\t${usage}`, `detail\t${cli} help ${name}`];
         const { values, switches } = flagsOf(spec);
         const parsed = parseArgv(argv, values, switches);
+
         if (!parsed.ok) {
             const dryRunAsked = argv.some((word) => word === `--${DRY_RUN_FLAG}` || word.startsWith(`--${DRY_RUN_FLAG}=`));
+
             if (parsed.code === 'unknown-flag' && spec.dryRun !== true && dryRunAsked) {
                 throw new VerbRefusal(
                     'no-dry-run',
@@ -205,20 +205,27 @@ export function createVerbRegistry<Call extends VerbCallBase>(options: { cli: st
                     dryRunVerbs.map((verb) => `verb\t${verb}\ttakes --${DRY_RUN_FLAG}`)
                 );
             }
+
             throw new VerbRefusal(parsed.code, parsed.message, usageLines);
         }
+
         const positionals = spec.positionals.safeParse(parsed.positionals);
+
         if (!positionals.success) {
             throw new VerbRefusal('bad-arguments', issueMessage(positionals.error, 'argument'), usageLines);
         }
+
         const { [REVISION_FLAG]: revision, ...given } = parsed.flags;
         const flags = spec.flags.safeParse(given);
+
         if (!flags.success) {
             throw new VerbRefusal('bad-arguments', issueMessage(flags.error, 'flag'), usageLines);
         }
+
         if (revision !== undefined && !/^\d+$/.test(revision)) {
             throw new VerbRefusal('bad-arguments', `--${REVISION_FLAG} takes the whole number a list printed as revision`, usageLines);
         }
+
         return spec.run(
             { positionals: positionals.data, flags: flags.data, switches: parsed.switches, dryRun: parsed.switches.has(DRY_RUN_FLAG) },
             revision === undefined ? call : { ...call, expectedRevision: Number(revision) }
@@ -231,10 +238,13 @@ export function createVerbRegistry<Call extends VerbCallBase>(options: { cli: st
         spec: VerbSpec<Positionals, Flags, Call>
     ): Omit<Verb<Call>, 'served'> => {
         const { values, switches } = flagsOf(spec);
+
         if (spec.dryRun === true) {
             dryRunVerbs.push(name);
         }
+
         const usage = usageWithFlags(spec.usage, spec.detail);
+
         return {
             name,
             usage,
@@ -258,6 +268,7 @@ export function createVerbRegistry<Call extends VerbCallBase>(options: { cli: st
 
     const defineNoun = (spec: NounSpec<Call>): Noun<Call> => {
         const words = spec.actions.map((action) => action.word);
+
         return {
             served: 'noun',
             name: spec.name,
@@ -268,6 +279,7 @@ export function createVerbRegistry<Call extends VerbCallBase>(options: { cli: st
             async run(argv, call) {
                 const [word, ...rest] = argv;
                 const action = spec.actions.find((candidate) => candidate.word === word);
+
                 if (!action) {
                     throw new VerbRefusal(
                         'unknown-action',
@@ -275,6 +287,7 @@ export function createVerbRegistry<Call extends VerbCallBase>(options: { cli: st
                         [...spec.actions.map((candidate) => `usage\t${candidate.name}\t${candidate.usage}`), `detail\t${cli} help ${spec.name}`]
                     );
                 }
+
                 return action.run(rest, call);
             }
         };
@@ -282,6 +295,7 @@ export function createVerbRegistry<Call extends VerbCallBase>(options: { cli: st
 
     const defineHelp = (spec: HelpSpec<Call>): Verb<Call> => {
         const detailLines = (entry: VerbHelp): string[] => [`usage\t${entry.name}\t${entry.usage}`, `about\t${entry.summary}`, ...entry.detail, spec.refusal];
+
         const nounLines = (noun: Noun<Call>): string[] => [
             `usage\t${noun.name}\t${noun.usage}`,
             `about\t${noun.summary}`,
@@ -290,9 +304,11 @@ export function createVerbRegistry<Call extends VerbCallBase>(options: { cli: st
             `detail\t${cli} help ${noun.name} <action>\tone action in full`,
             spec.refusal
         ];
+
         const topics = spec.topics ?? [];
         const topicLines = topics.map((topic) => `topic\t${topic.name}\t${topic.summary}`);
         const topicPointer = topics.length > 0 ? [`detail\t${cli} help <topic>\tone topic in full`] : [];
+
         return defineVerb({
             name: 'help',
             usage: '[noun] [action]',
@@ -311,6 +327,7 @@ export function createVerbRegistry<Call extends VerbCallBase>(options: { cli: st
             flags: z.object({}),
             run: async ({ positionals: [name, actionWord] }) => {
                 const entries = spec.entries();
+
                 if (name === undefined) {
                     return [
                         ...summaryLines(entries),
@@ -323,16 +340,20 @@ export function createVerbRegistry<Call extends VerbCallBase>(options: { cli: st
                         spec.refusal
                     ];
                 }
+
                 const entry = entries.find((candidate) => candidate.name === name);
                 const topic = entry ? undefined : topics.find((candidate) => candidate.name === name);
+
                 if (topic) {
                     if (actionWord !== undefined) {
                         throw new VerbRefusal('bad-arguments', `${name} is a topic and has no actions; ${cli} help ${name} prints it`, [
                             `detail\t${cli} help ${name}\tthe topic in full`
                         ]);
                     }
+
                     return [`about\t${topic.summary}`, ...topic.body];
                 }
+
                 if (!entry) {
                     throw new VerbRefusal('unknown-verb', topics.length > 0 ? `${name} is not a verb, a noun or a topic` : `${name} is not a verb or a noun`, [
                         `detail\t${cli} help\tevery verb and noun, with what each takes`,
@@ -340,21 +361,27 @@ export function createVerbRegistry<Call extends VerbCallBase>(options: { cli: st
                         ...topicLines
                     ]);
                 }
+
                 if (entry.served !== 'noun') {
                     if (actionWord !== undefined) {
                         throw new VerbRefusal('bad-arguments', `${name} is a verb and has no actions; ${cli} help ${name} details it`, [
                             `detail\t${cli} help ${name}\tone verb in full`
                         ]);
                     }
+
                     return detailLines(entry);
                 }
+
                 if (actionWord === undefined) {
                     return nounLines(entry);
                 }
+
                 const action = entry.actions.find((candidate) => candidate.word === actionWord);
+
                 if (!action) {
                     throw new VerbRefusal('unknown-action', `${actionWord} is not an action of ${name}`, actionLines(entry));
                 }
+
                 return detailLines(action);
             }
         });
@@ -373,6 +400,7 @@ export function lengthOf(input: unknown): number {
     if (typeof input === 'string' || Array.isArray(input)) {
         return input.length;
     }
+
     return 0;
 }
 

package/src/coordination/index.ts

@@ -1,5 +1,6 @@
 // Public API: exports.test.ts snapshots this list, so a name added or dropped here is an API change.
 export { type OutboxEntryOf, OutboxStore, type OutboxWorkShape, type OutboxEntryFields, type OutboxStoreOptions } from '../outbox/outbox.ts';
+
 export {
     RETRY_DELAYS_MS,
     type OutboxClock,
@@ -9,7 +10,9 @@ export {
     OutboxWorker,
     type OutboxWorkerOptions
 } from '../outbox/outbox-worker.ts';
+
 export { restartBackgroundLimits, type RestartedOutbox } from '../tasks/background-limit.ts';
+
 export {
     EndChildrenWorkSchema,
     endChildren,
@@ -19,8 +22,10 @@ export {
     type EndChildrenDeps,
     type EndChildren
 } from '../tasks/end-children.ts';
+
 export { type TaskCoordinatorDeps, TaskCoordinator } from '../tasks/task-coordinator.ts';
 export { TaskStore, type TaskListener, type TaskEvent, type TaskSink } from '../tasks/task-store.ts';
+
 export {
     BackgroundLimitWorkSchema,
     WakeParentWorkSchema,
@@ -35,6 +40,7 @@ export {
     type AnyOutboxEntry,
     type TaskOutbox
 } from '../tasks/task-work.ts';
+
 export {
     type ChatRequests,
     chatRequests,
@@ -44,8 +50,10 @@ export {
     type WaitingObserverDeps,
     type WaitingWords
 } from '../tasks/waiting-child.ts';
+
 export { RESULT_PREVIEW_BYTES, wakePrompt } from '../tasks/wake-parent.ts';
 export { type TaskVerbs, type TaskWords, wireTasks, type TaskChats, type TaskRecord, type TaskWiringDeps, type TaskWiring } from '../tasks/wiring.ts';
+
 export {
     DeliverMessageWorkSchema,
     deliverMessageHandler,
@@ -53,6 +61,7 @@ export {
     type DeliverMessageEntry,
     type DeliverMessageDeps
 } from '../messages/deliver-message.ts';
+
 export {
     type MessageWords,
     type ChatNoticeTargets,
@@ -62,6 +71,7 @@ export {
     showNotices,
     type NoticeChat
 } from '../messages/deliver-notice.ts';
+
 export { NoticeNotes, unshownNotes } from '../messages/notice-notes.ts';
 export { MAX_NOTICES, NOTICE_MAX_AGE_MS, type Notice, NoticeStore } from '../messages/notice-store.ts';
 export { AgentLineageStore } from '../lineage.ts';

package/src/error-text.ts

@@ -9,12 +9,19 @@ export function describeError(error: unknown, debug: boolean): string {
     if (!(error instanceof Error)) {
         return String(error);
     }
+
     if (debug) {
         return error.stack ?? `${error.name}: ${error.message}`;
     }
+
     return error.message === '' ? error.name : error.message;
 }
 
+/* What was thrown, as an Error a rejection can carry. */
+export function asError(thrown: unknown): Error {
+    return thrown instanceof Error ? thrown : new Error(String(thrown));
+}
+
 // The host decides once whether a stack is worth showing; the package reads no variable of its own.
 let showStacks = false;
 

package/src/fields.ts

@@ -0,0 +1,14 @@
+/* A field of a frame or a file that no schema promises a string in. */
+export function str(value: unknown): string | null {
+    return typeof value === 'string' ? value : null;
+}
+
+/* A count of a frame, zero for anything that is not a finite number. */
+export function num(value: unknown): number {
+    return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+
+/* The same, with an empty string read as nothing said. */
+export function filledStr(value: unknown): string | null {
+    return typeof value === 'string' && value !== '' ? value : null;
+}

package/src/fs.ts

@@ -1,6 +1,7 @@
 import { renameSync, writeFileSync } from 'node:fs';
 import { open, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
+import { wait } from './async.ts';
 
 // Windows can refuse a rename while a watcher or an indexer holds the target; a few short retries cover it.
 const RENAME_RETRIES = 5;
@@ -11,8 +12,12 @@ function sleepSync(ms: number): void {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
 
+export function hasErrorCode(e: unknown, ...codes: string[]): boolean {
+    return typeof e === 'object' && e !== null && 'code' in e && codes.includes(e.code as string);
+}
+
 function isTransient(e: unknown): boolean {
-    return typeof e === 'object' && e !== null && 'code' in e && (e.code === 'EPERM' || e.code === 'EBUSY' || e.code === 'EACCES');
+    return hasErrorCode(e, 'EPERM', 'EBUSY', 'EACCES');
 }
 
 // Two writes of the same file in flight at once (a fire-and-forget save next to an awaited one) must not share a temp name.
@@ -30,6 +35,7 @@ export interface WriteAtomicOptions {
 
 async function writeFlushed(path: string, content: string | Uint8Array, mode: number): Promise<void> {
     const handle = await open(path, 'w', mode);
+
     try {
         await handle.writeFile(content);
         await handle.sync();
@@ -43,7 +49,9 @@ async function syncDirectory(path: string): Promise<void> {
     if (process.platform === 'win32') {
         return;
     }
+
     const handle = await open(path, 'r');
+
     try {
         await handle.sync();
     } finally {
@@ -58,22 +66,27 @@ async function syncDirectory(path: string): Promise<void> {
  */
 export async function writeAtomic(target: string, content: string | Uint8Array, mode = 0o600, options: WriteAtomicOptions = {}): Promise<void> {
     const temp = tempNameFor(target);
+
     if (options.durable) {
         await writeFlushed(temp, content, mode);
     } else {
         await writeFile(temp, content, { mode });
     }
+
     for (let attempt = 0; ; attempt++) {
         try {
             await rename(temp, target);
+
             break;
         } catch (e) {
             if (!isTransient(e) || attempt >= RENAME_RETRIES) {
                 throw e;
             }
-            await new Promise((resolve) => setTimeout(resolve, RENAME_RETRY_MS));
+
+            await wait(RENAME_RETRY_MS);
         }
     }
+
     if (options.durable) {
         await syncDirectory(dirname(target));
     }
@@ -88,11 +101,13 @@ export function replaceSync(temp: string, target: string): void {
     for (let attempt = 0; ; attempt++) {
         try {
             renameSync(temp, target);
+
             return;
         } catch (e) {
             if (!isTransient(e) || attempt >= RENAME_RETRIES) {
                 throw e;
             }
+
             sleepSync(RENAME_RETRY_MS);
         }
     }
@@ -105,7 +120,7 @@ export function writeAtomicSync(target: string, content: string | Uint8Array, mo
 }
 
 export function isNotFound(e: unknown): boolean {
-    return typeof e === 'object' && e !== null && 'code' in e && e.code === 'ENOENT';
+    return hasErrorCode(e, 'ENOENT');
 }
 
 // Bun on Windows fails a forced rm with EFAULT while another delete of the same file is pending; it goes either way.
@@ -113,7 +128,7 @@ export async function removeFile(path: string, remove: (path: string, options: {
     try {
         await remove(path, { force: true });
     } catch (e) {
-        if (!(typeof e === 'object' && e !== null && 'code' in e && e.code === 'EFAULT')) {
+        if (!hasErrorCode(e, 'EFAULT')) {
             throw e;
         }
     }
@@ -122,6 +137,7 @@ export async function removeFile(path: string, remove: (path: string, options: {
 export async function fileExists(path: string): Promise<boolean> {
     try {
         await stat(path);
+
         return true;
     } catch {
         return false;

package/src/host/agent-host.ts

@@ -53,34 +53,42 @@ export class AgentHost<Core extends ChatCore = ChatCore> {
     static async open<Core extends ChatCore = ChatCore>(options: AgentHostOptions<Core>): Promise<AgentHost<Core>> {
         const host = new AgentHost(options);
         await host.accounts.load();
+
         if (host.background) {
             host.wiring.start();
         }
+
         return host;
     }
 
     /* Serves one client over `port` until the returned function or `close` lets go of it. */
     connect(port: FramePort): () => void {
         const clientId = `port-${this.nextClient++}`;
+
         const releases = [
             port.onFrame((frame) => void this.receive(port, clientId, frame)),
             this.wiring.connect(clientId, (event) => port.send({ type: 'event', event: event.event, payload: event.payload }))
         ];
+
         const disconnect = (): void => {
             if (!this.connections.delete(disconnect)) {
                 return;
             }
+
             for (const release of releases) {
                 release();
             }
         };
+
         this.connections.add(disconnect);
+
         return disconnect;
     }
 
     /* Lets go of every client, writes every thread and ends every CLI; settles once they exited. */
     close(): Promise<void> {
         this.closing ??= this.shutDown();
+
         return this.closing;
     }
 
@@ -88,35 +96,47 @@ export class AgentHost<Core extends ChatCore = ChatCore> {
         for (const disconnect of [...this.connections]) {
             disconnect();
         }
+
         await this.wiring.stop();
     }
 
     private async receive(port: FramePort, clientId: string, frame: unknown): Promise<void> {
         const parsed = parseRequest(frame);
+
         if (!parsed.ok) {
             // The id when the frame carried a usable one, so the client can settle its promise.
             const id = typeof frame === 'object' && frame !== null && 'id' in frame && typeof frame.id === 'string' && frame.id !== '' ? frame.id : null;
             port.send(errorReply(id, 'bad-request', parsed.message));
+
             return;
         }
+
         const { id, type, payload } = parsed.value;
+
         if (!isAgentRequest(type)) {
             port.send(errorReply(id, 'unknown-request', `Unknown request type: ${type}`));
+
             return;
         }
+
         const checked = AGENT_REQUEST_SCHEMAS[type].payload.safeParse(payload);
+
         if (!checked.success) {
             port.send(errorReply(id, 'bad-request', `Invalid payload for ${type}`));
+
             return;
         }
+
         try {
             const handler = this.wiring.handlers[type] as AgentHandler<AgentRequestType>;
             port.send({ id, ok: true, result: await handler(checked.data as never, clientId) });
         } catch (e) {
             if (e instanceof CodedError) {
                 port.send(errorReply(id, e.code, e.message));
+
                 return;
             }
+
             console.error(`Handler for ${type} failed:`, errorText(e));
             port.send(errorReply(id, 'internal', 'Request failed'));
         }

package/src/host/environment.ts

@@ -13,19 +13,25 @@ const COMPATIBILITY_PREFIXES = ['RUIMTE_HOOK_', 'RUIMTE_CONTEXT_'];
 export function cliEnvironment(env: Record<string, string | undefined> = process.env, policy: CliEnvironmentPolicy = {}): Record<string, string> {
     const variables = new Set<string>([...RUIMTE_SESSION_VARIABLES, ...(policy.variables ?? [])]);
     const prefixes = [...COMPATIBILITY_PREFIXES, ...(policy.prefixes ?? [])];
+
     for (const host of policy.sessionPrefixes ?? []) {
         const prefix = host.replace(/_+$/, '');
+
         if (prefix === '') {
             throw new Error('A session environment prefix must not be empty');
         }
+
         variables.add(`${prefix}_SESSION_ID`);
         prefixes.push(`${prefix}_HOOK_`, `${prefix}_CONTEXT_`);
     }
+
     const clean: Record<string, string> = {};
+
     for (const [name, value] of Object.entries(env)) {
         if (value !== undefined && !variables.has(name) && !prefixes.some((prefix) => name.startsWith(prefix))) {
             clean[name] = value;
         }
     }
+
     return clean;
 }

package/src/host/handlers.ts

@@ -42,6 +42,7 @@ export function chatHandlers(chats: ChatCore, providers: ProviderRegistry): { [T
         // What a chat the host starts on its own is made with, while this client is connected.
         'chat.setPreferences': (payload, clientId) => {
             chats.composerPreferences.set(clientId, payload);
+
             return {};
         },
         'chat.attach': (payload, clientId) => chats.attachWithBookmarks(payload.chatId, clientId, payload.historyLimit, payload.since),
@@ -49,18 +50,22 @@ export function chatHandlers(chats: ChatCore, providers: ProviderRegistry): { [T
         'chat.subagent': (payload, clientId) => chats.subagent(clientId, payload),
         'chat.stopSubagent': async (payload) => {
             await chats.stopSubagent(payload.chatId, payload.toolUseId);
+
             return {};
         },
         'chat.stopTask': async (payload) => {
             await chats.stopTask(payload.chatId, payload.taskId);
+
             return {};
         },
         'chat.goal': async (payload) => {
             await chats.goal(payload.chatId, payload.action);
+
             return {};
         },
         'chat.detach': (payload, clientId) => {
             chats.detach(payload.chatId, clientId);
+
             return {};
         },
         'chat.send': (payload) =>
@@ -83,15 +88,18 @@ export function chatHandlers(chats: ChatCore, providers: ProviderRegistry): { [T
         'chat.unqueue': (payload) => ({ message: chats.unqueue(payload.chatId, payload.messageId) }),
         'chat.sendNow': (payload) => {
             chats.sendNow(payload.chatId, payload.messageId);
+
             return {};
         },
         'skills.list': async (payload) => ({ skills: await chats.skills(payload.chatId) }),
         'chat.compact': (payload) => {
             chats.compact(payload.chatId);
+
             return {};
         },
         'chat.clear': async (payload) => {
             await chats.clear(payload.chatId, payload.force === true);
+
             return {};
         },
         'chat.turnDiff': async (payload) => ({ diff: await chats.turnDiff(payload.chatId, payload.turnId) }),
@@ -101,18 +109,22 @@ export function chatHandlers(chats: ChatCore, providers: ProviderRegistry): { [T
         'chat.continueOn': unsupported('continue a chat under another account'),
         'chat.cancel': (payload) => {
             chats.cancel(payload.chatId, payload.subagents === true);
+
             return {};
         },
         'chat.approve': (payload) => {
             chats.approve(payload.chatId, payload.requestId, payload.decision, payload.message);
+
             return {};
         },
         'chat.answer': (payload) => {
             chats.answer(payload.chatId, payload.requestId, payload.answers);
+
             return {};
         },
         'chat.dismiss': (payload) => {
             chats.dismiss(payload.chatId, payload.itemId);
+
             return {};
         },
         'chat.addBookmark': async (payload) => ({ bookmarks: await chats.addBookmark(payload.chatId, payload.itemId, payload.name) }),
@@ -121,10 +133,12 @@ export function chatHandlers(chats: ChatCore, providers: ProviderRegistry): { [T
         'chat.removeVisual': async (payload) => ({ visuals: await chats.removeVisual(payload.chatId, payload.visualId) }),
         'chat.kill': async (payload) => {
             await chats.kill(payload.chatId);
+
             return {};
         },
         'chat.restart': async (payload) => {
             await chats.restart(payload.chatId);
+
             return {};
         },
         'chat.list': () => ({ chats: chats.list() })
@@ -139,6 +153,7 @@ export function accountHandlers(accounts: ProviderAccountsService): { [T in Acco
         'accounts.create': (payload) => accounts.create(payload),
         'accounts.watchLogin': (payload) => {
             void accounts.watchLogin(payload.id);
+
             return {};
         }
     };
@@ -150,15 +165,18 @@ export function usageHandlers(usage: UsageService, limits: UsageMonitor): { [T i
         // While a client has the page open the host keeps scanning; every other client gets the event too.
         'usage.subscribe': (_payload, clientId) => {
             usage.follow(clientId);
+
             return {};
         },
         'usage.unsubscribe': (_payload, clientId) => {
             usage.unfollow(clientId);
+
             return {};
         },
         'usage.limits': () => limits.snapshot(),
         'usage.refreshLimits': async () => {
             await limits.refresh(true);
+
             return limits.snapshot();
         }
     };

package/src/host/memory-port.ts

@@ -7,9 +7,11 @@ import type { FramePort } from '@adecore/agent-contracts';
  */
 export function memoryPortPair(): [FramePort, FramePort] {
     const listeners: [Set<(frame: unknown) => void>, Set<(frame: unknown) => void>] = [new Set(), new Set()];
+
     const end = (own: number): FramePort => ({
         send: (frame) => {
             const copy = structuredClone(frame);
+
             queueMicrotask(() => {
                 for (const listener of listeners[1 - own]!) {
                     listener(copy);
@@ -18,10 +20,12 @@ export function memoryPortPair(): [FramePort, FramePort] {
         },
         onFrame: (listener) => {
             listeners[own]!.add(listener);
+
             return () => {
                 listeners[own]!.delete(listener);
             };
         }
     });
+
     return [end(0), end(1)];
 }