@agenticmail/claudecode 0.1.0

package/dist/config-BegnlyPD.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Shared types for the @agenticmail/claudecode package.
+ *
+ * Kept in one file so the install / uninstall / status / discovery modules can
+ * import a single source of truth without circular deps.
+ */
+/** An AgenticMail account as returned by `GET /api/agenticmail/accounts`. */
+interface AgenticMailAccount {
+    id: string;
+    name: string;
+    email: string;
+    apiKey: string;
+    role?: string;
+    metadata?: Record<string, unknown>;
+}
+/** Resolved configuration for everything the package does. */
+interface ClaudeCodeIntegrationConfig {
+    /** AgenticMail master API URL. */
+    apiUrl: string;
+    /** AgenticMail master key (mk_…). */
+    masterKey: string;
+    /** Path to Claude Code's user-level config (typically ~/.claude.json). */
+    claudeConfigPath: string;
+    /** Directory where per-agent Claude Code subagent .md files live (typically ~/.claude/agents). */
+    agentsDir: string;
+    /** Key under mcpServers in Claude Code's config. */
+    mcpServerName: string;
+    /** Name of the dedicated AgenticMail agent that represents Claude Code. */
+    bridgeAgentName: string;
+    /** Prefix for generated subagent names — produces e.g. `agenticmail-fola`. */
+    subagentPrefix: string;
+    /**
+     * Command used to invoke the AgenticMail MCP server.
+     * Defaults to the globally-installed `agenticmail-mcp` bin; falls back to
+     * `npx -y @agenticmail/mcp` for portability.
+     */
+    mcpCommand: string;
+    mcpArgs: string[];
+}
+/** Snapshot of the installation state — used by `status`. */
+interface InstallStatus {
+    state: 'installed' | 'not_installed' | 'partial';
+    /** Whether the MCP server block is present in Claude Code config. */
+    mcpInstalled: boolean;
+    /** Bridge agent (Claude Code's identity inside AgenticMail) exists. */
+    bridgeAgentExists: boolean;
+    /** Subagent .md files currently present, keyed by AgenticMail agent name. */
+    subagents: string[];
+    /** Path to Claude Code config (so the user knows what we touched). */
+    claudeConfigPath: string;
+    /** Directory used for subagent .md files. */
+    agentsDir: string;
+    /** Free-form notes for the user (e.g. "API unreachable"). */
+    notes: string[];
+    /** Dispatcher PM2 status (null when PM2 isn't installed or entry absent). */
+    dispatcher: {
+        running: boolean;
+        pid?: number;
+        restartCount?: number;
+        uptimeMs?: number;
+    } | null;
+}
+/** Result returned by `install`. */
+interface InstallResult {
+    /** AgenticMail agents that were turned into Claude Code subagents. */
+    registeredAgents: AgenticMailAccount[];
+    /** Where the MCP server block was written. */
+    claudeConfigPath: string;
+    /** Where the subagent .md files were written. */
+    agentsDir: string;
+    /** The bridge agent (Claude Code's identity inside AgenticMail). */
+    bridgeAgent: AgenticMailAccount;
+    /** True if the install changed any files (false on no-op re-runs). */
+    changed: boolean;
+    /** Dispatcher daemon launch status (best-effort; reason populated on failure). */
+    dispatcher?: {
+        started: boolean;
+        reason?: string;
+    };
+}
+/** Result returned by `uninstall`. */
+interface UninstallResult {
+    /** Whether anything was actually removed. */
+    changed: boolean;
+    /** Removed subagent .md files. */
+    removedSubagents: string[];
+    /** Whether the MCP server block was removed from Claude Code config. */
+    mcpBlockRemoved: boolean;
+    /** Whether the bridge agent was deleted (only if `--purge-bridge` was set). */
+    bridgeAgentDeleted: boolean;
+    /** Whether the dispatcher PM2 entry was stopped. */
+    dispatcherStopped: boolean;
+}
+
+/**
+ * Resolves a fully-populated ClaudeCodeIntegrationConfig from defaults +
+ * overrides + the on-disk AgenticMail config (~/.agenticmail/config.json).
+ *
+ * Reading the master key from disk lives here (not in install.ts) so tests
+ * can supply config inline without touching the filesystem.
+ */
+
+/** Public options for resolveConfig — everything is optional and overrides defaults. */
+interface ResolveConfigOptions {
+    apiUrl?: string;
+    masterKey?: string;
+    claudeConfigPath?: string;
+    agentsDir?: string;
+    mcpServerName?: string;
+    bridgeAgentName?: string;
+    subagentPrefix?: string;
+    mcpCommand?: string;
+    mcpArgs?: string[];
+    /**
+     * Override path to AgenticMail's config.json (defaults to
+     * ~/.agenticmail/config.json). Mainly useful in tests.
+     */
+    agenticmailConfigPath?: string;
+}
+declare function resolveConfig(opts?: ResolveConfigOptions): ClaudeCodeIntegrationConfig;
+
+export { type AgenticMailAccount as A, type ClaudeCodeIntegrationConfig as C, type InstallResult as I, type ResolveConfigOptions as R, type UninstallResult as U, type InstallStatus as a, resolveConfig as r };

package/dist/dispatcher-bin.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/dispatcher-bin.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import {
+  Dispatcher
+} from "./chunk-563BZ447.js";
+import "./chunk-XAW5NUNU.js";
+
+// src/dispatcher-bin.ts
+async function main() {
+  const dispatcher = new Dispatcher({
+    apiUrl: process.env.AGENTICMAIL_API_URL,
+    masterKey: process.env.AGENTICMAIL_MASTER_KEY,
+    agentsDir: process.env.CLAUDE_CODE_AGENTS_DIR,
+    maxConcurrentWorkers: positiveInt(process.env.AGENTICMAIL_DISPATCHER_MAX),
+    accountSyncIntervalMs: positiveInt(process.env.AGENTICMAIL_DISPATCHER_SYNC)
+  });
+  const shutdown = async (sig) => {
+    console.error(`[dispatcher-bin] received ${sig} \u2014 shutting down`);
+    try {
+      await dispatcher.stop();
+    } catch (err) {
+      console.error(`[dispatcher-bin] error during shutdown: ${err.message}`);
+    }
+    process.exit(0);
+  };
+  process.once("SIGINT", shutdown);
+  process.once("SIGTERM", shutdown);
+  process.on("unhandledRejection", (reason) => {
+    console.error("[dispatcher-bin] unhandledRejection:", reason);
+  });
+  await dispatcher.start();
+}
+function positiveInt(s) {
+  if (!s) return void 0;
+  const n = parseInt(s, 10);
+  return Number.isFinite(n) && n > 0 ? n : void 0;
+}
+main().catch((err) => {
+  console.error(`[dispatcher-bin] fatal: ${err.message}`);
+  process.exit(1);
+});

package/dist/dispatcher.d.ts

@@ -0,0 +1,116 @@
+import { R as ResolveConfigOptions, A as AgenticMailAccount } from './config-BegnlyPD.js';
+
+/**
+ * AgenticMail → Claude Code event dispatcher.
+ *
+ * Long-lived daemon that bridges AgenticMail's event stream to the
+ * Claude Agent SDK. Concretely: subscribes to the master API's SSE
+ * stream for every AgenticMail account, and when an event arrives —
+ * either a new mail in some agent's inbox, or a task assigned to some
+ * agent — it spawns a Claude-powered worker that *is* that agent (same
+ * persona, same `_account`-scoped MCP toolbelt) and lets it handle the
+ * trigger.
+ *
+ * This is what makes "send an email to fola@localhost and she wakes up
+ * and replies" work — without any always-on enterprise runtime, and
+ * without an interactive Claude Code session having to be open.
+ *
+ * # Design notes
+ *
+ *   - One SSE connection per account (the master API does not currently
+ *     expose a master-key "watch everything" endpoint). The dispatcher
+ *     polls `GET /accounts` every `accountSyncIntervalMs` to discover
+ *     newly-created accounts and tear down ones that disappeared, so
+ *     `create_account` is wake-able within ~one sync interval with zero
+ *     manual steps.
+ *
+ *   - Workers are spawned via `@anthropic-ai/claude-agent-sdk`'s
+ *     `query()` — same OAuth as the user's `claude`, same MCP server,
+ *     same persona prompt as the on-disk `.md`. Each worker drains its
+ *     query stream to completion, then exits.
+ *
+ *   - Concurrency is capped via a small semaphore (default 10). Beyond
+ *     that, wakes queue. This is a hard floor on Anthropic-side cost:
+ *     50 simultaneous wakes = 50 simultaneous Claude calls, which the
+ *     user is unlikely to want by default.
+ *
+ *   - Task events get an explicit "claim + submit_result" instruction
+ *     in the wake prompt so the call_agent long-poll on the master API
+ *     resolves cleanly. Mail events just say "you've got new mail" and
+ *     trust the persona to do the right thing (read / reply / archive).
+ */
+
+/** Event shape we accept off the SSE stream. */
+interface SSEEvent {
+    type?: string;
+    uid?: number;
+    from?: string;
+    subject?: string;
+    taskId?: string;
+    taskType?: string;
+    task?: string;
+    assignee?: string;
+    [key: string]: unknown;
+}
+interface DispatcherOptions extends ResolveConfigOptions {
+    /** Max concurrent workers. Default 10. Hard floor on Anthropic cost. */
+    maxConcurrentWorkers?: number;
+    /** How often to re-poll /accounts for new agents. Default 60s. */
+    accountSyncIntervalMs?: number;
+    /** How long to wait between SSE reconnect attempts (start). Default 2s. */
+    sseReconnectBaseMs?: number;
+    /** Max backoff between SSE reconnect attempts. Default 60s. */
+    sseReconnectMaxMs?: number;
+    /** Override the Claude Agent SDK `query` function. Used by tests. */
+    querySdk?: QueryFn;
+    /** Override the global `fetch`. Used by tests. */
+    fetchImpl?: typeof fetch;
+    /** Override the global EventSource. Optional — we don't use EventSource
+     *  by default (fetch + reader is simpler). */
+    log?: (level: 'info' | 'warn' | 'error', msg: string) => void;
+}
+/** Minimal Claude Agent SDK query signature we use. */
+interface QueryFn {
+    (params: {
+        prompt: string;
+        options?: Record<string, unknown>;
+    }): AsyncIterable<unknown>;
+}
+/**
+ * The dispatcher itself. Construct once, call .start() to begin watching,
+ * .stop() to tear down. Returns when stop() has finished cleaning up.
+ */
+declare class Dispatcher {
+    private cfg;
+    private maxConcurrent;
+    private syncIntervalMs;
+    private reconnectBaseMs;
+    private reconnectMaxMs;
+    private query;
+    private fetchImpl;
+    private log;
+    private channels;
+    private accountSyncTimer;
+    private running;
+    private waiters;
+    private stopped;
+    constructor(opts?: DispatcherOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Public for tests — directly hand an event to the routing path. */
+    handleEvent(account: AgenticMailAccount, event: SSEEvent): Promise<void>;
+    /** Re-fetch /accounts; open SSE for new ones, close for vanished ones. */
+    private syncAccounts;
+    /** Watch one account's SSE stream forever; reconnect with backoff on drop. */
+    private runChannel;
+    /** Single SSE attach. Returns when the stream closes for any reason. */
+    private streamOne;
+    /** Acquire a concurrency slot, run a worker, release the slot. */
+    private spawnWorker;
+    /** Build the env block we pass to the worker's MCP server child process. */
+    private buildMcpEnv;
+    private acquireSlot;
+    private releaseSlot;
+}
+
+export { Dispatcher, type DispatcherOptions, type QueryFn };

package/dist/dispatcher.js

@@ -0,0 +1,7 @@
+import {
+  Dispatcher
+} from "./chunk-563BZ447.js";
+import "./chunk-XAW5NUNU.js";
+export {
+  Dispatcher
+};

package/dist/http-routes.d.ts

@@ -0,0 +1,36 @@
+import { Router } from 'express';
+
+/**
+ * HTTP routes for the Claude Code integration.
+ *
+ * Mounted by `@agenticmail/api` (see app.ts) under
+ *   /api/agenticmail/integrations/claudecode
+ *
+ * Purpose: let an agent (Claude Code itself, a shell script, a CI job, …)
+ * install the integration with a single POST request, no terminal interaction
+ * required. The endpoints are deliberately registered BEFORE the master-key
+ * auth middleware because they ARE the bootstrap — a Claude Code session that
+ * doesn't yet have AgenticMail wired up has no way to know the master key,
+ * so requiring it would defeat the purpose.
+ *
+ * SECURITY MODEL
+ * --------------
+ * The AgenticMail master API binds to 127.0.0.1 by default. Any process that
+ * can reach this endpoint can already read ~/.agenticmail/config.json (same
+ * file ownership), so leaving these endpoints unauthenticated does not widen
+ * the attack surface. If the operator binds the API to a non-loopback
+ * interface they MUST put auth or a firewall in front of it — same as every
+ * other unauthenticated route on this server (e.g. /health).
+ *
+ * The install handler still reads the master key from disk before touching
+ * AgenticMail, so the routes don't grant *new* powers — they just save the
+ * agent the trouble of plumbing one in.
+ */
+
+/**
+ * Build the Express router. Caller mounts at the prefix of its choosing
+ * (typically `/api/agenticmail/integrations/claudecode`).
+ */
+declare function createIntegrationRoutes(): Router;
+
+export { createIntegrationRoutes };

package/dist/http-routes.js

@@ -0,0 +1,11 @@
+import {
+  createIntegrationRoutes
+} from "./chunk-UPA2YLSM.js";
+import "./chunk-P2DXF7DO.js";
+import "./chunk-RI4USTMC.js";
+import "./chunk-ULKJ773Y.js";
+import "./chunk-US5FT2UB.js";
+import "./chunk-XAW5NUNU.js";
+export {
+  createIntegrationRoutes
+};

package/dist/index.d.ts

@@ -0,0 +1,176 @@
+export { install } from './install.js';
+export { UninstallOptions, uninstall } from './uninstall.js';
+export { status } from './status.js';
+import { A as AgenticMailAccount } from './config-BegnlyPD.js';
+export { C as ClaudeCodeIntegrationConfig, I as InstallResult, a as InstallStatus, R as ResolveConfigOptions, U as UninstallResult, r as resolveConfig } from './config-BegnlyPD.js';
+export { createIntegrationRoutes } from './http-routes.js';
+export { Dispatcher, DispatcherOptions, QueryFn } from './dispatcher.js';
+import 'express';
+
+/**
+ * Thin client for the AgenticMail master API.
+ *
+ * We talk to ONE endpoint family — `/api/agenticmail/accounts` — to discover
+ * and provision agents. The MCP server itself handles every other call once
+ * Claude Code is wired up, so this client deliberately stays tiny.
+ */
+
+declare class AgenticMailApiError extends Error {
+    status: number;
+    constructor(status: number, message: string);
+}
+/**
+ * Confirm the master API is reachable.
+ *
+ * The `/health` route is intentionally unauthenticated upstream — we use it
+ * here precisely *because* it doesn't require the master key, so an early
+ * misconfiguration shows the user "API is down" rather than "key is wrong".
+ * Returns the version string from the response.
+ */
+declare function checkApiHealth(apiUrl: string): Promise<{
+    ok: true;
+    version?: string;
+}>;
+/** List every AgenticMail account (agents). Requires the master key. */
+declare function listAccounts(apiUrl: string, masterKey: string): Promise<AgenticMailAccount[]>;
+/** Look up a single account by name. Returns null if not found. */
+declare function getAccountByName(apiUrl: string, masterKey: string, name: string): Promise<AgenticMailAccount | null>;
+/**
+ * Create an AgenticMail account. Idempotent at the call site: if the name
+ * already exists, returns the existing record instead of throwing.
+ */
+declare function ensureAccount(apiUrl: string, masterKey: string, name: string, role?: string): Promise<AgenticMailAccount>;
+/** Delete an account by id. */
+declare function deleteAccount(apiUrl: string, masterKey: string, id: string): Promise<void>;
+
+/**
+ * Generates the markdown content for one Claude Code subagent file.
+ *
+ * A Claude Code subagent is a `.md` file in `~/.claude/agents/` with YAML
+ * frontmatter. When the host Claude Code session calls
+ *   Agent { subagent_type: "<name>", prompt: "..." }
+ * Claude Code spawns a fresh session whose system prompt is the body of the
+ * `.md` file and whose `tools` are restricted to those listed in frontmatter.
+ *
+ * # Design: Claude Code is the brain
+ *
+ * Each AgenticMail "agent" (Fola, John, …) is a mailbox + persistent state
+ * inside AgenticMail: an email address, a folder of past mail, a task
+ * queue, and an API key. This package supplies the missing piece — the
+ * *thinking* — by making the user's Claude Code session itself drive each
+ * agent's behaviour.
+ *
+ * When the host session calls `Agent { subagent_type: "agenticmail-fola",
+ * ... }`, Claude Code spawns a fresh subagent whose system prompt is the
+ * persona below. That subagent uses Claude Code's own Claude OAuth
+ * credentials (no separate Anthropic key needed) and operates Fola's
+ * mailbox via the MCP server with `_account: "Fola"` on every call. From
+ * the outside, Fola behaves as you'd expect: she reads her email, sends
+ * mail from fola@localhost, manages her tasks. Internally she is powered
+ * by the same Claude that powers the host session.
+ *
+ * This is the "AgenticMail rides on Claude Code" architecture.
+ *
+ * # Tiered tool loading (token budget)
+ *
+ * Loading all 62 AgenticMail tool schemas into a fresh subagent's context
+ * costs ~10K tokens per spawn — most of it never used. We mirror the
+ * three-tier lazy-loading design from the AgenticMail enterprise
+ * tool-resolver:
+ *
+ *   - Tier 1 — ESSENTIAL: a curated whitelist of ~9 common tools, plus
+ *     the two meta-tools `request_tools` and `invoke`. These are listed
+ *     in the subagent's `tools:` frontmatter so they're available
+ *     immediately at spawn.
+ *
+ *   - Tier 2/3 — ON-DEMAND: the other ~50 tools (signatures, drafts,
+ *     bulk ops, SMS voice, setup wizards, account admin, …). The agent
+ *     discovers them via `request_tools` (returns a text catalogue) and
+ *     calls them via `invoke({ tool, args, _account })`.
+ *
+ * Net effect: spawn cost drops from ~15K tokens to ~3-4K, while the full
+ * tool surface remains reachable. The trade-off is one extra round trip
+ * for uncommon operations.
+ *
+ * Generic Claude Code tools (Read/Edit/Bash/Glob/Grep/WebFetch/…) are
+ * NOT in the `tools:` whitelist — Claude Code will refuse to call them
+ * from inside this subagent, which mechanically enforces the
+ * "you operate an email account, not a developer environment" rule.
+ */
+
+/** Configuration shape used when building one subagent's .md content. */
+interface SubagentTemplateInput {
+    /** Subagent name (already includes the prefix, e.g. "agenticmail-fola"). */
+    name: string;
+    /** The AgenticMail agent this subagent embodies. */
+    agent: AgenticMailAccount;
+    /** MCP server key as configured in ~/.claude.json (e.g. "agenticmail"). */
+    mcpServerName: string;
+}
+/** Marker we embed in frontmatter so uninstall can be sure a file is ours. */
+declare const MANAGED_BY_MARKER = "@agenticmail/claudecode";
+/**
+ * Render JUST the persona body (no frontmatter, no .md wrapper).
+ *
+ * This is what the dispatcher feeds to the Claude Agent SDK as the
+ * `systemPrompt` when waking an agent — the SDK doesn't read `.md`
+ * frontmatter, only the prose. Splitting the body out also lets us
+ * generate a persona for a never-seen-before account (e.g. one that
+ * was just `create_account`ed by another worker) without needing a
+ * pre-written `.md` file on disk.
+ *
+ * `renderSubagentMarkdown` builds on top of this by adding the YAML
+ * frontmatter Claude Code's Agent tool needs.
+ */
+declare function renderPersonaBody(input: SubagentTemplateInput): string;
+/**
+ * Produce the full text (frontmatter + body) for one subagent .md file.
+ *
+ * The body is a "you are <Agent>" persona that drives the subagent to do
+ * real work using MCP tools scoped to its own account.
+ */
+declare function renderSubagentMarkdown(input: SubagentTemplateInput): string;
+
+/**
+ * Resolves a persona prompt for an AgenticMail agent, with two sources
+ * tried in order:
+ *
+ *   1. `~/.claude/agents/agenticmail-<name>.md` on disk (if present).
+ *      Lets the operator customise an agent's behaviour by hand-editing
+ *      its file. Owned-by-us files (frontmatter marker) AND user-owned
+ *      files are both honoured — the dispatcher trusts whatever is on
+ *      disk for that agent.
+ *
+ *   2. In-memory render from live AgenticMail account metadata via
+ *      `renderPersonaBody`. This is the path for agents that were just
+ *      `create_account`-ed and have no file yet — they become wake-able
+ *      immediately, no install step required.
+ *
+ * Returns the persona BODY (no YAML frontmatter). That's what the
+ * Claude Agent SDK consumes as a system prompt.
+ */
+
+interface LoadPersonaOptions {
+    agent: AgenticMailAccount;
+    /** Directory holding per-agent .md files. Default: ~/.claude/agents. */
+    agentsDir: string;
+    /** Prefix for filenames. Default: "agenticmail-". */
+    subagentPrefix: string;
+    /** MCP server name used inside tool examples in the prose. */
+    mcpServerName: string;
+}
+interface LoadedPersona {
+    /** The persona body — system prompt for the worker. */
+    body: string;
+    /** Where the body came from (for logs / debugging). */
+    source: 'file' | 'generated';
+    /** Resolved file path if source === 'file'. */
+    filePath?: string;
+}
+/**
+ * Try the disk file; fall back to live generation. Pure function — no
+ * side effects, no API calls (the account metadata is passed in).
+ */
+declare function loadPersonaForAgent(opts: LoadPersonaOptions): LoadedPersona;
+
+export { AgenticMailAccount, AgenticMailApiError, type LoadPersonaOptions, type LoadedPersona, MANAGED_BY_MARKER, checkApiHealth, deleteAccount, ensureAccount, getAccountByName, listAccounts, loadPersonaForAgent, renderPersonaBody, renderSubagentMarkdown };

package/dist/index.js

@@ -0,0 +1,47 @@
+import {
+  Dispatcher,
+  loadPersonaForAgent
+} from "./chunk-563BZ447.js";
+import {
+  createIntegrationRoutes
+} from "./chunk-UPA2YLSM.js";
+import {
+  install
+} from "./chunk-P2DXF7DO.js";
+import {
+  status
+} from "./chunk-RI4USTMC.js";
+import {
+  uninstall
+} from "./chunk-ULKJ773Y.js";
+import "./chunk-US5FT2UB.js";
+import {
+  AgenticMailApiError,
+  MANAGED_BY_MARKER,
+  checkApiHealth,
+  deleteAccount,
+  ensureAccount,
+  getAccountByName,
+  listAccounts,
+  renderPersonaBody,
+  renderSubagentMarkdown,
+  resolveConfig
+} from "./chunk-XAW5NUNU.js";
+export {
+  AgenticMailApiError,
+  Dispatcher,
+  MANAGED_BY_MARKER,
+  checkApiHealth,
+  createIntegrationRoutes,
+  deleteAccount,
+  ensureAccount,
+  getAccountByName,
+  install,
+  listAccounts,
+  loadPersonaForAgent,
+  renderPersonaBody,
+  renderSubagentMarkdown,
+  resolveConfig,
+  status,
+  uninstall
+};

package/dist/install.d.ts

@@ -0,0 +1,47 @@
+import { R as ResolveConfigOptions, I as InstallResult, A as AgenticMailAccount, C as ClaudeCodeIntegrationConfig } from './config-BegnlyPD.js';
+
+/**
+ * Install AgenticMail into Claude Code.
+ *
+ * Pure-function-ish: takes config, writes files, returns a result object.
+ * The chalk-painted CLI wizard (in agenticmail/src/cli.ts → cmdClaudeCode)
+ * is responsible for narrating progress. This module knows nothing about
+ * the terminal.
+ *
+ * What we write:
+ *   1. ~/.claude.json  →  adds mcpServers.<name> entry that runs the AgenticMail MCP server
+ *   2. ~/.claude/agents/<prefix><agent>.md  →  one Claude Code subagent per AgenticMail agent
+ *
+ * What we provision in AgenticMail:
+ *   - A single "claudecode" agent whose API key the MCP server uses as its identity.
+ *     This is the same model OpenClaw's plugin uses: every external host gets
+ *     its own AgenticMail identity so call traces are attributable.
+ *
+ * What we do NOT do:
+ *   - We do NOT touch ~/.claude/.credentials.json (the host Claude OAuth token).
+ *     Claude Code manages those credentials and uses them when spawning each
+ *     subagent — we never need to read or modify them. See README "How auth
+ *     works" for the full story.
+ *   - We do NOT touch any per-agent runtime artefacts that may exist outside
+ *     AgenticMail itself. Agent discovery uses the master API alone — that
+ *     is the only contract this package depends on.
+ */
+
+/**
+ * Decide which AgenticMail agents to surface as Claude Code subagents.
+ *
+ * Filters out:
+ *   - the bridge agent itself (Claude Code's own identity — calling yourself
+ *     is silly and would also create a duplicate-name collision in the
+ *     subagent_type namespace)
+ *   - any account with role="bridge" (reserved for hosts like this one)
+ */
+declare function selectExposableAgents(accounts: AgenticMailAccount[], cfg: ClaudeCodeIntegrationConfig): AgenticMailAccount[];
+/**
+ * Top-level install. Throws if the AgenticMail master API is unreachable —
+ * we refuse to write a half-broken config that Claude Code would silently
+ * load but never connect.
+ */
+declare function install(opts?: ResolveConfigOptions): Promise<InstallResult>;
+
+export { install, selectExposableAgents };

package/dist/install.js

@@ -0,0 +1,10 @@
+import {
+  install,
+  selectExposableAgents
+} from "./chunk-P2DXF7DO.js";
+import "./chunk-US5FT2UB.js";
+import "./chunk-XAW5NUNU.js";
+export {
+  install,
+  selectExposableAgents
+};

package/dist/status.d.ts

@@ -0,0 +1,18 @@
+import { R as ResolveConfigOptions, a as InstallStatus } from './config-BegnlyPD.js';
+
+/**
+ * Inspect the current install state of @agenticmail/claudecode.
+ *
+ * Used by:
+ *   - `agenticmail status` (top-level command, prints a one-line summary)
+ *   - `agenticmail claudecode --status` (prints a detailed report)
+ *   - tests
+ *
+ * The function is forgiving: anything that can't be checked (e.g. API down)
+ * is recorded as a note rather than a thrown error. The point of `status` is
+ * to help the user fix whatever's wrong, not to surface stack traces.
+ */
+
+declare function status(opts?: ResolveConfigOptions): Promise<InstallStatus>;
+
+export { status };

package/dist/status.js

@@ -0,0 +1,8 @@
+import {
+  status
+} from "./chunk-RI4USTMC.js";
+import "./chunk-US5FT2UB.js";
+import "./chunk-XAW5NUNU.js";
+export {
+  status
+};

package/dist/uninstall.d.ts

@@ -0,0 +1,25 @@
+import { R as ResolveConfigOptions, U as UninstallResult } from './config-BegnlyPD.js';
+
+/**
+ * Uninstall AgenticMail from Claude Code.
+ *
+ * Reverses everything install() did, in the opposite order, with one
+ * deliberate exception: we keep the bridge agent in AgenticMail by default.
+ *
+ * Why?  The bridge agent owns an inbox, may have ongoing conversations, and
+ * may be referenced from other agents' contact lists. Silently deleting it
+ * during a Claude Code uninstall is destructive in a way users would not
+ * expect. Pass { purgeBridgeAgent: true } if you really want it gone.
+ */
+
+interface UninstallOptions extends ResolveConfigOptions {
+    /**
+     * Also delete the bridge agent from AgenticMail. Default false — see header
+     * comment. Setting this to true is irreversible (the agent's API key, inbox
+     * folder layout, and contact references will all be invalidated).
+     */
+    purgeBridgeAgent?: boolean;
+}
+declare function uninstall(opts?: UninstallOptions): Promise<UninstallResult>;
+
+export { type UninstallOptions, uninstall };