@adecore/agents 0.0.1 → 0.17.0-beta.1

package/dist/host/handlers.js

@@ -0,0 +1,111 @@
+import { ChatError } from '../chat/errors.js';
+// A fork lands on a canvas and a summary goes back along its line, which a host of chats alone does not have.
+function unsupported(what) {
+    return () => {
+        throw new ChatError('chat-unsupported', `This host does not ${what}`);
+    };
+}
+/* The chat requests over a core, including the ones only a host with more than chats can answer, which say so. */
+export function chatHandlers(chats, providers) {
+    return {
+        'provider.list': async () => ({ providers: await providers.list() }),
+        'chat.create': (payload) => chats.create(payload),
+        'chat.configure': (payload) => chats.configure(payload),
+        // What a chat the host starts on its own is made with, while this client is connected.
+        'chat.setPreferences': (payload, clientId) => {
+            chats.composerPreferences.set(clientId, payload);
+            return {};
+        },
+        'chat.attach': (payload, clientId) => chats.attachWithBookmarks(payload.chatId, clientId, payload.historyLimit, payload.since),
+        'chat.history': (payload) => chats.history(payload.chatId, payload.cursor, payload.limit),
+        'chat.subagent': (payload, clientId) => chats.subagent(clientId, payload),
+        'chat.stopSubagent': async (payload) => {
+            await chats.stopSubagent(payload.chatId, payload.toolUseId);
+            return {};
+        },
+        'chat.stopTask': async (payload) => {
+            await chats.stopTask(payload.chatId, payload.taskId);
+            return {};
+        },
+        'chat.detach': (payload, clientId) => {
+            chats.detach(payload.chatId, clientId);
+            return {};
+        },
+        'chat.send': (payload) => chats.send(payload.chatId, payload.text, { mentions: payload.mentions, skills: payload.skills, chats: payload.chats }, payload.attachments),
+        'chat.unqueue': (payload) => ({ message: chats.unqueue(payload.chatId, payload.messageId) }),
+        'chat.sendNow': (payload) => {
+            chats.sendNow(payload.chatId, payload.messageId);
+            return {};
+        },
+        'skills.list': async (payload) => ({ skills: await chats.skills(payload.chatId) }),
+        'chat.compact': (payload) => {
+            chats.compact(payload.chatId);
+            return {};
+        },
+        'chat.clear': async (payload) => {
+            await chats.clear(payload.chatId, payload.force === true);
+            return {};
+        },
+        'chat.turnDiff': async (payload) => ({ diff: await chats.turnDiff(payload.chatId, payload.turnId) }),
+        'chat.fork': unsupported('fork chats'),
+        'chat.forkInfo': unsupported('fork chats'),
+        'chat.summarize': unsupported('fork chats'),
+        'chat.continueOn': unsupported('continue a chat under another account'),
+        'chat.cancel': (payload) => {
+            chats.cancel(payload.chatId, payload.subagents === true);
+            return {};
+        },
+        'chat.approve': (payload) => {
+            chats.approve(payload.chatId, payload.requestId, payload.decision, payload.message);
+            return {};
+        },
+        'chat.answer': (payload) => {
+            chats.answer(payload.chatId, payload.requestId, payload.answers);
+            return {};
+        },
+        'chat.dismiss': (payload) => {
+            chats.dismiss(payload.chatId, payload.itemId);
+            return {};
+        },
+        'chat.addBookmark': async (payload) => ({ bookmarks: await chats.addBookmark(payload.chatId, payload.itemId, payload.name) }),
+        'chat.renameBookmark': async (payload) => ({ bookmarks: await chats.renameBookmark(payload.chatId, payload.itemId, payload.name) }),
+        'chat.removeBookmark': async (payload) => ({ bookmarks: await chats.removeBookmark(payload.chatId, payload.itemId) }),
+        'chat.kill': async (payload) => {
+            await chats.kill(payload.chatId);
+            return {};
+        },
+        'chat.list': () => ({ chats: chats.list() })
+    };
+}
+/* The accounts are the person's settings of this host. */
+export function accountHandlers(accounts) {
+    return {
+        'accounts.list': () => accounts.snapshot(),
+        'accounts.save': (payload) => accounts.save(payload.accounts),
+        'accounts.refresh': () => accounts.refresh(),
+        'accounts.create': (payload) => accounts.create(payload),
+        'accounts.watchLogin': (payload) => {
+            void accounts.watchLogin(payload.id);
+            return {};
+        }
+    };
+}
+export function usageHandlers(usage, limits) {
+    return {
+        'usage.summary': (payload) => usage.summary(payload),
+        // While a client has the page open the host keeps scanning; every other client gets the event too.
+        'usage.subscribe': (_payload, clientId) => {
+            usage.follow(clientId);
+            return {};
+        },
+        'usage.unsubscribe': (_payload, clientId) => {
+            usage.unfollow(clientId);
+            return {};
+        },
+        'usage.limits': () => limits.snapshot(),
+        'usage.refreshLimits': async () => {
+            await limits.refresh(true);
+            return limits.snapshot();
+        }
+    };
+}

package/dist/host/memory-port.d.ts

@@ -0,0 +1,2 @@
+import type { FramePort } from '@adecore/agent-contracts';
+export declare function memoryPortPair(): [FramePort, FramePort];

package/dist/host/memory-port.js

@@ -0,0 +1,25 @@
+/*
+ * Two ends of a port in one process, for a test or a host and a client that live side by side. A
+ * frame crosses as a copy and only once the sender's own code ran, the way a MessagePort delivers it,
+ * so neither end ever holds the other's object.
+ */
+export function memoryPortPair() {
+    const listeners = [new Set(), new Set()];
+    const end = (own) => ({
+        send: (frame) => {
+            const copy = structuredClone(frame);
+            queueMicrotask(() => {
+                for (const listener of listeners[1 - own]) {
+                    listener(copy);
+                }
+            });
+        },
+        onFrame: (listener) => {
+            listeners[own].add(listener);
+            return () => {
+                listeners[own].delete(listener);
+            };
+        }
+    });
+    return [end(0), end(1)];
+}

package/dist/host/wiring.d.ts

@@ -0,0 +1,40 @@
+import { ChatCore, type ChatCoreOptions } from '../chat/chat-core.ts';
+import type { SpawnChatProcess } from '../chat/chat-process.ts';
+import type { ClaudeBackendOptions } from '../chat/claude-backend.ts';
+import { type CodexClientInfo } from '../chat/codex-transport.ts';
+import type { AgentEvent } from '../events.ts';
+import { ProviderAccountsService } from '../providers/accounts/service.ts';
+import type { AccountsHost } from '../providers/accounts/variables.ts';
+import { type CodexRules } from '../providers/codex-rules.ts';
+import { ProviderRegistry, type ProviderRegistryOptions } from '../providers/registry.ts';
+import { UsageMonitor } from '../usage/limits/monitor.ts';
+import { UsageService } from '../usage/usage-service.ts';
+import { type CliEnvironmentPolicy } from './environment.ts';
+import { type AgentHandlers } from './handlers.ts';
+export interface AgentWiringOptions<Core extends ChatCore = ChatCore> {
+    dataDir: string;
+    env?: Record<string, string | undefined>;
+    environmentPolicy?: CliEnvironmentPolicy;
+    systemNote?: string;
+    client?: CodexClientInfo;
+    accountsHost?: AccountsHost;
+    claude?: ClaudeBackendOptions;
+    codexRules?: CodexRules;
+    core?: (options: ChatCoreOptions) => Core;
+    command?: string[];
+    codexCommand?: string[];
+    spawn?: SpawnChatProcess;
+    detect?: ProviderRegistryOptions['detect'];
+}
+export interface AgentWiring<Core extends ChatCore = ChatCore> {
+    providers: ProviderRegistry;
+    accounts: ProviderAccountsService;
+    limits: UsageMonitor;
+    usage: UsageService;
+    chats: Core;
+    handlers: AgentHandlers;
+    connect(clientId: string, send: (event: AgentEvent) => void): () => void;
+    start(): void;
+    stop(): Promise<void>;
+}
+export declare function wireAgents<Core extends ChatCore = ChatCore>(options: AgentWiringOptions<Core>): AgentWiring<Core>;

package/dist/host/wiring.js

@@ -0,0 +1,120 @@
+import { AttachmentStore } from '../chat/attachment-store.js';
+import { BookmarkStore } from '../chat/bookmark-store.js';
+import { ChatCore } from '../chat/chat-core.js';
+import { ChatStore } from '../chat/chat-store.js';
+import { suggestChatTitle } from '../chat/chat-title.js';
+import { ClaudeTitleReader } from '../chat/claude-title.js';
+import { DEFAULT_CODEX_CLIENT } from '../chat/codex-transport.js';
+import { definedEnv } from '../providers/accounts/launch.js';
+import { ProviderAccountsService } from '../providers/accounts/service.js';
+import { createClaudeProvider } from '../providers/claude-provider.js';
+import { errorText } from '../error-text.js';
+import { createCodexProvider } from '../providers/codex-provider.js';
+import { codexRulesPathIn, defaultCodexHome, installCodexRules } from '../providers/codex-rules.js';
+import { ProviderRegistry } from '../providers/registry.js';
+import { chatSessionAccounts, limitAccountsOf, usageAccountsOf, usageRootsOf } from '../usage/accounts.js';
+import { UsageMonitor } from '../usage/limits/monitor.js';
+import { UsageService } from '../usage/usage-service.js';
+import { cliEnvironment } from './environment.js';
+import { accountHandlers, chatHandlers, usageHandlers } from './handlers.js';
+// A folder the rule cannot be written to only costs an approval per call, so it never stops the host.
+async function installRulesIn(kind, folder, rules) {
+    if (kind !== 'codex') {
+        return;
+    }
+    const path = codexRulesPathIn(folder, rules);
+    await installCodexRules(path, rules).catch((e) => console.error(`Could not write the codex rules in ${path}:`, errorText(e)));
+}
+/*
+ * The chats of a host with the providers, accounts and usage around them, and the handlers of
+ * every agent request. `AgentHost` serves them over a port; an app that answers requests on a wire
+ * of its own takes the handlers and `connect` from here. The accounts are read with
+ * `accounts.load()` before the first request.
+ */
+export function wireAgents(options) {
+    const env = options.env === undefined || options.environmentPolicy !== undefined ? cliEnvironment(options.env, options.environmentPolicy) : options.env;
+    const client = options.client ?? DEFAULT_CODEX_CLIENT;
+    const codexRules = options.codexRules;
+    const providers = new ProviderRegistry({ providers: [createClaudeProvider(options.claude), createCodexProvider({ client })], env, detect: options.detect });
+    const accounts = new ProviderAccountsService({
+        home: options.dataDir,
+        providers,
+        env,
+        client,
+        ...(options.accountsHost ? { host: options.accountsHost } : {}),
+        ...(codexRules ? { install: (kind, folder) => installRulesIn(kind, folder, codexRules) } : {})
+    });
+    if (codexRules) {
+        void installRulesIn('codex', defaultCodexHome(env), codexRules);
+    }
+    const nameOf = (kind) => providers.get(kind).name;
+    const limits = new UsageMonitor({ providers, accounts: limitAccountsOf(accounts, nameOf, env), client });
+    accounts.listen(() => limits.accountsChanged());
+    const attachments = new AttachmentStore(options.dataDir);
+    // Only without `core`, where `Core` is `ChatCore` itself.
+    const core = options.core ?? ((coreOptions) => new ChatCore(coreOptions));
+    const chats = core({
+        providers,
+        store: new ChatStore(options.dataDir, { attachments }),
+        attachments,
+        bookmarks: new BookmarkStore(options.dataDir),
+        env,
+        ...(options.systemNote === undefined ? {} : { instructions: options.systemNote }),
+        ...(options.command ? { command: options.command } : {}),
+        ...(options.codexCommand ? { codexCommand: options.codexCommand } : {}),
+        ...(options.spawn ? { spawn: options.spawn } : {}),
+        codexClient: client,
+        accounts,
+        onLimits: (update) => limits.applyLive(update),
+        claudeTitles: new ClaudeTitleReader(),
+        nameChat: (kind, input) => suggestChatTitle(providers, kind, input, definedEnv(env))
+    });
+    const usage = new UsageService({
+        home: options.dataDir,
+        knownProjects: () => Promise.resolve([]),
+        roots: () => usageRootsOf(accounts),
+        sessionAccounts: () => chatSessionAccounts(chats.list()),
+        accounts: () => usageAccountsOf(accounts, nameOf)
+    });
+    return {
+        providers,
+        accounts,
+        limits,
+        usage,
+        chats,
+        handlers: {
+            ...chatHandlers(chats, providers),
+            ...accountHandlers(accounts),
+            ...usageHandlers(usage, limits)
+        },
+        connect: (clientId, send) => {
+            const releases = [
+                chats.subscribe(clientId, send),
+                accounts.subscribe(clientId, send),
+                usage.subscribe(clientId, send),
+                limits.subscribe(clientId, send)
+            ];
+            return () => {
+                for (const release of releases) {
+                    release();
+                }
+                chats.detachAll(clientId);
+                usage.unfollow(clientId);
+            };
+        },
+        start: () => {
+            limits.start();
+            accounts.start();
+        },
+        stop: async () => {
+            try {
+                usage.stop();
+                limits.stop();
+                accounts.stop();
+            }
+            finally {
+                await chats.shutdown();
+            }
+        }
+    };
+}

package/dist/lineage.d.ts

@@ -0,0 +1,44 @@
+import { type RuntimeMode } from '@adecore/agent-contracts';
+import { z } from 'zod';
+declare const LineageSchema: z.ZodObject<{
+    projectId: z.ZodString;
+    nodeId: z.ZodString;
+    openedBy: z.ZodString;
+    depth: z.ZodNumber;
+    agent: z.ZodDefault<z.ZodBoolean>;
+    relation: z.ZodOptional<z.ZodLiteral<"fork">>;
+    ceiling: z.ZodOptional<z.ZodEnum<{
+        auto: "auto";
+        "auto-accept-edits": "auto-accept-edits";
+        "full-access": "full-access";
+        supervised: "supervised";
+    }>>;
+    createdAt: z.ZodNumber;
+    endedAt: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type Lineage = z.infer<typeof LineageSchema>;
+export declare class AgentLineageStore {
+    readonly dir: string;
+    private readonly opened;
+    constructor(dataDir: string);
+    load(): Promise<void>;
+    put(record: Omit<Lineage, 'createdAt' | 'endedAt'>): Promise<void>;
+    descendants(nodeId: string): string[];
+    projectOf(nodeId: string): string | null;
+    endedAt(nodeId: string): number | null;
+    markEnded(nodeIds: readonly string[]): Promise<void>;
+    orphans(projectId: string, ids: ReadonlySet<string>): Array<{
+        nodeId: string;
+        openedBy: string;
+    }>;
+    ceilingOf(nodeId: string): RuntimeMode | null;
+    depthOf(nodeId: string): number;
+    openedCount(callerId: string, include?: (nodeId: string) => boolean): number;
+    madeBy(nodeId: string): string | null;
+    startedBy(nodeId: string): string | null;
+    forkedFrom(nodeId: string): string | null;
+    forksOf(nodeId: string): string[];
+    forksLeaving(projectId: string, ids: ReadonlySet<string>): string[];
+    prune(projectId: string, ids: ReadonlySet<string>): Promise<void>;
+}
+export {};

package/dist/lineage.js

@@ -0,0 +1,134 @@
+import { join } from 'node:path';
+import { RuntimeModeSchema } from '@adecore/agent-contracts';
+import { z } from 'zod';
+import { RecordDirectory } from './record-directory.js';
+const LineageSchema = z.object({
+    projectId: z.string().min(1),
+    nodeId: z.string().min(1),
+    /* The node that ran the verb; a caller is counted against this to cap one runaway agent. */
+    openedBy: z.string().min(1),
+    depth: z.number().int().nonnegative(),
+    /* Whether this is an agent node, which is what the depth and the per-caller cap are about. A
+       record written before a plain node was written down at all is one of those, hence the default. */
+    agent: z.boolean().default(true),
+    /* A fork is a sibling a person made beside `openedBy` rather than a node it opened; absent is opened by a verb. */
+    relation: z.literal('fork').optional(),
+    /* The widest mode the agent may start in, the mode of its opener when it was made. Absent on a
+       record from before, and on a node nobody may widen anyway since no agent started it. */
+    ceiling: RuntimeModeSchema.optional(),
+    createdAt: z.number(),
+    /* When stopping or deleting the node that opened it ended this one too; a cascade never ends a node twice. */
+    endedAt: z.number().optional()
+});
+/* Opened by the agent it names, which is what every rule about children is about; a fork lives on its own. */
+function openedByAgent(entry) {
+    return entry.agent && entry.relation !== 'fork';
+}
+/*
+ * Lineage lives in `lineage` under the host's data folder, outside the agent-writable project, so agents
+ * cannot reset their own depth. Persisting it also prevents a restart of the host from resetting recursion limits.
+ */
+export class AgentLineageStore {
+    dir;
+    opened;
+    constructor(dataDir) {
+        this.dir = join(dataDir, 'lineage');
+        this.opened = new RecordDirectory({ dir: this.dir, schema: LineageSchema, idOf: (entry) => entry.nodeId });
+    }
+    /* Reads what an earlier run of the host wrote down. Call before any verb can ask. */
+    load() {
+        return this.opened.load();
+    }
+    async put(record) {
+        await this.opened.write({ ...record, createdAt: Date.now() });
+    }
+    /*
+     * The agent nodes this one opened and the ones those opened in turn that no cascade ended yet,
+     * nearest first, so whoever ends them can go from the leaves back up.
+     */
+    descendants(nodeId) {
+        const found = [];
+        const seen = new Set([nodeId]);
+        for (let i = -1; i < found.length; i++) {
+            const parent = i === -1 ? nodeId : found[i];
+            for (const entry of this.opened.all()) {
+                if (entry.openedBy === parent && openedByAgent(entry) && entry.endedAt === undefined && !seen.has(entry.nodeId)) {
+                    seen.add(entry.nodeId);
+                    found.push(entry.nodeId);
+                }
+            }
+        }
+        return found;
+    }
+    /* The project a node was made in, for work owed about it after the node that opened it is gone. */
+    projectOf(nodeId) {
+        return this.opened.get(nodeId)?.projectId ?? null;
+    }
+    endedAt(nodeId) {
+        return this.opened.get(nodeId)?.endedAt ?? null;
+    }
+    /* On the wall clock, like `createdAt`: a chat holds the mark against the time its turn started. */
+    async markEnded(nodeIds) {
+        const at = Date.now();
+        for (const nodeId of nodeIds) {
+            const entry = this.opened.get(nodeId);
+            if (entry && entry.endedAt === undefined) {
+                await this.opened.write({ ...entry, endedAt: at });
+            }
+        }
+    }
+    /* The nodes of this project whose opener it no longer places, and that no cascade ended yet. */
+    orphans(projectId, ids) {
+        return [...this.opened.all()]
+            .filter((entry) => entry.projectId === projectId && openedByAgent(entry) && entry.endedAt === undefined && ids.has(entry.nodeId) && !ids.has(entry.openedBy))
+            .map((entry) => ({ nodeId: entry.nodeId, openedBy: entry.openedBy }));
+    }
+    /* The widest mode this agent node may start in, every time it starts; null for one no agent opened. */
+    ceilingOf(nodeId) {
+        const entry = this.opened.get(nodeId);
+        return entry !== undefined && openedByAgent(entry) ? (entry.ceiling ?? null) : null;
+    }
+    /* How deep a node sits. A node nobody wrote down is one a person made, which is where a chain starts. */
+    depthOf(nodeId) {
+        return this.opened.get(nodeId)?.depth ?? 0;
+    }
+    // A host may exclude completed hidden agents while keeping their lineage for later reads and tasks.
+    openedCount(callerId, include = () => true) {
+        let count = 0;
+        for (const entry of this.opened.all()) {
+            if (entry.openedBy === callerId && openedByAgent(entry) && include(entry.nodeId)) {
+                count += 1;
+            }
+        }
+        return count;
+    }
+    /* Who made this node, or null for one a person made: the whole of the rule node delete follows. */
+    madeBy(nodeId) {
+        const entry = this.opened.get(nodeId);
+        return entry === undefined || entry.relation === 'fork' ? null : entry.openedBy;
+    }
+    /* The node that opened this one as an agent, or null for a node no agent or team started. */
+    startedBy(nodeId) {
+        const entry = this.opened.get(nodeId);
+        return entry !== undefined && openedByAgent(entry) ? entry.openedBy : null;
+    }
+    /* The chat a fork was made from, or null for a node that is no fork. */
+    forkedFrom(nodeId) {
+        const entry = this.opened.get(nodeId);
+        return entry?.relation === 'fork' ? entry.openedBy : null;
+    }
+    /* The forks made from a chat. */
+    forksOf(nodeId) {
+        return [...this.opened.all()].filter((entry) => entry.relation === 'fork' && entry.openedBy === nodeId).map((entry) => entry.nodeId);
+    }
+    /* The forks of this project whose node is gone, read before `prune` forgets them. */
+    forksLeaving(projectId, ids) {
+        return [...this.opened.all()]
+            .filter((entry) => entry.projectId === projectId && entry.relation === 'fork' && !ids.has(entry.nodeId))
+            .map((entry) => entry.nodeId);
+    }
+    /* Drops what this project wrote down for ids it no longer has: the node was deleted. */
+    prune(projectId, ids) {
+        return this.opened.prune((entry) => entry.projectId === projectId && !ids.has(entry.nodeId));
+    }
+}

package/dist/messages/deliver-message.d.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+import type { WakeChat } from '../chat/wake-chat.ts';
+import type { OutboxEntryOf } from '../outbox/outbox.ts';
+import type { OutboxOutcome } from '../outbox/outbox-worker.ts';
+import type { MessageWords } from './deliver-notice.ts';
+import type { NoticeStore } from './notice-store.ts';
+export declare const DeliverMessageWorkSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"deliver-message">;
+    payload: z.ZodObject<{
+        from: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type DeliverMessageWork = z.infer<typeof DeliverMessageWorkSchema>;
+export type DeliverMessageEntry = OutboxEntryOf<DeliverMessageWork>;
+export interface DeliverMessageDeps {
+    notices: Pick<NoticeStore, 'waiting'>;
+    chat(chatId: string): Promise<WakeChat | null>;
+    placed(nodeId: string): boolean;
+    words: Pick<MessageWords, 'prompt' | 'label'>;
+}
+export declare function deliverMessageHandler(deps: DeliverMessageDeps): (entry: DeliverMessageEntry) => Promise<OutboxOutcome>;

package/dist/messages/deliver-message.js

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+export const DeliverMessageWorkSchema = z.object({
+    kind: z.literal('deliver-message'),
+    // The target is the chat the message was left for; the message itself waits in the notice store, with any that came in beside it.
+    payload: z.object({ from: z.string().min(1) })
+});
+/*
+ * Opens the turn a message earns a chat. The messages themselves are not carried here: they wait in
+ * the notice store and the turn's preamble takes them (`NoticeNotes`), the same channel a person's
+ * own prompt reads them through, so one message is heard once whichever of the two opens the turn.
+ *
+ * One attempt, never `wait`. A chat that turned out to be in a turn reads the message in front of its
+ * next one, which is what a message to a busy chat has always done; holding the entry instead would
+ * make the host start turns nobody asked for long after the news was worth anything.
+ */
+export function deliverMessageHandler(deps) {
+    return async (entry) => {
+        if (!deps.placed(entry.target)) {
+            return;
+        }
+        const waiting = deps.notices.waiting(entry.target);
+        // A turn opened for an earlier message took these along, or they went stale: nothing to wake anyone for.
+        if (waiting.length === 0) {
+            return;
+        }
+        const chat = await deps.chat(entry.target);
+        if (chat === null) {
+            return;
+        }
+        /*
+         * No note of its own, and the preamble stays off the thread. A person read the message as it
+         * landed (`showNotices`), so anything the turn adds about it only says the same thing again;
+         * the label on the turn already names who it came from.
+         */
+        chat.wake({
+            text: deps.words.prompt(waiting.length),
+            label: deps.words.label(waiting),
+            taskIds: [],
+            messageFrom: [...new Set(waiting.map((notice) => notice.from))]
+        });
+    };
+}

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

@@ -0,0 +1,25 @@
+import type { ChatItem } from '@adecore/agent-contracts';
+import type { ChatCore } from '../chat/chat-core.ts';
+import type { Notice, NoticeStore } from './notice-store.ts';
+export interface MessageWords {
+    heard(notice: Notice): string;
+    shown(notice: Notice): string;
+    prompt(count: number): string;
+    label(notices: readonly Notice[]): string;
+}
+export interface ChatNoticeTargets {
+    chat(id: string): Promise<'idle' | 'running' | 'none'>;
+    fromMessage(id: string): boolean;
+}
+export interface ChatDelivery {
+    outcome: 'wake' | 'no-chat' | 'in-turn' | 'from-message';
+    waiting: number;
+}
+export declare function turnFromMessage(items: readonly ChatItem[], activeTurnId: string | null): boolean;
+export declare function chatNoticeTargets(chats: Pick<ChatCore, 'get' | 'hasStored'>): ChatNoticeTargets;
+export declare function deliverToChat(store: Pick<NoticeStore, 'put'>, targets: ChatNoticeTargets, notice: Omit<Notice, 'createdAt'>): Promise<ChatDelivery>;
+export interface NoticeChat {
+    has(id: string): Promise<boolean>;
+    note(id: string, text: string): Promise<void>;
+}
+export declare function showNotices(store: Pick<NoticeStore, 'show'>, chat: NoticeChat, words: Pick<MessageWords, 'shown'>, targetId: string): Promise<void>;

package/dist/messages/deliver-notice.js

@@ -0,0 +1,75 @@
+/*
+ * Whether the turn a chat is running was itself opened by a message. This is the whole of the stop:
+ * two agents that read each other would otherwise wake each other for as long as they kept writing,
+ * and nothing about that started with a person. It rides on the turn, so it survives a restart.
+ * Between turns the last one counts, since work it left running (a background subagent) may still
+ * write, and a turn the CLI opened by itself goes on with the step of the turn before it.
+ */
+export function turnFromMessage(items, activeTurnId) {
+    const from = activeTurnId === null ? items.findLastIndex((item) => item.kind === 'turn') : items.findIndex((item) => item.id === activeTurnId);
+    for (let i = from; i >= 0; i--) {
+        const turn = items[i];
+        if (turn.kind !== 'turn') {
+            continue;
+        }
+        if ((turn.messageFrom ?? []).length > 0) {
+            return true;
+        }
+        if (turn.origin !== 'agent' || turn.taskIds !== undefined || turn.summaryFor !== undefined) {
+            return false;
+        }
+    }
+    return false;
+}
+/* The chats of a core as a message sees them. */
+export function chatNoticeTargets(chats) {
+    return {
+        chat: async (id) => {
+            const session = chats.get(id);
+            if (session) {
+                return session.info.activeTurnId === null ? 'idle' : 'running';
+            }
+            // A chat nobody has loaded is idle: the turn opens on the thread the host reads back from disk.
+            return (await chats.hasStored(id)) ? 'idle' : 'none';
+        },
+        fromMessage: (id) => {
+            const session = chats.get(id);
+            return session !== undefined && turnFromMessage(session.thread.list(), session.info.activeTurnId);
+        }
+    };
+}
+/*
+ * One message on its way to a chat, and whether the chat owes a turn on it. A chat between turns gets
+ * one, the way a settled task gives one: a person watching two agents cannot tell a message from an
+ * assignment, and a message nobody starts a turn for sits there until someone happens to prompt that
+ * chat. One step deep, so the turn a message opened wakes nobody with a message of its own. A node the
+ * host runs something else in, such as a terminal, is the host's to deliver to before this.
+ */
+export async function deliverToChat(store, targets, notice) {
+    const waiting = await store.put(notice);
+    const chat = await targets.chat(notice.targetId);
+    if (chat === 'none') {
+        return { outcome: 'no-chat', waiting };
+    }
+    if (chat === 'running') {
+        return { outcome: 'in-turn', waiting };
+    }
+    if (targets.fromMessage(notice.from)) {
+        return { outcome: 'from-message', waiting };
+    }
+    return { outcome: 'wake', waiting };
+}
+/*
+ * What a chat has to show a person, in its thread, the moment a message lands and not when the model
+ * gets round to it: without this a message left for a busy node is a file on disk and nothing else.
+ * An id no chat holds shows nothing and marks nothing, so the chat that opens on that id later still
+ * has all of it.
+ */
+export async function showNotices(store, chat, words, targetId) {
+    if (!(await chat.has(targetId))) {
+        return;
+    }
+    for (const notice of await store.show(targetId)) {
+        await chat.note(targetId, words.shown(notice));
+    }
+}

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

@@ -0,0 +1,15 @@
+import type { PromptNotes } from '../chat/chat-session.ts';
+import type { MessageWords } from './deliver-notice.ts';
+import type { NoticeStore } from './notice-store.ts';
+export declare class NoticeNotes implements PromptNotes {
+    private readonly store;
+    private readonly chatId;
+    private readonly words;
+    constructor(store: Pick<NoticeStore, 'take'>, chatId: string, words: Pick<MessageWords, 'heard'>);
+    next(): {
+        shown: string[];
+        heard: string[];
+    };
+    reset(): void;
+}
+export declare function unshownNotes(store: Pick<NoticeStore, 'show'>, chatId: string, words: Pick<MessageWords, 'shown'>): Promise<string[]>;