@remnic/core 9.69.55 → 9.69.57

package/dist/connectors/live/registry.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @remnic/core — Live Connectors Registry (issue #683 PR 1/N)
+ *
+ * Pure in-memory registry. No I/O. Concrete connectors register themselves at
+ * orchestrator boot (later PRs); the maintenance scheduler asks the registry
+ * for the active set when running due syncs.
+ */
+import { type LiveConnector } from "./framework.js";
+/**
+ * Thrown when registering a duplicate id or an id that fails validation.
+ *
+ * Distinct error class so callers can distinguish framework-level mistakes
+ * (which are programmer errors) from connector-runtime failures.
+ */
+export declare class LiveConnectorRegistryError extends Error {
+    constructor(message: string);
+}
+/**
+ * In-memory registry of live connectors. One instance per orchestrator. Not
+ * safe for cross-process sharing — wire each process to its own registry.
+ */
+export declare class LiveConnectorRegistry {
+    private readonly connectors;
+    /**
+     * Register a connector. Throws `LiveConnectorRegistryError` if the id is
+     * malformed or already registered.
+     *
+     * Re-registration is rejected (rather than silently overwriting) because
+     * silent overwrites mask plugin loading bugs in development and could let
+     * a malicious extension shadow a built-in connector.
+     */
+    register(connector: LiveConnector): void;
+    /**
+     * Look up a connector by id. Returns `undefined` if not registered.
+     */
+    get(id: string): LiveConnector | undefined;
+    /**
+     * Return all registered connectors, sorted by id for stable enumeration.
+     */
+    list(): LiveConnector[];
+    /**
+     * Remove a connector. Returns `true` if a connector was removed, `false`
+     * otherwise. The cursor / state file on disk is **not** touched — callers
+     * who want to fully decommission a connector must also delete its state
+     * file via the `state-store` module.
+     */
+    unregister(id: string): boolean;
+    /**
+     * Number of registered connectors. Cheap; safe to call frequently.
+     */
+    size(): number;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/connectors/live/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/connectors/live/registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAsB,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAExE;;;;;GAKG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;gBACvC,OAAO,EAAE,MAAM;CAI5B;AAED;;;GAGG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoC;IAE/D;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,aAAa,GAAG,IAAI;IAkCxC;;OAEG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAI1C;;OAEG;IACH,IAAI,IAAI,aAAa,EAAE;IAIvB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAI/B;;OAEG;IACH,IAAI,IAAI,MAAM;CAGf"}

package/dist/connectors/live/state-store.d.ts

@@ -0,0 +1,120 @@
+/**
+ * @remnic/core — Live Connectors State Store (issue #683 PR 1/N)
+ *
+ * Persists per-connector cursor + sync metadata to
+ *   `<memoryDir>/state/connectors/<id>.json`
+ *
+ * Reasons this lives next to memory data, not in user config:
+ *   - cursors are *operational* state that should travel with the memory
+ *     directory when a user moves it across machines;
+ *   - it keeps memory + ingest provenance co-located so tooling that backs up
+ *     the memory directory captures cursor state too.
+ *
+ * Atomic-write contract (CLAUDE.md gotcha #54):
+ *   - We NEVER `rmSync(target)` before `renameSync(tmp, target)`.
+ *   - Writes go to a sibling tmp file and `rename()` swaps it in.
+ *   - On error, the tmp file is best-effort cleaned up; the previous good
+ *     state file is left untouched.
+ *
+ * Privacy: cursors are opaque connector-defined strings. We do not log them
+ * and do not surface them through user-visible APIs. Document content NEVER
+ * touches this module.
+ */
+import { type ConnectorCursor } from "./framework.js";
+/**
+ * Status of the most recent sync attempt for a connector.
+ *
+ * `"never"` is distinct from `"success"` so callers can detect
+ * "registered but never run" without inspecting timestamps. Per CLAUDE.md
+ * gotcha #34, we deliberately distinguish empty/unknown from failure states.
+ */
+export type ConnectorSyncStatus = "success" | "error" | "never";
+/**
+ * Persisted per-connector state.
+ *
+ * Stored as pretty-printed JSON for human inspection — the file is small
+ * (one record per connector) and operators may need to debug stuck cursors
+ * by hand.
+ */
+export interface ConnectorState {
+    /** Connector id. Matches the filename stem. */
+    readonly id: string;
+    /** Last persisted cursor, or `null` if the connector has never synced. */
+    readonly cursor: ConnectorCursor | null;
+    /** ISO 8601 timestamp of the last completed sync attempt, or `null`. */
+    readonly lastSyncAt: string | null;
+    /** Status of the last completed sync attempt. */
+    readonly lastSyncStatus: ConnectorSyncStatus;
+    /** Optional error message from the last failed sync. Truncated to 1 KB. */
+    readonly lastSyncError?: string;
+    /** Cumulative count of documents successfully imported across all syncs. */
+    readonly totalDocsImported: number;
+    /** ISO 8601 timestamp of when this state record was last written. */
+    readonly updatedAt: string;
+}
+export declare class ConnectorStateLockLostError extends Error {
+    constructor(message: string);
+}
+interface ConnectorLockLease {
+    readonly path: string;
+    readonly token: string;
+}
+interface ConnectorStateLockOptions {
+    readonly heartbeatMs?: number;
+    readonly unrefHeartbeat?: boolean;
+}
+declare function tryAcquireConnectorLock(memoryDir: string, id: string): Promise<ConnectorLockLease | null>;
+declare function unlinkStaleConnectorLock(lockPath: string): Promise<void>;
+declare function refreshConnectorLock(lease: ConnectorLockLease): Promise<boolean>;
+declare function releaseConnectorLock(lease: ConnectorLockLease): Promise<void>;
+export declare function withConnectorStateLock<T>(memoryDir: string, id: string, run: (abortSignal: AbortSignal) => Promise<T>): Promise<T>;
+export declare function _withConnectorStateLockForTest<T>(memoryDir: string, id: string, run: (abortSignal: AbortSignal) => Promise<T>, options: ConnectorStateLockOptions): Promise<T>;
+/**
+ * Read the persisted state for a single connector.
+ *
+ * Returns `null` if the file does not exist (ENOENT). Throws on any other
+ * I/O error or on shape mismatch — operators should see corruption loudly.
+ *
+ * Rejects symlinks anywhere on the path so a planted symlink can't redirect
+ * reads outside the memory root. (PR #724 review.)
+ */
+export declare function readConnectorState(memoryDir: string, id: string): Promise<ConnectorState | null>;
+/**
+ * Write state atomically: create-tmp + rename. Never destroys the previous
+ * file before the new one is in place — see CLAUDE.md gotcha #54.
+ *
+ * We accept `Omit<ConnectorState, "updatedAt">` and stamp `updatedAt`
+ * ourselves so callers can't accidentally persist a stale timestamp.
+ */
+export declare function writeConnectorState(memoryDir: string, id: string, state: Omit<ConnectorState, "updatedAt">): Promise<ConnectorState>;
+/**
+ * Enumerate every persisted connector state. Returns an empty array when
+ * the directory does not exist yet (clean install, no syncs ever run).
+ *
+ * Files that do not match the `<id>.json` naming rule are skipped — this
+ * keeps stray editor backups (`.json~`, `.swp`) from breaking enumeration.
+ *
+ * Corruption (unparseable JSON, shape mismatch, id mismatch) is also
+ * skipped so one bad file doesn't take down the listing. Operators
+ * inspecting `state/connectors/` can still see the offending file by hand.
+ *
+ * **Genuine I/O failures (`EACCES`, `EIO`, etc.) are NOT swallowed** —
+ * silently returning an incomplete state set would make active connectors
+ * appear missing and trigger duplicate ingestion on the next scheduler tick.
+ * (PR #724 review.)
+ */
+export declare function listConnectorStates(memoryDir: string): Promise<ConnectorState[]>;
+/**
+ * Test-only helper: resolve where a given connector's state lives. Exported
+ * so tests can assert the on-disk layout without duplicating the path math.
+ * Not part of the stable public API.
+ *
+ * @internal
+ */
+export declare function _connectorStatePathForTest(memoryDir: string, id: string): string;
+export declare const _unlinkStaleConnectorLockForTest: typeof unlinkStaleConnectorLock;
+export declare const _tryAcquireConnectorLockForTest: typeof tryAcquireConnectorLock;
+export declare const _refreshConnectorLockForTest: typeof refreshConnectorLock;
+export declare const _releaseConnectorLockForTest: typeof releaseConnectorLock;
+export {};
+//# sourceMappingURL=state-store.d.ts.map

package/dist/connectors/live/state-store.d.ts.map

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

package/dist/connectors/live/transient-errors.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared transient-error classifier for live connectors.
+ *
+ * All three connectors (Drive, Notion, Gmail) need to distinguish transient
+ * errors (re-throw so the pass stops without advancing the cursor — the next
+ * poll retries the same batch) from terminal errors (skip-and-continue — the
+ * resource is gone, inaccessible, or malformed in a non-recoverable way).
+ *
+ * Having three independent copies of this logic caused divergent edge-case
+ * handling (Cursor thread PRRT_kwDORJXyws59sdH4 / #745). This module is the
+ * single source of truth; all three connectors import from here.
+ *
+ * Transient classes:
+ *   - 429  (rate-limit / quota — retry after backoff)
+ *   - 5xx  (backend error — retry)
+ *   - AbortError / cancelled requests
+ *   - Network errors with no HTTP status (ECONNRESET, ETIMEDOUT, ENOTFOUND, EAI_AGAIN, …)
+ *   - Bare `Error` with no metadata (plain network failures)
+ *
+ * Terminal classes (skip-and-continue):
+ *   - 400  (bad request — won't be fixed by retrying)
+ *   - 403  (permission denied)
+ *   - 404  (resource gone or not shared)
+ *   - 410  (gone)
+ *   - Any other 4xx that isn't 429
+ *
+ * Connector-specific status properties are resolved via the `statusProps`
+ * parameter. Connectors attach their own status property name (e.g.
+ * `gmailStatus`, `notionStatus`) so the classifier can resolve it without
+ * knowing the error shape in detail.
+ */
+/**
+ * Generic transient-error classifier.
+ *
+ * Returns `true` when `err` looks transient (caller should re-throw without
+ * advancing the cursor so the next poll retries). Returns `false` for terminal
+ * errors (skip-and-continue is safe).
+ *
+ * @param err      - The caught error value.
+ * @param statusProps - Additional property names the caller attaches an HTTP
+ *                  status to (e.g. `["gmailStatus"]`, `["notionStatus"]`).
+ *                  Pass an empty array when only the generic locations are needed.
+ */
+export declare function isTransientHttpError(err: unknown, statusProps?: readonly string[]): boolean;
+//# sourceMappingURL=transient-errors.d.ts.map

package/dist/connectors/live/transient-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transient-errors.d.ts","sourceRoot":"","sources":["../../../src/connectors/live/transient-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AA6EH;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,OAAO,EACZ,WAAW,GAAE,SAAS,MAAM,EAAO,GAClC,OAAO,CA2BT"}

package/dist/connectors/materialize-paths.d.ts

@@ -0,0 +1,15 @@
+/**
+ * materialize-paths.ts — containment guard for the materializer's managed
+ * sub-directories (`rollout_summaries/`, `skills/`).
+ *
+ * Extracted from codex-materialize.ts so the skills section (issue #2369) and
+ * the rollout section share ONE containment implementation instead of forking
+ * the check (rule 22).
+ */
+/**
+ * Resolve a managed sub-directory of `memoriesDir`, creating it when absent,
+ * and refuse a symlinked or escaping target. Returns the (unchanged) path so
+ * callers can use it directly.
+ */
+export declare function ensureSafeManagedSubdir(memoriesDir: string, subdir: string, label: string): string;
+//# sourceMappingURL=materialize-paths.d.ts.map

package/dist/connectors/materialize-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"materialize-paths.d.ts","sourceRoot":"","sources":["../../src/connectors/materialize-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CA8BlG"}

package/dist/connectors/materialize-skills.d.ts

@@ -0,0 +1,52 @@
+/**
+ * materialize-skills.ts — the `skills/` section of the Codex materializer
+ * (issue #2369).
+ *
+ * Extracted from codex-materialize.ts (which sits at its structural LOC cap)
+ * so the skill staging / commit / prune rules live in one small module. Format
+ * and slug rules stay in the host-agnostic `procedural/skill-projection.ts`;
+ * this module only decides what lands on disk.
+ *
+ * Ownership rule: Remnic removes ONLY the slugs a previous run recorded in the
+ * sentinel's `projected_skills`. A skill folder a user (or another tool)
+ * created is never in that list, so it is never a removal candidate.
+ */
+import { type SkillBundle } from "../procedural/skill-projection.js";
+/** Sub-directory for projected procedural skill bundles. */
+export declare const SKILLS_SUBDIR = "skills";
+export interface SkillFile {
+    slug: string;
+    body: string;
+}
+export interface SkillPlan {
+    /** False when the caller omitted `skills` — leave `skills/` untouched. */
+    supplied: boolean;
+    /** Bundles to write, deduplicated on slug. */
+    files: SkillFile[];
+    /** Previously projected slugs this run no longer projects. */
+    retiredSlugs: string[];
+}
+/**
+ * Decide what this run writes and removes. `undefined` bundles mean "not our
+ * business this run"; an empty array is authoritative and retires everything
+ * previously projected.
+ */
+export declare function planSkillFiles(bundles: SkillBundle[] | undefined, previouslyProjectedSlugs: readonly string[]): SkillPlan;
+/** Absolute path of a projected bundle's SKILL.md under `memoriesDir`. */
+export declare function skillFilePath(memoriesDir: string, slug: string): string;
+/** Relative path recorded in `MaterializeResult.filesWritten`. */
+export declare function skillFileRelPath(slug: string): string;
+/**
+ * True when no retired folder is still on disk. Guards the idempotent
+ * early-return: a hash match is only a safe no-op if the removals also landed.
+ */
+export declare function retiredSkillsAlreadyRemoved(memoriesDir: string, retiredSlugs: readonly string[]): boolean;
+/** Render bundles into the per-run staging directory. */
+export declare function stageSkillFiles(tmpDir: string, files: readonly SkillFile[]): void;
+/**
+ * Remove retired folders, then rename each staged SKILL.md into place. Per-file
+ * renames (never directory renames) so an existing folder cannot cause
+ * ENOTEMPTY and so Codex never observes a half-written file.
+ */
+export declare function commitSkillFiles(memoriesDir: string, tmpDir: string, plan: SkillPlan): void;
+//# sourceMappingURL=materialize-skills.d.ts.map

package/dist/connectors/materialize-skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"materialize-skills.d.ts","sourceRoot":"","sources":["../../src/connectors/materialize-skills.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,EAAsC,KAAK,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAIzG,4DAA4D;AAC5D,eAAO,MAAM,aAAa,WAAW,CAAC;AAEtC,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,SAAS;IACxB,0EAA0E;IAC1E,QAAQ,EAAE,OAAO,CAAC;IAClB,8CAA8C;IAC9C,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,8DAA8D;IAC9D,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,WAAW,EAAE,GAAG,SAAS,EAClC,wBAAwB,EAAE,SAAS,MAAM,EAAE,GAC1C,SAAS,CAgBX;AAED,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED,kEAAkE;AAClE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAEzG;AAED,yDAAyD;AACzD,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,SAAS,EAAE,GAAG,IAAI,CAMjF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,IAAI,CA8B3F"}

package/dist/connectors/paths.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Connector registry directory name. Kept under the canonical `remnic` config
+ * root for new installs; legacy installs that still live under `engram` are
+ * read-transparent via {@link getActiveConnectorsConfigRoot} (issue #1518).
+ */
+export declare const REGISTRY_DIR_NAME = ".remnic-connectors";
+/**
+ * Legacy registry directory name from the engram era. Used only for the
+ * read-fallback so existing installs keep resolving until the user migrates.
+ */
+export declare const LEGACY_REGISTRY_DIR_NAME = ".engram-connectors";
+/**
+ * Single source of truth for the canonical connectors config root
+ * (`$XDG_CONFIG_HOME/remnic` or `~/.config/remnic`). New writes ALWAYS go
+ * here. Issue #1527 flagged this derivation as previously duplicated across
+ * call sites — add new callers here, never re-derive the path inline.
+ */
+export declare function getConnectorsConfigRoot(): string;
+/**
+ * Legacy config root from the engram era (`$XDG_CONFIG_HOME/engram` or
+ * `~/.config/engram`). Exposed for tests and the migration path only —
+ * production code should call {@link getActiveConnectorsConfigRoot} so the
+ * read-fallback is applied uniformly.
+ */
+export declare function getLegacyConnectorsConfigRoot(): string;
+/**
+ * Read-time fallback: pick the config root that actually holds (or will hold)
+ * the connector registry.
+ *
+ *   1. Canonical `remnic/` root when its `.remnic-connectors` registry dir
+ *      already exists (post-migration, or a fresh install that has already
+ *      written its first connector).
+ *   2. Legacy `engram/` root when ONLY its `.engram-connectors` registry dir
+ *      exists — an existing install we keep reading in place until the user
+ *      runs `remnic migrate`.
+ *   3. Canonical `remnic/` root otherwise (fresh install with no registry on
+ *      disk yet) so the first write lands at the new path.
+ *
+ * The probe looks for the REGISTRY SUBDIR (`.remnic-connectors` /
+ * `.engram-connectors`), not the bare config root. The config root
+ * `~/.config/remnic/` is created by unrelated daemon setup (e.g. the daemon's
+ * own `config.json`), so probing the bare root would falsely resolve to
+ * remnic and hide connector data that still lives under
+ * `~/.config/engram/.engram-connectors/` (cursor review round 1, #1620).
+ *
+ * This is a READ-time fallback. Writes go to whichever root this returns, so
+ * a legacy install keeps its data colocated for the active session; a fresh
+ * install writes straight to `remnic/`.
+ */
+export declare function getActiveConnectorsConfigRoot(): string;
+/**
+ * Path of the connector registry manifest file. The registry subdir name
+ * (`.remnic-connectors` vs the legacy `.engram-connectors`) is chosen from the
+ * active root so a pre-rename install reads its existing files without a
+ * rename-side migration step (#1518).
+ */
+export declare function getRegistryPath(): string;
+/**
+ * Directory holding one `<connector-id>.json` per installed connector. The
+ * registry subdir name follows the active root (see {@link getRegistryPath}).
+ */
+export declare function getConnectorsDir(): string;
+/**
+ * Sticky-legacy evidence for `emitLegacyTools` (issue #1550): any persisted
+ * connector entry under the LEGACY engram registry means an existing install
+ * whose clients may still address engram_* aliases. Missing or unreadable
+ * legacy dir means fresh install — no evidence, no aliases.
+ *
+ * Probes ONLY the legacy engram registry (`$XDG_CONFIG_HOME/engram/.engram-connectors`),
+ * never the active/canonical root. A fresh post-rename install that just
+ * wrote its first connector under `remnic/.remnic-connectors/` is NOT legacy
+ * evidence — counting it would flip `resolveEmitLegacyTools` to true and
+ * advertise deprecated `engram.*` aliases to users who never had them
+ * (#1620 review, codex P2). An unmigrated install still reports its entries
+ * here because its data lives under the engram tree.
+ */
+export declare function hasLegacyConnectorEntries(): boolean;
+//# sourceMappingURL=paths.d.ts.map

package/dist/connectors/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/connectors/paths.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,uBAAuB,CAAC;AAEtD;;;GAGG;AACH,eAAO,MAAM,wBAAwB,uBAAuB,CAAC;AAc7D;;;;;GAKG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAKhD;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,IAAI,MAAM,CAKtD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,6BAA6B,IAAI,MAAM,CAMtD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAIxC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAIzC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,IAAI,OAAO,CAWnD"}

package/dist/connectors/prime-agent.d.ts

@@ -0,0 +1,13 @@
+import type { ConnectorManifest } from "./index.js";
+/**
+ * Builtin manifest for the Prime Agent connector (#2313). Prime Agent is a
+ * Pi-fork coding agent; the runtime extension is `@remnic/plugin-pi`, published
+ * to `~/.prime/agent/extensions/remnic` (override: `PRIME_AGENT_CODING_AGENT_DIR`)
+ * by `PrimeAgentMemoryExtensionPublisher` in the plugin-pi package.
+ *
+ * Declared in this sibling module — not inline in index.ts — so the connector
+ * catalog addition does not grow index.ts past its file-size ratchet ceiling
+ * (same pattern as `DROID_CONNECTOR_MANIFEST` in droid-mcp.ts).
+ */
+export declare const PRIME_AGENT_CONNECTOR_MANIFEST: ConnectorManifest;
+//# sourceMappingURL=prime-agent.d.ts.map

package/dist/connectors/prime-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prime-agent.d.ts","sourceRoot":"","sources":["../../src/connectors/prime-agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD;;;;;;;;;GASG;AACH,eAAO,MAAM,8BAA8B,EAAE,iBAyB5C,CAAC"}

package/dist/connectors-cli.d.ts

@@ -1,2 +1,170 @@
-import './framework-CNDn2164.js';
-export { b as CONNECTORS_OUTPUT_FORMATS, c as ConnectorRow, n as ConnectorRowDefinition, C as ConnectorRunResult, a as ConnectorsOutputFormat, P as ParsedConnectorsListOptions, f as ParsedConnectorsStatusOptions, R as RunConnectorPollOnceArgs, o as buildConnectorRowsFromDefinitions, p as parseConnectorsFormat, g as parseConnectorsListOptions, h as parseConnectorsRunName, i as parseConnectorsStatusOptions, j as renderConnectorsList, k as renderConnectorsRunResult, m as runConnectorPollOnce } from './connectors-cli-2iaQ5tX2.js';
+/**
+ * `remnic connectors` CLI helpers (issue #683 PR 6/N).
+ *
+ * Three subcommands:
+ *
+ *   remnic connectors list
+ *     Lists all configured live connectors, their enabled state, last poll
+ *     time, and last error.  Output formats: text (default), markdown, json.
+ *
+ *   remnic connectors status
+ *     Identical data to `list` but defaults to JSON output so scripts can
+ *     reliably parse it.  Accepts `--format` to override.
+ *
+ *   remnic connectors run <name>
+ *     Manually triggers a single `syncIncremental()` pass for the named
+ *     connector.  Operator debug surface — useful when you want to test
+ *     credentials without waiting for the scheduler tick.  Prints the
+ *     number of new documents imported plus any error.
+ *
+ * Design decisions:
+ *
+ *   - Pure functions for list / status / run option parsing so they can be
+ *     unit-tested without booting an orchestrator (CLAUDE.md rules 14 + 51).
+ *   - Rendering lives here (not in cli.ts) so HTTP/MCP surfaces can reuse the
+ *     same output without forking formatting (CLAUDE.md rule 22).
+ *   - The `run` command requires the caller to pass a `pollFn` callback
+ *     (wrapping the actual connector's `syncIncremental`).  This keeps the
+ *     helper module free of direct orchestrator / live-connector imports while
+ *     still being testable (CLAUDE.md rule 33 — mock signatures must match
+ *     production).
+ *   - CLAUDE.md rule 51: invalid `--format` throws with listed options; unknown
+ *     connector name in `run` throws a descriptive error; `--format` without a
+ *     value is caught by Commander's built-in argument check.
+ *   - `runConnectorPollOnce` encapsulates the persist-before-cursor-advance
+ *     contract (CLAUDE.md gotcha #25, #43) so it can be unit-tested in
+ *     isolation without an orchestrator.
+ */
+import { type ConnectorCursor, type ConnectorDocument, type ConnectorState, type ConnectorSyncStatus } from "./connectors/live/index.js";
+/**
+ * A lightweight descriptor for one live connector, assembled from the parsed
+ * config and any persisted state.  The CLI handler builds this from
+ * `orchestrator.config.connectors` + `listConnectorStates(memoryDir)`.
+ */
+export interface ConnectorRow {
+    /** Stable connector id (e.g. `"google-drive"`, `"notion"`). */
+    id: string;
+    /** Human-readable display name. */
+    displayName: string;
+    /** Whether the operator has enabled this connector in config. */
+    enabled: boolean;
+    /** Persisted sync state, or `null` if no sync has ever run. */
+    state: ConnectorState | null;
+}
+export interface ConnectorRowDefinition {
+    id: string;
+    displayName: string;
+    enabled: boolean;
+}
+export declare function buildConnectorRowsFromDefinitions(definitions: readonly ConnectorRowDefinition[], states: readonly ConnectorState[]): ConnectorRow[];
+/**
+ * Result returned by the `run` command's poll function.
+ */
+export interface ConnectorRunResult {
+    /** Number of new documents imported in this pass. */
+    docsImported: number;
+    /**
+     * Error message if the sync or ingest failed, undefined on full success.
+     * When only the cursor write failed after a successful ingest, this field is
+     * undefined and `stateWriteError` carries the failure. When persisting error
+     * state fails after a sync/ingest error, both fields are set so callers can
+     * preserve the primary failure while also reporting stale persisted state.
+     */
+    error?: string;
+    /**
+     * Set when cursor/error-state persistence fails. On the success path,
+     * `docsImported` reflects the actual count of successfully ingested docs so
+     * the operator knows data was persisted even though the cursor did not
+     * advance. On the error path, `error` preserves the primary sync/ingest
+     * failure and this field reports the secondary persistence failure.
+     */
+    stateWriteError?: string;
+}
+export declare const CONNECTORS_OUTPUT_FORMATS: readonly ["text", "markdown", "json"];
+export type ConnectorsOutputFormat = (typeof CONNECTORS_OUTPUT_FORMATS)[number];
+/**
+ * Validate `--format <fmt>`.  Throws a listed-options error for any value not
+ * in `CONNECTORS_OUTPUT_FORMATS`.  Returns the given default when the value is
+ * `undefined` (no flag supplied).
+ */
+export declare function parseConnectorsFormat(value: unknown, defaultFormat?: ConnectorsOutputFormat): ConnectorsOutputFormat;
+export interface ParsedConnectorsListOptions {
+    format: ConnectorsOutputFormat;
+}
+export interface ParsedConnectorsStatusOptions {
+    /** `status` defaults to JSON for scripting; `--format` can override. */
+    format: ConnectorsOutputFormat;
+}
+/**
+ * Validate the option bag for `remnic connectors list`.
+ */
+export declare function parseConnectorsListOptions(options: Record<string, unknown>): ParsedConnectorsListOptions;
+/**
+ * Validate the option bag for `remnic connectors status`.
+ * Defaults to `json` (machine-readable) unless `--format` overrides.
+ */
+export declare function parseConnectorsStatusOptions(options: Record<string, unknown>): ParsedConnectorsStatusOptions;
+/**
+ * Validate the positional `<name>` argument for `remnic connectors run`.
+ */
+export declare function parseConnectorsRunName(rawName: unknown): string;
+/**
+ * Render connector rows for `remnic connectors list` / `remnic connectors status`.
+ */
+export declare function renderConnectorsList(rows: readonly ConnectorRow[], format: ConnectorsOutputFormat): string;
+/**
+ * Render the result of a manual `remnic connectors run <name>` invocation.
+ */
+export declare function renderConnectorsRunResult(connectorId: string, result: ConnectorRunResult, format: ConnectorsOutputFormat): string;
+/**
+ * Arguments for a single connector poll pass.
+ *
+ * All I/O is injectable so callers (cli.ts) can supply real implementations
+ * and tests can supply lightweight stubs without booting an orchestrator.
+ */
+export interface RunConnectorPollOnceArgs {
+    /** Connector identifier (used in error/success state writes). */
+    connectorId: string;
+    /** Prior persisted state, or `null` on the very first sync. */
+    priorState: ConnectorState | null;
+    /**
+     * Perform a single incremental sync.  Returns newly-fetched documents and
+     * the cursor that should be persisted on success.
+     */
+    syncFn: (cursor: ConnectorCursor | null) => Promise<{
+        newDocs: ConnectorDocument[];
+        nextCursor: ConnectorCursor;
+    }>;
+    /**
+     * Ingest fetched documents into the memory layer.  Called BEFORE the cursor
+     * is advanced.  If this throws the cursor is NOT advanced (CLAUDE.md gotcha
+     * #25 — don't destroy old state before confirming new state succeeds).
+     */
+    ingestFn: (docs: ConnectorDocument[]) => Promise<void>;
+    /**
+     * Persist connector state (cursor + metadata).  Called after `ingestFn`
+     * succeeds (success path) or when `syncFn` / `ingestFn` throws (error path,
+     * with old cursor retained).
+     */
+    writeCursorFn: (state: {
+        cursor: ConnectorCursor | null;
+        lastSyncStatus: ConnectorSyncStatus;
+        lastSyncError?: string;
+        totalDocsImported: number;
+    }) => Promise<void>;
+}
+/**
+ * Execute one `syncIncremental` pass for a live connector, enforcing the
+ * persist-before-advance-cursor contract.
+ *
+ * Invariant (CLAUDE.md gotcha #25 + #43):
+ *   1. `syncFn` fetches new docs and a next cursor.
+ *   2. `ingestFn` persists the docs into the memory layer.
+ *   3. Only if (2) succeeds does `writeCursorFn` advance the cursor.
+ *   4. If (1) or (2) throws, `writeCursorFn` is still called but retains the
+ *      **prior** cursor so the next poll re-fetches the same window.
+ *
+ * Returns the `ConnectorRunResult` that `cli.ts` uses for output rendering.
+ */
+export declare function runConnectorPollOnce(args: RunConnectorPollOnceArgs): Promise<ConnectorRunResult>;
+//# sourceMappingURL=connectors-cli.d.ts.map

package/dist/connectors-cli.d.ts.map

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