@agentage/cli 0.0.3 → 0.25.0

package/dist/lib/status/vaults-status.js

@@ -0,0 +1,53 @@
+import { isAccountVault } from '@agentage/memory-core';
+import { loadVaultsConfig } from '../vault/vaults.js';
+// Config alone decides the channel: an `agentage` origin is the cloud (couch) channel, any other
+// origin is an external git remote, and no origin at all is a local-only vault (nothing to sync).
+const channelOf = (entry) => {
+    if (isAccountVault(entry))
+        return 'cloud';
+    return entry.origin?.some((o) => o.remote.trim() && o.remote.trim() !== 'agentage')
+        ? 'git'
+        : 'local';
+};
+// Live state from the daemon wins; a local-only vault is `idle` (nothing to sync), and any synced
+// vault with no daemon report is `unknown` (daemon down or the vault not yet scheduled).
+const stateFrom = (channel, live, daemonUp) => {
+    if (channel === 'local')
+        return 'idle';
+    if (!daemonUp)
+        return 'unknown';
+    if (!live)
+        return 'unknown';
+    if (live.lastError)
+        return 'error';
+    if (live.running)
+        return 'syncing';
+    return live.lastRun ? 'ok' : 'idle';
+};
+// Index the daemon's per-vault reports by name across both channels into one lookup.
+const indexLive = (sync) => {
+    const map = new Map();
+    for (const v of sync?.vaults ?? [])
+        map.set(v.vault, { running: v.running, lastError: v.lastError, lastRun: v.lastRun });
+    for (const c of sync?.couch ?? [])
+        map.set(c.vault, { running: c.running, lastError: c.lastError, lastRun: c.lastSync });
+    return map;
+};
+// The full per-vault picture: every configured vault (so local-only vaults are never hidden),
+// classified by channel and annotated with the daemon's live sync state when available.
+export const buildVaultStatuses = (sync, daemonUp, config = loadVaultsConfig().config) => {
+    const live = indexLive(sync);
+    return Object.entries(config.vaults ?? {})
+        .map(([name, entry]) => {
+        const channel = channelOf(entry);
+        const l = live.get(name);
+        return {
+            name,
+            channel,
+            status: stateFrom(channel, l, daemonUp),
+            lastRun: l?.lastRun,
+            lastError: l?.lastError,
+        };
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+};

package/dist/lib/update/update-cache.d.ts

@@ -0,0 +1,14 @@
+export interface UpdateCache {
+    checkedAt: number;
+    latest: string | null;
+}
+export declare const readUpdateCache: () => UpdateCache | null;
+export declare const updateHint: () => string | null;
+export declare const fetchLatestVersion: (timeoutMs: number, url?: string) => Promise<string | null>;
+export interface RefreshDeps {
+    now?: () => number;
+    read?: () => UpdateCache | null;
+    fetch?: () => Promise<string | null>;
+    write?: (latest: string | null, now: number) => void;
+}
+export declare const refreshUpdateCache: (deps?: RefreshDeps) => Promise<void>;

package/dist/lib/update/update-cache.js

@@ -0,0 +1,63 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ensureConfigDir, getConfigDir } from '../fs/config.js';
+import { fetchJsonUnref } from '../net/http.js';
+import { compareVersions, INSTALL_HINT, REGISTRY_URL } from './update-check.js';
+import { VERSION } from '../../utils/version.js';
+const CACHE_FILE = 'update-check.json';
+const TTL_MS = 60 * 60 * 1000; // passive checks refresh at most once an hour
+const BG_TIMEOUT_MS = 3000; // hard cap on the whole background attempt, connect included
+const cachePath = () => join(getConfigDir(), CACHE_FILE);
+export const readUpdateCache = () => {
+    try {
+        const c = JSON.parse(readFileSync(cachePath(), 'utf-8'));
+        return typeof c.checkedAt === 'number' ? c : null;
+    }
+    catch {
+        return null;
+    }
+};
+const writeUpdateCache = (latest, now) => {
+    ensureConfigDir();
+    writeFileSync(cachePath(), JSON.stringify({ checkedAt: now, latest }) + '\n', 'utf-8');
+};
+// The one dim hint line printed after a command, read purely from the cache (never the network),
+// only when the cached latest is newer than us. null = print nothing.
+export const updateHint = () => {
+    const c = readUpdateCache();
+    if (!c?.latest)
+        return null;
+    return compareVersions(VERSION, c.latest) < 0
+        ? `update available: ${c.latest} -> ${INSTALL_HINT}`
+        : null;
+};
+// Shares fetchJsonUnref (node:https, unref'd timer) so an offline background check never stalls
+// process exit the way an aborted global fetch does.
+export const fetchLatestVersion = async (timeoutMs, url = REGISTRY_URL) => {
+    const res = await fetchJsonUnref(url, timeoutMs);
+    if (!res?.ok)
+        return null;
+    const v = res.json?.version;
+    return typeof v === 'string' ? v : null;
+};
+// Fire-and-forget refresh, throttled by the TTL. checkedAt advances on FAILURE too (keeping any
+// previously known version), so an offline machine retries once an hour, not on every command.
+export const refreshUpdateCache = async (deps = {}) => {
+    const now = (deps.now ?? Date.now)();
+    const cached = (deps.read ?? readUpdateCache)();
+    if (cached && now - cached.checkedAt < TTL_MS)
+        return;
+    let version = null;
+    try {
+        version = await (deps.fetch ?? (() => fetchLatestVersion(BG_TIMEOUT_MS)))();
+    }
+    catch {
+        version = null;
+    }
+    try {
+        (deps.write ?? writeUpdateCache)(version ?? cached?.latest ?? null, now);
+    }
+    catch {
+        // total silence: a background check never disrupts a command
+    }
+};

package/dist/lib/update/update-check.d.ts

@@ -0,0 +1,27 @@
+export declare const INSTALL_HINT = "npm i -g @agentage/cli@latest";
+export declare const REGISTRY_URL = "https://registry.npmjs.org/@agentage/cli/latest";
+export interface CliLatest {
+    version: string | null;
+    minSupported: string;
+    message: string | null;
+}
+export type UpdateStatus = {
+    kind: 'current';
+} | {
+    kind: 'update-available';
+    latest: string;
+} | {
+    kind: 'unsupported';
+    latest: string | null;
+    minSupported: string;
+} | {
+    kind: 'unknown';
+};
+export interface UpdateInfo {
+    status: UpdateStatus;
+    message: string | null;
+}
+export declare const compareVersions: (a: string, b: string) => number;
+export declare const fetchCliLatest: (timeoutMs?: number) => Promise<CliLatest | null>;
+export declare const evaluateUpdate: (installed: string, latest: CliLatest | null) => UpdateInfo;
+export declare const checkForUpdate: (installed: string) => Promise<UpdateInfo>;

package/dist/lib/update/update-check.js

@@ -0,0 +1,50 @@
+// Self-update check. Reads the latest published version straight from the public npm registry
+// (the canonical source of truth for a published package). Never throws: an unreachable registry
+// or any malformed payload yields 'unknown'.
+import { fetchJsonUnref } from '../net/http.js';
+export const INSTALL_HINT = 'npm i -g @agentage/cli@latest';
+export const REGISTRY_URL = 'https://registry.npmjs.org/@agentage/cli/latest';
+// Compare dotted numeric versions (major.minor.patch); prerelease/build suffixes are
+// ignored - good enough for an update hint. Returns -1 / 0 / 1.
+export const compareVersions = (a, b) => {
+    const parts = (v) => v
+        .split('-')[0]
+        .split('.')
+        .map((n) => Number.parseInt(n, 10) || 0);
+    const pa = parts(a);
+    const pb = parts(b);
+    for (let i = 0; i < 3; i++) {
+        const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (d !== 0)
+            return d < 0 ? -1 : 1;
+    }
+    return 0;
+};
+export const fetchCliLatest = async (timeoutMs = 5000) => {
+    // node:https via fetchJsonUnref, not global fetch: undici's ref'd connect timer stalls exit.
+    const res = await fetchJsonUnref(REGISTRY_URL, timeoutMs);
+    if (!res?.ok)
+        return null;
+    const body = res.json;
+    const version = typeof body?.version === 'string' ? body.version : null;
+    if (!version)
+        return null;
+    // The registry carries no support floor or notice, so neither gates an update hint.
+    return { version, minSupported: '0.0.0', message: null };
+};
+export const evaluateUpdate = (installed, latest) => {
+    if (!latest)
+        return { status: { kind: 'unknown' }, message: null };
+    const message = latest.message;
+    if (compareVersions(installed, latest.minSupported) < 0) {
+        return {
+            status: { kind: 'unsupported', latest: latest.version, minSupported: latest.minSupported },
+            message,
+        };
+    }
+    if (latest.version && compareVersions(installed, latest.version) < 0) {
+        return { status: { kind: 'update-available', latest: latest.version }, message };
+    }
+    return { status: { kind: 'current' }, message };
+};
+export const checkForUpdate = async (installed) => evaluateUpdate(installed, await fetchCliLatest());

package/dist/lib/update/update-lock.d.ts

@@ -0,0 +1,2 @@
+export declare const acquireUpdateLock: (now?: number) => boolean;
+export declare const releaseUpdateLock: () => void;

package/dist/lib/update/update-lock.js

@@ -0,0 +1,109 @@
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ensureConfigDir, getConfigDir } from '../fs/config.js';
+const LOCK_FILE = 'update.lock';
+const LOCK_TTL_MS = 10 * 60 * 1000; // a lock older than this whose holder is gone is a crashed run
+// Past this age a holder is taken over even if its pid still resolves (pid reuse after a crash); far
+// beyond any real run or scheduler pause, so a live-but-slow holder is never mistaken for crashed.
+const STALE_HARD_MS = 30 * 60 * 1000;
+const lockPath = () => join(getConfigDir(), LOCK_FILE);
+// The lock file holds "<pid> <timestamp>": pid gates crash-takeover, the trailing token is the
+// acquisition time. A legacy single-token file parses as pid 0 (unknown holder), aging out on TTL.
+const holderOf = (path) => {
+    try {
+        const parts = readFileSync(path, 'utf-8').trim().split(/\s+/);
+        const at = Number.parseInt(parts[parts.length - 1] ?? '', 10);
+        if (Number.isNaN(at))
+            return null;
+        const pid = parts.length >= 2 ? Number.parseInt(parts[0] ?? '', 10) : 0;
+        return { pid: Number.isNaN(pid) ? 0 : pid, at };
+    }
+    catch {
+        return null;
+    }
+};
+// Same-host liveness probe. ESRCH = the holder is gone (crashed); EPERM = alive but owned by another
+// user. pid 0/unknown counts as gone so a legacy or malformed lock still ages out on the TTL.
+const holderAlive = (pid) => {
+    if (pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+};
+// A holder is safe to take over only once it is past the TTL AND provably gone: a dead pid, our own
+// leftover pid, or so old that pid reuse is the only explanation. A live holder merely starved of
+// CPU is never stolen - stealing it would let two writers run concurrently.
+const isCrashed = (holder, now) => {
+    const age = now - holder.at;
+    if (age < LOCK_TTL_MS)
+        return false;
+    if (age >= STALE_HARD_MS)
+        return true;
+    return holder.pid === process.pid || !holderAlive(holder.pid);
+};
+const unlinkQuiet = (path) => {
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        // already gone
+    }
+};
+// Serialize stale-lock takeover behind its own exclusive create, so no taker can ever delete a
+// lock that turned FRESH mid-takeover (the ABA race: reader sees the stale timestamp, a winner
+// re-creates the lock, the reader deletes the winner's file). Under the guard the staleness is
+// re-checked and only a genuinely stale lock is cleared; losers simply refuse. A guard left by a
+// crashed taker expires like the lock itself. Returns whether to re-race the create.
+const takeOverStale = (now) => {
+    const guard = `${lockPath()}.takeover`;
+    const guardHeld = holderOf(guard);
+    if (guardHeld !== null && isCrashed(guardHeld, now))
+        unlinkQuiet(guard);
+    try {
+        writeFileSync(guard, `${process.pid} ${now}`, { flag: 'wx' });
+    }
+    catch {
+        return false; // another taker is mid-takeover; let it win
+    }
+    try {
+        const holder = holderOf(lockPath());
+        if (holder !== null && !isCrashed(holder, now))
+            return false; // fresh or a live-but-slow holder
+        unlinkQuiet(lockPath());
+        return true;
+    }
+    finally {
+        unlinkQuiet(guard);
+    }
+};
+// Acquire the single-writer update lock. The O_EXCL ('wx') create IS the mutex - concurrent runs
+// cannot both win it, unlike a check-then-write. A fresh holder (younger than the TTL) refuses;
+// a stale one (crashed run) is cleared under the takeover guard and re-raced once. `now` is
+// injectable.
+export const acquireUpdateLock = (now = Date.now()) => {
+    ensureConfigDir();
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            writeFileSync(lockPath(), `${process.pid} ${now}`, { flag: 'wx' });
+            return true;
+        }
+        catch {
+            const holder = holderOf(lockPath());
+            if (holder !== null && !isCrashed(holder, now))
+                return false;
+            if (!takeOverStale(now))
+                return false;
+        }
+    }
+    return false;
+};
+export const releaseUpdateLock = () => {
+    const path = lockPath();
+    if (existsSync(path))
+        unlinkSync(path);
+};

package/dist/lib/vault/vault-registry.d.ts

@@ -0,0 +1,12 @@
+import { type VaultEntry, type VaultsConfig } from '@agentage/memory-core';
+export type VaultType = 'account' | 'git' | 'local' | 'remote';
+export declare const vaultType: (entry: VaultEntry) => VaultType;
+export declare const ensureVaultDir: (path: string) => void;
+export declare const formatVaultLine: (name: string, entry: VaultEntry) => string;
+export declare const redactEntry: (entry: VaultEntry) => VaultEntry;
+export declare const addVault: (config: VaultsConfig, name: string, entry: VaultEntry) => VaultsConfig;
+export declare const removeVault: (config: VaultsConfig, name: string) => VaultsConfig;
+export declare const appendDiscoverIgnore: (config: VaultsConfig, name: string, vaultPath: string) => {
+    config: VaultsConfig;
+    root: string;
+} | null;

package/dist/lib/vault/vault-registry.js

@@ -0,0 +1,82 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { expandPath, isAccountVault, validateConfig, } from '@agentage/memory-core';
+import { redactRemoteUrl } from '../../sync/git/remote-url.js';
+import { isValidVaultName } from './vaults.schema.js';
+// The human-facing type of an entry: an agentage origin is an account vault (local mirror +
+// cloud channel); otherwise a path with an external origin is git, a bare path is local, and an
+// origin without a path is remote.
+export const vaultType = (entry) => {
+    if (isAccountVault(entry))
+        return 'account';
+    if (entry.path)
+        return entry.origin?.length ? 'git' : 'local';
+    return 'remote';
+};
+// A local vault's markdown directory is created on `vault add` (~ is expanded).
+export const ensureVaultDir = (path) => {
+    const dir = expandPath(path);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+};
+export const formatVaultLine = (name, entry) => {
+    const kind = vaultType(entry);
+    const rawWhere = entry.path ? expandPath(entry.path) : (entry.origin?.[0]?.remote ?? '');
+    const where = entry.path ? rawWhere : redactRemoteUrl(rawWhere);
+    // Only an external git remote is worth echoing; the account channel is implied by the type.
+    const remote = kind === 'git' && entry.origin?.length
+        ? `  <- ${redactRemoteUrl(entry.origin[0].remote)}`
+        : '';
+    return `${name.padEnd(16)} ${kind.padEnd(8)} ${where}${remote}`;
+};
+// A copy of `entry` with every origin remote redacted (credentials stripped) for display/JSON;
+// the on-disk value is never mutated.
+export const redactEntry = (entry) => entry.origin?.length
+    ? { ...entry, origin: entry.origin.map((o) => ({ ...o, remote: redactRemoteUrl(o.remote) })) }
+    : entry;
+// Add an entry under `name`; the first vault added also becomes the `default`.
+export const addVault = (config, name, entry) => {
+    if (!isValidVaultName(name))
+        throw new Error(`invalid vault name: ${JSON.stringify(name)}`);
+    const vaults = config.vaults ?? {};
+    if (vaults[name])
+        throw new Error(`vault '${name}' already exists`);
+    return validateConfig({
+        ...config,
+        default: config.default ?? name,
+        vaults: { ...vaults, [name]: entry },
+    });
+};
+// Remove an entry; if it was the `default`, reassign to a remaining vault or drop the field.
+export const removeVault = (config, name) => {
+    const vaults = config.vaults ?? {};
+    if (!vaults[name])
+        throw new Error(`vault '${name}' not found`);
+    const rest = { ...vaults };
+    delete rest[name];
+    const next = { ...config, vaults: rest };
+    if (config.default === name) {
+        const fallback = Object.keys(rest)[0];
+        if (fallback)
+            next.default = fallback;
+        else
+            delete next.default;
+    }
+    return validateConfig(next);
+};
+// V8: when a removed vault sat directly under a discover root, append its name to that root's
+// `ignore` so the next scan does not re-add it. Returns the updated config plus the matched root
+// path (for the message), or null when the path is not directly under any discover root.
+export const appendDiscoverIgnore = (config, name, vaultPath) => {
+    const parent = resolve(expandPath(vaultPath), '..');
+    const roots = config.discover ?? [];
+    const idx = roots.findIndex((r) => resolve(expandPath(r.path)) === parent);
+    if (idx === -1)
+        return null;
+    const root = roots[idx];
+    if (root.ignore?.includes(name))
+        return { config, root: root.path };
+    const next = [...roots];
+    next[idx] = { ...root, ignore: [...(root.ignore ?? []), name] };
+    return { config: validateConfig({ ...config, discover: next }), root: root.path };
+};

package/dist/lib/vault/vaults.d.ts

@@ -0,0 +1,10 @@
+import { type VaultsConfig } from '@agentage/memory-core';
+export declare const vaultsJsonPath: () => string;
+export interface LoadedVaults {
+    config: VaultsConfig;
+    source: string | null;
+}
+export declare const loadVaultsConfig: () => LoadedVaults;
+export declare const ensureVaultsConfig: () => void;
+export declare const saveVaultsConfig: (config: VaultsConfig) => string;
+export declare const mutateVaultsConfig: (fn: (config: VaultsConfig) => VaultsConfig | null | void) => Promise<VaultsConfig>;

package/dist/lib/vault/vaults.js

@@ -0,0 +1,66 @@
+import { randomBytes } from 'node:crypto';
+import { chmodSync, existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { validateConfig } from '@agentage/memory-core';
+import { ensureConfigDir, getConfigDir } from '../fs/config.js';
+import { withFileLock } from '../fs/file-lock.js';
+import { VAULTS_SCHEMA_URL } from './vaults.schema.js';
+export const vaultsJsonPath = () => join(getConfigDir(), 'vaults.json');
+const EMPTY = { version: 1, vaults: {} };
+// JSON only (one format everywhere; the standalone @agentage/server-memory reads the same file
+// and parses only JSON). A missing file yields an empty config; a bad shape throws ConfigError.
+export const loadVaultsConfig = () => {
+    const path = vaultsJsonPath();
+    if (!existsSync(path))
+        return { config: EMPTY, source: null };
+    const raw = JSON.parse(readFileSync(path, 'utf-8'));
+    return { config: validateConfig(raw), source: path };
+};
+// Scaffold an empty, $schema-linked vaults.json when none exists yet, so a fresh machine always
+// has an editable file with editor autocomplete. Leaves any existing file untouched.
+export const ensureVaultsConfig = () => {
+    if (existsSync(vaultsJsonPath()))
+        return;
+    saveVaultsConfig(EMPTY);
+};
+// Atomic 0600 write. Re-injects the canonical $schema first and preserves every other field.
+export const saveVaultsConfig = (config) => {
+    ensureConfigDir();
+    const path = vaultsJsonPath();
+    const out = { $schema: VAULTS_SCHEMA_URL, version: config.version };
+    if (config.vaultsDir !== undefined)
+        out.vaultsDir = config.vaultsDir;
+    if (config.autodiscover !== undefined)
+        out.autodiscover = config.autodiscover;
+    if (config.autoInit !== undefined)
+        out.autoInit = config.autoInit;
+    if (config.default !== undefined)
+        out.default = config.default;
+    if (config.discover !== undefined)
+        out.discover = config.discover;
+    out.vaults = config.vaults ?? {};
+    // A per-save tmp name: two concurrent savers can never clobber each other's tmp file.
+    const tmp = `${path}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+    writeFileSync(tmp, JSON.stringify(out, null, 2) + '\n', { encoding: 'utf-8', mode: 0o600 });
+    renameSync(tmp, path);
+    chmodSync(path, 0o600);
+    return path;
+};
+// Cross-process-safe read-modify-write on vaults.json (issue #231). Under the advisory lock, re-read
+// FRESH from disk, apply `fn`, then atomic-save - so a concurrent `vault add` or the daemon's
+// discovery write-back can never clobber each other's update. `fn` may return a new config, mutate
+// the fresh one in place and return void, or return null to skip the write entirely (a no-op scan
+// must not re-touch the file, else the daemon's config watcher would loop). Returns the config on
+// disk after the call. A plain read stays lock-free via loadVaultsConfig.
+export const mutateVaultsConfig = async (fn) => {
+    ensureConfigDir();
+    return withFileLock(vaultsJsonPath(), () => {
+        const fresh = loadVaultsConfig().config;
+        const next = fn(fresh);
+        if (next === null)
+            return fresh; // explicit no-op: leave the file untouched
+        const result = next ?? fresh;
+        saveVaultsConfig(result);
+        return result;
+    });
+};

package/dist/lib/vault/vaults.schema.d.ts

@@ -0,0 +1,2 @@
+export declare const VAULTS_SCHEMA_URL = "https://agentage.io/schemas/vaults.schema.json";
+export { isValidVaultName, VAULT_NAME_PATTERN } from '@agentage/memory-core';

package/dist/lib/vault/vaults.schema.js

@@ -0,0 +1,10 @@
+// The vaults.json format is owned by @agentage/memory-core (validateConfig / VaultsConfig).
+// This module keeps the one CLI-surface piece memory-core does not: the editor-tooling $schema
+// pointer written on create. Name validation re-exports memory-core's single source of truth.
+// The public JSON Schema location (served by the landing). Written into the file on create so
+// editors get autocomplete + inline validation; accepted-and-ignored on load. A fixed
+// production URL by design: editor tooling fetches it regardless of the CLI's target FQDN.
+export const VAULTS_SCHEMA_URL = 'https://agentage.io/schemas/vaults.schema.json';
+// ADR-013 AA-4: every name stays a valid cloud path segment (`<sub>/<name>.git`). memory-core's
+// schema accepts any string key, so the CLI guards the name at the add surface with its allowlist.
+export { isValidVaultName, VAULT_NAME_PATTERN } from '@agentage/memory-core';

package/dist/mcp/local-server.d.ts

@@ -0,0 +1,4 @@
+import { type VaultRegistry } from '@agentage/memory-core';
+import { type McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare const createLocalMemoryServer: (registry: VaultRegistry) => McpServer;
+export declare const loadLocalMemoryServer: () => Promise<McpServer>;

package/dist/mcp/local-server.js

@@ -0,0 +1,26 @@
+import { createRegistry } from '@agentage/memory-core';
+import { createMemoryServer } from '@agentage/server-memory';
+import { loadVaultsConfig } from '../lib/vault/vaults.js';
+import { VERSION } from '../utils/version.js';
+// Restrict a registry to its offline (git working-copy) vaults, so the local MCP surface exposes
+// exactly what the DirectClient does - never a network-backed vault over the no-auth loopback.
+const localOnly = (registry) => {
+    const local = registry.list().filter((h) => h.backend.capabilities().kind === 'local');
+    const byId = new Map(local.map((h) => [h.id, h]));
+    const def = registry.default();
+    const defaultHandle = def && byId.has(def.id) ? def : undefined;
+    return {
+        list: () => local,
+        get: (id) => byId.get(id),
+        default: () => defaultHandle,
+        surfaced: () => local,
+        watch: () => () => { },
+        close: async () => { },
+    };
+};
+// Build the frozen 6-tool MCP server over one registry, reusing @agentage/server-memory's contract
+// layer verbatim (descriptions, schemas, annotations, per-connection instructions) - zero drift.
+export const createLocalMemoryServer = (registry) => createMemoryServer(localOnly(registry), { scope: 'local', version: VERSION });
+// The whole local stack: read this machine's vaults.json (the same config the daemon + CLI verbs
+// load) -> registry -> an MCP server over the surfaced local vaults.
+export const loadLocalMemoryServer = async () => createLocalMemoryServer(await createRegistry(loadVaultsConfig().config));

package/dist/sync/couch/cycle.d.ts

@@ -0,0 +1,2 @@
+import { type CouchRuntime, type CouchSyncResult, type TargetState } from './manager.types.js';
+export declare const runCouchCycle: (rt: CouchRuntime, st: TargetState) => Promise<CouchSyncResult>;

package/dist/sync/couch/cycle.js

@@ -0,0 +1,58 @@
+import { ensureWire, pendingCount } from './wire.js';
+// One couch cycle: commit dirty local truth first, drain queued pushes/deletions, then push+pull.
+// Every failure is caught and recorded (lastError / paused); it never throws to the caller.
+export const runCouchCycle = async (rt, st) => {
+    const vault = st.target.vault;
+    const build = (extra) => ({
+        vault,
+        channel: 'couch',
+        ok: true,
+        committed: false,
+        pulled: false,
+        pendingCount: pendingCount(st),
+        ...extra,
+    });
+    if (st.running)
+        return build({});
+    st.running = true;
+    try {
+        const bearer = await rt.getBearer();
+        if (!bearer) {
+            st.paused = 'signed out';
+            st.lastError = undefined;
+            return build({ paused: 'signed out' });
+        }
+        const decision = await rt.discovery.channelFor(vault, bearer);
+        if (decision.kind === 'paused') {
+            st.paused = decision.reason;
+            st.lastError = undefined;
+            return build({ paused: decision.reason });
+        }
+        st.paused = undefined;
+        const couch = await ensureWire(rt, st, decision);
+        const pre = await rt.commitDirty(st.target.path, `sync: ${rt.nowIso()}`);
+        await couch.flushPending(); // drain queued pushes AND queued deletions first
+        const res = await couch.syncNow(); // pushAll + reconcile deletions, then pullOnce
+        const post = await rt.commitDirty(st.target.path, `sync: couch ${rt.nowIso()}`);
+        if (res.error) {
+            st.lastError = res.error;
+            return build({
+                ok: false,
+                committed: pre.committed,
+                pulled: post.committed,
+                error: res.error,
+            });
+        }
+        st.lastSync = rt.nowIso();
+        st.lastError = undefined;
+        return build({ committed: pre.committed, pulled: post.committed });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        st.lastError = msg;
+        return build({ ok: false, error: msg });
+    }
+    finally {
+        st.running = false;
+    }
+};

package/dist/sync/couch/discovery.d.ts

@@ -0,0 +1,22 @@
+import { type FetchJson } from '@agentage/memory-core';
+import { type ProvisionResult } from '../../lib/auth/provision.js';
+export type ChannelDecision = {
+    kind: 'couch';
+    endpoint: string;
+    db: string;
+    tokenUrl: string;
+} | {
+    kind: 'paused';
+    reason: string;
+};
+export interface DiscoveryDeps {
+    bootstrapHost: string;
+    fetchJson: FetchJson;
+    provision: (vault: string) => Promise<ProvisionResult>;
+    now?: () => number;
+}
+export interface Discovery {
+    channelFor(vault: string, token: string): Promise<ChannelDecision>;
+    reset(): void;
+}
+export declare const createDiscovery: (deps: DiscoveryDeps) => Discovery;