@relayhistory/capture 0.0.0 → 0.18.7

package/README.md

@@ -0,0 +1,94 @@
+# Optional RelayHistory plugin
+
+Install alongside the local SDK: `npm install ai-hist @relayhistory/capture`.
+This package owns RelayHistory authentication, legacy sharing/replay, a durable
+destination, and explicit readback/source adapters. It depends on the public
+local SDK; installing or configuring it does not log in, read credentials, or
+start uploads. `ai-hist` itself has no cloud package dependency.
+
+The matching optional platform package supplies the Rust `relayhistory-plugin`
+helper. Development builds may set `RELAYHISTORY_PLUGIN_BIN` or `binaryPath`.
+No second native addon is needed. The helper preserves existing stage auth files,
+refresh locks, error codes, and legacy cursors. Public error classes come from
+`ai-hist`, so `instanceof` retains one identity.
+
+```sh
+relayhistory-plugin login --base-url https://history.agentrelay.com
+relayhistory-plugin token --base-url https://history.agentrelay.com
+```
+
+Agent Relay Cloud sign-in runs in that Rust helper, not in JavaScript: no Cloud
+SDK is bundled and no JavaScript code reads a Cloud credential. Without
+`--token`, the helper takes `CLOUD_API_ACCESS_TOKEN`, then an unexpired Agent
+Relay CLI session at `~/.agentworkforce/relay/cloud-auth.json` matching
+`CLOUD_API_URL`, and only with a terminal attached the browser/device flow,
+whose approval URL it writes to that terminal. A run with no terminal and no
+credential fails immediately rather than waiting for an approval nobody sees.
+
+These commands intentionally remain in the optional package. Replace imports
+from `ai-hist/cloud` with `@relayhistory/capture`; local Git hook/commit-link
+functions stay in `ai-hist`.
+
+Create an explicit plugin config, located beside the application's node_modules:
+
+```json
+{"plugins":[{"module":"@relayhistory/capture","options":{"baseUrl":"https://history.agentrelay.com","instanceId":"personal"}}]}
+```
+
+Create a selection file before enabling delivery:
+
+```json
+{"all_sources":false,"sources":["claude","codex"],"sessions":[],"kinds":["history","session_event","tool_call","file_edit","session","presence","relationship","commit_link","trajectory","source_observation","observation_evidence"],"excluded_sessions":[]}
+```
+
+```sh
+ai-hist plugin relayhistory-migration-status --config history.json
+ai-hist plugin relayhistory-enable --config history.json -- --selection selection.json
+ai-hist delivery run --config history.json
+ai-hist delivery status
+```
+
+Enable creates a new explicit delivery generation. It never interprets a legacy
+positional push cursor as an acknowledgment. Stop/remove old managed launchd or
+cron push schedules first: active schedules block delivery and cannot be
+acknowledged away. If the inspection is unavailable, explicitly set
+`acknowledgeUninspectedLegacySchedules: true` after checking your own schedules;
+this acknowledges an uninspected state, not a verified clear state. Arbitrary
+user-created supervisors remain their owner's responsibility. Migration checks
+are read-only and repeat before prepare/send. Background operation uses the same
+`ai-hist delivery run` coordinator under your existing supervisor.
+
+Jobs bind both the canonical service endpoint and the auth-derived organization/
+workspace account. Changing endpoint requires a new instance/job; changing
+account requires a new job. A swapped token cannot send an old account's batch.
+The Rust queue persists the exact prepared bytes before sending. Uncertain
+outcomes retry those bytes; the server accepts exact revision IDs durably in one
+transaction and fences older revisions. No legacy `/ingest` fallback exists.
+Durable acceptance does not promise search indexing. Inspect status for blocked
+jobs, pending bytes and last acknowledgment; fix auth/config then retry explicitly.
+
+`deliveryAccount({baseUrl})` resolves the account label. Pin that result as
+`expectedAccount` in plugin options before cloud source acquisition. Remote
+acquisition is selected with `--source-connector cloud --config history.json`.
+The source adapter uses a fresh complete live readback traversal per acquisition;
+cursors are not incremental checkpoints. Normalized evidence enters the local
+engine through revision-fenced public source APIs, with independent connector
+provenance and per-kind snapshots.
+
+```ts
+import { getDeliveredSession, getSessionThreadWithHistory } from '@relayhistory/capture';
+const evidence = await getDeliveredSession({source:'claude',sessionId:'session-id'}, options);
+const thread = await getSessionThreadWithHistory({source:'claude',sessionId:'session-id'}, options);
+```
+
+`getDeliveredSession` retains returned evidence records and projects a chronological
+transcript, preferring session events over prompt fallback. The explicitly
+registered MCP `get_session_thread` includes those records plus legacy lifecycle
+links using one pinned account; `legacyStatus` exposes unavailable legacy data.
+`read_delivered_history` exposes the live listing. Neither tool is present in the
+ordinary local MCP server. Set `AI_HIST_PLUGIN_CONFIG` to register configured tools.
+
+The service applies its documented recursive credential scrubbing and omits opaque
+whole-provider blobs. Tool args, patches and normalized evidence remain readable
+within that policy; delivered data is not a byte-exact backup of raw secrets.
+See the repository's `plans/009-delivery-protocol.md` for the wire contract.

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/** Optional compatibility CLI. Local history commands remain in ai-hist. */
+import { accessToken, enableCloud, login, replay } from './cloud-client.js';
+import { createHistoryPlugin } from './plugin.js';
+async function main() {
+    const [command, ...args] = process.argv.slice(2).filter(arg => arg !== '--no-warning');
+    const flags = new Map();
+    const positionals = [];
+    const booleans = new Set(['json', 'once', 'help']);
+    for (let index = 0; index < args.length; index++) {
+        const value = args[index];
+        if (value === '-h') {
+            flags.set('help', true);
+            continue;
+        }
+        if (!value.startsWith('--')) {
+            positionals.push(value);
+            continue;
+        }
+        const [name, inline] = value.slice(2).split(/=(.*)/s);
+        if (!['json', 'once', 'help', 'base-url', 'token', 'label', 'db', 'interval', 'limit', 'max-content', 'out'].includes(name))
+            throw new Error(`Unknown option --${name}`);
+        if (booleans.has(name)) {
+            flags.set(name, true);
+            continue;
+        }
+        const text = inline ?? args[++index];
+        if (text === undefined)
+            throw new Error(`--${name} requires a value`);
+        flags.set(name, text);
+    }
+    const text = (name) => typeof flags.get(name) === 'string' ? flags.get(name) : undefined;
+    const number = (name) => { const value = text(name); if (value === undefined)
+        return undefined; const n = Number(value); if (!Number.isSafeInteger(n) || n < 0)
+        throw new Error(`--${name} must be a non-negative integer`); return n; };
+    if (flags.has('help') || !command) {
+        process.stdout.write('relayhistory-plugin login|token|replay|enable-cloud [options]\nNew reliable jobs: ai-hist plugin relayhistory-enable --config FILE -- --selection FILE\n');
+        return;
+    }
+    const baseUrl = text('base-url');
+    if (command === 'token') {
+        if ([...flags.keys()].some(key => key !== 'base-url'))
+            throw new Error('token accepts only --base-url');
+        if (positionals.length)
+            throw new Error('token takes no positional arguments');
+        process.stdout.write(`${await accessToken({ baseUrl })}\n`);
+        return;
+    }
+    if (command === 'replay') {
+        if (positionals.length !== 1)
+            throw new Error('replay requires SESSION_ID');
+        const result = await replay(positionals[0], { baseUrl, limit: number('limit'), maxContent: number('max-content'), json: flags.has('json'), out: text('out') });
+        if (result.transcript !== null)
+            process.stdout.write(result.transcript);
+        return;
+    }
+    if (command === 'login' || command === 'enable-cloud') {
+        if (positionals.length)
+            throw new Error(`${command} takes no positional arguments`);
+        if (command === 'login' && text('token') && !baseUrl)
+            throw new Error('login requires --base-url with --token');
+        // Agent Relay Cloud sign-in, its credential precedence and its destination
+        // gate all run in the Rust helper; this only reports whether a terminal is
+        // attached, so a browser approval is never started where nobody sees it.
+        const token = text('token');
+        if (command === 'login') {
+            const auth = await login({ baseUrl, relayAccessToken: token, label: text('label'), ...(token ? {} : { interactive: process.stdin.isTTY === true }) });
+            process.stdout.write(flags.has('json') ? JSON.stringify({ ok: true, base_url: auth.baseUrl }) + '\n' : `Logged in to ${auth.baseUrl} (session stored).\n`);
+            return;
+        }
+        const handle = await enableCloud({ baseUrl, dbPath: text('db'), relayAccessToken: token, ...(token ? {} : { interactive: process.stdin.isTTY === true }), intervalMs: (number('interval') ?? 60) * 1000, watch: !flags.has('once'), onPush: result => process.stdout.write(JSON.stringify({ base_url: result.baseUrl, sent: result.sent, accepted: result.accepted, sync_skipped: result.syncSkipped }) + '\n') });
+        const { stop, ...result } = handle;
+        process.stdout.write(JSON.stringify({ base_url: result.baseUrl, sent: result.sent, accepted: result.accepted, sync_skipped: result.syncSkipped }) + '\n');
+        process.once('SIGINT', () => void stop());
+        process.once('SIGTERM', () => void stop());
+        return;
+    }
+    const operation = createHistoryPlugin({ baseUrl }).commands?.find(item => item.name === command);
+    if (!operation)
+        throw new Error('Unknown RelayHistory plugin command');
+    process.stdout.write(JSON.stringify(await operation.run(args)) + '\n');
+}
+main().catch(error => { process.stderr.write((error instanceof Error ? error.message : 'RelayHistory operation failed') + '\n'); process.exitCode = 2; });
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/cloud-client.d.ts

@@ -0,0 +1,225 @@
+export interface RelayhistoryAuth {
+    baseUrl: string;
+    accessToken: string;
+    refreshToken?: string;
+    accessTokenExpiresAt?: string;
+    /** Cached provenance; never an authorization selector. */
+    orgId?: string;
+    workspaceId?: string;
+}
+export type LoginCloudResult = {
+    ok: true;
+    auth: RelayhistoryAuth;
+} | {
+    ok: false;
+    error: string;
+};
+export interface CloudPushResult {
+    baseUrl: string;
+    sent: number;
+    accepted: number;
+    syncSkipped: boolean;
+}
+/** Return a secret service token with at least 60 seconds of validity. Rust
+ * selects the stage, refreshes if needed and atomically saves rotated tokens. */
+export declare function accessToken(options?: {
+    baseUrl?: string;
+}): Promise<string>;
+export interface ReplayOptions {
+    baseUrl?: string;
+    /** Page size, not a total cap; Rust fetches every page in server order. */
+    limit?: number;
+    maxContent?: number;
+    /** Return the raw event array serialized as JSON instead of readable text. */
+    json?: boolean;
+    /** Atomically save in Rust after all pages succeed; transcript is then null. */
+    out?: string;
+}
+export interface ReplayResult {
+    eventCount: number;
+    transcript: string | null;
+    outputPath: string | null;
+}
+/** Fetch a cloud transcript without opening or importing into the local DB. */
+export declare function replay(sessionId: string, options?: ReplayOptions): Promise<ReplayResult>;
+export interface CloudOptions {
+    dbPath?: string;
+    baseUrl?: string;
+    relayAccessToken?: string;
+    label?: string;
+    /** Without a token, Rust may start the browser device flow only when this is true. */
+    interactive?: boolean;
+    /** Optional workspace selector for the Cloud sign-in Rust performs. */
+    workspace?: string;
+}
+export interface EnableCloudOptions extends CloudOptions {
+    /** Keep syncing until stop() is called. Defaults to true. */
+    watch?: boolean;
+    intervalMs?: number;
+    onPush?: (result: CloudPushResult) => void;
+    onError?: (error: unknown) => void;
+}
+export interface CloudHandle extends CloudPushResult {
+    stop(): Promise<void>;
+}
+/** Both SDK consumers and the engine use the same stage-scoped Rust auth store. */
+export declare function loadStoredRelayhistoryAuth(baseUrl?: string): Promise<RelayhistoryAuth | null>;
+export type CloudSessionResolution = {
+    auth: RelayhistoryAuth;
+    /** Marks a stored session eligible for native refresh after a 401. Omit for caller-managed auth. */
+    session?: true;
+} | {
+    auth: null;
+    detail: string;
+};
+/** Read-only connector probe; stage selection and eligibility belong to Rust. */
+export declare function resolveCloudSession(baseUrl?: string, now?: number): Promise<CloudSessionResolution>;
+/** Rotate a rejected stored bearer under the native stage lock. */
+export declare function refreshCloudSession(baseUrl: string, rejectedToken: string): Promise<RelayhistoryAuth | null>;
+export interface LoginOptions {
+    baseUrl?: string;
+    /**
+     * An Agent Relay Cloud bearer to exchange. Omit it to let Rust resolve
+     * identity itself: `CLOUD_API_ACCESS_TOKEN`, then the Agent Relay CLI session
+     * file, then — only with {@link interactive} — the OAuth device flow.
+     */
+    relayAccessToken?: string;
+    label?: string;
+    /**
+     * Whether Rust may run the browser/device flow and write its approval URL to
+     * the controlling terminal. Without it a login that has no usable credential
+     * fails fast instead of waiting for an approval nobody can see.
+     */
+    interactive?: boolean;
+    /** Optional workspace selector for the Cloud sign-in Rust performs. */
+    workspace?: string;
+}
+/**
+ * Exchange an Agent Relay Cloud bearer for a RelayHistory session.
+ *
+ * Sign-in itself lives in the Rust helper: this passes the request through and
+ * never obtains, stores or inspects a Cloud credential in JavaScript.
+ */
+export declare function login(options?: LoginOptions): Promise<RelayhistoryAuth>;
+export declare function loginCloud(relayAccessToken: string, options?: {
+    baseUrl?: string;
+    label?: string;
+}): Promise<LoginCloudResult>;
+export declare function pushCloud(options?: CloudOptions): Promise<CloudPushResult>;
+/** Device login, service-token exchange and first push run in Rust. The optional
+ * loop is host orchestration only: no token, refresh, stage or cursor logic in JS.
+ * The loop remains in this process; await stop() before shutdown. */
+export declare function enableCloud(options?: EnableCloudOptions): Promise<CloudHandle>;
+export type TraceVisibility = 'public' | 'private' | 'direct-link';
+export interface ShareableTrace {
+    url: string;
+    visibility: TraceVisibility;
+    eventCount: number;
+}
+/** Share the already-pushed, frozen server snapshot of a session. */
+export declare function createShareableTrace(sessionId: string, options: {
+    visibility: TraceVisibility;
+    source?: string;
+    baseUrl?: string;
+}): Promise<ShareableTrace>;
+/**
+ * The unsupported-operation message, in the shape the sibling remote
+ * connectors use.
+ *
+ * The leading phrase `no remote provider connectors are configured` is an
+ * explicit compatibility contract that callers and tests match on — see
+ * `crates/ai-hist/src/remote.rs::unconfigured_message`, whose format this
+ * reproduces for the one connector a thread can be served by (`cloud`).
+ */
+export declare function cloudUnconfiguredMessage(operation: string, detail: string): string;
+/** One lifecycle link, as the recall API returns it. */
+export interface SessionThreadLink {
+    linkKind: string;
+    linkRef: string;
+    linkUrl: string | null;
+    /** ISO 8601, up to six fractional digits. Null for undated links. */
+    linkTs: string | null;
+    metadata: unknown;
+    /** 0..1, converted server-side from stored basis points. */
+    confidence: number | null;
+}
+/** One shipped-commit outcome, as the recall API returns it. */
+export interface SessionThreadOutcome {
+    commitSha: string;
+    shippedAt: string | null;
+    reverted: boolean;
+    revertedBySha: string | null;
+    revertedAt: string | null;
+}
+/**
+ * The `GET /v1/sessions/:sessionId/thread` envelope. This is a description of
+ * what the recall API returns, not a normalization target: the envelope
+ * reaches the caller exactly as the service sent it, so a field this SDK build
+ * does not know about is passed through rather than dropped.
+ */
+export interface SessionThread {
+    session: {
+        source: string;
+        sessionId: string;
+        orgId: string;
+        workspaceId: string;
+        firstEventAt: string | null;
+        lastEventAt: string | null;
+    } | null;
+    outcomes: SessionThreadOutcome[];
+    links: SessionThreadLink[];
+    nextCursor: string | null;
+}
+export interface SessionThreadQuery {
+    /** Upstream source. Validated against this build's source list. */
+    source: string;
+    /** The session id. Carried in the path, never as a query parameter. */
+    sessionId: string;
+    /**
+     * Optional `link_kind` filter, at most {@link MAX_THREAD_KINDS} values. Sent
+     * comma-separated, as the route expects. Not validated against a fixed list:
+     * new lenses add kinds, and the route filters on whatever it is given.
+     */
+    kinds?: readonly string[];
+    /** Optional ISO 8601 lower bound. */
+    since?: string;
+    /** Opaque page cursor from a previous `nextCursor`. */
+    cursor?: string;
+    /**
+     * Links per page. The route clamps to {@link MIN_THREAD_LIMIT}..{@link
+     * MAX_THREAD_LIMIT} and defaults to 100. Only links are paged; outcomes come
+     * back whole on every page.
+     */
+    limit?: number;
+}
+export interface SessionThreadOptions {
+    /** Overrides the stored session's base URL. */
+    baseUrl?: string;
+    /**
+     * The connector-status resolver: a usable stored RelayHistory session means
+     * the `cloud` connector is configured, and anything else carries the reason
+     * it is not. Defaults to {@link resolveCloudSession}.
+     * Return `{ auth }` without `session: true` for caller-managed credentials or
+     * isolated mocks: a 401 then throws AuthenticationExpiredError without refresh.
+     */
+    resolveSession?: (requestedBaseUrl?: string) => Promise<CloudSessionResolution>;
+    /**
+     * Transport for thread GET requests and their retries. Defaults to global fetch.
+     * Does not handle authentication requests: stored-session refresh uses Rust's
+     * native HTTP client and can make a real network request after a 401, even when
+     * this function is a mock. Proxy and TLS settings here do not configure refresh.
+     * For isolated mocks, also provide resolveSession returning `{ auth }` without
+     * `session: true`, which disables automatic refresh.
+     */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Fetch one page of a session's lifecycle thread from the recall API.
+ *
+ * Cloud-only. When no RelayHistory session is stored the `cloud` connector is
+ * unconfigured and this throws {@link UnsupportedOperationError} *without
+ * performing a network call* — the same classification the native engine gives
+ * a remote-only request no connector can serve.
+ */
+export declare function getSessionThread(query: SessionThreadQuery, opts?: SessionThreadOptions): Promise<SessionThread>;
+//# sourceMappingURL=cloud-client.d.ts.map

package/dist/cloud-client.d.ts.map

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