@adecore/agents 0.0.1 → 0.17.0-beta.1

package/src/host/environment.ts

@@ -0,0 +1,31 @@
+// These inherited hooks must remain blocked while older hosts are still in use.
+export const RUIMTE_SESSION_VARIABLES = ['RUIMTE_HOOK_URL', 'RUIMTE_HOOK_TOKEN', 'RUIMTE_CONTEXT_URL', 'RUIMTE_CONTEXT_TOKEN', 'RUIMTE_SESSION_ID'] as const;
+
+export interface CliEnvironmentPolicy {
+    variables?: readonly string[];
+    prefixes?: readonly string[];
+    /* A host prefix such as APP strips its hook/context variables and session id, leaving APP_HOME intact. */
+    sessionPrefixes?: readonly string[];
+}
+
+const COMPATIBILITY_PREFIXES = ['RUIMTE_HOOK_', 'RUIMTE_CONTEXT_'];
+
+export function cliEnvironment(env: Record<string, string | undefined> = process.env, policy: CliEnvironmentPolicy = {}): Record<string, string> {
+    const variables = new Set<string>([...RUIMTE_SESSION_VARIABLES, ...(policy.variables ?? [])]);
+    const prefixes = [...COMPATIBILITY_PREFIXES, ...(policy.prefixes ?? [])];
+    for (const host of policy.sessionPrefixes ?? []) {
+        const prefix = host.replace(/_+$/, '');
+        if (prefix === '') {
+            throw new Error('A session environment prefix must not be empty');
+        }
+        variables.add(`${prefix}_SESSION_ID`);
+        prefixes.push(`${prefix}_HOOK_`, `${prefix}_CONTEXT_`);
+    }
+    const clean: Record<string, string> = {};
+    for (const [name, value] of Object.entries(env)) {
+        if (value !== undefined && !variables.has(name) && !prefixes.some((prefix) => name.startsWith(prefix))) {
+            clean[name] = value;
+        }
+    }
+    return clean;
+}

package/src/host/handlers.ts

@@ -0,0 +1,142 @@
+import type { AGENT_REQUEST_SCHEMAS, AgentRequestType } from '@adecore/agent-contracts';
+import type { z } from 'zod';
+import type { ChatCore } from '../chat/chat-core.ts';
+import { ChatError } from '../chat/errors.ts';
+import type { ProviderAccountsService } from '../providers/accounts/service.ts';
+import type { ProviderRegistry } from '../providers/registry.ts';
+import type { UsageMonitor } from '../usage/limits/monitor.ts';
+import type { UsageService } from '../usage/usage-service.ts';
+
+export type AgentRequestMap = {
+    [T in AgentRequestType]: {
+        payload: z.infer<(typeof AGENT_REQUEST_SCHEMAS)[T]['payload']>;
+        result: z.infer<(typeof AGENT_REQUEST_SCHEMAS)[T]['result']>;
+    };
+};
+
+/* One request as a host answers it, for the client that asked. */
+export type AgentHandler<T extends AgentRequestType> = (
+    payload: AgentRequestMap[T]['payload'],
+    clientId: string
+) => AgentRequestMap[T]['result'] | Promise<AgentRequestMap[T]['result']>;
+
+export type AgentHandlers = { [T in AgentRequestType]: AgentHandler<T> };
+
+type AccountRequestType = Extract<AgentRequestType, `accounts.${string}`>;
+type UsageRequestType = Extract<AgentRequestType, `usage.${string}`>;
+export type ChatRequestType = Exclude<AgentRequestType, AccountRequestType | UsageRequestType>;
+
+// 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: string) {
+    return (): never => {
+        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: ChatCore, providers: ProviderRegistry): { [T in ChatRequestType]: AgentHandler<T> } {
+    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: ProviderAccountsService): { [T in AccountRequestType]: AgentHandler<T> } {
+    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: UsageService, limits: UsageMonitor): { [T in UsageRequestType]: AgentHandler<T> } {
+    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/src/host/memory-port.ts

@@ -0,0 +1,27 @@
+import type { FramePort } from '@adecore/agent-contracts';
+
+/*
+ * 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(): [FramePort, FramePort] {
+    const listeners: [Set<(frame: unknown) => void>, Set<(frame: unknown) => void>] = [new Set(), new Set()];
+    const end = (own: number): FramePort => ({
+        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/src/host/wiring.ts

@@ -0,0 +1,164 @@
+import type { AgentKind, UsageProvider } from '@adecore/agent-contracts';
+import { AttachmentStore } from '../chat/attachment-store.ts';
+import { BookmarkStore } from '../chat/bookmark-store.ts';
+import { ChatCore, type ChatCoreOptions } from '../chat/chat-core.ts';
+import type { SpawnChatProcess } from '../chat/chat-process.ts';
+import { ChatStore } from '../chat/chat-store.ts';
+import { suggestChatTitle } from '../chat/chat-title.ts';
+import type { ClaudeBackendOptions } from '../chat/claude-backend.ts';
+import { ClaudeTitleReader } from '../chat/claude-title.ts';
+import { DEFAULT_CODEX_CLIENT, type CodexClientInfo } from '../chat/codex-transport.ts';
+import type { AgentEvent } from '../events.ts';
+import { definedEnv } from '../providers/accounts/launch.ts';
+import { ProviderAccountsService } from '../providers/accounts/service.ts';
+import type { AccountsHost } from '../providers/accounts/variables.ts';
+import { createClaudeProvider } from '../providers/claude-provider.ts';
+import { errorText } from '../error-text.ts';
+import { createCodexProvider } from '../providers/codex-provider.ts';
+import { codexRulesPathIn, defaultCodexHome, installCodexRules, type CodexRules } from '../providers/codex-rules.ts';
+import { ProviderRegistry, type ProviderRegistryOptions } from '../providers/registry.ts';
+import { chatSessionAccounts, limitAccountsOf, usageAccountsOf, usageRootsOf } from '../usage/accounts.ts';
+import { UsageMonitor } from '../usage/limits/monitor.ts';
+import { UsageService } from '../usage/usage-service.ts';
+import { cliEnvironment, type CliEnvironmentPolicy } from './environment.ts';
+import { accountHandlers, chatHandlers, usageHandlers, type AgentHandlers } from './handlers.ts';
+
+export interface AgentWiringOptions<Core extends ChatCore = ChatCore> {
+    // Where the chats, their attachments and bookmarks, the accounts and the usage index are kept.
+    dataDir: string;
+    // The environment the CLIs start in; absent, this process's own through `cliEnvironment`.
+    env?: Record<string, string | undefined>;
+    environmentPolicy?: CliEnvironmentPolicy;
+    // What every agent is told once, at the start of its process.
+    systemNote?: string;
+    // How the host names itself: to Codex, in a refusal about an account, and in the keychain.
+    client?: CodexClientInfo;
+    accountsHost?: AccountsHost;
+    claude?: ClaudeBackendOptions;
+    // The commands Codex runs outside its sandbox without asking, such as the host's context CLI; written in its home and every account's.
+    codexRules?: CodexRules;
+    // The core of an app that extends `ChatCore`, made from what a plain core would get; absent, a plain core.
+    core?: (options: ChatCoreOptions) => Core;
+    // A test runs fake CLIs: the commands to start and how.
+    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;
+    /* Sends one client its chat, account and usage events until the returned function lets go of it. */
+    connect(clientId: string, send: (event: AgentEvent) => void): () => void;
+    /* Checks who is signed in and reads what is left of each plan on their own clocks, until `stop`. */
+    start(): void;
+    /* Stops the clocks, writes every thread and ends every CLI; settles once they exited. */
+    stop(): Promise<void>;
+}
+
+// A folder the rule cannot be written to only costs an approval per call, so it never stops the host.
+async function installRulesIn(kind: AgentKind, folder: string, rules: CodexRules): Promise<void> {
+    if (kind !== 'codex') {
+        return;
+    }
+    const path = codexRulesPathIn(folder, rules);
+    await installCodexRules(path, rules).catch((e: unknown) => 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<Core extends ChatCore = ChatCore>(options: AgentWiringOptions<Core>): AgentWiring<Core> {
+    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: AgentKind, folder: string) => installRulesIn(kind, folder, codexRules) } : {})
+    });
+    if (codexRules) {
+        void installRulesIn('codex', defaultCodexHome(env), codexRules);
+    }
+    const nameOf = (kind: AgentKind | UsageProvider): string => 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: ChatCoreOptions) => new ChatCore(coreOptions) as Core);
+    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/src/lineage.ts

@@ -0,0 +1,159 @@
+import { join } from 'node:path';
+import { RuntimeModeSchema, type RuntimeMode } from '@adecore/agent-contracts';
+import { z } from 'zod';
+import { RecordDirectory } from './record-directory.ts';
+
+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()
+});
+
+type Lineage = z.infer<typeof LineageSchema>;
+
+/* Opened by the agent it names, which is what every rule about children is about; a fork lives on its own. */
+function openedByAgent(entry: Lineage): boolean {
+    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 {
+    readonly dir: string;
+    private readonly opened: RecordDirectory<Lineage>;
+
+    constructor(dataDir: string) {
+        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(): Promise<void> {
+        return this.opened.load();
+    }
+
+    async put(record: Omit<Lineage, 'createdAt' | 'endedAt'>): Promise<void> {
+        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: string): string[] {
+        const found: string[] = [];
+        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: string): string | null {
+        return this.opened.get(nodeId)?.projectId ?? null;
+    }
+
+    endedAt(nodeId: string): number | null {
+        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: readonly string[]): Promise<void> {
+        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: string, ids: ReadonlySet<string>): Array<{ nodeId: string; openedBy: string }> {
+        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: string): RuntimeMode | null {
+        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: string): number {
+        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: string, include: (nodeId: string) => boolean = () => true): number {
+        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: string): string | null {
+        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: string): string | null {
+        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: string): string | null {
+        const entry = this.opened.get(nodeId);
+        return entry?.relation === 'fork' ? entry.openedBy : null;
+    }
+
+    /* The forks made from a chat. */
+    forksOf(nodeId: string): string[] {
+        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: string, ids: ReadonlySet<string>): string[] {
+        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: string, ids: ReadonlySet<string>): Promise<void> {
+        return this.opened.prune((entry) => entry.projectId === projectId && !ids.has(entry.nodeId));
+    }
+}

package/src/messages/deliver-message.ts

@@ -0,0 +1,61 @@
+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 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) })
+});
+
+export type DeliverMessageWork = z.infer<typeof DeliverMessageWorkSchema>;
+export type DeliverMessageEntry = OutboxEntryOf<DeliverMessageWork>;
+
+export interface DeliverMessageDeps {
+    notices: Pick<NoticeStore, 'waiting'>;
+    /* The chat the message was left for, loaded from disk when nobody has it; null for a node with no thread. */
+    chat(chatId: string): Promise<WakeChat | null>;
+    /* Whether a project still places the node; one that is gone reads nothing any more. */
+    placed(nodeId: string): boolean;
+    words: Pick<MessageWords, 'prompt' | 'label'>;
+}
+
+/*
+ * 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: DeliverMessageDeps) {
+    return async (entry: DeliverMessageEntry): Promise<OutboxOutcome> => {
+        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))]
+        });
+    };
+}