@adecore/agents 0.0.1 → 0.17.0-beta.1

package/dist/chat/bookmark-store.js

@@ -0,0 +1,141 @@
+import { mkdir, readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CHAT_BOOKMARK_LIMITS, ChatBookmarksSchema, clipText } from '@adecore/agent-contracts';
+import { z } from 'zod';
+import { isNotFound, writeAtomic } from '../fs.js';
+import { KeyedSerializer } from '../serializer.js';
+import { ChatError } from './errors.js';
+const SUFFIX = '.bookmarks.json';
+const BookmarkFileSchema = z.object({ version: z.literal(1), bookmarks: ChatBookmarksSchema });
+export function bookmarkFileName(chatId) {
+    return `${encodeURIComponent(chatId)}${SUFFIX}`;
+}
+/* Whether a name in the chats folder is a bookmarks file, which the chat records beside it must not count as a chat. */
+export function isBookmarkFileName(name) {
+    return name.endsWith(SUFFIX);
+}
+/* A name as it is kept: trimmed, and none at all when nothing is left. */
+function cleanName(name) {
+    const trimmed = name === undefined ? undefined : clipText(name.trim(), CHAT_BOOKMARK_LIMITS.name);
+    return trimmed === undefined || trimmed === '' ? undefined : trimmed;
+}
+function named(bookmark, name) {
+    const { name: _previous, ...rest } = bookmark;
+    return name === undefined ? rest : { ...rest, name };
+}
+/*
+ * The bookmarks of every chat, one file per chat beside its record under `<home>/chats`, apart
+ * from the record, which is rewritten on every turn. One chain per chat puts two clients' clicks
+ * after each other, and every change is told to the listeners from inside that chain, so the lists
+ * go out in the order they were written.
+ */
+export class BookmarkStore {
+    dir;
+    writes = new KeyedSerializer();
+    listeners = new Set();
+    constructor(home) {
+        this.dir = join(home, 'chats');
+    }
+    listen(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /* The bookmarks of one chat in the order they were made, after any write still on its way. */
+    read(chatId) {
+        return this.writes.run(chatId, () => this.readFile(chatId));
+    }
+    /* Marks a message; one that already has a bookmark keeps it, and takes the name when one is given. */
+    add(chatId, input, now) {
+        return this.change(chatId, (bookmarks) => {
+            const name = cleanName(input.name);
+            const existing = bookmarks.find((bookmark) => bookmark.itemId === input.itemId);
+            if (existing) {
+                return name === undefined ? null : bookmarks.map((bookmark) => (bookmark === existing ? named(bookmark, name) : bookmark));
+            }
+            if (bookmarks.length >= CHAT_BOOKMARK_LIMITS.perChat) {
+                throw new ChatError('too-many-bookmarks', `This chat already keeps ${CHAT_BOOKMARK_LIMITS.perChat} bookmarks; remove one first`);
+            }
+            const excerpt = clipText(input.excerpt, CHAT_BOOKMARK_LIMITS.excerpt);
+            return [...bookmarks, named({ itemId: input.itemId, excerpt, createdAt: now }, name)];
+        });
+    }
+    rename(chatId, itemId, name) {
+        return this.change(chatId, (bookmarks) => {
+            if (!bookmarks.some((bookmark) => bookmark.itemId === itemId)) {
+                throw new ChatError('bookmark-not-found', `This chat has no bookmark on ${itemId}`);
+            }
+            return bookmarks.map((bookmark) => (bookmark.itemId === itemId ? named(bookmark, cleanName(name)) : bookmark));
+        });
+    }
+    remove(chatId, itemId) {
+        return this.change(chatId, (bookmarks) => bookmarks.some((bookmark) => bookmark.itemId === itemId) ? bookmarks.filter((bookmark) => bookmark.itemId !== itemId) : null);
+    }
+    /* The bookmarks go with the chat or with a clear of it. A file that no longer parses goes too, since nothing could show it again. */
+    removeChat(chatId) {
+        return this.writes.run(chatId, async () => {
+            const had = await this.readFile(chatId).then((bookmarks) => bookmarks.length > 0, () => true);
+            await rm(join(this.dir, bookmarkFileName(chatId)), { force: true });
+            if (had) {
+                this.tell(chatId, []);
+            }
+        });
+    }
+    /* A fork keeps the bookmarks on the messages it copied, which are the ones up to where it was cut. */
+    async copyChat(fromChatId, toChatId, keep) {
+        const kept = (await this.read(fromChatId)).filter((bookmark) => keep(bookmark.itemId));
+        if (kept.length === 0) {
+            return;
+        }
+        await this.writes.run(toChatId, async () => {
+            await this.writeFile(toChatId, kept);
+            this.tell(toChatId, kept);
+        });
+    }
+    /* One read, one decision and one write in the chat's chain; a change that returns null changes nothing and tells nobody. */
+    change(chatId, decide) {
+        return this.writes.run(chatId, async () => {
+            const bookmarks = await this.readFile(chatId);
+            const next = decide(bookmarks);
+            if (next === null) {
+                return bookmarks;
+            }
+            await this.writeFile(chatId, next);
+            this.tell(chatId, next);
+            return next;
+        });
+    }
+    tell(chatId, bookmarks) {
+        for (const listener of this.listeners) {
+            listener(chatId, bookmarks);
+        }
+    }
+    async readFile(chatId) {
+        let raw;
+        try {
+            raw = await readFile(join(this.dir, bookmarkFileName(chatId)), 'utf8');
+        }
+        catch (e) {
+            if (isNotFound(e)) {
+                return [];
+            }
+            throw e;
+        }
+        // A file that does not parse is refused rather than read as empty, which the next write would make true.
+        const parsed = BookmarkFileSchema.safeParse(JSON.parse(raw));
+        if (!parsed.success) {
+            throw new Error(`The bookmarks file of chat ${chatId} is not valid: ${parsed.error.issues[0]?.message ?? 'unknown problem'}`);
+        }
+        return parsed.data.bookmarks;
+    }
+    async writeFile(chatId, bookmarks) {
+        const path = join(this.dir, bookmarkFileName(chatId));
+        if (bookmarks.length === 0) {
+            await rm(path, { force: true });
+            return;
+        }
+        await mkdir(this.dir, { recursive: true, mode: 0o700 });
+        await writeAtomic(path, JSON.stringify({ version: 1, bookmarks }));
+    }
+}

package/dist/chat/chat-core.d.ts

@@ -0,0 +1,311 @@
+import { type AgentKind, type ChatAttachment, type ChatAttachResult, type ChatAttachmentUpload, type ChatBookmark, type ChatCheckpointDiff, type ChatConfigurePayload, type ChatCreatePayload, type ChatEvent, type ChatHistoryResult, type ChatInfo, type ChatItem, type ChatQueuedMessage, type ChatSkill, type ChatSubagentPayload, type ChatSubagentResult, type ChatTurnItem, type ModelSelection, type RuntimeMode } from '@adecore/agent-contracts';
+import { ClientSinks } from '../client-sinks.ts';
+import type { AgentEvent, AgentSink } from '../events.ts';
+import type { OutboxOutcome } from '../outbox/outbox-worker.ts';
+import { type AccountLaunches } from '../providers/accounts/launch.ts';
+import type { ProviderRegistry } from '../providers/registry.ts';
+import { SkillIndex } from '../skills.ts';
+import type { LimitsUpdate } from '../usage/limits/normalize.ts';
+import type { AttachmentStore } from './attachment-store.ts';
+import type { BookmarkStore } from './bookmark-store.ts';
+import type { SpawnChatProcess } from './chat-process.ts';
+import { ChatSession, type ChatReferences, type ChatSendExtras, type PromptNotes, type ResumeWords, type TurnCheckpoints } from './chat-session.ts';
+import type { ChatRecord, ChatRecordExtras, ChatStore } from './chat-store.ts';
+import type { ChatTitleInput } from './chat-title.ts';
+import type { CodexProcessSpec } from './codex-thread.ts';
+import type { CodexClientInfo } from './codex-transport.ts';
+import { ComposerPreferences } from './composer-preferences.ts';
+import { DeltaCoalescer } from './delta-coalescer.ts';
+import { type BackgroundWork } from './background-work.ts';
+import { SubagentReader, type SubagentReaderOptions } from './subagent-reader.ts';
+export interface InterruptedRun {
+    chatId: string;
+    turnId: string;
+    attempt: number;
+}
+export interface ChatCoreOptions {
+    providers: ProviderRegistry;
+    store?: ChatStore;
+    checkpoints?: TurnCheckpoints;
+    env?: Record<string, string | undefined>;
+    instructions?: string;
+    command?: string[];
+    codexCommand?: string[];
+    spawn?: SpawnChatProcess;
+    codexClient?: CodexClientInfo;
+    skills?: SkillIndex;
+    attachments: AttachmentStore;
+    bookmarks?: BookmarkStore;
+    onLimits?: (update: LimitsUpdate) => void;
+    claudeTitles?: {
+        forSession(agentSessionId: string, projectsDir: string): Promise<string | null>;
+    };
+    nameChat?: (provider: AgentKind, input: ChatTitleInput) => Promise<string | null>;
+    subagents?: Partial<Pick<SubagentReaderOptions, 'claudeProjectsDir' | 'seams' | 'now' | 'listOnce'>>;
+    onInterruptedRun?: (run: InterruptedRun) => Promise<boolean>;
+    limitResume?: {
+        allowed(): boolean;
+        now(): number;
+        owe(chatId: string, turnId: string, at: number): Promise<void>;
+        lapse(chatId: string): Promise<void>;
+        owed(chatId: string): boolean;
+    };
+    accounts?: AccountLaunches;
+}
+export declare class ChatCore {
+    protected readonly providers: ProviderRegistry;
+    protected readonly store: ChatStore | null;
+    protected readonly bookmarks: BookmarkStore | null;
+    protected readonly accounts: AccountLaunches | null;
+    protected readonly attachments: AttachmentStore;
+    protected readonly env: Record<string, string>;
+    protected readonly chats: Map<string, ChatSession>;
+    protected readonly creating: Map<string, Promise<{
+        chatId: string;
+        provider: "apple" | "claude" | "codex" | "copilot" | "gemini";
+        account?: string | undefined;
+        cwd: string;
+        agentSessionId: string | null;
+        model: string | null;
+        selection: {
+            model: string;
+            options: Record<string, string | boolean>;
+        };
+        runtimeMode: "auto" | "auto-accept-edits" | "full-access" | "supervised";
+        effectiveRuntimeMode?: "auto" | "auto-accept-edits" | "full-access" | "supervised" | undefined;
+        permissionMode?: string | undefined;
+        status: "error" | "exited" | "idle" | "needs-you" | "running";
+        running: boolean;
+        activeTurnId: string | null;
+        slashCommands: string[];
+        skills?: string[] | undefined;
+        queue?: {
+            id: string;
+            turnId?: string | undefined;
+            text: string;
+            mentions?: string[] | undefined;
+            skills?: string[] | undefined;
+            chats?: string[] | undefined;
+            attachments?: {
+                id: string;
+                name: string;
+                mime: string;
+                size: number;
+                path: string;
+            }[] | undefined;
+            createdAt: number;
+        }[] | undefined;
+        queuePaused?: boolean | undefined;
+        background?: {
+            id: string;
+            kind: "monitor" | "shell";
+            description: string;
+            command: string | null;
+            startedAt: number;
+        }[] | undefined;
+        delegating?: boolean | undefined;
+        usage: {
+            contextTokens: number;
+            contextWindow: number | null;
+            costUsd: number;
+            turns: number;
+            breakdown?: {
+                toolOutput: number;
+                filesRead: number;
+                conversation: number;
+                system: number;
+            } | undefined;
+        };
+        suggestedTitle?: string | undefined;
+        hidden?: boolean | undefined;
+        forkOf?: {
+            chatId: string;
+            turnId: string;
+            at: number;
+        } | undefined;
+        resumeAtReset?: boolean | undefined;
+        limit?: {
+            kind: "overload" | "usage";
+            resetsAt?: number | undefined;
+        } | undefined;
+        resumeAt?: number | undefined;
+        requests?: {
+            requestId: string;
+            itemId: string;
+            kind: "approval" | "question";
+            createdAt: number;
+            approval?: {
+                toolName: string;
+                subject: string;
+                description: string | null;
+                path?: string | undefined;
+                files?: number | undefined;
+                diff?: string | undefined;
+                command?: string | undefined;
+                truncated?: boolean | undefined;
+                canAllowAlways: boolean;
+                allowAlways?: {
+                    label: string;
+                    description: string;
+                } | undefined;
+            } | undefined;
+            question?: {
+                questions: {
+                    id: string;
+                    header: string;
+                    question: string;
+                    choices: {
+                        label: string;
+                        description: string;
+                    }[];
+                    multiSelect: boolean;
+                }[];
+                async?: boolean | undefined;
+            } | undefined;
+        }[] | undefined;
+        createdAt: number;
+    }>>;
+    protected readonly sinks: ClientSinks<AgentEvent>;
+    protected readonly attached: Map<string, Set<string>>;
+    protected readonly coalescers: Map<string, DeltaCoalescer>;
+    protected readonly subagents: SubagentReader;
+    readonly claudeProjectsDir: string;
+    readonly composerPreferences: ComposerPreferences;
+    private readonly checkpoints;
+    private readonly instructions;
+    private readonly skillIndex;
+    private readonly onLimits;
+    private readonly commands;
+    private readonly spawn;
+    private readonly codexClient;
+    private readonly announced;
+    private readonly logs;
+    private readonly sizes;
+    private readonly waiting;
+    private readonly unlogged;
+    private readonly writes;
+    private readonly activity;
+    private readonly observers;
+    private readonly claudeTitles;
+    private readonly nameChat;
+    private readonly onInterruptedRun;
+    private readonly limitResume;
+    constructor(options: ChatCoreOptions);
+    codexProcess(info: Pick<ChatInfo, 'cwd' | 'account'>): CodexProcessSpec;
+    claudeProjectsDirOf(info: Pick<ChatInfo, 'account'>): string;
+    canContinue(kind: AgentKind, from: string | undefined, to: string | undefined): boolean;
+    requireAccount(kind: AgentKind, account: string | undefined): void;
+    accountLabel(kind: AgentKind, account: string | undefined): string;
+    readChat(chatId: string): Promise<{
+        info: ChatInfo;
+        items: ChatItem[];
+    } | null>;
+    startingPoint(provider: AgentKind, selection?: ModelSelection): {
+        selection: ModelSelection;
+        runtimeMode?: RuntimeMode;
+        contextWindow: number | null;
+    };
+    observe(sink: AgentSink): () => void;
+    subscribe(clientId: string, sink: AgentSink): () => void;
+    create(payload: ChatCreatePayload): Promise<ChatInfo>;
+    private createNow;
+    storedBackground(chatId: string): Promise<{
+        turnId: string | null;
+        items: BackgroundWork[];
+        commands: string[];
+    }>;
+    save(chatId: string): Promise<void>;
+    isLoading(chatId: string): boolean;
+    configure(payload: ChatConfigurePayload): ChatInfo;
+    protected switchAccount(session: ChatSession, requested: string): void;
+    attach(chatId: string, clientId: string, historyLimit?: number, since?: number): ChatAttachResult;
+    attachWithBookmarks(chatId: string, clientId: string, historyLimit?: number, since?: number): Promise<ChatAttachResult>;
+    addBookmark(chatId: string, itemId: string, name?: string): Promise<ChatBookmark[]>;
+    renameBookmark(chatId: string, itemId: string, name: string): Promise<ChatBookmark[]>;
+    removeBookmark(chatId: string, itemId: string): Promise<ChatBookmark[]>;
+    private requireBookmarks;
+    history(chatId: string, cursor: string, limit?: number): ChatHistoryResult;
+    detach(chatId: string, clientId: string): void;
+    detachAll(clientId: string): void;
+    subagent(clientId: string, payload: ChatSubagentPayload): Promise<ChatSubagentResult>;
+    stopSubagent(chatId: string, toolUseId: string): Promise<void>;
+    stopTask(chatId: string, taskId: string): Promise<void>;
+    subagentItems(chatId: string, toolUseId: string): Promise<ChatItem[]>;
+    hasStored(chatId: string): Promise<boolean>;
+    lastTurn(chatId: string): Promise<ChatTurnItem | null>;
+    addNote(chatId: string, level: 'info' | 'warning' | 'error', text: string): Promise<void>;
+    deliverNote(chatId: string, delivery: {
+        noteId: string;
+        note: string;
+        from?: string;
+        preamble: string;
+    }): Promise<boolean>;
+    send(chatId: string, text: string, extras?: ChatSendExtras, uploads?: ChatAttachmentUpload[]): Promise<{
+        queued: boolean;
+        turnId: string;
+    }>;
+    attachment(chatId: string, id: string): ChatAttachment | null;
+    unqueue(chatId: string, messageId: string): ChatQueuedMessage;
+    sendNow(chatId: string, messageId: string): void;
+    skills(chatId: string): Promise<ChatSkill[]>;
+    compact(chatId: string): void;
+    clear(chatId: string, force?: boolean): Promise<void>;
+    cancel(chatId: string, subagents?: boolean): void;
+    turnDiff(chatId: string, turnId: string): Promise<ChatCheckpointDiff | null>;
+    approve(chatId: string, requestId: string, decision: 'allow' | 'allow-always' | 'deny', message?: string): void;
+    answer(chatId: string, requestId: string, answers: Record<string, string>): void;
+    dismiss(chatId: string, itemId: string): void;
+    kill(chatId: string): Promise<void>;
+    stop(chatId: string, reason: string): Promise<void>;
+    processTargets(): {
+        id: string;
+        pid: number;
+        provider: AgentKind;
+        status: ChatInfo['status'];
+        updatedAt: number;
+    }[];
+    list(): ChatInfo[];
+    get(chatId: string): ChatSession | undefined;
+    resumeRun(chatId: string, turnId: string, attempt: number): Promise<void>;
+    takeUpAfterLimit(chatId: string, turnId: string): Promise<OutboxOutcome>;
+    resumeSettingChanged(): void;
+    abandonRun(chatId: string, turnId: string, reason: string): void;
+    recoverInterrupted(): Promise<void>;
+    shutdown(): Promise<void>;
+    persistAllSync(): void;
+    persisted(chatId: string): Promise<void>;
+    protected loaded(chatId: string): Promise<void>;
+    protected persist(chatId: string): void;
+    protected require(chatId: string): ChatSession;
+    protected instructionsFor(_chatId: string): string | null;
+    protected resumeNoteFor(_chatId: string): string | null;
+    protected foldersFor(_chatId: string): readonly string[];
+    protected hiddenFor(_chatId: string): boolean;
+    protected promptNotesFor(_chatId: string): PromptNotes | undefined;
+    protected referencesFor(_chatId: string): ChatReferences | undefined;
+    protected envFor(_chatId: string, base: Record<string, string>): Record<string, string | undefined>;
+    protected admit(_chatId: string, _cwd: string): Promise<void>;
+    protected openingSelection(_chatId: string, _kind: AgentKind): ModelSelection | undefined;
+    protected runtimeModeFor(_chatId: string, mode: RuntimeMode): RuntimeMode;
+    protected opened(_session: ChatSession, _stored: ChatRecord | null): Promise<void>;
+    protected recordExtras(_chatId: string): ChatRecordExtras;
+    protected cleared(_chatId: string): Promise<void>;
+    protected clearing(_chatId: string): Promise<void>;
+    protected forgotten(_chatId: string): void;
+    protected removed(_chatId: string, _chat: {
+        info: ChatInfo;
+        items: ChatItem[];
+    }): Promise<void>;
+    protected broadcasted(_chatId: string, _event: ChatEvent): void;
+    protected endedAt(_chatId: string): number | null;
+    protected unownedReason(_chatId: string): string;
+    protected resumeWords(_chatId: string): Promise<ResumeWords>;
+    private persistSoon;
+    private cancelWaiting;
+    private persistNow;
+    private emit;
+    private broadcast;
+    private announceStatus;
+    private openLog;
+    private owedResume;
+}