@decibelsystems/tools 2.2.0-beta.0 → 3.0.0

package/dist/tools/postoffice/index.js

@@ -0,0 +1,218 @@
+// ============================================================================
+// Post Office Tools — EPIC-0037
+// ============================================================================
+// Seven verbs, one per tool. The surface is deliberately exactly the far side's
+// surface: an eighth verb is a contract change across two repos, so there is no
+// convenience action here that composes several.
+// ============================================================================
+import { toolSuccess, toolError, requireFields } from '../shared/index.js';
+import { agentsList, threadsOpen, messagesSend, messagesRead, messagesAck, handoffRequest, handoffRespond, isPostOfficeError, } from '../postoffice.js';
+/**
+ * Post office failures carry a code and usually a hint that names the fix.
+ * Flattening them into a bare message would discard the actionable half — an
+ * unconfigured credential and a revoked one need different responses.
+ */
+function settle(result) {
+    if (isPostOfficeError(result)) {
+        return toolError(JSON.stringify({ error: result.error, code: result.code, hint: result.hint }));
+    }
+    return toolSuccess(result);
+}
+export const postOfficeAgentsListTool = {
+    definition: {
+        name: 'postoffice_agents_list',
+        description: 'List agents reachable through AgentHQ, with live presence. A view over presence, not a second roster.',
+        annotations: { title: 'List Agents', readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+        inputSchema: { type: 'object', properties: {} },
+    },
+    handler: async () => {
+        try {
+            return settle(await agentsList());
+        }
+        catch (err) {
+            return toolError(err instanceof Error ? err.message : String(err));
+        }
+    },
+};
+export const postOfficeThreadsOpenTool = {
+    definition: {
+        name: 'postoffice_threads_open',
+        description: 'Open a conversation thread. A thread is the unit a handoff happens inside — open one before sending.',
+        annotations: { title: 'Open Thread', readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                subject: { type: 'string', description: 'What the thread is about. Required.' },
+                project: { type: 'string', description: 'Optional HQ project UUID (not a Decibel project slug — hq.agent_threads.project_id is a uuid). Omit unless you hold the uuid.' },
+                intent: { type: 'string', description: 'Optional free-text intent for the thread as a whole.' },
+            },
+            required: ['subject'],
+        },
+    },
+    handler: async (args) => {
+        try {
+            requireFields(args, 'subject');
+            return settle(await threadsOpen(args));
+        }
+        catch (err) {
+            return toolError(err instanceof Error ? err.message : String(err));
+        }
+    },
+};
+export const postOfficeMessagesSendTool = {
+    definition: {
+        name: 'postoffice_messages_send',
+        description: 'Send a message to another agent inside a thread. The recipient is addressed by agent name or id; the sender is taken from the credential and cannot be spoofed.',
+        annotations: { title: 'Send Message', readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                to: { type: 'string', description: 'Recipient agent name or uuid, in your org.' },
+                thread: { type: 'string', description: 'Thread id from postoffice_threads_open.' },
+                summary: { type: 'string', description: 'The message. Max 2048 characters.' },
+                intent: {
+                    type: 'string',
+                    enum: ['inform', 'request', 'respond'],
+                    description: 'Why you are writing. Defaults to inform. Handoff intents are set by the handoff tools.',
+                },
+                context_refs: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Up to 32 references (issue ids, file paths, URLs) the recipient will need.',
+                },
+                request: { type: 'string', description: 'What you are asking for, when intent is request.' },
+                expected_output: { type: 'string', description: 'What a good answer looks like. Max 1024 characters.' },
+            },
+            required: ['to', 'thread', 'summary'],
+        },
+    },
+    handler: async (args) => {
+        try {
+            requireFields(args, 'to', 'thread', 'summary');
+            return settle(await messagesSend(args));
+        }
+        catch (err) {
+            return toolError(err instanceof Error ? err.message : String(err));
+        }
+    },
+};
+export const postOfficeMessagesReadTool = {
+    definition: {
+        name: 'postoffice_messages_read',
+        description: 'Read your mail. Reading does NOT acknowledge — ack separately with postoffice_messages_ack once you have acted. Do not poll with status="sent": reading marks sent->read, so that filter cannot return a message twice and a reader that dies before acting loses it silently. Leave status unset to see everything still addressed to you.',
+        annotations: { title: 'Read Messages', readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                thread: { type: 'string', description: 'Optional: restrict to one thread.' },
+                status: {
+                    type: 'string',
+                    enum: ['sent', 'read', 'acked', 'failed'],
+                    description: 'Optional exact-status filter. Omit when polling — see the tool description.',
+                },
+                limit: { type: 'number', description: 'Max messages to return. Default 25, capped at 100.' },
+            },
+        },
+    },
+    handler: async (args) => {
+        try {
+            return settle(await messagesRead((args ?? {})));
+        }
+        catch (err) {
+            return toolError(err instanceof Error ? err.message : String(err));
+        }
+    },
+};
+export const postOfficeMessagesAckTool = {
+    definition: {
+        name: 'postoffice_messages_ack',
+        description: 'Acknowledge a message: "I have this and I am acting on it." Separate from reading on purpose. Acking twice is not an error and does not change status, but it currently REWRITES acked_at to the later time — so a retry moves the recorded acknowledgement time. Only the recipient can ack.',
+        // idempotentHint is FALSE deliberately, and it is not a mistake that the
+        // description says acking twice is safe. Status is idempotent; acked_at is
+        // not — a double ack measured 0.959s of drift against the live service on
+        // 2026-08-31, and the drift always moves the timestamp LATER, which flatters
+        // any ack-latency measure. A retry-on-timeout is exactly when a client acks
+        // twice and exactly when the first ack probably landed, so the error
+        // correlates with slow calls and hides them.
+        //
+        // Claiming idempotent here would tell a client that retrying is free. It is
+        // free for delivery and not free for the record. HQ owns the fix
+        // (coalesce(acked_at, now()) server-side); when it lands this flips back to
+        // true and this comment explains why it ever moved.
+        annotations: { title: 'Ack Message', readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+        inputSchema: {
+            type: 'object',
+            properties: { message: { type: 'string', description: 'Message id to acknowledge.' } },
+            required: ['message'],
+        },
+    },
+    handler: async (args) => {
+        try {
+            requireFields(args, 'message');
+            return settle(await messagesAck(args));
+        }
+        catch (err) {
+            return toolError(err instanceof Error ? err.message : String(err));
+        }
+    },
+};
+export const postOfficeHandoffRequestTool = {
+    definition: {
+        name: 'postoffice_handoff_request',
+        description: 'Ask another agent to take over a thread. Writes a handoff_request message so the handoff is legible in the thread it happened in, rather than in a side table.',
+        annotations: { title: 'Request Handoff', readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                thread: { type: 'string', description: 'Thread to hand over.' },
+                to: { type: 'string', description: 'Agent to hand it to, by name or uuid.' },
+                summary: { type: 'string', description: 'What you are handing over and what state it is in.' },
+            },
+            required: ['thread'],
+        },
+    },
+    handler: async (args) => {
+        try {
+            requireFields(args, 'thread');
+            return settle(await handoffRequest(args));
+        }
+        catch (err) {
+            return toolError(err instanceof Error ? err.message : String(err));
+        }
+    },
+};
+export const postOfficeHandoffRespondTool = {
+    definition: {
+        name: 'postoffice_handoff_respond',
+        description: 'Accept or decline a handoff you were offered. Writes a handoff_respond message into the same thread.',
+        annotations: { title: 'Respond to Handoff', readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                thread: { type: 'string', description: 'Thread the handoff was offered in.' },
+                accept: { type: 'boolean', description: 'true to take it, false to decline.' },
+                summary: { type: 'string', description: 'Optional note explaining the decision.' },
+            },
+            required: ['thread', 'accept'],
+        },
+    },
+    handler: async (args) => {
+        try {
+            requireFields(args, 'thread', 'accept');
+            return settle(await handoffRespond(args));
+        }
+        catch (err) {
+            return toolError(err instanceof Error ? err.message : String(err));
+        }
+    },
+};
+export const postOfficeTools = [
+    postOfficeAgentsListTool,
+    postOfficeThreadsOpenTool,
+    postOfficeMessagesSendTool,
+    postOfficeMessagesReadTool,
+    postOfficeMessagesAckTool,
+    postOfficeHandoffRequestTool,
+    postOfficeHandoffRespondTool,
+];
+//# sourceMappingURL=index.js.map

package/dist/tools/postoffice/index.js.map

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

package/dist/tools/postoffice.d.ts

@@ -0,0 +1,78 @@
+/** The seven verbs the far side implements. An eighth is a two-repo change. */
+export type PostOfficeVerb = 'agents.list' | 'threads.open' | 'messages.send' | 'messages.read' | 'messages.ack' | 'handoff.request' | 'handoff.respond';
+export interface PostOfficeError {
+    error: string;
+    code: 'HQ_NOT_CONFIGURED' | 'HQ_UNAUTHORIZED' | 'HQ_FORBIDDEN' | 'HQ_NOT_FOUND' | 'HQ_REJECTED' | 'HQ_UNAVAILABLE';
+    hint?: string;
+}
+export declare function isPostOfficeError(v: unknown): v is PostOfficeError;
+/**
+ * One request to the post office.
+ *
+ * Every failure is mapped to something a caller can act on. The far side is
+ * deliberate about its status codes — 403 names the scope it wanted, 404
+ * distinguishes an unknown recipient from an unknown thread — and flattening
+ * those into "request failed" would discard the part that tells you what to fix.
+ */
+export declare function postOfficeCall(verb: PostOfficeVerb, payload?: Record<string, unknown>): Promise<Record<string, unknown> | PostOfficeError>;
+export declare function agentsList(): Promise<Record<string, unknown> | PostOfficeError>;
+export interface ThreadsOpenInput {
+    subject: string;
+    /**
+     * HQ project UUID, NOT a Decibel project slug. hq.agent_threads.project_id is
+     * a uuid referencing hq.projects, so passing 'decibel-tools-mcp' is rejected
+     * by Postgres rather than resolved. There is no lookup verb in the seven, so
+     * a caller that does not already hold the uuid should omit this.
+     */
+    project?: string;
+    intent?: string;
+}
+export declare function threadsOpen(input: ThreadsOpenInput): Promise<Record<string, unknown> | PostOfficeError>;
+export interface MessagesSendInput {
+    to: string;
+    thread: string;
+    summary: string;
+    intent?: 'inform' | 'request' | 'respond';
+    context_refs?: string[];
+    request?: string;
+    expected_output?: string;
+}
+export declare function messagesSend(input: MessagesSendInput): Promise<Record<string, unknown> | PostOfficeError>;
+export interface MessagesReadInput {
+    thread?: string;
+    status?: string;
+    limit?: number;
+}
+/**
+ * Read this agent's mail.
+ *
+ * `status` is deliberately NOT defaulted, and polling must not set it to
+ * 'sent'. The far side marks sent -> read as a side effect of reading, so a
+ * mailbox query filtered to status='sent' never returns a message twice: a
+ * reader that fetches and then dies before acting has silently consumed it,
+ * and no restart recovers it. Unfiltered, the same message comes back as
+ * 'read' and can still be acted on.
+ *
+ * That is the whole reason read and ack are separate verbs — at-least-once
+ * beats at-most-once here, because a duplicated message costs a minute and a
+ * dropped handoff stalls work invisibly.
+ */
+export declare function messagesRead(input?: MessagesReadInput): Promise<Record<string, unknown> | PostOfficeError>;
+export interface MessagesAckInput {
+    message: string;
+}
+/** Idempotent by construction on the far side: acking twice is not an error. */
+export declare function messagesAck(input: MessagesAckInput): Promise<Record<string, unknown> | PostOfficeError>;
+export interface HandoffRequestInput {
+    thread: string;
+    to?: string;
+    summary?: string;
+}
+export declare function handoffRequest(input: HandoffRequestInput): Promise<Record<string, unknown> | PostOfficeError>;
+export interface HandoffRespondInput {
+    thread: string;
+    accept: boolean;
+    summary?: string;
+}
+export declare function handoffRespond(input: HandoffRespondInput): Promise<Record<string, unknown> | PostOfficeError>;
+//# sourceMappingURL=postoffice.d.ts.map

package/dist/tools/postoffice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postoffice.d.ts","sourceRoot":"","sources":["../../src/tools/postoffice.ts"],"names":[],"mappings":"AAiCA,+EAA+E;AAC/E,MAAM,MAAM,cAAc,GACtB,aAAa,GACb,cAAc,GACd,eAAe,GACf,eAAe,GACf,cAAc,GACd,iBAAiB,GACjB,iBAAiB,CAAC;AAEtB,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EACA,mBAAmB,GACnB,iBAAiB,GACjB,cAAc,GACd,cAAc,GACd,aAAa,GACb,gBAAgB,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,eAAe,CAElE;AA+BD;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,cAAc,EACpB,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACpC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,eAAe,CAAC,CAqFpD;AAMD,wBAAgB,UAAU,uDAEzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AACD,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,sDAMlD;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;IAC1C,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AACD,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,sDAEpD;AAED,MAAM,WAAW,iBAAiB;IAAG,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CAAE;AACxF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,KAAK,GAAE,iBAAsB,sDAMzD;AAED,MAAM,WAAW,gBAAgB;IAAG,OAAO,EAAE,MAAM,CAAC;CAAE;AACtD,gFAAgF;AAChF,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,sDAElD;AAED,MAAM,WAAW,mBAAmB;IAAG,MAAM,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAAE;AACvF,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,sDAExD;AAED,MAAM,WAAW,mBAAmB;IAAG,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAAE;AAC3F,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,sDAExD"}

package/dist/tools/postoffice.js

@@ -0,0 +1,199 @@
+// ============================================================================
+// Post Office — the client half of EPIC-0037
+// ============================================================================
+// AgentHQ runs the post office: hq.agent_threads / hq.agent_messages behind an
+// edge function that speaks seven verbs over a bearer credential. ChatGPT could
+// already authenticate and write into a thread; Claude Code could not read or
+// ack, which is the only thing that stood between here and a round trip.
+//
+// This module is a transport, not a second model. It does not cache messages,
+// does not maintain its own inbox, and does not decide delivery — the runtime
+// on the other side owns all of that. Everything here maps one facade action to
+// one verb and surfaces what came back.
+//
+// THE CREDENTIAL IS NEVER LOGGED. It is read from the environment or
+// ~/.decibel/config.yaml and used only as an Authorization header. It is not a
+// tool argument, so it never reaches ~/.decibel/logs/dispatch.jsonl, which is
+// written to disk in plaintext. Nothing here may put it in an error message
+// either: an access token lasts an hour and a refresh token thirty days, so a
+// leak into a rotated log file is not a momentary exposure.
+// ============================================================================
+import { log } from '../config.js';
+import { loadConfig } from '../daemonConfig.js';
+/**
+ * Default origin. NOT hq.decibelsystems.com — that host has no DNS at all
+ * (verified 2026-08-30, unresolvable). Pointing at it fails closed with a
+ * DNS error rather than anything a caller can act on.
+ */
+const DEFAULT_HQ_URL = 'https://home.theagenthq.app';
+const POST_OFFICE_PATH = '/agents/mcp';
+const REQUEST_TIMEOUT_MS = 15_000;
+export function isPostOfficeError(v) {
+    return typeof v === 'object' && v !== null && 'code' in v && 'error' in v;
+}
+/**
+ * Resolve the endpoint and credential.
+ *
+ * Env wins over config so a session can point at a staging HQ without editing
+ * a file that other processes read. Returns an error rather than throwing,
+ * because "you have not set this up yet" is a normal state for most projects
+ * and should read as instructions, not as a stack trace.
+ */
+function resolveCredential() {
+    const cfg = loadConfig();
+    const url = (process.env.DECIBEL_HQ_URL || cfg.hq?.url || DEFAULT_HQ_URL).replace(/\/+$/, '');
+    const token = process.env.DECIBEL_HQ_TOKEN || cfg.hq?.token;
+    if (!token) {
+        return {
+            error: 'No AgentHQ credential is configured, so this agent cannot reach the post office.',
+            code: 'HQ_NOT_CONFIGURED',
+            hint: 'A credential is issued once and never recoverable. An org admin runs ' +
+                "hq.issue_agent_token(p_org, p_agent_name, ...) and it returns the raw token exactly once. " +
+                'Then set DECIBEL_HQ_TOKEN, or add hq.token to ~/.decibel/config.yaml. ' +
+                `Endpoint currently resolves to ${url}${POST_OFFICE_PATH}.`,
+        };
+    }
+    return { url, token };
+}
+/**
+ * One request to the post office.
+ *
+ * Every failure is mapped to something a caller can act on. The far side is
+ * deliberate about its status codes — 403 names the scope it wanted, 404
+ * distinguishes an unknown recipient from an unknown thread — and flattening
+ * those into "request failed" would discard the part that tells you what to fix.
+ */
+export async function postOfficeCall(verb, payload = {}) {
+    const cred = resolveCredential();
+    if (isPostOfficeError(cred))
+        return cred;
+    const endpoint = `${cred.url}${POST_OFFICE_PATH}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    let res;
+    try {
+        res = await fetch(endpoint, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                // The only place the credential appears. Not logged, not echoed.
+                Authorization: `Bearer ${cred.token}`,
+            },
+            body: JSON.stringify({ verb, ...payload }),
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return {
+            error: `Could not reach the post office at ${endpoint}: ${detail}`,
+            code: 'HQ_UNAVAILABLE',
+            hint: 'Check the host resolves and is reachable. Note hq.decibelsystems.com has no DNS — ' +
+                `the working origin is ${DEFAULT_HQ_URL}.`,
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    const text = await res.text();
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        return {
+            error: `Post office returned ${res.status} with a non-JSON body: ${text.slice(0, 200)}`,
+            code: 'HQ_UNAVAILABLE',
+        };
+    }
+    if (res.ok) {
+        log(`PostOffice: ${verb} ok`);
+        return body;
+    }
+    // The far side attaches `detail` to rejections that came from Postgres —
+    // a CHECK bound, a type mismatch, a missing FK. That detail IS the
+    // actionable half: "thread_rejected" says nothing, while
+    // 'invalid input syntax for type uuid: "decibel-tools-mcp"' says exactly
+    // what to pass instead. Dropping it was the first thing that cost a
+    // round-trip attempt to diagnose.
+    const base = typeof body.error === 'string' ? body.error : `HTTP ${res.status}`;
+    const detail = typeof body.detail === 'string' ? body.detail : undefined;
+    const message = detail ? `${base}: ${detail}` : base;
+    if (res.status === 401) {
+        return {
+            error: `The post office rejected this agent's credential: ${message}`,
+            code: 'HQ_UNAUTHORIZED',
+            hint: 'The token is wrong, revoked, or expired. Tokens are stored as a sha256 and cannot be ' +
+                'recovered — issue a new one with hq.issue_agent_token and replace DECIBEL_HQ_TOKEN.',
+        };
+    }
+    if (res.status === 403) {
+        const required = typeof body.required === 'string' ? body.required : 'a scope';
+        return {
+            error: `This credential lacks ${required}.`,
+            code: 'HQ_FORBIDDEN',
+            hint: 'Reads need postoffice.read and writes need postoffice.write. Re-issue with the scope.',
+        };
+    }
+    if (res.status === 404) {
+        return { error: message, code: 'HQ_NOT_FOUND' };
+    }
+    if (res.status === 400) {
+        const supported = Array.isArray(body.supported)
+            ? ` Supported verbs: ${body.supported.join(', ')}.`
+            : '';
+        return { error: `${message}${supported}`, code: 'HQ_REJECTED' };
+    }
+    return { error: `Post office error (${res.status}): ${message}`, code: 'HQ_UNAVAILABLE' };
+}
+// ============================================================================
+// Verbs
+// ============================================================================
+export function agentsList() {
+    return postOfficeCall('agents.list');
+}
+export function threadsOpen(input) {
+    return postOfficeCall('threads.open', {
+        subject: input.subject,
+        project: input.project,
+        intent: input.intent,
+    });
+}
+export function messagesSend(input) {
+    return postOfficeCall('messages.send', { ...input });
+}
+/**
+ * Read this agent's mail.
+ *
+ * `status` is deliberately NOT defaulted, and polling must not set it to
+ * 'sent'. The far side marks sent -> read as a side effect of reading, so a
+ * mailbox query filtered to status='sent' never returns a message twice: a
+ * reader that fetches and then dies before acting has silently consumed it,
+ * and no restart recovers it. Unfiltered, the same message comes back as
+ * 'read' and can still be acted on.
+ *
+ * That is the whole reason read and ack are separate verbs — at-least-once
+ * beats at-most-once here, because a duplicated message costs a minute and a
+ * dropped handoff stalls work invisibly.
+ */
+export function messagesRead(input = {}) {
+    const payload = {};
+    if (input.thread)
+        payload.thread = input.thread;
+    if (input.status)
+        payload.status = input.status;
+    if (input.limit)
+        payload.limit = input.limit;
+    return postOfficeCall('messages.read', payload);
+}
+/** Idempotent by construction on the far side: acking twice is not an error. */
+export function messagesAck(input) {
+    return postOfficeCall('messages.ack', { message: input.message });
+}
+export function handoffRequest(input) {
+    return postOfficeCall('handoff.request', { ...input });
+}
+export function handoffRespond(input) {
+    return postOfficeCall('handoff.respond', { ...input });
+}
+//# sourceMappingURL=postoffice.js.map

package/dist/tools/postoffice.js.map

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

package/dist/tools/provenance.d.ts

@@ -31,6 +31,13 @@ export interface ListProvenanceInput {
 export interface ListProvenanceOutput {
     events: ProvenanceEvent[];
     total_count: number;
+    /**
+     * Records that could not be read or parsed and are therefore absent from
+     * `events`. Zero on a healthy store. Present so that a short list is
+     * detectable — an empty result with unreadable_count > 0 means "could not
+     * read", which is a different fact from "no activity".
+     */
+    unreadable_count: number;
 }
 export interface ProjectResolutionError {
     error: 'project_resolution_failed';

package/dist/tools/provenance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provenance.d.ts","sourceRoot":"","sources":["../../src/tools/provenance.ts"],"names":[],"mappings":"AAaA,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,IAAI,GAAG,QAAQ,CAAC;AAClD,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AACjH,MAAM,MAAM,UAAU,GAClB,kBAAkB,GAClB,YAAY,GACZ,YAAY,GACZ,eAAe,GACf,gBAAgB,GAChB,YAAY,GACZ,WAAW,GACX,SAAS,CAAC;AAEd,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,CAAC;IACtB,MAAM,EAAE,gBAAgB,CAAC;IACzB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,EAAE,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,gBAAgB,CAAC;IACzB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,EAAE,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,2BAA2B,CAAC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAeD;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAMxC;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGnD;AAsBD;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAc1C;AAgDD;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,mBAAmB,EAC1B,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,GAAG,sBAAsB,CAAC,CAyC1C;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,oBAAoB,GAAG,sBAAsB,CAAC,CA+CxD;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,GAAG,sBAAsB,CAAC,CAgB1C"}
+{"version":3,"file":"provenance.d.ts","sourceRoot":"","sources":["../../src/tools/provenance.ts"],"names":[],"mappings":"AAaA,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,IAAI,GAAG,QAAQ,CAAC;AAClD,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AACjH,MAAM,MAAM,UAAU,GAClB,kBAAkB,GAClB,YAAY,GACZ,YAAY,GACZ,eAAe,GACf,gBAAgB,GAChB,YAAY,GACZ,WAAW,GACX,SAAS,CAAC;AAEd,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,CAAC;IACtB,MAAM,EAAE,gBAAgB,CAAC;IACzB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,EAAE,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,gBAAgB,CAAC;IACzB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,EAAE,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,2BAA2B,CAAC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAeD;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAMxC;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGnD;AAsBD;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAc1C;AAgDD;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,mBAAmB,EAC1B,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,GAAG,sBAAsB,CAAC,CAyC1C;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,oBAAoB,GAAG,sBAAsB,CAAC,CA0ExD;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,GAAG,sBAAsB,CAAC,CAgB1C"}

package/dist/tools/provenance.js

@@ -173,26 +173,51 @@ export async function listProvenance(input) {
     const eventsDir = resolved.subPath('provenance', 'events');
     const limit = input.limit || 50;
     let events = [];
+    // A missing directory means "no events yet" and is the only failure that may
+    // be reported as emptiness. Anything else — EMFILE under a fan-out, EACCES, a
+    // bad mount — must reach the caller: this used to be a bare catch around both
+    // the readdir AND the read loop, so any of those returned `{events: [],
+    // total_count: 0}` through a SUCCESS envelope, indistinguishable from a
+    // project with no activity. HQ measured ten of thirty-four projects reporting
+    // empty that demonstrably had events (2026-08-30).
+    let yamlFiles;
     try {
         const files = await fs.readdir(eventsDir);
-        const yamlFiles = files.filter(f => f.endsWith('.yml') && f.startsWith('PROV-'));
-        for (const file of yamlFiles) {
-            const filePath = path.join(eventsDir, file);
-            const event = await parseProvenanceFile(filePath);
-            if (!event)
-                continue;
-            // Apply filters
-            if (input.artifact_ref && !event.artifact_refs.includes(input.artifact_ref)) {
-                continue;
-            }
-            if (input.actor_id && event.actor_id !== input.actor_id) {
-                continue;
-            }
-            events.push(event);
+        yamlFiles = files.filter(f => f.endsWith('.yml') && f.startsWith('PROV-'));
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            return { events: [], total_count: 0, unreadable_count: 0 };
         }
+        throw err;
     }
-    catch {
-        // Directory doesn't exist yet
+    // Per-file failures do not abort the listing — one corrupt record should not
+    // hide the other ninety-nine — but they are counted, because a silently short
+    // list is a lie a caller cannot detect. `parseProvenanceFile` also returns
+    // null for a record missing required fields; that is the same loss.
+    let unreadable = 0;
+    for (const file of yamlFiles) {
+        const filePath = path.join(eventsDir, file);
+        let event;
+        try {
+            event = await parseProvenanceFile(filePath);
+        }
+        catch {
+            unreadable++;
+            continue;
+        }
+        if (!event) {
+            unreadable++;
+            continue;
+        }
+        // Apply filters
+        if (input.artifact_ref && !event.artifact_refs.includes(input.artifact_ref)) {
+            continue;
+        }
+        if (input.actor_id && event.actor_id !== input.actor_id) {
+            continue;
+        }
+        events.push(event);
     }
     const totalCount = events.length;
     // Sort by timestamp descending (newest first)
@@ -202,6 +227,7 @@ export async function listProvenance(input) {
     return {
         events,
         total_count: totalCount,
+        unreadable_count: unreadable,
     };
 }
 /**