@adecore/agents 0.0.1 → 0.17.0-beta.2

package/LICENSE

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 - present Bas Milius
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# @adecore/agents
+
+[![npm](https://img.shields.io/npm/v/@adecore/agents)](https://www.npmjs.com/package/@adecore/agents)
+[![Docs](https://img.shields.io/badge/docs-adecore.dev-blue)](https://adecore.dev/agents/)
+
+A host for agent chats in Node, Bun or an Electron utility process. It runs Claude Code and Codex as chat backends, keeps every thread on disk, streams it to its clients, and manages the CLIs' accounts and usage. It answers the requests of [`@adecore/agent-contracts`](https://adecore.dev/agent-contracts/) over a port you hand it, and registers no channel of its own.
+
+## Install
+
+```sh
+bun add @adecore/agents @adecore/agent-contracts
+```
+
+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';
+
+const host = await AgentHost.open({ dataDir });
+const disconnect = host.connect(port);
+
+// later
+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.
+
+## Documentation
+
+| Page | What it covers |
+|---|---|
+| [Getting started](https://adecore.dev/agents/getting-started) | A whole turn against a fake CLI, in one file |
+| [Host](https://adecore.dev/agents/host) | `AgentHost`, its options, `wireAgents`, the hooks of `ChatCore` and Electron |
+| [Chats and turns](https://adecore.dev/agents/chats) | Sending, queuing, approvals, stopping and restarts |
+| [Providers](https://adecore.dev/agents/providers) | The CLIs, their model catalogs and the runtime modes |
+| [Accounts and usage](https://adecore.dev/agents/accounts) | Config folders, secrets, the environment and usage |
+| [Coordination](https://adecore.dev/agents/coordination) | The outbox, tasks between chats, lineage and messages |
+| [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 |
+
+## License
+
+FSL-1.1-MIT. See [LICENSE](./LICENSE).

package/dist/async.d.ts

@@ -0,0 +1,2 @@
+export declare function wait(ms: number, signal?: AbortSignal): Promise<void>;
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, message: string): Promise<T>;

package/dist/async.js

@@ -0,0 +1,31 @@
+/* The two waits the host does: a pause it can be woken from, and a deadline on somebody else's promise. */
+/*
+ * Resolves after `ms`, or at once when the signal is raised. An abort ends the wait rather than
+ * failing it: every caller here is a loop that checks the signal itself on the next turn, and a
+ * rejection would only be caught and thrown away.
+ */
+export function wait(ms, signal) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener('abort', () => {
+            clearTimeout(timer);
+            resolve();
+        }, { once: true });
+    });
+}
+/*
+ * The promise, or `message` when it takes longer than `ms`. The timer is cleared either way, so a
+ * call that answers at once does not hold the process for the rest of its deadline.
+ */
+export function withTimeout(promise, ms, message) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(message)), ms);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (e) => {
+            clearTimeout(timer);
+            reject(e instanceof Error ? e : new Error(String(e)));
+        });
+    });
+}

package/dist/chat/attachment-store.d.ts

@@ -0,0 +1,10 @@
+import { type ChatAttachment, type ChatAttachmentUpload } from '@adecore/agent-contracts';
+export declare function extensionFor(name: string, mime: string): string;
+export declare class AttachmentStore {
+    readonly dir: string;
+    constructor(home: string);
+    save(chatId: string, upload: ChatAttachmentUpload): Promise<ChatAttachment>;
+    removeAll(chatId: string): Promise<void>;
+    private folder;
+}
+export declare function migrateInlineAttachments(chatId: string, record: unknown, store: AttachmentStore): Promise<unknown | null>;

package/dist/chat/attachment-store.js

@@ -0,0 +1,93 @@
+import { randomBytes } from 'node:crypto';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { extname, join } from 'node:path';
+import { 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',
+    'image/jpeg': 'jpg',
+    'image/gif': 'gif',
+    'image/webp': 'webp',
+    'image/svg+xml': 'svg',
+    'application/pdf': 'pdf',
+    'application/json': 'json',
+    'text/csv': 'csv',
+    'text/markdown': 'md',
+    'text/plain': 'txt'
+};
+const SAFE_EXTENSION = /^[A-Za-z0-9]{1,8}$/;
+/* What the file is called on disk: the id, plus an extension the agent's tools can recognize. */
+export function extensionFor(name, mime) {
+    const own = extname(name).slice(1).toLowerCase();
+    if (SAFE_EXTENSION.test(own)) {
+        return own;
+    }
+    const known = EXTENSIONS[mime.toLowerCase()];
+    if (known) {
+        return known;
+    }
+    const subtype = mime.split('/')[1]?.replace(/\+.*$/, '') ?? '';
+    return SAFE_EXTENSION.test(subtype) ? subtype.toLowerCase() : 'bin';
+}
+/*
+ * The files people attach to a message, under `<home>/attachments/<chatId>`. The thread keeps
+ * only what a row needs (name, mime, size, path); the bytes stay on disk, so a thread with a video
+ * in it is still a small JSON file.
+ */
+export class AttachmentStore {
+    dir;
+    constructor(home) {
+        this.dir = join(home, 'attachments');
+    }
+    /* Writes one upload and answers the metadata the thread stores. */
+    async save(chatId, upload) {
+        const bytes = Buffer.from(upload.data, 'base64');
+        const mime = attachmentImageMime(upload) ?? upload.mime;
+        const id = randomBytes(8).toString('hex');
+        const folder = this.folder(chatId);
+        await mkdir(folder, { recursive: true, mode: 0o700 });
+        const path = join(folder, `${id}.${extensionFor(upload.name, mime)}`);
+        await writeFile(path, bytes, { mode: 0o600 });
+        return { id, name: upload.name, mime, size: bytes.byteLength, path };
+    }
+    /* Everything a chat attached; used when the chat itself is deleted. */
+    async removeAll(chatId) {
+        await rm(this.folder(chatId), { recursive: true, force: true });
+    }
+    folder(chatId) {
+        return join(this.dir, encodeURIComponent(chatId));
+    }
+}
+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';
+}
+/*
+ * Writes out the images a thread still carries inline and answers the record with metadata in their
+ * place, or null when there was nothing to do. Old records are migrated on the read that opens the
+ * chat, before the schema sees them, because the schema no longer knows the inline shape.
+ */
+export async function migrateInlineAttachments(chatId, record, store) {
+    const items = isRecord(record) && Array.isArray(record.items) ? record.items : null;
+    if (!items) {
+        return null;
+    }
+    let migrated = false;
+    const next = await Promise.all(items.map(async (item) => {
+        if (!isRecord(item) || !Array.isArray(item.attachments) || !item.attachments.some(isInline)) {
+            return item;
+        }
+        const attachments = await Promise.all(item.attachments.map(async (attachment) => {
+            if (!isInline(attachment)) {
+                return attachment;
+            }
+            migrated = true;
+            return await store.save(chatId, { name: attachment.name, mime: attachment.mediaType, data: attachment.data });
+        }));
+        return { ...item, attachments };
+    }));
+    return migrated ? { ...record, items: next } : null;
+}

package/dist/chat/backend.d.ts

@@ -0,0 +1,214 @@
+import type { ChatAttachment, ChatFileChange, 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 {
+    command: string[];
+    cwd: string;
+    env: Record<string, string>;
+    selection: ModelSelection;
+    modelName: string;
+    runtimeMode: RuntimeMode;
+    resume: string | null;
+    generation: number;
+    instructions: string | null;
+    resumeNote: string | null;
+    folders?: readonly string[];
+    spawn?: SpawnChatProcess;
+}
+export interface TurnInput {
+    promptId?: string;
+    text: string;
+    preamble: string | null;
+    attachments: ChatAttachment[];
+    mentions: string[];
+    skills: string[];
+}
+export type ApprovalDecision = 'allow' | 'allow-always' | 'deny';
+export type BackendEvent = {
+    type: 'turn.accepted';
+    promptId: string;
+} | {
+    type: 'session';
+    agentSessionId: string | null;
+    model: string | null;
+    slashCommands?: string[];
+    skills?: string[];
+    title?: string | null;
+    effectiveRuntimeMode?: RuntimeMode;
+    permissionMode?: string;
+} | {
+    type: 'title';
+    title: string;
+} | {
+    type: 'permissions';
+    permissionMode: string;
+    effectiveRuntimeMode?: RuntimeMode;
+} | {
+    type: 'text.delta';
+    ref: string;
+    text: string;
+} | {
+    type: 'text.done';
+    ref: string;
+    text: string;
+    parentRef?: string | null;
+} | {
+    type: 'thinking.delta';
+    ref: string;
+    text: string;
+} | {
+    type: 'thinking.done';
+    ref: string;
+    text: string;
+} | {
+    type: 'tool.started';
+    ref: string;
+    name: string;
+    input: unknown;
+    parentRef: string | null;
+    changes?: ChatFileChange[];
+} | {
+    type: 'tool.progress';
+    ref: string;
+    startedAt: number | null;
+    description: string | null;
+} | {
+    type: 'tool.output';
+    ref: string;
+    text: string;
+} | {
+    type: 'tool.done';
+    ref: string;
+    output: string | null;
+    state: 'done' | 'error';
+    changes?: ChatFileChange[];
+} | {
+    type: 'approval.requested';
+    requestId: string;
+    ref: string | null;
+    toolName: string;
+    input: unknown;
+    description: string | null;
+    canAllowAlways: boolean;
+    background?: boolean;
+    allowAlways?: {
+        label: string;
+        description: string;
+    };
+} | {
+    type: 'question.requested';
+    requestId: string;
+    questions: ChatQuestion[];
+    async?: boolean;
+    background?: boolean;
+} | {
+    type: 'request.withdrawn';
+    requestId: string;
+} | {
+    type: 'task.started';
+    ref: string;
+    description: string | null;
+    subagentType: string | null;
+    prompt: string | null;
+    background: boolean;
+    taskId?: string | null;
+    threadId?: string | null;
+    depth?: number;
+    resumed?: boolean;
+} | {
+    type: 'task.progress';
+    ref: string;
+    taskId?: string | null;
+    summary: string | null;
+    lastTool: string | null;
+    usage: ChatSubagentUsage | null;
+} | {
+    type: 'task.model';
+    ref: string;
+    model: string;
+} | {
+    type: 'task.done';
+    ref: string | null;
+    taskId?: string | null;
+    summary: string | null;
+    ok: boolean;
+    usage?: ChatSubagentUsage | null;
+    outputFile?: string | null;
+} | {
+    type: 'workflow.progress';
+    ref: string;
+    workflow: ChatWorkflow;
+} | {
+    type: 'background.started';
+    taskId: string;
+    ref: string | null;
+    monitor: boolean;
+    description: string | null;
+} | {
+    type: 'background.ended';
+    taskId: string;
+} | {
+    type: 'usage';
+    contextTokens?: number;
+    contextWindow?: number;
+    costUsd?: number;
+} | {
+    type: 'limits';
+    update: LimitsUpdate;
+} | {
+    type: 'compaction';
+    preTokens: number | null;
+} | {
+    type: 'model';
+    model: string;
+} | {
+    type: 'note';
+    level: 'info' | 'warning' | 'error';
+    text: string;
+} | {
+    type: 'turn.done';
+    promptId?: string;
+    state: 'done' | 'aborted' | 'error';
+    costUsd: number;
+    error?: string;
+    native?: {
+        turnId?: string;
+        lastUuid?: string;
+    };
+    limit?: ChatTurnLimit;
+} | {
+    type: 'failed';
+    message: string;
+    processAlive?: boolean;
+} | {
+    type: 'exit';
+    exitCode: number | null;
+    stderr?: string;
+};
+export interface BackendHost {
+    onEvent(event: BackendEvent): void;
+}
+export interface ChatBackend {
+    readonly acknowledgesTurns?: boolean;
+    readonly running: boolean;
+    readonly pid: number | null;
+    start(): Promise<void>;
+    sendTurn(input: TurnInput): void;
+    compact(): void;
+    interrupt(): void;
+    respondApproval(requestId: string, decision: ApprovalDecision, message?: string): boolean;
+    respondQuestion(requestId: string, answers: Record<string, string>): boolean;
+    stopTask?(taskId: string): void;
+    declineRequest?(requestId: string, message: string): boolean;
+    dismissRequest?(requestId: string): boolean;
+    setTitle?(title: string): void;
+    listSkills?(): Promise<ChatSkill[]>;
+    listThreadItems?(params: {
+        threadId: string;
+        cursor?: string;
+        limit: number;
+        sortDirection: 'asc' | 'desc';
+    }): Promise<unknown>;
+    stop(): void;
+    dispose(): Promise<void>;
+}

package/dist/chat/backend.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,8 @@
+import type { AgentKind, ChatBackgroundTask, ChatItem, ChatSubagentItem, 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;
+export declare function runningInBackground(items: readonly ChatItem[]): BackgroundWork[];
+export declare const BACKGROUND_COMMAND_LIMIT_MS: number;
+export declare function commandLabel(task: ChatBackgroundTask): string;
+export declare function reportsOnBackgroundWork(provider: AgentKind): boolean;

package/dist/chat/background-work.js

@@ -0,0 +1,33 @@
+/*
+ * 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
+ * answers at launch. A command or a monitor sent to the background is not work of this kind but a
+ * `ChatBackgroundTask` in the chat's info, held to `BACKGROUND_COMMAND_LIMIT_MS`; a row the host drew for
+ * 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');
+}
+export function runsInBackground(item) {
+    return item.kind === 'subagent' ? item.status === 'running' : item.state === 'running';
+}
+export function runningInBackground(items) {
+    return items.filter((item) => isBackgroundWork(item) && runsInBackground(item));
+}
+/*
+ * How long a command or a monitor still running in the background holds a child's task once nothing
+ * else does, since a dev server never ends. Subagents and workflows have no such limit.
+ */
+export const BACKGROUND_COMMAND_LIMIT_MS = 30 * 60_000;
+export function commandLabel(task) {
+    return task.command ?? (task.description === '' ? task.id : task.description);
+}
+/*
+ * Whether the CLI opens a turn of its own once its background work ended, to tell what came of it.
+ * Claude Code 2.1.282 does after every task notification, a command's included; a command a subagent
+ * started first takes that subagent up again, which then notifies the main agent. Codex 0.156.1
+ * reports a spawned agent completed and opens nothing.
+ */
+export function reportsOnBackgroundWork(provider) {
+    return provider === 'claude';
+}

package/dist/chat/bookmark-store.d.ts

@@ -0,0 +1,25 @@
+import { type ChatBookmark } from '@adecore/agent-contracts';
+export declare function bookmarkFileName(chatId: string): string;
+export declare function isBookmarkFileName(name: string): boolean;
+export type BookmarkListener = (chatId: string, bookmarks: ChatBookmark[]) => void;
+export declare class BookmarkStore {
+    readonly dir: string;
+    private readonly writes;
+    private readonly listeners;
+    constructor(home: string);
+    listen(listener: BookmarkListener): () => void;
+    read(chatId: string): Promise<ChatBookmark[]>;
+    add(chatId: string, input: {
+        itemId: string;
+        excerpt: string;
+        name?: string;
+    }, now: number): Promise<ChatBookmark[]>;
+    rename(chatId: string, itemId: string, name: string): Promise<ChatBookmark[]>;
+    remove(chatId: string, itemId: string): Promise<ChatBookmark[]>;
+    removeChat(chatId: string): Promise<void>;
+    copyChat(fromChatId: string, toChatId: string, keep: (itemId: string) => boolean): Promise<void>;
+    private change;
+    private tell;
+    private readFile;
+    private writeFile;
+}