ai-hist 0.16.0 → 0.18.0

package/README.md

@@ -1,8 +1,9 @@
 # ai-hist
 
-The public TypeScript SDK, Node CLI, and MCP server for RelayHistory. Every
-operation uses the mandatory `ai-hist-native` Node-API engine; there is no
-JavaScript SQLite implementation or provider-file fallback.
+The local history TypeScript SDK, Node CLI, and MCP server. Storage and local
+ingestion use one mandatory `ai-hist-native` Node-API engine. Optional source and
+destination plugins compose through public interfaces; no JavaScript SQL or
+commercial dependency is required by this package.
 
 ```bash
 npm install ai-hist
@@ -50,7 +51,8 @@ cache-only. `discoverSessions` is shallow discovery. `hydrateSession` is
 targeted evidence acquisition for one existing catalog row. It returns
 `hydrated`, `updated`, `unchanged`, or `capability_limited`, an indexed source
 stamp, evidence counts, related native session IDs, and bounded-work metrics.
-Targeted remote hydration uses `scope: 'remote'`: Claude web sessions can
+Targeted remote hydration uses `scope: 'remote'` and an explicitly configured
+source plugin registry: Claude web sessions can
 return `capability: 'full'` after complete teleport evidence is acquired;
 Codex cloud tasks return `partial` when their supported unified diff is indexed
 or `shallow_only` when no richer evidence is exposed. Partial results retain
@@ -70,14 +72,29 @@ offline behavior and making provider-cloud access explicit. The CLI exposes the
 same mutually exclusive `--local`, `--remote`, and `--all` flags; omitting them
 is equivalent to `--local`.
 
-Cached reads already support every scope. Remote acquisition runs through
-provider connectors — claude.ai/code web sessions and Codex cloud tasks —
-that are configured by the provider CLI's own sign-in on the machine (see the
-repository's `docs/remote-connectors.md`). On a machine with no connector
-configured, `discoverSessions({ scope: 'remote' })` and
-`sync({ scope: 'remote' })` fail with `UnsupportedOperationError` and the stable
-code `UNSUPPORTED_OPERATION`; they never fall back to local acquisition.
-`scope: 'all'` runs the local adapters plus every configured connector.
+Cached reads preserve the requested scope and never consult commercial auth.
+Stored remote history can be queried with absent, malformed, expired, or
+ambiguous credentials. Remote acquisition requires an explicitly loaded plugin
+registry. Install `@agent-relay/history-provider-sources` for Claude web/Codex
+cloud, or `@agent-relay/relayhistory` for RelayHistory. Installing a package does
+not register it, inspect auth or start delivery.
+
+```ts
+import { HistoryPluginRegistry } from 'ai-hist';
+import { createHistoryPlugin } from '@agent-relay/history-provider-sources';
+const plugins = new HistoryPluginRegistry();
+plugins.register(createHistoryPlugin({connectors:['claude-web']}));
+await discoverSessions({ scope:'remote', plugins, sourceConnectors:['claude-web'] });
+await sync({ scope:'all', plugins, sourceConnectors:[] }); // local adapters only
+const cached = await stats({ scope:'remote' }); // no login required
+```
+
+The CLI accepts `--config history.json` on acquisition commands. Config lists
+explicit plugin modules/options; `--source-connector` selects their IDs and is
+repeatable. `--no-source-connectors` disables remote acquisition. MCP uses
+`AI_HIST_PLUGIN_CONFIG` and `source_connectors`. Scope defaults to local even
+with plugins configured. See [source plugins](../docs/remote-connectors.md).
+Native contract 14 rejects old addons that lack the source/delivery boundary.
 
 Catalog pages, discovery results, statistics, and sync results echo the requested `scope`,
 and discovery results additionally report `locationsRun` — the connector
@@ -188,75 +205,36 @@ evidence, and connector/parser failures with dedicated error subclasses.
 The old synchronous `AiHist` class and `openAiHist()` API were removed in 1.0.
 See [the migration guide](https://github.com/AgentWorkforce/relayhistory/blob/main/docs/native-sdk-migration.md).
 
-## Cloud opt-in
-
-Run `ai-hist enable-cloud` to log in, drain local history and keep pushing. Use `--once` to exit after draining. The npm CLI bundles Agent Relay Cloud login, so no separate `agent-relay` CLI install is required; a run without a TTY fails promptly with interactive-login and token guidance. The async SDK exports `enableCloud`, `pushCloud`, `installGitHooks` and `createShareableTrace`; RelayHistory exchange, transport, and stage-scoped auth stay in Rust. See [cloud setup](https://github.com/AgentWorkforce/relayhistory/blob/main/docs/enable-cloud.md).
-
-`ai-hist/cloud` owns the cloud API wrappers, including `loginCloud` and
-`loadStoredRelayhistoryAuth`, and delegates to the Rust cloud layer through N-API.
-The root `ai-hist` entrypoint re-exports the cloud API for convenience. Credentials
-live in `$RELAYHISTORY_HOME/stages`, defaulting to
-`~/.agentworkforce/relayhistory/stages`. The Rust layer selects the stage, checks
-transport security, preserves session metadata, and saves rotated tokens atomically.
-
-## Session thread transport
-
-`getSessionThread` accepts `SessionThreadOptions.fetchImpl` for the thread GET
-request and its retries. Authentication requests use the Rust HTTP client.
-A stored-session 401 can therefore trigger a native refresh request even when
-`fetchImpl` is mocked. Custom proxy or TLS settings supplied through `fetchImpl`
-apply only to thread requests; the auth endpoint must also be reachable by the
-native client for automatic refresh to succeed.
-
-For isolated mocks or caller-managed credentials, supply `resolveSession` that
-returns `{ auth }` without the `session: true` marker:
-
-```ts
-import { getSessionThread } from 'ai-hist/cloud';
-
-const thread = await getSessionThread(
-  { source: 'claude', sessionId: 'example-session' },
-  {
-    resolveSession: async () => ({
-      auth: { baseUrl: 'https://history.example.com', accessToken: 'rth_at_fixture' },
-    }),
-    fetchImpl: async () => new Response(JSON.stringify({
-      session: null, outcomes: [], links: [], nextCursor: null,
-    })),
-  },
-);
-```
-
-This resolver disables automatic refresh. A 401 from the selected transport
-throws `AuthenticationExpiredError` without an authentication request. The
-default `resolveCloudSession` returns the marker for stored credentials and
-enables native refresh.
-
-## Cloud token and replay
-
-The npm CLI uses the same Rust engine as the public async SDK:
-
-```bash
-# Shell-safe token export (fails if ai-hist token fails)
-RTH_TOKEN="$(ai-hist token)" || { echo "Failed to get token" >&2; exit 1; }
-export RTH_TOKEN
-ai-hist replay SESSION_ID
-ai-hist replay SESSION_ID --json --out transcript.json
-```
-
-```ts
-import { accessToken, replay } from 'ai-hist';
-
-const token = await accessToken(); // Secret: do not log it.
-const result = await replay('SESSION_ID', { json: true });
-const events = JSON.parse(result.transcript!);
-await replay('SESSION_ID', { json: true, out: 'transcript.json' });
-```
-
-Both APIs accept `baseUrl` (`--base-url` in the CLI) for explicit stage selection.
-Token refresh and persistence run in Rust before returning a token with at least
-60 seconds of recorded validity. Piped `token` stdout contains only the token
-and one newline; failures leave stdout empty. Replay fetches every page in
-server order; `limit` is the page size, and `maxContent` caps each event's content.
-File output replaces its destination atomically only after all pages succeed.
-Neither command opens or imports into the local history database.
+## Optional cloud services
+
+Use a `HistoryDestination` plugin for any service or pipe the public NDJSON
+export to your own program. The local package has no cloud exports, login CLI,
+or default cloud MCP tool. RelayHistory's auth, sharing, replay, durable upload
+and readback live in [`@agent-relay/relayhistory`](../plugins/relayhistory/sdk/README.md).
+Move imports from `ai-hist/cloud` to that package. Git hooks and commit linking
+remain local SDK operations.
+
+## Export and durable delivery
+
+Use `exportHistory(selection)` for a bounded historical snapshot or
+`ai-hist export --selection selection.json` for NDJSON stdout. Explicitly enabled
+delivery jobs use `createHistoryDelivery`, `HistoryPluginRegistry`, and
+`drainHistoryDelivery`/`runHistoryDelivery`. The same Rust queue handles one-shot
+and background runs, immutable retries, exact acknowledgments, and worker leases.
+Native contract 14 is required. See [delivery setup and contracts](../docs/history-delivery.md).
+
+Source discovery and hydration accept `acquisitionTimeoutMs` for each selected
+connector operation, including a complete paginated snapshot. The default is
+300,000 ms; choose an integer from 1 through 3,600,000 ms. CLI acquisitions accept
+`--acquisition-timeout-ms N`; MCP acquisitions accept `acquisition_timeout_ms`.
+The same budget and cancellation signal reach the optional source helper.
+Timeouts return `SOURCE_ACQUISITION_TIMEOUT`, cancellation returns
+`SOURCE_ACQUISITION_CANCELLED`, and neither commits a partial snapshot. Typed
+source failures such as `AUTHENTICATION_EXPIRED` and `SESSION_NOT_FOUND` retain
+their public classes/codes with sanitized messages.
+
+To remove a persistent delivery exclusion, cancel affected delivery jobs first,
+clear the exclusion, then create new jobs to backfill the skipped history. A
+running or paused generation cannot rewind revisions it already skipped;
+attempting this returns `DELIVERY_GENERATION_REQUIRED`. Jobs whose selection
+permanently excludes that session or cannot include it may continue.

package/dist/cli.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import { readFile } from 'node:fs/promises';
-import { discoverSessions, ensureLocalStore, formatSessionRow, getSession, getSessionEventsPage, getSessionFileEditsPage, getSessionRelationships, getSessionToolCallsPage, getSessionTree, hydrateSession, listSessionCatalogPage, loadStoredRelayhistoryAuth, login, recent, resumeCommand, search, stats, sync, enableCloud, accessToken, replay, validateCloudExchangeBaseUrl, } from './index.js';
-import { prepareCloudSessionForEnableCloud } from './cloud-preflight.js';
-const BOOLEAN_FLAGS = new Set(['all', 'fts', 'help', 'json', 'local', 'no-bootstrap', 'no-related', 'no-warning', 'once', 'pretty', 'remote', 'version']);
+import { discoverSessions, ensureLocalStore, formatSessionRow, getSession, getSessionEventsPage, getSessionFileEditsPage, getSessionRelationships, getSessionToolCallsPage, getSessionTree, hydrateSession, listSessionCatalogPage, recent, resumeCommand, search, stats, sync, } from './index.js';
+import { runDeliveryCommand, runHistoryExportCommand, loadHistoryApplicationConfig } from './delivery-cli.js';
+const BOOLEAN_FLAGS = new Set(['all', 'fts', 'help', 'json', 'local', 'no-bootstrap', 'no-related', 'no-source-connectors', 'no-warning', 'once', 'pretty', 'remote', 'version']);
 const VALUE_FLAGS = new Set([
-    'base-url', 'interval', 'label', 'max-content', 'out', 'after', 'after-ms', 'after-session-id', 'after-source', 'before-ms', 'db', 'limit',
-    'max-depth', 'max-nodes', 'project', 'source', 'tag', 'token', 'tokens',
+    'config', 'job', 'selection', 'poll-ms', 'timeout-ms', 'base-url', 'interval', 'label', 'max-content', 'out', 'after', 'after-ms', 'after-session-id', 'after-source', 'before-ms', 'db', 'limit',
+    'max-depth', 'max-nodes', 'config', 'source-connector', 'project', 'source', 'tag', 'token', 'tokens',
 ]);
 const KNOWN_FLAGS = new Set([...BOOLEAN_FLAGS, ...VALUE_FLAGS]);
 function versionTriple(value) {
@@ -101,21 +101,17 @@ function textFlag(args, name) {
     const value = args.flags.get(name)?.at(-1);
     return typeof value === 'string' ? value : undefined;
 }
-async function relayAccessTokenForCloudCommand(command, rawArgs, args, reuseStoredAuth) {
-    const explicitToken = textFlag(args, 'token');
-    if (explicitToken !== undefined)
-        return explicitToken;
-    const baseUrl = textFlag(args, 'base-url');
-    if (reuseStoredAuth && await loadStoredRelayhistoryAuth(baseUrl))
-        return undefined;
-    const preparedToken = await prepareCloudSessionForEnableCloud(command, rawArgs, process.env);
-    if (preparedToken !== null)
-        await validateCloudExchangeBaseUrl(baseUrl);
-    return preparedToken ?? undefined;
-}
 function textFlags(args, name) {
     return (args.flags.get(name) ?? []).filter((value) => typeof value === 'string');
 }
+function sourceConnectorFlags(args) {
+    if (args.flags.has('no-source-connectors')) {
+        if (args.flags.has('source-connector'))
+            usage('--no-source-connectors and --source-connector are mutually exclusive');
+        return [];
+    }
+    return args.flags.has('source-connector') ? textFlags(args, 'source-connector') : undefined;
+}
 function numberFlag(args, name) {
     const value = textFlag(args, name);
     if (value === undefined)
@@ -204,10 +200,9 @@ function output(value, json) {
 function showHelp() {
     process.stdout.write(`Usage:
   ai-hist [--no-bootstrap] [--db PATH] [--json] [--help]
-  ai-hist enable-cloud [--base-url URL] [--token TOKEN] [--db PATH] [--interval SECONDS] [--once] [--json]
   ai-hist sessions list [--pretty] [--local | --remote | --all] [--source SOURCE]... [--limit N] [--before-ms MS] [--after JSON | --after-source SOURCE --after-session-id ID [--after-ms MS]] [--json]
-  ai-hist sessions discover [--local | --remote | --all] [--source SOURCE] [--limit N] [--json]
-  ai-hist sessions hydrate SOURCE SESSION_ID [--local | --remote | --all] [--no-related] [--db PATH] [--json]
+  ai-hist sessions discover [--local | --remote | --all] [--source-connector ID | --no-source-connectors] [--acquisition-timeout-ms N] [--source SOURCE] [--limit N] [--json]
+  ai-hist sessions hydrate SOURCE SESSION_ID [--local | --remote | --all] [--source-connector ID | --no-source-connectors] [--acquisition-timeout-ms N] [--no-related] [--db PATH] [--json]
   ai-hist sessions relationships SOURCE SESSION_ID [--db PATH] [--json]
   ai-hist sessions tree SOURCE SESSION_ID [--max-depth N] [--max-nodes N] [--db PATH] [--json]
   ai-hist sessions tools SOURCE SESSION_ID [--limit N] [--after JSON] [--db PATH] [--json]
@@ -218,11 +213,12 @@ function showHelp() {
   ai-hist events SESSION_ID [--source SOURCE] [--limit N] [--after JSON] [--json]
   ai-hist resume QUERY... [--local | --remote | --all] [--db PATH] [--fts] [--json]
   ai-hist pack QUERY... [--local | --remote | --all] [--source SOURCE] [--project PATH] [--tag TAG] [--limit N] [--tokens N] [--db PATH] [--fts] [--json]
-  ai-hist login [--base-url URL] [--token TOKEN] [--label LABEL] [--json]
-  ai-hist token [--base-url URL]
-  ai-hist replay SESSION_ID [--base-url URL] [--limit N] [--max-content N] [--json] [--out PATH] [--help]
   ai-hist stats [--local | --remote | --all] [--json]
-  ai-hist sync [--local | --remote | --all] [--db PATH] [--json]
+  ai-hist export --selection FILE [--out FILE] [--db PATH]
+  ai-hist delivery enable|drain|run --config FILE [--job ID] [--db PATH]
+  ai-hist delivery status|pause|resume|retry|cancel [--job ID] [--db PATH]
+  ai-hist plugin COMMAND --config FILE -- [ARGS...]
+  ai-hist sync [--local | --remote | --all] [--source-connector ID | --no-source-connectors] [--acquisition-timeout-ms N] [--db PATH] [--json]
 
 Every command that reads local history indexes it on first use; pass
 --no-bootstrap to answer from the store exactly as it stands.
@@ -234,10 +230,9 @@ function usage(message) {
         process.stderr.write(`ai-hist: ${message}\n\n`);
     process.stderr.write(`Usage:
   ai-hist [--no-bootstrap] [--db PATH] [--json] [--help]
-  ai-hist enable-cloud [--base-url URL] [--token TOKEN] [--db PATH] [--interval SECONDS] [--once] [--json]
   ai-hist sessions list [--pretty] [--local | --remote | --all] [--source SOURCE]... [--limit N] [--before-ms MS] [--after JSON | --after-source SOURCE --after-session-id ID [--after-ms MS]] [--json]
-  ai-hist sessions discover [--local | --remote | --all] [--source SOURCE] [--limit N] [--json]
-  ai-hist sessions hydrate SOURCE SESSION_ID [--local | --remote | --all] [--no-related] [--db PATH] [--json]
+  ai-hist sessions discover [--local | --remote | --all] [--source-connector ID | --no-source-connectors] [--acquisition-timeout-ms N] [--source SOURCE] [--limit N] [--json]
+  ai-hist sessions hydrate SOURCE SESSION_ID [--local | --remote | --all] [--source-connector ID | --no-source-connectors] [--acquisition-timeout-ms N] [--no-related] [--db PATH] [--json]
   ai-hist sessions relationships SOURCE SESSION_ID [--db PATH] [--json]
   ai-hist sessions tree SOURCE SESSION_ID [--max-depth N] [--max-nodes N] [--db PATH] [--json]
   ai-hist sessions tools SOURCE SESSION_ID [--limit N] [--after JSON] [--db PATH] [--json]
@@ -248,11 +243,12 @@ function usage(message) {
   ai-hist events SESSION_ID [--source SOURCE] [--limit N] [--after JSON] [--json]
   ai-hist resume QUERY... [--local | --remote | --all] [--db PATH] [--fts] [--json]
   ai-hist pack QUERY... [--local | --remote | --all] [--source SOURCE] [--project PATH] [--tag TAG] [--limit N] [--tokens N] [--db PATH] [--fts] [--json]
-  ai-hist login [--base-url URL] [--token TOKEN] [--label LABEL] [--json]
-  ai-hist token [--base-url URL]
-  ai-hist replay SESSION_ID [--base-url URL] [--limit N] [--max-content N] [--json] [--out PATH] [--help]
   ai-hist stats [--local | --remote | --all] [--json]
-  ai-hist sync [--local | --remote | --all] [--db PATH] [--json]
+  ai-hist export --selection FILE [--out FILE] [--db PATH]
+  ai-hist delivery enable|drain|run --config FILE [--job ID] [--db PATH]
+  ai-hist delivery status|pause|resume|retry|cancel [--job ID] [--db PATH]
+  ai-hist plugin COMMAND --config FILE -- [ARGS...]
+  ai-hist sync [--local | --remote | --all] [--source-connector ID | --no-source-connectors] [--acquisition-timeout-ms N] [--db PATH] [--json]
 
 Every command that reads local history indexes it on first use; pass
 --no-bootstrap to answer from the store exactly as it stands.
@@ -549,17 +545,11 @@ function validateInterval(args) {
 // stops `search` and `ai-hist` disagreeing about whether a store exists.
 const COMMANDS = new Map([
     ['', { name: 'ai-hist', positionals: [0, 0], allowed: ['db', 'json', 'help'], readsLocalStore: true }],
-    ['login', { name: 'login', positionals: [0, 0],
-            allowed: ['base-url', 'json', 'label', 'token'],
-            validate: (args) => {
-                if (textFlag(args, 'token') && !textFlag(args, 'base-url'))
-                    usage('login requires --base-url with --token');
-            } }],
-    ['token', { name: 'token', positionals: [0, 0], allowed: ['base-url'] }],
-    ['replay', { name: 'replay', positionals: [1, 1], requires: 'replay requires SESSION_ID',
-            allowed: ['base-url', 'limit', 'max-content', 'json', 'out', 'help'] }],
-    ['enable-cloud', { name: 'enable-cloud', positionals: [0, 0], validate: validateInterval,
-            allowed: ['base-url', 'db', 'interval', 'once', 'json', 'token'] }],
+    ['export', { name: 'export', positionals: [0, 0], allowed: ['db', 'selection', 'out'] }],
+    ['plugin', { name: 'plugin', positionals: [1, null], allowed: ['config'], requires: 'plugin requires a command name' }],
+    ...['enable', 'status', 'drain', 'run', 'pause', 'resume', 'retry', 'cancel'].map((action) => [`delivery ${action}`, {
+            name: `delivery ${action}`, positionals: [0, 0], allowed: ['db', 'config', 'job', 'poll-ms', 'timeout-ms'],
+        }]),
     ['sessions list', { name: 'sessions list', positionals: [0, 0], readsLocalStore: true,
             validate: (args) => {
                 if (args.flags.has('json') && args.flags.has('pretty'))
@@ -570,10 +560,12 @@ const COMMANDS = new Map([
                 'json', 'limit', 'local', 'pretty', 'remote', 'source',
             ] }],
     ['sessions discover', { name: 'sessions discover', positionals: [0, 0],
-            allowed: ['all', 'db', 'json', 'limit', 'local', 'remote', 'source'] }],
-    ['sessions hydrate', { name: 'sessions hydrate', positionals: [2, 2], readsLocalStore: true,
+            validate: (args) => { sourceConnectorFlags(args); },
+            allowed: ['all', 'db', 'json', 'limit', 'local', 'remote', 'source', 'config', 'source-connector', 'no-source-connectors', 'acquisition-timeout-ms'] }],
+    ['sessions hydrate', { name: 'sessions hydrate', positionals: [2, 2],
             requires: 'sessions hydrate requires SOURCE and SESSION_ID',
-            allowed: ['all', 'db', 'json', 'local', 'no-related', 'remote'] }],
+            validate: (args) => { sourceConnectorFlags(args); },
+            allowed: ['all', 'db', 'json', 'local', 'no-bootstrap', 'no-related', 'remote', 'config', 'source-connector', 'no-source-connectors', 'acquisition-timeout-ms'] }],
     ['sessions relationships', { name: 'sessions relationships', positionals: [2, 2], readsLocalStore: true,
             rejectsScope: true, requires: 'sessions relationships requires SOURCE and SESSION_ID',
             allowed: ['all', 'db', 'json', 'local', 'remote'] }],
@@ -609,35 +601,36 @@ const COMMANDS = new Map([
             allowed: ['all', 'db', 'json', 'local', 'remote', 'tag'] }],
     // sync and `sessions discover` build the store rather than read it, so they
     // do not bootstrap first; running them is itself the remedy for an empty one.
-    ['sync', { name: 'sync', positionals: [0, 0], allowed: ['all', 'db', 'json', 'local', 'remote'] }],
+    ['sync', { name: 'sync', positionals: [0, 0], validate: (args) => { sourceConnectorFlags(args); },
+            allowed: ['all', 'db', 'json', 'local', 'remote', 'config', 'source-connector', 'no-source-connectors', 'acquisition-timeout-ms'] }],
 ]);
 /** Command words consumed before the positional arguments start. */
 function commandWords(command) {
     if (command === undefined)
         return 0;
-    return command === 'sessions' ? 2 : 1;
+    return command === 'sessions' || command === 'delivery' ? 2 : 1;
 }
 function commandSpec(command, subcommand) {
     if (command === undefined)
         return COMMANDS.get('');
-    if (command === 'sessions')
-        return subcommand ? COMMANDS.get(`sessions ${subcommand}`) : undefined;
+    if (command === 'sessions' || command === 'delivery')
+        return subcommand ? COMMANDS.get(`${command} ${subcommand}`) : undefined;
     return COMMANDS.get(command);
 }
 function unknownCommandMessage(command, subcommand) {
     if (command === undefined)
         return 'invalid usage';
-    if (command === 'sessions') {
+    if (command === 'sessions' || command === 'delivery') {
         if (subcommand === undefined)
-            return 'sessions requires a subcommand';
-        return `unknown sessions subcommand '${subcommand}'`;
+            return `${command} requires a subcommand`;
+        return `unknown ${command} subcommand '${subcommand}'`;
     }
     return `unknown command '${command}'`;
 }
 // A store that was never built and a store holding no match are different
 // answers, and `No results.` is only true of the second. Wording and exit code
 // separate them; the query is not run against a store that cannot hold one.
-/** `--all` may skip remote and answer from local even when the local store is empty. */
+/** Cached remote evidence can answer an all-scope query even when local history is empty. */
 function skipUnusableStoreGate(spec, scope) {
     if (scope !== 'all')
         return false;
@@ -668,7 +661,12 @@ async function main() {
         await maybePrintUpdateNotice(version, rawArgs);
         return;
     }
-    const args = parse(rawArgs.map((arg) => arg === '-h' ? '--help' : arg));
+    const boundary = rawArgs.indexOf('--');
+    const beforeBoundary = boundary < 0 ? rawArgs : rawArgs.slice(0, boundary);
+    const separator = boundary >= 0 && parse(beforeBoundary).positional[0] === 'plugin' ? boundary : -1;
+    const pluginArgs = separator < 0 ? [] : rawArgs.slice(separator + 1);
+    const coreArgs = separator < 0 ? rawArgs : rawArgs.slice(0, separator);
+    const args = parse(coreArgs.map((arg) => arg === '-h' ? '--help' : arg));
     const [command, subcommand, ...rest] = args.positional;
     const json = args.flags.has('json');
     // Handle help before command resolution to prevent unknown command errors
@@ -678,7 +676,7 @@ async function main() {
     if (command === 'help' && subcommand === undefined && rest.length === 0) {
         showHelp();
     }
-    if (command === 'sessions' && subcommand === undefined && args.flags.has('help')) {
+    if ((command === 'sessions' || command === 'delivery') && subcommand === undefined && args.flags.has('help')) {
         showHelp();
     }
     const spec = commandSpec(command, subcommand);
@@ -704,6 +702,30 @@ async function main() {
     const sessionId = command === 'sessions' ? tail[1] : undefined;
     const recentFallback = command === 'recent' && tail.length > 0 ? Number(tail[0]) : undefined;
     const scope = scopeFlag(args);
+    if (command === 'delivery') {
+        await runDeliveryCommand(subcommand, { dbPath: textFlag(args, 'db'), configPath: textFlag(args, 'config'),
+            jobId: textFlag(args, 'job'), pollIntervalMs: numberFlag(args, 'poll-ms'), requestTimeoutMs: numberFlag(args, 'timeout-ms') });
+        return;
+    }
+    if (command === 'export') {
+        const selectionPath = textFlag(args, 'selection');
+        if (!selectionPath)
+            usage('export requires --selection FILE');
+        await runHistoryExportCommand({ dbPath: textFlag(args, 'db'), selectionPath, outputPath: textFlag(args, 'out') });
+        return;
+    }
+    if (command === 'plugin') {
+        const configPath = textFlag(args, 'config');
+        if (!configPath)
+            usage('plugin requires --config FILE');
+        const { registry } = await loadHistoryApplicationConfig(configPath);
+        const operation = registry.command(tail[0]);
+        if (!operation)
+            usage('configured plugin command not found');
+        output(await operation.run([...tail.slice(1), ...pluginArgs]), true);
+        return;
+    }
+    const acquisitionPlugins = ['sync', 'sessions'].includes(command ?? '') && textFlag(args, 'config') ? (await loadHistoryApplicationConfig(textFlag(args, 'config'))).registry : undefined;
     let readiness = null;
     if (spec.readsLocalStore) {
         readiness = await ensureLocalStore({
@@ -734,53 +756,6 @@ async function main() {
         }
         return;
     }
-    if (command === 'login') {
-        const relayAccessToken = await relayAccessTokenForCloudCommand(command, rawArgs, args, false);
-        const auth = await login({
-            baseUrl: textFlag(args, 'base-url'),
-            relayAccessToken,
-            label: textFlag(args, 'label'),
-        });
-        if (json)
-            output({ ok: true, baseUrl: auth.baseUrl }, true);
-        else
-            process.stdout.write(`Logged in to ${auth.baseUrl} (session stored).\n`);
-        return;
-    }
-    if (command === 'token') {
-        const token = await accessToken({ baseUrl: textFlag(args, 'base-url') });
-        if (process.stdout.isTTY)
-            process.stderr.write('Warning: this access token is a secret and will remain in terminal scrollback.\n');
-        process.stdout.write(`${token}\n`);
-        return;
-    }
-    if (command === 'replay') {
-        const result = await replay(subcommand, {
-            baseUrl: textFlag(args, 'base-url'), limit: nonNegativeIntFlag(args, 'limit'),
-            maxContent: nonNegativeIntFlag(args, 'max-content'), json, out: textFlag(args, 'out'),
-        });
-        if (result.transcript !== null)
-            process.stdout.write(result.transcript);
-        return;
-    }
-    if (command === 'enable-cloud') {
-        const relayAccessToken = await relayAccessTokenForCloudCommand(command, rawArgs, args, true);
-        const handle = await enableCloud({
-            baseUrl: textFlag(args, 'base-url'), dbPath: textFlag(args, 'db'),
-            relayAccessToken,
-            intervalMs: intervalSeconds * 1000,
-            watch: !args.flags.has('once'),
-            onPush: (result) => output(result, json),
-        });
-        const { stop, ...result } = handle;
-        output(result, json);
-        if (!args.flags.has('once')) {
-            const shutdown = () => { void stop(); };
-            process.once('SIGINT', shutdown);
-            process.once('SIGTERM', shutdown);
-        }
-        return;
-    }
     if (command === 'sessions' && subcommand === 'list') {
         const sources = textFlags(args, 'source');
         const page = await listSessionCatalogPage({
@@ -803,6 +778,7 @@ async function main() {
     if (command === 'sessions' && subcommand === 'discover') {
         const sources = textFlags(args, 'source');
         outputDiscovery(await discoverSessions({
+            sourceConnectors: sourceConnectorFlags(args), acquisitionTimeoutMs: numberFlag(args, 'acquisition-timeout-ms'), plugins: acquisitionPlugins,
             dbPath: textFlag(args, 'db'), scope: scopeFlag(args), sources: sources.length ? sources : undefined,
             limit: numberFlag(args, 'limit'),
         }), json);
@@ -810,6 +786,7 @@ async function main() {
     }
     if (command === 'sessions' && subcommand === 'hydrate') {
         outputHydration(await hydrateSession({
+            sourceConnectors: sourceConnectorFlags(args), acquisitionTimeoutMs: numberFlag(args, 'acquisition-timeout-ms'), plugins: acquisitionPlugins,
             source: sessionSource,
             sessionId: sessionId,
             scope: scopeFlag(args),
@@ -878,7 +855,7 @@ async function main() {
         return;
     }
     if (command === 'sync') {
-        output(await sync({ dbPath: textFlag(args, 'db'), scope: scopeFlag(args) }), json);
+        output(await sync({ dbPath: textFlag(args, 'db'), scope: scopeFlag(args), sourceConnectors: sourceConnectorFlags(args), acquisitionTimeoutMs: numberFlag(args, 'acquisition-timeout-ms'), plugins: acquisitionPlugins }), json);
         return;
     }
     usage();