@agent-workshop/adoc-core 0.1.0

package/dist/herdr.js

@@ -0,0 +1,134 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { createConnection } from 'node:net';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { AdocError } from './errors.js';
+let requestId = 0;
+/** Sends one request over a herdr session socket (NDJSON) and returns its result. */
+export function herdrCall(socketPath, method, params = {}) {
+    return new Promise((resolve, reject) => {
+        const socket = createConnection(socketPath);
+        let buffer = '';
+        const id = `adoc-${++requestId}`;
+        socket.setTimeout(10_000, () => socket.destroy(new Error(`herdr ${method} timed out`)));
+        socket.on('connect', () => socket.write(JSON.stringify({ id, method, params }) + '\n'));
+        socket.on('data', (chunk) => {
+            buffer += chunk.toString('utf8');
+            const end = buffer.indexOf('\n');
+            if (end < 0)
+                return;
+            socket.end();
+            const reply = JSON.parse(buffer.slice(0, end));
+            if (reply.error)
+                reject(new AdocError('herdr.error', `herdr ${method}: ${reply.error.message ?? reply.error.code}`));
+            else
+                resolve(reply.result);
+        });
+        socket.on('error', (error) => reject(new AdocError('herdr.unreachable', `herdr socket ${socketPath}: ${error.message}`)));
+    });
+}
+/**
+ * Subscribes to herdr events on a session socket; the connection stays open.
+ * Returns a function that closes the subscription.
+ */
+export function herdrSubscribe(socketPath, subscriptions, onEvent, onClose) {
+    const socket = createConnection(socketPath);
+    let buffer = '';
+    socket.on('connect', () => socket.write(JSON.stringify({ id: `adoc-sub-${++requestId}`, method: 'events.subscribe', params: { subscriptions } }) + '\n'));
+    socket.on('data', (chunk) => {
+        buffer += chunk.toString('utf8');
+        let end;
+        while ((end = buffer.indexOf('\n')) >= 0) {
+            const line = buffer.slice(0, end);
+            buffer = buffer.slice(end + 1);
+            try {
+                const message = JSON.parse(line);
+                if (message.event)
+                    onEvent(message);
+            }
+            catch {
+                // Ignore a malformed line.
+            }
+        }
+    });
+    socket.on('close', onClose);
+    socket.on('error', () => undefined);
+    return () => socket.destroy();
+}
+/** The socket of every herdr session on this computer, by session name. */
+export async function herdrSessions(home = homedir()) {
+    const root = join(home, '.config', 'herdr', 'sessions');
+    try {
+        const names = await readdir(root);
+        return names.map((name) => ({ name, socket: join(root, name, 'herdr.sock') }));
+    }
+    catch {
+        return [];
+    }
+}
+export async function herdrPanes(socketPath) {
+    const result = await herdrCall(socketPath, 'session.snapshot');
+    return result.snapshot.panes;
+}
+/** Whether this process runs under a shared agent daemon such as the Codex app-server, whose HERDR_PANE_ID is not the agent's. */
+export async function underSharedDaemon(pid = process.ppid) {
+    for (let current = pid, depth = 0; current > 1 && depth < 64; depth++) {
+        try {
+            const args = (await readFile(`/proc/${current}/cmdline`, 'utf8')).split('\0').join(' ');
+            if (args.includes('codex') && args.split(/\s+/).includes('app-server'))
+                return true;
+            const stat = await readFile(`/proc/${current}/stat`, 'utf8');
+            current = Number(stat.slice(stat.lastIndexOf(')') + 2).split(' ')[1]);
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
+}
+/** The session-id variables that agent runtimes export to their tool processes. */
+const SESSION_VARIABLES = [
+    ['claude', 'CLAUDE_CODE_SESSION_ID'],
+    ['codex', 'CODEX_SESSION_ID'],
+];
+/**
+ * Finds the caller's herdr pane, in the order of _Agent_Claim_Command_: `--pane`, then the pane whose
+ * recorded agent session is the caller's session id, then HERDR_PANE_ID unless under a shared daemon.
+ */
+export async function resolveAgentPane(env, options = {}) {
+    const sessions = (await herdrSessions(env.HOME)).filter((s) => !options.herdrSession || s.name === options.herdrSession);
+    if (!sessions.length)
+        throw new AdocError('claim.herdr', 'No herdr session found on this computer; adoc agent claim needs herdr.');
+    const inSession = async (paneId, preferred) => {
+        const ordered = preferred ? [...sessions.filter((s) => s.socket === preferred), ...sessions.filter((s) => s.socket !== preferred)] : sessions;
+        for (const session of ordered) {
+            const pane = (await herdrPanes(session.socket).catch(() => [])).find((p) => p.pane_id === paneId);
+            if (pane)
+                return { session, pane };
+        }
+        return undefined;
+    };
+    if (options.pane) {
+        const found = await inSession(options.pane, env.HERDR_SOCKET_PATH);
+        if (!found)
+            throw new AdocError('claim.pane', `No herdr pane ${options.pane}.`);
+        return { herdrSession: found.session.name, socket: found.session.socket, pane: found.pane, via: 'option' };
+    }
+    for (const [, variable] of SESSION_VARIABLES) {
+        const id = env[variable];
+        if (!id)
+            continue;
+        for (const session of sessions) {
+            const pane = (await herdrPanes(session.socket).catch(() => [])).find((p) => p.agent_session?.value === id);
+            if (pane)
+                return { herdrSession: session.name, socket: session.socket, pane, via: 'session-id' };
+        }
+    }
+    if (env.HERDR_PANE_ID && !(await underSharedDaemon())) {
+        const found = await inSession(env.HERDR_PANE_ID, env.HERDR_SOCKET_PATH);
+        if (found)
+            return { herdrSession: found.session.name, socket: found.session.socket, pane: found.pane, via: 'environment' };
+    }
+    throw new AdocError('claim.unknown', 'Cannot tell which herdr pane this agent runs in; run adoc agent claim --pane <pane id> (see herdr pane list).');
+}
+//# sourceMappingURL=herdr.js.map

package/dist/herdr.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"herdr.js","sourceRoot":"","sources":["../src/herdr.ts"],"names":[],"mappings":"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"}

package/dist/home.d.ts

@@ -0,0 +1,12 @@
+export declare const HOME_DIRECTORY = ".adoc";
+export declare const HOME_VARIABLE = "ADOC_HOME";
+export declare const CONFIG_FILE = "adoc.yaml";
+/** A selected _Adoc_Home_ and the _Adoc_Workspace_ that holds it. */
+export interface AdocHome {
+    readonly home: string;
+    readonly workspace: string;
+    readonly configPath: string;
+    readonly origin: 'option' | 'environment' | 'ancestor';
+}
+/** Selects the _Adoc_Home_: `--home`, then `ADOC_HOME`, then the nearest `.adoc` from `cwd` upward. */
+export declare function discoverHome(cwd: string, explicit?: string, env?: NodeJS.ProcessEnv): Promise<AdocHome>;

package/dist/home.js

@@ -0,0 +1,43 @@
+import { stat } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { AdocError } from './errors.js';
+export const HOME_DIRECTORY = '.adoc';
+export const HOME_VARIABLE = 'ADOC_HOME';
+export const CONFIG_FILE = 'adoc.yaml';
+async function isDirectory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function select(path, origin, cwd) {
+    const home = resolve(cwd, path);
+    return { home, workspace: dirname(home), configPath: join(home, CONFIG_FILE), origin };
+}
+/** Selects the _Adoc_Home_: `--home`, then `ADOC_HOME`, then the nearest `.adoc` from `cwd` upward. */
+export async function discoverHome(cwd, explicit, env = process.env) {
+    if (explicit !== undefined) {
+        const selected = select(explicit, 'option', cwd);
+        if (!(await isDirectory(selected.home)))
+            throw new AdocError('home.missing', `--home ${explicit} is not a directory.`);
+        return selected;
+    }
+    const variable = env[HOME_VARIABLE];
+    if (variable !== undefined && variable.trim() !== '') {
+        const selected = select(variable, 'environment', cwd);
+        if (!(await isDirectory(selected.home)))
+            throw new AdocError('home.missing', `${HOME_VARIABLE}=${variable} is not a directory.`);
+        return selected;
+    }
+    for (let directory = resolve(cwd);; directory = dirname(directory)) {
+        const candidate = join(directory, HOME_DIRECTORY);
+        if (await isDirectory(candidate))
+            return select(candidate, 'ancestor', cwd);
+        if (dirname(directory) === directory)
+            break;
+    }
+    throw new AdocError('home.missing', `No ${HOME_DIRECTORY} directory from ${cwd} upward; run adoc init.`);
+}
+//# sourceMappingURL=home.js.map

package/dist/home.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"home.js","sourceRoot":"","sources":["../src/home.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AACtC,MAAM,CAAC,MAAM,aAAa,GAAG,WAAW,CAAC;AACzC,MAAM,CAAC,MAAM,WAAW,GAAG,WAAW,CAAC;AAUvC,KAAK,UAAU,WAAW,CAAC,IAAY;IACrC,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,SAAS,MAAM,CAAC,IAAY,EAAE,MAA0B,EAAE,GAAW;IACnE,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAChC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;AACzF,CAAC;AAED,uGAAuG;AACvG,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,GAAW,EAAE,QAAiB,EAAE,GAAG,GAAsB,OAAO,CAAC,GAAG;IACrG,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC;QACjD,IAAI,CAAC,CAAC,MAAM,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAAE,MAAM,IAAI,SAAS,CAAC,cAAc,EAAE,UAAU,QAAQ,sBAAsB,CAAC,CAAC;QACvH,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,MAAM,QAAQ,GAAG,GAAG,CAAC,aAAa,CAAC,CAAC;IACpC,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACrD,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,CAAC,CAAC;QACtD,IAAI,CAAC,CAAC,MAAM,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAAE,MAAM,IAAI,SAAS,CAAC,cAAc,EAAE,GAAG,aAAa,IAAI,QAAQ,sBAAsB,CAAC,CAAC;QACjI,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,KAAK,IAAI,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,GAAI,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACpE,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;QAClD,IAAI,MAAM,WAAW,CAAC,SAAS,CAAC;YAAE,OAAO,MAAM,CAAC,SAAS,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC;QAC5E,IAAI,OAAO,CAAC,SAAS,CAAC,KAAK,SAAS;YAAE,MAAM;IAC9C,CAAC;IACD,MAAM,IAAI,SAAS,CAAC,cAAc,EAAE,MAAM,cAAc,mBAAmB,GAAG,yBAAyB,CAAC,CAAC;AAC3G,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+export { AdocError, errorMessage } from './errors.js';
+export { discoverHome, HOME_DIRECTORY, HOME_VARIABLE, CONFIG_FILE, type AdocHome } from './home.js';
+export { readConfig, userConfigPath, CONFIG_TEMPLATE, type AdocConfig, type DeclaredPlugin, type TransportConfig } from './config.js';
+export { PLUGIN_KEY_PATTERN, LOCAL_ID_PATTERN, parseDocumentTarget } from './names.js';
+export { loadPlugins, pluginDirectory, parseGithubSource, fetchedFolder, readSkillSource, scopeOf, type GithubSource, type LoadedPlugin, type Scope, type SkillSource } from './plugins.js';
+export { fetchGithubPlugins, folderHash, type FetchOutcome } from './fetch.js';
+export { scanDocuments, readDocument, type DocumentRecord, type ScanProblem } from './scan.js';
+export { Workspace, type SummaryEntry, type DocumentView, type CheckEntry, type PluginInfo, type ActionOutcome, type DocumentChanges, type StoredVersion } from './workspace.js';
+export { MessageQueue, formatMessage, formatMessages, formatTarget, messageFields, type UserMessage, type UserComment, type MessageTarget } from './messages.js';
+export { createTransport, attachTransport, type MessageTransport, type ClaimSource } from './transports.js';
+export { readClaim, writeClaim, removeClaim, claimPath, CLAIM_FILE, type AgentClaim } from './claim.js';
+export { herdrCall, herdrSubscribe, herdrSessions, herdrPanes, resolveAgentPane, underSharedDaemon, type HerdrPane, type ResolvedPane } from './herdr.js';
+export { AdocServer, PROTOCOL, publicMessage, type BrowserSession, type ServerExtension, type ServerOptions } from './server.js';
+export { readServerRecord, type ServerRecord } from './registry.js';
+export { ServerClient } from './client.js';
+export { formatCheck } from './report.js';
+export { isGitRepository } from './git.js';
+export { listSkills, viewSkill, installSkills, uninstallSkills, checkSkills, readSkillFile, editSkillFile, type SkillEntry, type SkillInstallOptions } from './skills.js';

package/dist/index.js

@@ -0,0 +1,19 @@
+export { AdocError, errorMessage } from './errors.js';
+export { discoverHome, HOME_DIRECTORY, HOME_VARIABLE, CONFIG_FILE } from './home.js';
+export { readConfig, userConfigPath, CONFIG_TEMPLATE } from './config.js';
+export { PLUGIN_KEY_PATTERN, LOCAL_ID_PATTERN, parseDocumentTarget } from './names.js';
+export { loadPlugins, pluginDirectory, parseGithubSource, fetchedFolder, readSkillSource, scopeOf } from './plugins.js';
+export { fetchGithubPlugins, folderHash } from './fetch.js';
+export { scanDocuments, readDocument } from './scan.js';
+export { Workspace } from './workspace.js';
+export { MessageQueue, formatMessage, formatMessages, formatTarget, messageFields } from './messages.js';
+export { createTransport, attachTransport } from './transports.js';
+export { readClaim, writeClaim, removeClaim, claimPath, CLAIM_FILE } from './claim.js';
+export { herdrCall, herdrSubscribe, herdrSessions, herdrPanes, resolveAgentPane, underSharedDaemon } from './herdr.js';
+export { AdocServer, PROTOCOL, publicMessage } from './server.js';
+export { readServerRecord } from './registry.js';
+export { ServerClient } from './client.js';
+export { formatCheck } from './report.js';
+export { isGitRepository } from './git.js';
+export { listSkills, viewSkill, installSkills, uninstallSkills, checkSkills, readSkillFile, editSkillFile } from './skills.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,WAAW,EAAiB,MAAM,WAAW,CAAC;AACpG,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,eAAe,EAA8D,MAAM,aAAa,CAAC;AACtI,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACvF,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,iBAAiB,EAAE,aAAa,EAAE,eAAe,EAAE,OAAO,EAAsE,MAAM,cAAc,CAAC;AAC5L,OAAO,EAAE,kBAAkB,EAAE,UAAU,EAAqB,MAAM,YAAY,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,YAAY,EAAyC,MAAM,WAAW,CAAC;AAC/F,OAAO,EAAE,SAAS,EAAwI,MAAM,gBAAgB,CAAC;AACjL,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAA0D,MAAM,eAAe,CAAC;AACjK,OAAO,EAAE,eAAe,EAAE,eAAe,EAA2C,MAAM,iBAAiB,CAAC;AAC5G,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAmB,MAAM,YAAY,CAAC;AACxG,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,aAAa,EAAE,UAAU,EAAE,gBAAgB,EAAE,iBAAiB,EAAqC,MAAM,YAAY,CAAC;AAC1J,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,aAAa,EAAiE,MAAM,aAAa,CAAC;AACjI,OAAO,EAAE,gBAAgB,EAAqB,MAAM,eAAe,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,EAAE,eAAe,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAA6C,MAAM,aAAa,CAAC"}

package/dist/messages.d.ts

@@ -0,0 +1,76 @@
+import { EventEmitter } from 'node:events';
+/** _User_Message_Target_: one of five levels. */
+export type MessageTarget = {
+    level: 'workspace';
+} | {
+    level: 'plugin';
+    pluginKey: string;
+} | {
+    level: 'document';
+    key: string;
+} | {
+    level: 'anchor';
+    key: string;
+    anchor: string;
+} | {
+    level: 'skill';
+    name: string;
+};
+/** One _User_Comment_ inside a comment message. */
+export interface UserComment {
+    target: MessageTarget;
+    text: string;
+    quote?: string;
+    source?: string;
+}
+/** A _User_Comment_Message_: the composer text with its target, and the draft comments, in the order added. */
+export interface CommentInput {
+    target?: MessageTarget;
+    text?: string;
+    comments: UserComment[];
+}
+export interface ActionMessageInput {
+    target: MessageTarget;
+    action: string;
+    value: string;
+    to?: string;
+    applied: boolean;
+    text: string;
+}
+/** A held _User_Message_. */
+export type UserMessage = ({
+    number: number;
+    kind: 'comment';
+    createdAt: string;
+} & CommentInput) | ({
+    number: number;
+    kind: 'action';
+    createdAt: string;
+} & ActionMessageInput);
+export declare function formatTarget(target: MessageTarget): string;
+/** The structured fields of a message, in _User_Message_Format_ order. */
+export declare function messageFields(message: UserMessage): Record<string, unknown>;
+/** Renders one message in _User_Message_Format_: the header line, the main text, then attached YAML fields after `--`. */
+export declare function formatMessage(message: UserMessage): string;
+export declare function formatMessages(messages: readonly UserMessage[]): string;
+/**
+ * Holds every _User_Message_ until it is delivered, in creation order.
+ * Emits `change` whenever the held set changes.
+ */
+export declare class MessageQueue extends EventEmitter {
+    private next;
+    private held;
+    private waiters;
+    add(input: ({
+        kind: 'comment';
+    } & CommentInput) | ({
+        kind: 'action';
+    } & ActionMessageInput)): UserMessage;
+    list(): UserMessage[];
+    /** Removes and returns every held message. */
+    takeAll(): UserMessage[];
+    /** Removes the given messages after a push transport delivered them. */
+    markDelivered(numbers: readonly number[]): void;
+    /** Waits until at least one message is held, then takes all of them; resolves with [] after `timeoutMs`. */
+    wait(timeoutMs?: number, signal?: AbortSignal): Promise<UserMessage[]>;
+}

package/dist/messages.js

@@ -0,0 +1,119 @@
+import { EventEmitter } from 'node:events';
+import { stringify } from 'yaml';
+export function formatTarget(target) {
+    switch (target.level) {
+        case 'workspace':
+            return 'workspace';
+        case 'plugin':
+            return target.pluginKey;
+        case 'document':
+            return target.key;
+        case 'anchor':
+            return `${target.key}#${target.anchor}`;
+        case 'skill':
+            return `skill ${target.name}`;
+    }
+}
+/** The structured fields of a message, in _User_Message_Format_ order. */
+export function messageFields(message) {
+    const fields = { number: message.number, kind: message.kind };
+    if (message.kind === 'comment') {
+        if (message.target)
+            fields.target = formatTarget(message.target);
+        if (message.text)
+            fields.text = message.text;
+        if (message.comments.length)
+            fields.comments = message.comments.map((comment) => {
+                const entry = { target: formatTarget(comment.target) };
+                if (comment.source)
+                    entry.source = comment.source;
+                if (comment.quote)
+                    entry.quote = comment.quote;
+                entry.text = comment.text;
+                return entry;
+            });
+    }
+    else {
+        fields.target = formatTarget(message.target);
+        fields.action = message.action;
+        fields.value = message.value;
+        if (message.to !== undefined)
+            fields.to = message.to;
+        fields.applied = message.applied;
+        fields.text = message.text;
+    }
+    return fields;
+}
+/** Renders one message in _User_Message_Format_: the header line, the main text, then attached YAML fields after `--`. */
+export function formatMessage(message) {
+    const { number, kind, target, text, ...attached } = messageFields(message);
+    const header = `[adoc message ${number}] ${kind}${target ? ` · ${target}` : ''}`;
+    const body = typeof text === 'string' && text ? `${text.replace(/\s+$/, '')}\n` : '';
+    const attachments = Object.keys(attached).length ? `--\n${stringify(attached, { lineWidth: 0, blockQuote: 'literal' })}` : '';
+    return `${header}\n${body}${attachments}`;
+}
+export function formatMessages(messages) {
+    return messages.map(formatMessage).join('\n');
+}
+/**
+ * Holds every _User_Message_ until it is delivered, in creation order.
+ * Emits `change` whenever the held set changes.
+ */
+export class MessageQueue extends EventEmitter {
+    next = 1;
+    held = [];
+    waiters = [];
+    add(input) {
+        const message = { ...input, number: this.next++, createdAt: new Date().toISOString() };
+        this.held.push(message);
+        this.emit('change');
+        this.emit('added', message);
+        for (const wake of this.waiters.splice(0))
+            wake();
+        return message;
+    }
+    list() {
+        return [...this.held];
+    }
+    /** Removes and returns every held message. */
+    takeAll() {
+        const taken = this.held;
+        this.held = [];
+        if (taken.length)
+            this.emit('change');
+        return taken;
+    }
+    /** Removes the given messages after a push transport delivered them. */
+    markDelivered(numbers) {
+        const before = this.held.length;
+        this.held = this.held.filter((m) => !numbers.includes(m.number));
+        if (this.held.length !== before)
+            this.emit('change');
+    }
+    /** Waits until at least one message is held, then takes all of them; resolves with [] after `timeoutMs`. */
+    async wait(timeoutMs, signal) {
+        if (this.held.length)
+            return this.takeAll();
+        return new Promise((resolve) => {
+            let timer;
+            const finish = () => {
+                clearTimeout(timer);
+                this.waiters = this.waiters.filter((w) => w !== wake);
+                signal?.removeEventListener('abort', abort);
+            };
+            const wake = () => {
+                finish();
+                resolve(this.takeAll());
+            };
+            const abort = () => {
+                finish();
+                resolve([]);
+            };
+            this.waiters.push(wake);
+            signal?.addEventListener('abort', abort);
+            if (timeoutMs !== undefined)
+                timer = setTimeout(abort, timeoutMs);
+        });
+    }
+}
+//# sourceMappingURL=messages.js.map

package/dist/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"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"}

package/dist/names.d.ts

@@ -0,0 +1,14 @@
+/** _Plugin_Key_: uppercase letters only. */
+export declare const PLUGIN_KEY_PATTERN: RegExp;
+/** _Document_Local_ID_: lowercase letters, digits, hyphens, underscores and dots. */
+export declare const LOCAL_ID_PATTERN: RegExp;
+/** A file or folder name that starts like a _Document_Key_. */
+export declare const KEY_PREFIX_PATTERN: RegExp;
+export interface ParsedTarget {
+    key: string;
+    pluginKey: string;
+    localId: string;
+    anchor?: string;
+}
+/** Parses `TASK-1231` or `TASK-1231#method`. Returns undefined when the text is not a document key. */
+export declare function parseDocumentTarget(text: string): ParsedTarget | undefined;

package/dist/names.js

@@ -0,0 +1,19 @@
+/** _Plugin_Key_: uppercase letters only. */
+export const PLUGIN_KEY_PATTERN = /^[A-Z]+$/;
+/** _Document_Local_ID_: lowercase letters, digits, hyphens, underscores and dots. */
+export const LOCAL_ID_PATTERN = /^[a-z0-9._-]+$/;
+/** A file or folder name that starts like a _Document_Key_. */
+export const KEY_PREFIX_PATTERN = /^([A-Z]+)-(.+)$/;
+/** Parses `TASK-1231` or `TASK-1231#method`. Returns undefined when the text is not a document key. */
+export function parseDocumentTarget(text) {
+    const hash = text.indexOf('#');
+    const key = hash < 0 ? text : text.slice(0, hash);
+    const match = KEY_PREFIX_PATTERN.exec(key);
+    if (!match || !LOCAL_ID_PATTERN.test(match[2]))
+        return undefined;
+    const parsed = { key, pluginKey: match[1], localId: match[2] };
+    if (hash >= 0)
+        parsed.anchor = text.slice(hash + 1);
+    return parsed;
+}
+//# sourceMappingURL=names.js.map

package/dist/names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"names.js","sourceRoot":"","sources":["../src/names.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,MAAM,CAAC,MAAM,kBAAkB,GAAG,UAAU,CAAC;AAC7C,qFAAqF;AACrF,MAAM,CAAC,MAAM,gBAAgB,GAAG,gBAAgB,CAAC;AACjD,+DAA+D;AAC/D,MAAM,CAAC,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AASpD,uGAAuG;AACvG,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/B,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IAClD,MAAM,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC3C,IAAI,CAAC,KAAK,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC;QAAE,OAAO,SAAS,CAAC;IAClE,MAAM,MAAM,GAAiB,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC,CAAE,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC,CAAE,EAAE,CAAC;IAC/E,IAAI,IAAI,IAAI,CAAC;QAAE,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;IACpD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/plugins.d.ts

@@ -0,0 +1,43 @@
+import type { PluginDefinition } from '@agent-workshop/adoc-plugin-kit';
+import type { AdocConfig, DeclaredPlugin } from './config.js';
+import type { AdocHome } from './home.js';
+/** Project scope: inside the _Adoc_Workspace_; user scope: anywhere else, such as the user _Plugin_Directory_ or adoc's installation. */
+export type Scope = 'project' | 'user';
+/** An _Agent_Skill_ folder: `skill/` with a `SKILL.md` whose front matter names it. */
+export interface SkillSource {
+    readonly name: string;
+    readonly description: string;
+    readonly directory: string;
+    readonly scope: Scope;
+}
+/** One declared _Plugin_, loaded or failed. */
+export interface LoadedPlugin {
+    readonly key: string;
+    /** The _Plugin_Source_ as declared. */
+    readonly source: string;
+    /** The plugin folder, when its entry was found. */
+    readonly directory?: string;
+    readonly definition?: PluginDefinition;
+    /** The _Plugin_Skill_. */
+    readonly skill?: SkillSource;
+    readonly error?: string;
+}
+/** The _Plugin_Directory_ next to the config file whose folder is `base`. */
+export declare function pluginDirectory(base: string): string;
+/** A parsed GitHub _Plugin_Source_. */
+export interface GithubSource {
+    readonly owner: string;
+    readonly repo: string;
+    /** The folder inside the repository; empty for its root. */
+    readonly folder: string;
+    readonly ref?: string;
+}
+/** `github:<owner>/<repo>[/<folder>][#<ref>]`, or undefined for any other source. */
+export declare function parseGithubSource(source: string): GithubSource | undefined;
+/** The folder a GitHub _Plugin_Source_ is fetched to: the plugin key in lowercase, in the _Plugin_Directory_. */
+export declare function fetchedFolder(plugin: DeclaredPlugin): string;
+export declare function scopeOf(home: AdocHome, path: string): Scope;
+/** Reads the `skill/SKILL.md` of an owner folder; throws when it is missing or has no name and description. */
+export declare function readSkillSource(owner: string, scope: Scope): Promise<SkillSource>;
+/** Loads every plugin declared in the _Adoc_Config_. A failure is kept as the plugin's error, never thrown. */
+export declare function loadPlugins(home: AdocHome, config: AdocConfig, fresh?: boolean): Promise<Map<string, LoadedPlugin>>;