@adecore/agents 0.0.1 → 0.17.0-beta.1

package/dist/messages/notice-notes.js

@@ -0,0 +1,26 @@
+/*
+ * What another node left for a chat, taken from the queue in front of its next prompt so the model
+ * hears it once. Nothing of it is shown: a person read each message in the thread as it landed
+ * (`showNotices`), so repeating it above the turn says the same thing twice.
+ */
+export class NoticeNotes {
+    store;
+    chatId;
+    words;
+    constructor(store, chatId, words) {
+        this.store = store;
+        this.chatId = chatId;
+        this.words = words;
+    }
+    next() {
+        return { shown: [], heard: this.store.take(this.chatId).map((notice) => this.words.heard(notice)) };
+    }
+    reset() { }
+}
+/*
+ * The lines a chat that just loaded owes a person for what landed while nobody held it, marked so a
+ * reload writes none again. The model still hears the messages themselves from the queue.
+ */
+export async function unshownNotes(store, chatId, words) {
+    return (await store.show(chatId)).map((notice) => words.shown(notice));
+}

package/dist/messages/notice-store.d.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+export declare const MAX_NOTICES = 10;
+export declare const NOTICE_MAX_AGE_MS: number;
+declare const NoticeSchema: z.ZodObject<{
+    projectId: z.ZodString;
+    targetId: z.ZodString;
+    from: z.ZodString;
+    fromTitle: z.ZodString;
+    text: z.ZodString;
+    createdAt: z.ZodNumber;
+    shown: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type Notice = z.infer<typeof NoticeSchema>;
+export declare class NoticeStore {
+    readonly dir: string;
+    private readonly queues;
+    private readonly now;
+    private lastDrop;
+    constructor(dataDir: string, now?: () => number);
+    load(): Promise<void>;
+    put(notice: Omit<Notice, 'createdAt'>): Promise<number>;
+    take(targetId: string): Notice[];
+    settled(): Promise<void>;
+    show(targetId: string): Promise<Notice[]>;
+    waiting(targetId: string): Notice[];
+    prune(projectId: string, ids: ReadonlySet<string>): Promise<void>;
+    private fresh;
+    private persist;
+}
+export {};

package/dist/messages/notice-store.js

@@ -0,0 +1,120 @@
+import { join } from 'node:path';
+import { z } from 'zod';
+import { errorText } from '../error-text.js';
+import { RecordDirectory } from '../record-directory.js';
+// Per receiver. Past this the oldest goes: an agent in a loop must not fill a queue nobody reads.
+export const MAX_NOTICES = 10;
+/*
+ * A message nobody picked up in this long is dropped rather than delivered. It is news about work
+ * happening now ("the build is green"), and a model reading it six hours late would act on
+ * something that has moved on. The cap alone would not do it: one message in a queue of one waits
+ * for ever.
+ */
+export const NOTICE_MAX_AGE_MS = 6 * 60 * 60 * 1000;
+const NoticeSchema = z.object({
+    projectId: z.string().min(1),
+    /* The node the message is for; also the file it waits in. */
+    targetId: z.string().min(1),
+    /* The node that sent it, by id, since that is what the receiver can act on. */
+    from: z.string().min(1),
+    fromTitle: z.string(),
+    text: z.string().min(1),
+    createdAt: z.number(),
+    /*
+     * Whether a person was shown this message already. Its own mark, beside the queue: the queue is
+     * emptied by the model reading the message, and the two readers must not take it from each
+     * other. Absent is unshown, so a message left by an older host is still shown once.
+     */
+    shown: z.boolean().optional()
+});
+/* A queue waits in the file of the node it is for, so the first message in it names that node. */
+const FileSchema = z.object({ notices: z.array(NoticeSchema).min(1) });
+/*
+ * The messages waiting for each node, held until that node's agent has a moment to hear them, under
+ * `<dataDir>/notices`. On disk because the receiver may well be a node nobody has mounted yet, and a
+ * host that restarts must not lose what was left for it. Delivered once, whichever channel gets there
+ * first.
+ */
+export class NoticeStore {
+    dir;
+    queues;
+    now;
+    lastDrop = Promise.resolve();
+    constructor(dataDir, now = Date.now) {
+        this.dir = join(dataDir, 'notices');
+        this.now = now;
+        this.queues = new RecordDirectory({
+            dir: this.dir,
+            schema: FileSchema,
+            idOf: (file) => file.notices[0].targetId,
+            // What went stale while the host was down is not delivered; a queue of nothing else goes.
+            keep: (file) => {
+                const fresh = file.notices.filter((notice) => this.fresh(notice));
+                return fresh[0] === undefined ? null : { notices: fresh };
+            }
+        });
+    }
+    load() {
+        return this.queues.load();
+    }
+    /* Puts one message in a node's queue and answers how many now wait for it. */
+    async put(notice) {
+        const queue = [...this.waiting(notice.targetId), { ...notice, createdAt: this.now() }].slice(-MAX_NOTICES);
+        await this.persist(notice.targetId, queue);
+        return queue.length;
+    }
+    /*
+     * Everything waiting for a node, gone the moment it is asked for. Synchronous, because the
+     * callers are: a shell's first screen and a hook's answer are both written before anything can
+     * be awaited. The queue leaves memory first and the file follows, so two channels asking in the
+     * same tick cannot both be handed the same message.
+     */
+    take(targetId) {
+        const queue = this.waiting(targetId);
+        if (queue.length === 0) {
+            return [];
+        }
+        this.lastDrop = this.persist(targetId, []).catch((e) => console.error(`Dropping the messages of ${targetId} failed:`, errorText(e)));
+        return queue;
+    }
+    /* Resolves once the file the last `take` dropped is gone; `take` cannot hand that promise back itself. */
+    settled() {
+        return this.lastDrop;
+    }
+    /*
+     * What nobody showed a person yet, marked here so it is shown once. The messages stay in the
+     * queue: this is the second reader, and only the model's copy may be taken away.
+     */
+    async show(targetId) {
+        const queue = this.waiting(targetId);
+        const unshown = queue.filter((notice) => notice.shown !== true);
+        if (unshown.length === 0) {
+            return [];
+        }
+        await this.persist(targetId, queue.map((notice) => ({ ...notice, shown: true })));
+        return unshown;
+    }
+    /* What waits for a node, without taking it; the stale ones are already gone from the answer. */
+    waiting(targetId) {
+        const file = this.queues.get(targetId);
+        if (file === undefined) {
+            return [];
+        }
+        return file.notices.filter((notice) => this.fresh(notice));
+    }
+    /* Drops what a project was holding for ids it no longer has: the node was deleted before it read them. */
+    prune(projectId, ids) {
+        return this.queues.prune((file) => file.notices[0].projectId === projectId && !ids.has(file.notices[0].targetId));
+    }
+    fresh(notice) {
+        return this.now() - notice.createdAt < NOTICE_MAX_AGE_MS;
+    }
+    /* The queue of one node, emptied here and on disk both; an empty one leaves no file behind. */
+    async persist(targetId, queue) {
+        if (queue.length === 0) {
+            await this.queues.remove(targetId);
+            return;
+        }
+        await this.queues.write({ notices: queue });
+    }
+}

package/dist/modes.d.ts

@@ -0,0 +1,11 @@
+import { type RuntimeMode } from '@adecore/agent-contracts';
+import { z } from 'zod';
+export declare const MODE_ORDER: ("auto" | "auto-accept-edits" | "full-access" | "supervised")[];
+export declare function narrowerMode(mode: RuntimeMode, ceiling: RuntimeMode): RuntimeMode;
+export declare function ceilingForOpening(opener: RuntimeMode, requested: RuntimeMode | undefined): RuntimeMode;
+export declare const modeFlag: z.ZodOptional<z.ZodEnum<{
+    auto: "auto";
+    "auto-accept-edits": "auto-accept-edits";
+    "full-access": "full-access";
+    supervised: "supervised";
+}>>;

package/dist/modes.js

@@ -0,0 +1,28 @@
+import { RuntimeModeSchema } from '@adecore/agent-contracts';
+import { z } from 'zod';
+import { VerbRefusal } from './context/verb.js';
+/*
+ * Every CLI's flags widen in this order (its permission flags and the Codex thread options), and where
+ * two modes share a flag clamping down grants the same, never more. So one order serves every CLI.
+ */
+export const MODE_ORDER = RuntimeModeSchema.options;
+function rankOf(mode) {
+    return MODE_ORDER.indexOf(mode);
+}
+export function narrowerMode(mode, ceiling) {
+    return rankOf(mode) <= rankOf(ceiling) ? mode : ceiling;
+}
+function modeLines(mine) {
+    return [`mode\tyou\t${mine}`, ...MODE_ORDER.filter((mode) => rankOf(mode) <= rankOf(mine)).map((mode) => `mode\t${mode}\tallowed`)];
+}
+/*
+ * The mode an agent the opener opens may get at most, refusing a `--mode` above it. The ceiling is
+ * the opener's own mode, so a chain of agents can only ever narrow what it may do, never widen it.
+ */
+export function ceilingForOpening(opener, requested) {
+    if (requested !== undefined && rankOf(requested) > rankOf(opener)) {
+        throw new VerbRefusal('mode-above-parent', `You run in ${opener} and --mode ${requested} is wider; an agent you open runs in your mode or a narrower one`, modeLines(opener));
+    }
+    return opener;
+}
+export const modeFlag = z.enum(MODE_ORDER, { error: `--mode is one of ${MODE_ORDER.join(', ')}` }).optional();

package/dist/outbox/manual-clock.d.ts

@@ -0,0 +1,10 @@
+import type { OutboxClock } from './outbox-worker.ts';
+export declare class ManualClock implements OutboxClock {
+    private time;
+    private timers;
+    private nextId;
+    now(): number;
+    setTimeout(run: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+    advance(ms: number): void;
+}

package/dist/outbox/manual-clock.js

@@ -0,0 +1,25 @@
+/* A clock a test moves by hand. A timer fires only inside `advance`, never on its own. */
+export class ManualClock {
+    time = 1_000_000;
+    timers = [];
+    nextId = 1;
+    now() {
+        return this.time;
+    }
+    setTimeout(run, ms) {
+        const id = this.nextId++;
+        this.timers.push({ at: this.time + ms, run, id });
+        return id;
+    }
+    clearTimeout(handle) {
+        this.timers = this.timers.filter((timer) => timer.id !== handle);
+    }
+    advance(ms) {
+        this.time += ms;
+        const due = this.timers.filter((timer) => timer.at <= this.time);
+        this.timers = this.timers.filter((timer) => timer.at > this.time);
+        for (const timer of due) {
+            timer.run();
+        }
+    }
+}

package/dist/outbox/outbox-worker.d.ts

@@ -0,0 +1,44 @@
+import type { OutboxEntryOf, OutboxStore, OutboxWorkShape } from './outbox.ts';
+export declare const RETRY_DELAYS_MS: readonly number[];
+export interface OutboxClock {
+    now(): number;
+    setTimeout(run: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+export declare const systemClock: OutboxClock;
+export type OutboxOutcome = void | 'wait';
+export type OutboxHandlers<Work extends OutboxWorkShape> = {
+    [K in Work['kind']]: (entry: Extract<OutboxEntryOf<Work>, {
+        kind: K;
+    }>) => Promise<OutboxOutcome>;
+};
+export interface OutboxWorkerOptions<Work extends OutboxWorkShape> {
+    store: OutboxStore<Work>;
+    handlers: OutboxHandlers<Work>;
+    clock?: OutboxClock;
+    onParked?: (entry: OutboxEntryOf<Work>, error: unknown) => void;
+}
+export declare class OutboxWorker<Work extends OutboxWorkShape> {
+    private readonly store;
+    private readonly handlers;
+    private readonly clock;
+    private readonly onParked;
+    private readonly running;
+    private readonly waiting;
+    private readonly wakes;
+    private timer;
+    private started;
+    private waiters;
+    constructor(options: OutboxWorkerOptions<Work>);
+    start(): void;
+    stop(): void;
+    enqueue(projectId: string, target: string, work: Work, notBefore?: number): Promise<void>;
+    wake(target: string): void;
+    settled(): Promise<void>;
+    private drain;
+    private run;
+    private failed;
+    private schedule;
+    private isSettled;
+    private notifySettled;
+}

package/dist/outbox/outbox-worker.js

@@ -0,0 +1,173 @@
+import { errorText } from '../error-text.js';
+/* How long a failed entry waits before each next attempt; one more failure than there are delays parks it. */
+export const RETRY_DELAYS_MS = [1_000, 5_000, 30_000];
+export const systemClock = {
+    now: () => Date.now(),
+    setTimeout: (run, ms) => setTimeout(run, ms),
+    clearTimeout: (handle) => clearTimeout(handle)
+};
+/*
+ * Works the outbox off, oldest first and one entry at a time per target, so two pieces of work
+ * about one node never overlap while nodes beside it do not wait on each other. A handler is
+ * idempotent, since a restart between the work and the removal of its file runs it again.
+ */
+export class OutboxWorker {
+    store;
+    handlers;
+    clock;
+    onParked;
+    running = new Set();
+    // Entries that said `wait`, until their target is woken; in memory only, so a restart looks again.
+    waiting = new Set();
+    // Bumped by every wake of a target, so a wake that lands while its entry is still deciding to wait is not lost.
+    wakes = new Map();
+    timer = null;
+    started = false;
+    waiters = [];
+    constructor(options) {
+        this.store = options.store;
+        this.handlers = options.handlers;
+        this.clock = options.clock ?? systemClock;
+        this.onParked = options.onParked ?? (() => undefined);
+    }
+    start() {
+        this.started = true;
+        this.drain();
+    }
+    stop() {
+        this.started = false;
+        if (this.timer !== null) {
+            this.clock.clearTimeout(this.timer);
+            this.timer = null;
+        }
+    }
+    /* Owes a piece of work and starts on it; resolves once the entry is on disk, not once it is done. */
+    async enqueue(projectId, target, work, notBefore) {
+        const now = this.clock.now();
+        await this.store.put(projectId, target, work, now, notBefore ?? now);
+        this.drain();
+    }
+    /*
+     * Something about this target changed (a chat ended its turn), so whatever waited on it looks again.
+     * Deferred, so it never runs inside the broadcast of the chat that said so.
+     */
+    wake(target) {
+        this.wakes.set(target, (this.wakes.get(target) ?? 0) + 1);
+        let woke = false;
+        for (const entry of this.store.list()) {
+            if (entry.target === target && this.waiting.delete(entry.id)) {
+                woke = true;
+            }
+        }
+        if (woke) {
+            queueMicrotask(() => this.drain());
+        }
+    }
+    /* Resolves once nothing is running and nothing is due; an entry waiting out a retry or a wake does not count. */
+    settled() {
+        if (this.isSettled()) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            this.waiters.push(resolve);
+        });
+    }
+    drain() {
+        if (!this.started) {
+            this.notifySettled();
+            return;
+        }
+        const now = this.clock.now();
+        const busy = new Set(this.running);
+        let nextDue = null;
+        for (const entry of this.store.list()) {
+            // A waiting entry holds no lane. The resume of a chat must not queue behind a wake that waits for it.
+            if (busy.has(entry.target) || this.waiting.has(entry.id)) {
+                continue;
+            }
+            // Nor does work due at a later time, which nothing owed before it has to wait for.
+            if (entry.attempts === 0 && entry.notBefore > now) {
+                nextDue = nextDue === null ? entry.notBefore : Math.min(nextDue, entry.notBefore);
+                continue;
+            }
+            const lanes = this.store.lanesOf(entry);
+            // Oldest first per target. A younger entry never overtakes one that waits out a retry.
+            for (const lane of lanes) {
+                busy.add(lane);
+            }
+            // The other lanes only wait for work that is running; work that is merely owed there is what ending takes away.
+            if (lanes.some((lane) => lane !== entry.target && this.running.has(lane))) {
+                continue;
+            }
+            if (entry.notBefore > now) {
+                nextDue = nextDue === null ? entry.notBefore : Math.min(nextDue, entry.notBefore);
+                continue;
+            }
+            void this.run(entry);
+        }
+        this.schedule(nextDue, now);
+        this.notifySettled();
+    }
+    async run(entry) {
+        const lanes = this.store.lanesOf(entry);
+        for (const lane of lanes) {
+            this.running.add(lane);
+        }
+        const woken = this.wakes.get(entry.target) ?? 0;
+        try {
+            const outcome = await this.handlers[entry.kind](entry);
+            if (outcome === 'wait') {
+                if ((this.wakes.get(entry.target) ?? 0) === woken && this.store.has(entry.id)) {
+                    this.waiting.add(entry.id);
+                }
+                return;
+            }
+            await this.store.remove(entry.id);
+        }
+        catch (e) {
+            await this.failed(entry, e).catch((error) => console.error(`The outbox could not record a failed ${entry.kind}:`, errorText(error)));
+        }
+        finally {
+            for (const lane of lanes) {
+                this.running.delete(lane);
+            }
+            this.drain();
+        }
+    }
+    async failed(entry, error) {
+        const delay = RETRY_DELAYS_MS[entry.attempts];
+        if (delay === undefined) {
+            await this.store.remove(entry.id);
+            console.error(`Gave up on ${entry.kind} for ${entry.target}:`, errorText(error));
+            this.onParked(entry, error);
+            return;
+        }
+        await this.store.update({ ...entry, attempts: entry.attempts + 1, notBefore: this.clock.now() + delay });
+    }
+    schedule(nextDue, now) {
+        if (this.timer !== null) {
+            this.clock.clearTimeout(this.timer);
+            this.timer = null;
+        }
+        if (nextDue !== null) {
+            this.timer = this.clock.setTimeout(() => {
+                this.timer = null;
+                this.drain();
+            }, Math.max(0, nextDue - now));
+        }
+    }
+    isSettled() {
+        const now = this.clock.now();
+        return this.running.size === 0 && (!this.started || !this.store.list().some((entry) => entry.notBefore <= now && !this.waiting.has(entry.id)));
+    }
+    notifySettled() {
+        if (!this.isSettled()) {
+            return;
+        }
+        const waiting = this.waiters;
+        this.waiters = [];
+        for (const resolve of waiting) {
+            resolve();
+        }
+    }
+}

package/dist/outbox/outbox.d.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+export interface OutboxWorkShape {
+    kind: string;
+    payload: unknown;
+}
+declare const OutboxEntryFieldsSchema: z.ZodObject<{
+    id: z.ZodString;
+    projectId: z.ZodString;
+    target: z.ZodString;
+    createdAt: z.ZodNumber;
+    attempts: z.ZodNumber;
+    notBefore: z.ZodNumber;
+}, z.core.$strip>;
+export type OutboxEntryFields = z.infer<typeof OutboxEntryFieldsSchema>;
+export type OutboxEntryOf<Work extends OutboxWorkShape> = Work & OutboxEntryFields;
+export interface OutboxStoreOptions<Work extends OutboxWorkShape> {
+    dataDir: string;
+    work: z.ZodType<Work>;
+    lanesOf?(entry: OutboxEntryOf<Work>): string[];
+    outlivesTarget?(entry: OutboxEntryOf<Work>): boolean;
+}
+export declare class OutboxStore<Work extends OutboxWorkShape> {
+    readonly dir: string;
+    private readonly entries;
+    private readonly lanes;
+    private readonly outlivesTarget;
+    constructor(options: OutboxStoreOptions<Work>);
+    load(): Promise<void>;
+    put(projectId: string, target: string, work: Work, now: number, notBefore?: number): Promise<OutboxEntryOf<Work>>;
+    update(entry: OutboxEntryOf<Work>): Promise<void>;
+    remove(id: string): Promise<void>;
+    list(): OutboxEntryOf<Work>[];
+    has(id: string): boolean;
+    lanesOf(entry: OutboxEntryOf<Work>): string[];
+    prune(projectId: string, ids: ReadonlySet<string>): Promise<void>;
+}
+export {};

package/dist/outbox/outbox.js

@@ -0,0 +1,76 @@
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { RecordDirectory } from '../record-directory.js';
+const OutboxEntryFieldsSchema = z.object({
+    id: z.string().min(1),
+    projectId: z.string().min(1),
+    // The node the work is about. Entries for one target run one at a time, and it goes with the node.
+    target: z.string().min(1),
+    createdAt: z.number(),
+    attempts: z.number().int().nonnegative(),
+    notBefore: z.number()
+});
+/*
+ * Work a host still owes, one file per entry under `<dataDir>/outbox`, removed once it is done. On
+ * disk because the owing outlives the process: a node written a moment before a restart still has
+ * its agent started after it.
+ */
+export class OutboxStore {
+    dir;
+    entries;
+    lanes;
+    outlivesTarget;
+    constructor(options) {
+        this.dir = join(options.dataDir, 'outbox');
+        this.entries = new RecordDirectory({
+            dir: this.dir,
+            schema: z.intersection(options.work, OutboxEntryFieldsSchema),
+            idOf: (entry) => entry.id
+        });
+        this.lanes = options.lanesOf ?? ((entry) => [entry.target]);
+        this.outlivesTarget = options.outlivesTarget ?? (() => false);
+    }
+    /* Reads what an earlier run of the host still owed. Call before the worker starts. */
+    load() {
+        return this.entries.load();
+    }
+    /* `notBefore` later than `now` is work due at a time, which holds no lane until then. */
+    async put(projectId, target, work, now, notBefore = now) {
+        const entry = {
+            ...work,
+            id: `${work.kind}-${randomBytes(6).toString('hex')}`,
+            projectId,
+            target,
+            createdAt: now,
+            attempts: 0,
+            notBefore
+        };
+        await this.entries.write(entry);
+        return entry;
+    }
+    /* The same entry with what its last attempt left behind. */
+    async update(entry) {
+        if (!this.entries.has(entry.id)) {
+            return;
+        }
+        await this.entries.write(entry);
+    }
+    remove(id) {
+        return this.entries.remove(id);
+    }
+    /* Oldest first, which is the order the work was owed in. */
+    list() {
+        return this.entries.all().sort((a, b) => a.createdAt - b.createdAt);
+    }
+    has(id) {
+        return this.entries.has(id);
+    }
+    lanesOf(entry) {
+        return this.lanes(entry);
+    }
+    /* Drops what this project owed for ids it no longer has, since nothing is started for a node that was deleted. */
+    prune(projectId, ids) {
+        return this.entries.prune((entry) => entry.projectId === projectId && !this.outlivesTarget(entry) && !ids.has(entry.target));
+    }
+}

package/dist/providers/accounts/accounts.d.ts

@@ -0,0 +1,20 @@
+import { type AgentKind, type ProviderAccount, type ProviderAccountMap } from '@adecore/agent-contracts';
+import type { ChatProvider } from '../provider.ts';
+import { type AccountsHost, type ReservedVariables } from './variables.ts';
+export type Env = Record<string, string | undefined>;
+export declare function isKnownKind(kind: string): kind is AgentKind;
+export declare function isDefaultAccount(id: string, account: Pick<ProviderAccount, 'kind'>): boolean;
+export declare function expandHome(path: string, env: Env): string;
+export declare function accountProblem(id: string, account: ProviderAccount, provider: ChatProvider, env: Env, reserved?: ReservedVariables): string | null;
+export declare function folderVariablesOf(providerOf: (kind: AgentKind) => ChatProvider): string[];
+export declare function withDefaults(accounts: ProviderAccountMap): ProviderAccountMap;
+export declare function defaultFolder(provider: ChatProvider, env: Env): string;
+export declare function accountFolder(id: string, account: ProviderAccount, provider: ChatProvider, env: Env): string;
+export declare function transcriptFolder(id: string, account: ProviderAccount, provider: ChatProvider, env: Env): string;
+export declare function accountEnv(id: string, account: ProviderAccount, provider: ChatProvider, baseEnv: Env, variables?: Record<string, string>): Env;
+export interface NamedAccount {
+    id: string;
+    account: ProviderAccount;
+}
+export declare function canContinue(from: NamedAccount, to: NamedAccount, providerOf: (kind: AgentKind) => ChatProvider, env: Env): boolean;
+export declare function readAccount(id: string, raw: unknown, providerOf: (kind: AgentKind) => ChatProvider, env: Env, host?: AccountsHost): unknown;