@adecore/agents 0.23.0 → 0.24.0

package/README.md

@@ -16,7 +16,7 @@ The package brings no CLI: install Claude Code or Codex and sign in with it.
 ## Use
 
 ```ts
-import { AgentHost } from '@adecore/agents/host/agent-host';
+import { AgentHost } from '@adecore/agents/host';
 
 const host = await AgentHost.open({ dataDir });
 const disconnect = host.connect(port);
@@ -26,7 +26,7 @@ disconnect();
 await host.close();
 ```
 
-Every module has its own subpath, `@adecore/agents/<path>`; there is no root import. A new chat runs in `full-access` unless it names a runtime mode, so name one.
+The root holds the file, process and error helpers; `/host`, `/chat`, `/providers`, `/usage`, `/coordination`, `/context` and `/testing` hold the rest. A module that no entry exports is internal. A new chat runs in `full-access` unless it names a runtime mode, so name one.
 
 ## Documentation
 
@@ -41,7 +41,7 @@ Every module has its own subpath, `@adecore/agents/<path>`; there is no root imp
 | [Context commands](https://adecore.dev/agents/context-commands) | A command line your agents call back into |
 | [Storage](https://adecore.dev/agents/storage) | What is written where, and the file helpers |
 | [Testing](https://adecore.dev/agents/testing) | The fakes and the error codes |
-| [Modules](https://adecore.dev/agents/reference) | Every subpath of the package |
+| [Exports](https://adecore.dev/agents/reference) | Every entry point and its exports |
 
 ## License
 

package/dist/chat/attachment-store.js

@@ -1,7 +1,7 @@
 import { createHash, randomBytes } from 'node:crypto';
 import { link, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { extname, join } from 'node:path';
-import { attachmentImageMime } from '@adecore/agent-contracts';
+import { isRecord, attachmentImageMime } from '@adecore/agent-contracts';
 // The extension the file gets on disk when its name does not carry a usable one.
 const EXTENSIONS = {
     'image/png': 'png',
@@ -92,12 +92,11 @@ export class AttachmentStore {
     }
     /* Where the files of one chat are; a store that keeps more of a chat's files beside them writes them here. */
     folderOf(chatId) {
-        return join(this.dir, encodeURIComponent(chatId));
+        // `encodeURIComponent` leaves `.` and `..` as they are, and those would name this folder or the host's own.
+        const segment = chatId === '.' || chatId === '..' ? chatId.replaceAll('.', '%2E') : encodeURIComponent(chatId);
+        return join(this.dir, segment);
     }
 }
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 // What an attachment looked like before the files moved out of the thread: the bytes inline.
 function isInline(value) {
     return isRecord(value) && typeof value.name === 'string' && typeof value.mediaType === 'string' && typeof value.data === 'string';

package/dist/chat/backend.d.ts

@@ -1,4 +1,4 @@
-import type { ChatAttachment, ChatAttachmentUpload, ChatFileChange, ChatQuestion, ChatSkill, ChatSubagentUsage, ChatTurnLimit, ChatWorkflow, ModelSelection, RuntimeMode } from '@adecore/agent-contracts';
+import type { ChatAttachment, ChatAttachmentUpload, ChatFileChange, ChatGoal, ChatGoalAction, ChatQuestion, ChatSkill, ChatSubagentUsage, ChatTurnLimit, ChatWorkflow, ModelSelection, RuntimeMode } from '@adecore/agent-contracts';
 import type { LimitsUpdate } from '../usage/limits/normalize.ts';
 import type { SpawnChatProcess } from './chat-process.ts';
 export interface BackendLaunch {
@@ -12,6 +12,7 @@ export interface BackendLaunch {
     generation: number;
     instructions: string | null;
     resumeNote: string | null;
+    goal?: ChatGoal;
     folders?: readonly string[];
     spawn?: SpawnChatProcess;
     saveGeneratedImage?(ref: string, upload: ChatAttachmentUpload): Promise<ChatAttachment>;
@@ -169,6 +170,9 @@ export type BackendEvent = {
 } | {
     type: 'compaction';
     preTokens: number | null;
+} | {
+    type: 'goal';
+    goal: ChatGoal | null;
 } | {
     type: 'model';
     model: string;
@@ -214,6 +218,7 @@ export interface ChatBackend {
     interrupt(): void;
     respondApproval(requestId: string, decision: ApprovalDecision, message?: string): boolean;
     respondQuestion(requestId: string, answers: Record<string, string>): boolean;
+    goal?(action: ChatGoalAction): Promise<void>;
     stopTask?(taskId: string): void;
     declineRequest?(requestId: string, message: string): boolean;
     dismissRequest?(requestId: string): boolean;

package/dist/chat/background-work.d.ts

@@ -1,4 +1,4 @@
-import type { AgentKind, ChatBackgroundTask, ChatItem, ChatSubagentItem, ChatToolItem } from '@adecore/agent-contracts';
+import { type AgentKind, type ChatBackgroundTask, type ChatItem, type ChatSubagentItem, type ChatToolItem } from '@adecore/agent-contracts';
 export type BackgroundWork = ChatSubagentItem | ChatToolItem;
 export declare function isBackgroundWork(item: ChatItem): item is BackgroundWork;
 export declare function runsInBackground(item: BackgroundWork): boolean;

package/dist/chat/background-work.js

@@ -1,3 +1,4 @@
+import { HOST_TASK_ORIGIN } from '@adecore/agent-contracts';
 /*
  * Work a chat's CLI goes on with after the turn that started it ended: a subagent it runs in the
  * background (Claude's `run_in_background`, every agent Codex spawns) and a Claude workflow, whose call
@@ -6,7 +7,7 @@
  * work it delegated itself (origin `ruimte` on the wire) is that work's own.
  */
 export function isBackgroundWork(item) {
-    return (item.kind === 'subagent' && item.background && item.origin !== 'ruimte') || (item.kind === 'tool' && item.name === 'Workflow');
+    return (item.kind === 'subagent' && item.background && item.origin !== HOST_TASK_ORIGIN) || (item.kind === 'tool' && item.name === 'Workflow');
 }
 export function runsInBackground(item) {
     return item.kind === 'subagent' ? item.status === 'running' : item.state === 'running';

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

@@ -1,5 +1,4 @@
-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 ChatUiChoicePayload, type ChatUiQueryPayload, type ChatUiLinkPayload, type ChatSkill, type ChatSubagentPayload, type ChatSubagentResult, type ChatTurnItem, type ChatVisual, type ModelSelection, type RuntimeMode } from '@adecore/agent-contracts';
-import { ClientSinks } from '../client-sinks.ts';
+import { type AgentKind, type ChatAttachment, type ChatAttachResult, type ChatAttachmentUpload, type ChatBookmark, type ChatCheckpointDiff, type ChatConfigurePayload, type ChatCreatePayload, type ChatEvent, type ChatHistoryResult, type ChatGoalAction, type ChatInfo, type ChatItem, type ChatQueuedMessage, type ChatUiChoicePayload, type ChatUiQueryPayload, type ChatUiLinkPayload, type ChatSkill, type ChatSubagentPayload, type ChatSubagentResult, type ChatTurnItem, type ChatVisual, type ModelSelection, type RuntimeMode } from '@adecore/agent-contracts';
 import type { AgentEvent, AgentSink } from '../events.ts';
 import type { OutboxOutcome } from '../outbox/outbox-worker.ts';
 import { type AccountLaunches } from '../providers/accounts/launch.ts';
@@ -16,8 +15,7 @@ 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 { SubagentReader, type SubagentReaderOptions } from './subagent-reader.ts';
+import { type SubagentReaderOptions } from './subagent-reader.ts';
 import { type ChatUiHost } from './ui-queries.ts';
 import type { VisualInput, VisualStore } from './visual-store.ts';
 export interface InterruptedRun {
@@ -25,6 +23,31 @@ export interface InterruptedRun {
     turnId: string;
     attempt: number;
 }
+export interface ChatCoreHooks {
+    admit?(chatId: string, cwd: string): Promise<void>;
+    openingSelection?(chatId: string, kind: AgentKind): ModelSelection | undefined;
+    runtimeModeFor?(chatId: string, mode: RuntimeMode): RuntimeMode;
+    instructionsFor?(chatId: string): string | null;
+    resumeNoteFor?(chatId: string): string | null;
+    foldersFor?(chatId: string): readonly string[];
+    hiddenFor?(chatId: string): boolean;
+    promptNotesFor?(chatId: string): PromptNotes | undefined;
+    referencesFor?(chatId: string): ChatReferences | undefined;
+    envFor?(chatId: string, base: Record<string, string>): Record<string, string | undefined>;
+    opened?(session: ChatSession, stored: ChatRecord | null): Promise<void>;
+    recordExtras?(chatId: string): ChatRecordExtras;
+    clearing?(chatId: string): Promise<void>;
+    cleared?(chatId: string): Promise<void>;
+    forgotten?(chatId: string): void;
+    removed?(chatId: string, chat: {
+        info: ChatInfo;
+        items: ChatItem[];
+    }): Promise<void>;
+    broadcasted?(chatId: string, event: ChatEvent): void;
+    endedAt?(chatId: string): number | null;
+    unownedReason?(chatId: string): string;
+    resumeWords?(chatId: string): Promise<ResumeWords>;
+}
 export interface ChatCoreOptions {
     intelligentUi?: ChatUiHost;
     uiFenceLanguage?: string;
@@ -43,7 +66,7 @@ export interface ChatCoreOptions {
     visuals?: VisualStore;
     onLimits?: (update: LimitsUpdate) => void;
     claudeTitles?: {
-        forSession(agentSessionId: string, projectsDir: string): Promise<string | null>;
+        forSession(agentSessionId: string, projectsDir: string, cwd: string): Promise<string | null>;
     };
     nameChat?: (provider: AgentKind, input: ChatTitleInput) => Promise<string | null>;
     subagents?: Partial<Pick<SubagentReaderOptions, 'claudeProjectsDir' | 'seams' | 'now' | 'listOnce'>>;
@@ -56,141 +79,24 @@ export interface ChatCoreOptions {
         owed(chatId: string): boolean;
     };
     accounts?: AccountLaunches;
+    hooks?: ChatCoreHooks;
 }
 export declare class ChatCore {
-    protected readonly providers: ProviderRegistry;
-    protected readonly store: ChatStore | null;
     protected readonly bookmarks: BookmarkStore | null;
     protected readonly visuals: VisualStore | 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;
-                width?: number | undefined;
-                height?: number | undefined;
-            }[] | undefined;
-            createdAt: number;
-            uiChoice?: {
-                itemId: string;
-                blockId: string;
-                revision: string;
-                choiceId: string;
-                label: string;
-                sourceAt: number;
-                older: boolean;
-                values?: Record<string, unknown> | undefined;
-                at: number;
-            } | undefined;
-            quoteSource?: {
-                itemId: string;
-            } | undefined;
-        }[] | 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;
+    private readonly providers;
+    private readonly store;
+    private readonly accounts;
+    private readonly attachments;
+    private readonly env;
+    private readonly hooks;
+    private readonly chats;
+    private readonly creating;
+    private readonly sinks;
+    private readonly attached;
+    private readonly listChanges;
+    private readonly coalescers;
+    private readonly subagents;
     readonly claudeProjectsDir: string;
     readonly composerPreferences: ComposerPreferences;
     private readonly uiQueries;
@@ -231,12 +137,14 @@ export declare class ChatCore {
     };
     observe(sink: AgentSink): () => void;
     subscribe(clientId: string, sink: AgentSink): () => void;
+    sendTo(clientId: string, event: AgentEvent): void;
     create(payload: ChatCreatePayload): Promise<ChatInfo>;
     private createNow;
     storedBackground(chatId: string): Promise<{
         turnId: string | null;
         items: BackgroundWork[];
         commands: string[];
+        goal: boolean;
     }>;
     save(chatId: string): Promise<void>;
     isLoading(chatId: string): boolean;
@@ -244,6 +152,7 @@ export declare class ChatCore {
     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>;
+    private listChanged;
     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[]>;
@@ -252,14 +161,17 @@ export declare class ChatCore {
     listVisuals(chatId: string): Promise<ChatVisual[]>;
     removeVisual(chatId: string, visualId: string): Promise<ChatVisual[]>;
     private requireVisuals;
-    history(chatId: string, cursor: string, limit?: number): ChatHistoryResult;
+    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>;
+    goal(chatId: string, action: ChatGoalAction): Promise<void>;
     subagentItems(chatId: string, toolUseId: string): Promise<ChatItem[]>;
     hasStored(chatId: string): Promise<boolean>;
+    writeRecord(chatId: string, info: ChatInfo, items: ChatItem[], preambles?: string[]): Promise<void>;
+    deleteRecord(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: {
@@ -314,6 +226,7 @@ export declare class ChatCore {
     unqueue(chatId: string, messageId: string): ChatQueuedMessage;
     sendNow(chatId: string, messageId: string): void;
     skills(chatId: string): Promise<ChatSkill[]>;
+    restart(chatId: string): Promise<void>;
     compact(chatId: string): void;
     clear(chatId: string, force?: boolean): Promise<void>;
     cancel(chatId: string, subagents?: boolean): void;
@@ -321,6 +234,8 @@ export declare class ChatCore {
     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;
+    holdForPerson(chatId: string, key: string): boolean;
+    releaseHold(chatId: string, key: string): void;
     kill(chatId: string): Promise<void>;
     stop(chatId: string, reason: string): Promise<void>;
     processTargets(): {
@@ -341,31 +256,8 @@ export declare class ChatCore {
     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 persist;
     private persistSoon;
     private cancelWaiting;
     private persistNow;