@adecore/agents 0.0.1 → 0.17.0-beta.1

package/LICENSE

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 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,33 @@
+# @adecore/agents
+
+Agent chat hosting for Node and Bun, including an Electron utility process. Claude Code and Codex backends share a session/thread model, streamed events, persisted chats, provider accounts, usage, and durable coordination modules. A consumer supplies permissions, transport ownership, placement, context commands, and application lifecycle policy.
+
+```ts
+import { AgentHost } from '@adecore/agents/host/agent-host';
+import { cliEnvironment } from '@adecore/agents/host/environment';
+import type { FramePort } from '@adecore/agent-contracts';
+
+export async function openHost(dataDir: string, port: FramePort) {
+    const host = await AgentHost.open({ dataDir, env: cliEnvironment(process.env, { sessionPrefixes: ['APP'] }) });
+    const disconnect = host.connect(port);
+    return {
+        host,
+        async close(): Promise<void> {
+            disconnect();
+            await host.close();
+        }
+    };
+}
+```
+
+A chat starts a CLI on its first prompt. Choose its runtime mode explicitly: the plain core defaults to `full-access`. Install/authenticate provider CLIs separately. For checks without real providers, inject `spawn` and `detect` and use the complete [fake-provider walkthrough](https://adecore.dev/agents/getting-started).
+
+The [documentation](https://adecore.dev/agents/) covers [transport](https://adecore.dev/agents/transport), [host hooks](https://adecore.dev/agents/host-integration), [providers/models](https://adecore.dev/agents/providers-and-models), [turns/requests](https://adecore.dev/agents/turns-and-requests), [accounts/environment](https://adecore.dev/agents/accounts-and-environment), [outbox/tasks/messages](https://adecore.dev/agents/coordination), [context commands](https://adecore.dev/agents/context-commands), [persistence/helpers](https://adecore.dev/agents/persistence-and-helpers), [testing](https://adecore.dev/agents/testing-and-troubleshooting), [subpaths](https://adecore.dev/agents/entrypoints), and [migration](https://adecore.dev/agents/migration).
+
+`wireAgents` supplies the same services and handlers for a host protocol of your own. `ChatCore` is extensible through admission, instructions, environment, prompt notes, folders, policy, persistence, and recovery hooks. A plain host refuses placement-dependent fork/continuation requests and installs no task/message context endpoint.
+
+Import per module, `@adecore/agents/<path under src>` without an extension; there is no root export. Existing helper and coordination subpaths remain supported. [examples/agent-port](../../examples/agent-port) checks host, React transport/client, scope, and locale loading with fakes. Run its `test` script for source exports or `test:dist` after building for Node default exports.
+
+Build `@adecore/agent-contracts` first, then run this package's `typecheck`, `test`, and `build` scripts. Default exports use compiled JavaScript/declarations; `source` selects TypeScript. No production source requires a Bun API.
+
+This package is private at `0.0.0`, pending publication setup, and retains 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;
+}