@getfamiliar/shared 0.1.2

package/build/HandlerCatalog.js

@@ -0,0 +1,165 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { matchesAnyGlob } from "./PathGlob.js";
+/**
+ * Workspace files at the very top level that are not handlers and
+ * must be filtered out of {@link HandlerCatalog.list}. These are the
+ * documents read by `buildSystemPrompt` rather than executed as
+ * handlers (see `CLAUDE.md` — markdown layers / global context).
+ */
+const RESERVED_ROOT_FILES = new Set(["SOUL.md", "CONTEXT.md"]);
+/**
+ * Workspace subtrees that contain markdown but never handlers.
+ * `skills/<name>/SKILL.md` is a shared recipe loaded via `fs_read`,
+ * not an agent entry point.
+ */
+const RESERVED_TOP_DIRS = new Set(["skills"]);
+/**
+ * Read-only view over the `workspace/` directory's handler files.
+ *
+ * Mirrors the resolution semantics implemented by
+ * `container/src/HandlerFile.ts` so host-side code (CLI, cron
+ * scheduler introspection, tab-completion) can answer "does this
+ * handler exist?" and "list every handler" without depending on
+ * container internals or reimplementing the topic-walk inheritance.
+ *
+ * The catalog is stateless on the disk — every method re-scans —
+ * so live workspace edits are reflected without a daemon restart.
+ * At REPL frequencies this is cheap; if a hot path later needs
+ * caching it can wrap an instance.
+ */
+export class HandlerCatalog {
+    workspaceDir;
+    writablePathGlobs;
+    /**
+     * @param workspaceDir Absolute path of the `workspace/` directory.
+     * @param writablePathGlobs `core.writablePaths` globs (e.g. `wiki/**`).
+     *   Files under these are writable by non-privileged runs and are
+     *   therefore never handlers — they are excluded from {@link list}
+     *   and {@link resolve} so they are never proposed or resolved as a
+     *   handler. Mirrors the container's `HandlerFile.load` guard.
+     */
+    constructor(workspaceDir, writablePathGlobs = []) {
+        this.workspaceDir = workspaceDir;
+        this.writablePathGlobs = writablePathGlobs;
+    }
+    /**
+     * Walk `workspace/` and return one {@link HandlerPath} per
+     * candidate handler file. Excludes the global-context files at
+     * the workspace root (`SOUL.md`, `CONTEXT.md`)
+     * and the `skills/` subtree. Every other `.md` file under a topic
+     * directory is included, even if it's a knowledge file (e.g.
+     * `people/anna.md`) — `HandlerCatalog` does not police what is or
+     * isn't a "proper" handler; that's a handler-loading concern.
+     *
+     * Sorted by `slashPath` for stable display ordering in
+     * tab-completion. Returns an empty array when the workspace
+     * directory does not exist.
+     */
+    async list() {
+        const exists = await directoryExists(this.workspaceDir);
+        if (!exists) {
+            return [];
+        }
+        const results = [];
+        await walkMarkdown(this.workspaceDir, [], results, this.workspaceDir, this.writablePathGlobs);
+        results.sort((a, b) => a.slashPath.localeCompare(b.slashPath));
+        return results;
+    }
+    /**
+     * Resolve a handler call: given a topic (e.g. `chat:telegram`)
+     * and a basename (e.g. `index`), return the absolute path of the
+     * deepest existing handler file, mirroring the container's
+     * inheritance walk.
+     *
+     * For topic `a:b:c` and basename `x` the resolution tries, in
+     * order: `a/b/c/x.md`, `a/b/x.md`, `a/x.md`. Returns the first
+     * existing path or `null` if none exist. The deepest existing
+     * file is what `HandlerFile.load` would treat as the leaf — for
+     * cli-chat existence checks, that's exactly the question we
+     * want answered.
+     */
+    async resolve(topic, handler) {
+        const segments = topic.split(":");
+        for (let depth = segments.length; depth >= 1; depth--) {
+            const rel = path.join(...segments.slice(0, depth), `${handler}.md`);
+            const relPosix = rel.split(path.sep).join("/");
+            const absolute = path.join(this.workspaceDir, rel);
+            if (await fileExists(absolute)) {
+                // A file under `core.writablePaths` is never a handler, even
+                // when it exists — mirror the container's `HandlerFile.load`
+                // guard so host-side callers agree it does not resolve.
+                if (matchesAnyGlob(this.writablePathGlobs, relPosix)) {
+                    return null;
+                }
+                return absolute;
+            }
+        }
+        return null;
+    }
+}
+/**
+ * Recursively walk `dir`, accumulating one {@link HandlerPath} per
+ * `.md` file. `segments` tracks the topic path from the workspace
+ * root; an empty array means we're at the root, where reserved files
+ * are skipped.
+ */
+async function walkMarkdown(dir, segments, out, workspaceDir, writablePathGlobs) {
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            if (segments.length === 0 && RESERVED_TOP_DIRS.has(entry.name)) {
+                continue;
+            }
+            await walkMarkdown(path.join(dir, entry.name), [...segments, entry.name], out, workspaceDir, writablePathGlobs);
+            continue;
+        }
+        if (!entry.isFile() || !entry.name.endsWith(".md")) {
+            continue;
+        }
+        if (segments.length === 0 && RESERVED_ROOT_FILES.has(entry.name)) {
+            continue;
+        }
+        if (segments.length === 0) {
+            // Stray `.md` at the workspace root with no topic folder —
+            // not a handler. Skip silently rather than reporting an
+            // empty topic.
+            continue;
+        }
+        const handlerBase = entry.name.slice(0, -".md".length);
+        const topic = segments.join(":");
+        const absolutePath = path.join(dir, entry.name);
+        const relativePath = path.relative(workspaceDir, absolutePath).split(path.sep).join("/");
+        // Files under `core.writablePaths` (e.g. `wiki/**`) are writable by
+        // non-privileged runs and are never handlers — never propose them.
+        if (matchesAnyGlob(writablePathGlobs, relativePath)) {
+            continue;
+        }
+        const slashPath = `/${[...segments, handlerBase].join("/")}`;
+        out.push({ topic, handler: handlerBase, absolutePath, relativePath, slashPath });
+    }
+}
+async function fileExists(absolute) {
+    try {
+        const stat = await fs.stat(absolute);
+        return stat.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function directoryExists(absolute) {
+    try {
+        const stat = await fs.stat(absolute);
+        return stat.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}

package/build/InferenceEvent.d.ts

@@ -0,0 +1,30 @@
+/**
+ * One model HTTP call outcome.
+ *
+ * - `success`  — the upstream returned a 2xx the runner accepted.
+ * - `retryable` — the upstream returned 408/429/5xx or otherwise signalled
+ *   transient failure; AgentRunner postponed the agentrun.
+ * - `fatal`    — non-retryable upstream error (auth, malformed request,
+ *   unknown model id) that immediately settled the agentrun as `failed`.
+ */
+export type InferenceOutcome = "success" | "retryable" | "fatal";
+/** Persisted shape of an `inference_events` row. */
+export interface InferenceEventRow {
+    readonly id: string;
+    readonly provider: string;
+    readonly model: string;
+    readonly agentRunId: string | null;
+    readonly outcome: InferenceOutcome;
+    readonly statusCode: number | null;
+    readonly errorExcerpt: string | null;
+    readonly occurredAt: Date;
+}
+/** Insert shape — `id` and `occurredAt` are filled by the DB. */
+export interface NewInferenceEvent {
+    readonly provider: string;
+    readonly model: string;
+    readonly agentRunId?: string | null;
+    readonly outcome: InferenceOutcome;
+    readonly statusCode?: number | null;
+    readonly errorExcerpt?: string | null;
+}

package/build/InferenceEvent.js

@@ -0,0 +1 @@
+export {};

package/build/InferenceEventBus.d.ts

@@ -0,0 +1,39 @@
+import type { InferenceEventRow, NewInferenceEvent } from "./InferenceEvent.js";
+import type { PostgresConnection } from "./PostgresConnection.js";
+/**
+ * Domain client for the `inference_events` table — every upstream model
+ * HTTP call AgentRunner attempted, classified into success / retryable /
+ * fatal. Append-only: there is no update or delete on this table outside
+ * the global retention sweep. Mirrors {@link import("./AgentRunBus.js").AgentRunBus}
+ * in its constructor + Pool access pattern; does not own connection
+ * lifecycle.
+ */
+export declare class InferenceEventBus {
+    private readonly connection;
+    constructor(connection: PostgresConnection);
+    /**
+     * Apply the bus-state schema (idempotent). Same SQL bundle every
+     * other bus client installs; calling any one is sufficient on
+     * daemon start.
+     */
+    installSchema(): Promise<void>;
+    /**
+     * Insert one inference event. Fire-and-forget from AgentRunner; any
+     * thrown error is the caller's responsibility to log — we don't want
+     * to mask a real model error with an audit-table write error.
+     */
+    add(row: NewInferenceEvent): Promise<void>;
+    /**
+     * Fetch every inference event with `occurred_at >= since`, optionally
+     * filtered to one model id. Ordered by `occurred_at DESC` so the
+     * reflection tool's "last successful call" lookup is the first hit.
+     */
+    listSince(since: Date, model?: string): Promise<readonly InferenceEventRow[]>;
+    /**
+     * Delete rows older than `cutoff`. Returns the number of rows
+     * removed. Run from the same retention pass that prunes daemon log
+     * files so the two retention policies stay aligned with
+     * `core.logRetentionDays`.
+     */
+    pruneBefore(cutoff: Date): Promise<number>;
+}

package/build/InferenceEventBus.js

@@ -0,0 +1,80 @@
+import { SCHEMA_SQL } from "./Schema.js";
+/**
+ * Domain client for the `inference_events` table — every upstream model
+ * HTTP call AgentRunner attempted, classified into success / retryable /
+ * fatal. Append-only: there is no update or delete on this table outside
+ * the global retention sweep. Mirrors {@link import("./AgentRunBus.js").AgentRunBus}
+ * in its constructor + Pool access pattern; does not own connection
+ * lifecycle.
+ */
+export class InferenceEventBus {
+    connection;
+    constructor(connection) {
+        this.connection = connection;
+    }
+    /**
+     * Apply the bus-state schema (idempotent). Same SQL bundle every
+     * other bus client installs; calling any one is sufficient on
+     * daemon start.
+     */
+    async installSchema() {
+        await this.connection.getPool().query(SCHEMA_SQL);
+    }
+    /**
+     * Insert one inference event. Fire-and-forget from AgentRunner; any
+     * thrown error is the caller's responsibility to log — we don't want
+     * to mask a real model error with an audit-table write error.
+     */
+    async add(row) {
+        await this.connection.getPool().query(`INSERT INTO inference_events
+                (provider, model, agent_run_id, outcome, status_code, error_excerpt)
+             VALUES ($1, $2, $3, $4, $5, $6)`, [
+            row.provider,
+            row.model,
+            row.agentRunId ?? null,
+            row.outcome,
+            row.statusCode ?? null,
+            row.errorExcerpt ?? null,
+        ]);
+    }
+    /**
+     * Fetch every inference event with `occurred_at >= since`, optionally
+     * filtered to one model id. Ordered by `occurred_at DESC` so the
+     * reflection tool's "last successful call" lookup is the first hit.
+     */
+    async listSince(since, model) {
+        const pool = this.connection.getPool();
+        const result = model === undefined
+            ? await pool.query(`SELECT * FROM inference_events
+                       WHERE occurred_at >= $1
+                       ORDER BY occurred_at DESC`, [since])
+            : await pool.query(`SELECT * FROM inference_events
+                       WHERE occurred_at >= $1 AND model = $2
+                       ORDER BY occurred_at DESC`, [since, model]);
+        return result.rows.map(mapRow);
+    }
+    /**
+     * Delete rows older than `cutoff`. Returns the number of rows
+     * removed. Run from the same retention pass that prunes daemon log
+     * files so the two retention policies stay aligned with
+     * `core.logRetentionDays`.
+     */
+    async pruneBefore(cutoff) {
+        const result = await this.connection
+            .getPool()
+            .query(`DELETE FROM inference_events WHERE occurred_at < $1`, [cutoff]);
+        return result.rowCount ?? 0;
+    }
+}
+function mapRow(raw) {
+    return {
+        id: raw.id,
+        provider: raw.provider,
+        model: raw.model,
+        agentRunId: raw.agent_run_id,
+        outcome: raw.outcome,
+        statusCode: raw.status_code,
+        errorExcerpt: raw.error_excerpt,
+        occurredAt: raw.occurred_at,
+    };
+}

package/build/Mail.d.ts

@@ -0,0 +1,250 @@
+/**
+ * Plugin-agnostic mail model. Lives in `shared/` because both the host
+ * (which owns the `mail_*` agent tools and the safety gate) and the
+ * plugin providers (which translate the typed interface into provider
+ * API calls) trade in the same shapes.
+ *
+ * The core has no mail cache of its own — providers fetch live every
+ * time. Plugin pollers still emit `mail:<plugin>` events to wake
+ * handlers, but the persisted entity is the event row; the mail body
+ * and attachments are pulled on demand through the provider.
+ *
+ * **Mail ids** are provider-prefixed strings: `<pluginId>:<mailbox>:<realId>`.
+ * The mailbox segment lets the host route a tool call to the correct
+ * provider AND the correct logged-in account without needing a separate
+ * mailbox registry. {@link buildMailId} / {@link parseMailId} are the
+ * canonical helpers; raw string concatenation is forbidden.
+ *
+ * **Folders.** The core uses three abstract aliases — `inbox`, `archive`,
+ * `trash` — which each provider maps to its native folder names
+ * (e.g. ms365 → `inbox`, `archive`, `deleteditems`; gmail eventually →
+ * `INBOX`, `[Gmail]/All Mail`, `[Gmail]/Trash`).
+ */
+export type MailFolder = "inbox" | "archive" | "trash" | "sent";
+/**
+ * One downloaded attachment. The core tool stages these into the
+ * agentrun's scratch directory; the provider supplies the raw bytes.
+ */
+export interface MailAttachment {
+    readonly name: string;
+    readonly contents: Buffer;
+}
+/**
+ * Sanitized address bundle as it appears in the `mail:new` event
+ * payload and in {@link MailSearchHit} results. `address` is always
+ * safe to use as a filename component; `rawAddress` is `null` when the
+ * upstream address passed validation, otherwise it carries the
+ * original bytes for audit (handlers must NEVER use it as a path).
+ */
+export interface MailAddress {
+    readonly name: string | null;
+    readonly address: string;
+    readonly rawAddress: string | null;
+}
+/**
+ * Attachment metadata that ships with a `mail:new` payload and search
+ * hits. Bytes never travel through this shape — the agent calls
+ * `mail_fetch_attachments` to download contents on demand.
+ */
+export interface MailAttachmentMeta {
+    readonly id: string;
+    readonly name: string;
+    readonly contentType: string;
+    readonly size: number;
+    readonly isInline: boolean;
+}
+/**
+ * Predicates for {@link MailProvider.search}. Date bounds are passed
+ * in already-resolved UTC ISO form (the host parses agent-supplied
+ * local-tz strings against `core.timezone` before dispatching, so
+ * providers never have to know about timezones).
+ */
+export interface MailSearchQuery {
+    /** Full-text query, applied across subject/body/from/to/cc. */
+    readonly text?: string;
+    /** Address that must appear as sender, To, or Cc. */
+    readonly contact?: string;
+    /** Inclusive lower bound on receivedDateTime (UTC ISO instant). */
+    readonly after?: string;
+    /** Exclusive upper bound on receivedDateTime (UTC ISO instant). */
+    readonly before?: string;
+    /** Restrict to one abstract folder; otherwise any folder is in scope. */
+    readonly folder?: MailFolder;
+    /**
+     * Optional mailbox restriction. When omitted the provider searches
+     * every mailbox in its configured set, regardless of polling state.
+     * When given and not in the configured set, providers may still
+     * attempt the call as a best-effort fallback.
+     */
+    readonly mailbox?: string;
+    /**
+     * Hard ceiling on hits to return. The host passes the remaining
+     * global budget (initial 100, decremented across providers) so a
+     * provider can stop paging early instead of fetching results that
+     * would be dropped anyway.
+     */
+    readonly limit: number;
+}
+/**
+ * One match returned by {@link MailProvider.search}. Shape is
+ * intentionally identical to the `mail:new` event payload so handlers
+ * can treat search hits and live mail events with the same code path.
+ */
+export interface MailSearchHit {
+    readonly mail_id: string;
+    readonly isShared: boolean;
+    readonly from: MailAddress;
+    readonly to: readonly MailAddress[];
+    readonly cc: readonly MailAddress[];
+    readonly subject: string;
+    readonly date: string;
+    readonly internetMessageId: string;
+    readonly hasAttachments: boolean;
+    readonly attachments: readonly MailAttachmentMeta[] | null;
+    /**
+     * Folder the hit currently lives in, using the same vocabulary the
+     * agent passes to `mail_search`'s `folder` argument and `mail_move`:
+     * one of the three known aliases (`inbox` / `archive` / `trash`) or
+     * `other` for anything else (custom user folders the agent doesn't
+     * have a verb for today). `null` only when the provider couldn't
+     * resolve the folder for a given hit.
+     */
+    readonly folder: MailFolder | "other" | null;
+}
+/**
+ * Composition input for {@link MailProvider.draftReply} /
+ * {@link MailProvider.sendReply}. The body is markdown; providers render
+ * to their native body format (HTML for Graph) before dispatch.
+ */
+export interface ReplyInput {
+    readonly bodyMarkdown: string;
+    /** When `true`, address every recipient on the original mail. */
+    readonly replyAll: boolean;
+}
+/**
+ * Composition input for {@link MailProvider.draftForward} /
+ * {@link MailProvider.sendForward}. The optional comment renders above
+ * the quoted original. Original attachments are carried over by the
+ * provider where possible.
+ */
+export interface ForwardInput {
+    readonly to: readonly string[];
+    readonly cc: readonly string[];
+    readonly commentMarkdown: string;
+}
+/**
+ * Composition input for a brand-new mail (no source message). The
+ * "from" mailbox is passed separately to {@link MailProvider.draftNew} /
+ * {@link MailProvider.sendNew} as the first argument so the same shape
+ * carries through every send/draft variant.
+ */
+export interface NewMailInput {
+    readonly to: readonly string[];
+    readonly cc: readonly string[];
+    readonly subject: string;
+    readonly bodyMarkdown: string;
+}
+/**
+ * The contract a provider plugin implements + registers via
+ * {@link MailApi.registerProvider}. The host's `mail_*` tools dispatch
+ * here by parsing the mail id's `<pluginId>:` prefix and looking the
+ * provider up in the registry.
+ *
+ * Methods return raw provider-native ids; the core wraps them with
+ * the `<pluginId>:<mailbox>:` prefix before handing them back to the
+ * agent. That way every id the agent sees is self-routing.
+ *
+ * Provider safety (send guards, attendee stripping, etc.) is **not**
+ * the provider's concern — those policies live in core (`MailSafety`
+ * in the host). Providers focus on the API call.
+ */
+export interface MailProvider {
+    /** Identifies this provider in the registry. Matches the plugin id. */
+    readonly pluginId: string;
+    /** Fetch the plain-text body of one message. */
+    fetchBody(mailbox: string, messageId: string): Promise<string>;
+    /** Download every non-inline attachment as in-memory buffers. */
+    fetchAttachments(mailbox: string, messageId: string): Promise<readonly MailAttachment[]>;
+    /**
+     * Inspect an existing message and return the recipient set a reply
+     * would address (sender always; to/cc lists when `replyAll`). Used
+     * by core to gate `send_reply` against the safety whitelist *before*
+     * the send call; saves one round trip in the gated path and lets
+     * the agent see the recipients in the result envelope.
+     */
+    previewReplyRecipients(mailbox: string, messageId: string, replyAll: boolean): Promise<readonly string[]>;
+    /** Create a draft reply. Returns the provider-native draft id. */
+    draftReply(mailbox: string, messageId: string, input: ReplyInput): Promise<string>;
+    /** Create a draft forward. Returns the provider-native draft id. */
+    draftForward(mailbox: string, messageId: string, input: ForwardInput): Promise<string>;
+    /** Create a brand-new draft under `mailbox`. Returns its id. */
+    draftNew(mailbox: string, input: NewMailInput): Promise<string>;
+    /**
+     * Compose and dispatch a reply immediately. The core has already
+     * cleared the safety gate by the time this is called.
+     */
+    sendReply(mailbox: string, messageId: string, input: ReplyInput): Promise<void>;
+    /** Compose and dispatch a forward immediately. */
+    sendForward(mailbox: string, messageId: string, input: ForwardInput): Promise<void>;
+    /** Compose and dispatch a brand-new mail immediately. */
+    sendNew(mailbox: string, input: NewMailInput): Promise<void>;
+    /** Move a message to one of the abstract folder aliases. */
+    move(mailbox: string, messageId: string, folder: MailFolder): Promise<void>;
+    /**
+     * Search this provider's mail for hits matching `query`. The host
+     * fans out to every registered provider when no `plugin` filter is
+     * set; per-provider results are merged into a single JSONL response
+     * to the agent. Implementations should:
+     *
+     *  - target `query.mailbox` when given (best-effort: try even if
+     *    the address isn't in the configured set), otherwise iterate
+     *    over every mailbox the provider considers configured —
+     *    independent of whether that mailbox is being polled;
+     *  - cap returned hits at `query.limit` (the host's remaining
+     *    global budget) and stop paging once the cap is hit;
+     *  - shape each hit identically to the provider's `mail:new`
+     *    event payload, so downstream tools accept the `mail_id` as
+     *    self-routing.
+     */
+    search(query: MailSearchQuery): Promise<readonly MailSearchHit[]>;
+}
+/**
+ * Capabilities the host exposes to plugins for mail data. Reached via
+ * `ctx.mail` on a plugin's `HostContext`. Tiny by design: there is no
+ * mail cache in core, so the only thing plugins do here is register
+ * their provider during `start()`.
+ */
+export interface MailApi {
+    /**
+     * Register the create / send / fetch callbacks a provider plugin
+     * implements. Throws if the same `pluginId` registers twice — a
+     * wiring bug, not a feature.
+     */
+    registerProvider(provider: MailProvider): void;
+}
+/**
+ * Build a self-routing mail id from the three segments. Format:
+ * `<pluginId>:<mailbox>:<realId>`. The id is what flows through tool
+ * args, event payloads, and agent prompts — the agent never sees the
+ * three segments separately.
+ *
+ * No escaping is applied: mailboxes containing literal `:` (rare;
+ * RFC 5321 allows quoted local parts) are unsupported. Graph ids
+ * routinely contain `=`, `+`, `/` but never `:`, so the parse split is
+ * unambiguous in practice.
+ */
+export declare function buildMailId(pluginId: string, mailbox: string, realId: string): string;
+/**
+ * Parse a mail id back into its three segments. The split is on the
+ * first two `:` characters; anything after the second colon is the
+ * real id (which provider implementations may use freely).
+ *
+ * @throws If the id has fewer than two `:` separators or any segment
+ *   is empty. The error message names the offending input so a bad
+ *   id surfaced from agent args produces an actionable tool failure.
+ */
+export declare function parseMailId(id: string): {
+    readonly pluginId: string;
+    readonly mailbox: string;
+    readonly realId: string;
+};

package/build/Mail.js

@@ -0,0 +1,73 @@
+/**
+ * Plugin-agnostic mail model. Lives in `shared/` because both the host
+ * (which owns the `mail_*` agent tools and the safety gate) and the
+ * plugin providers (which translate the typed interface into provider
+ * API calls) trade in the same shapes.
+ *
+ * The core has no mail cache of its own — providers fetch live every
+ * time. Plugin pollers still emit `mail:<plugin>` events to wake
+ * handlers, but the persisted entity is the event row; the mail body
+ * and attachments are pulled on demand through the provider.
+ *
+ * **Mail ids** are provider-prefixed strings: `<pluginId>:<mailbox>:<realId>`.
+ * The mailbox segment lets the host route a tool call to the correct
+ * provider AND the correct logged-in account without needing a separate
+ * mailbox registry. {@link buildMailId} / {@link parseMailId} are the
+ * canonical helpers; raw string concatenation is forbidden.
+ *
+ * **Folders.** The core uses three abstract aliases — `inbox`, `archive`,
+ * `trash` — which each provider maps to its native folder names
+ * (e.g. ms365 → `inbox`, `archive`, `deleteditems`; gmail eventually →
+ * `INBOX`, `[Gmail]/All Mail`, `[Gmail]/Trash`).
+ */
+/**
+ * Build a self-routing mail id from the three segments. Format:
+ * `<pluginId>:<mailbox>:<realId>`. The id is what flows through tool
+ * args, event payloads, and agent prompts — the agent never sees the
+ * three segments separately.
+ *
+ * No escaping is applied: mailboxes containing literal `:` (rare;
+ * RFC 5321 allows quoted local parts) are unsupported. Graph ids
+ * routinely contain `=`, `+`, `/` but never `:`, so the parse split is
+ * unambiguous in practice.
+ */
+export function buildMailId(pluginId, mailbox, realId) {
+    if (pluginId.length === 0 || pluginId.includes(":")) {
+        throw new Error(`pluginId must be non-empty and ":"-free: "${pluginId}"`);
+    }
+    if (mailbox.length === 0 || mailbox.includes(":")) {
+        throw new Error(`mailbox must be non-empty and ":"-free: "${mailbox}"`);
+    }
+    if (realId.length === 0) {
+        throw new Error("realId must be non-empty");
+    }
+    return `${pluginId}:${mailbox}:${realId}`;
+}
+/**
+ * Parse a mail id back into its three segments. The split is on the
+ * first two `:` characters; anything after the second colon is the
+ * real id (which provider implementations may use freely).
+ *
+ * @throws If the id has fewer than two `:` separators or any segment
+ *   is empty. The error message names the offending input so a bad
+ *   id surfaced from agent args produces an actionable tool failure.
+ */
+export function parseMailId(id) {
+    const first = id.indexOf(":");
+    if (first <= 0) {
+        throw new Error(`mail id "${id}" is malformed: expected "<plugin>:<mailbox>:<realId>"`);
+    }
+    const second = id.indexOf(":", first + 1);
+    if (second <= first + 1) {
+        throw new Error(`mail id "${id}" is malformed: missing mailbox segment`);
+    }
+    const realId = id.slice(second + 1);
+    if (realId.length === 0) {
+        throw new Error(`mail id "${id}" is malformed: empty real-id segment`);
+    }
+    return {
+        pluginId: id.slice(0, first),
+        mailbox: id.slice(first + 1, second),
+        realId,
+    };
+}