aismemory 0.6.0 → 0.6.1

package/dist/cli/doctor.d.ts

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import { type OAuthCredentials } from '../oauth-credentials.js';
+export type CheckStatus = 'PASS' | 'WARN' | 'FAIL';
+export interface CheckResult {
+    name: string;
+    status: CheckStatus;
+    message: string;
+    hint?: string;
+}
+export interface DoctorReport {
+    aisUrl: string;
+    checks: CheckResult[];
+    problemCount: number;
+    verdict: 'pass' | 'problems';
+    exitCode: 0 | 1;
+}
+export declare function checkNodeVersion(nodeVersion?: string, minMajor?: number): CheckResult;
+export interface DnsLookupFn {
+    (hostname: string): Promise<{
+        address: string;
+        family: number;
+    }>;
+}
+export declare function checkDnsResolution(host: string, lookup?: DnsLookupFn): Promise<CheckResult>;
+export interface TlsProbeFn {
+    (host: string, port: number, timeoutMs: number): Promise<void>;
+}
+export declare function checkTlsReachability(host: string, probe?: TlsProbeFn, port?: number, timeoutMs?: number): Promise<CheckResult>;
+export type FetchFn = typeof fetch;
+export interface RestHealthResult extends CheckResult {
+    /** The `Date` response header, if present — reused by the clock-skew check. */
+    dateHeader?: string;
+}
+export declare function checkRestHealth(baseUrl: string, fetchImpl?: FetchFn): Promise<RestHealthResult>;
+export declare function checkMcpEndpoint(baseUrl: string, fetchImpl?: FetchFn): Promise<CheckResult>;
+export interface CredentialsCheckDeps {
+    load?: (home?: string) => OAuthCredentials | null;
+    now?: () => number;
+    fetchImpl?: FetchFn;
+    home?: string;
+}
+export declare function checkCredentials(baseUrl: string, deps?: CredentialsCheckDeps): Promise<CheckResult>;
+export declare function checkProxyEnv(env?: NodeJS.ProcessEnv): CheckResult;
+export declare function checkClockSkew(dateHeader: string | undefined, now?: () => number, warnThresholdMs?: number): CheckResult;
+export interface DoctorOptions {
+    aisUrl?: string;
+    env?: NodeJS.ProcessEnv;
+    nodeVersion?: string;
+    now?: () => number;
+    fetchImpl?: FetchFn;
+    dnsLookup?: DnsLookupFn;
+    tlsProbe?: TlsProbeFn;
+    loadCreds?: (home?: string) => OAuthCredentials | null;
+    home?: string;
+}
+export declare function runDoctor(options?: DoctorOptions): Promise<DoctorReport>;
+export declare function main(argv?: string[]): Promise<void>;

package/dist/cli/doctor.js

@@ -0,0 +1,332 @@
+#!/usr/bin/env node
+/**
+ * `aismemory doctor` — read-only self-diagnosis for "it doesn't work" reports.
+ *
+ * A new user whose MCP client can't reach AIS has no way to tell whether the
+ * problem is DNS, a corporate proxy, an unbonded agent, an expired token, or
+ * clock skew. This command runs a fixed set of read-only checks against the
+ * local environment and the AIS host and prints a PASS/WARN/FAIL report with
+ * a one-line remediation hint per problem — no writes to the API, no agent
+ * creation.
+ *
+ * Usage:
+ *   npx aismemory doctor
+ *   npx aismemory doctor --json
+ *   AIS_URL=https://other.example.com npx aismemory doctor
+ *
+ * Exit codes:
+ *   0 — no FAIL checks (WARNs are still reported but don't fail the command)
+ *   1 — at least one FAIL check
+ */
+import { lookup as dnsLookupDefault } from 'node:dns/promises';
+import { connect as tlsConnectDefault } from 'node:tls';
+import { loadOAuthCredentials, credentialsFilePath } from '../oauth-credentials.js';
+import { isCredsStale } from '../auth-staleness.js';
+/** Minimum Node major version this package requires (per @modelcontextprotocol/sdk engines). */
+const MIN_NODE_MAJOR = 18;
+const PROXY_ENV_KEYS = ['HTTPS_PROXY', 'https_proxy', 'HTTP_PROXY', 'http_proxy', 'NO_PROXY', 'no_proxy'];
+const CLOCK_SKEW_WARN_MS = 5 * 60 * 1000;
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+// ── Individual checks ────────────────────────────────────
+export function checkNodeVersion(nodeVersion = process.version, minMajor = MIN_NODE_MAJOR) {
+    const match = /^v?(\d+)\./.exec(nodeVersion);
+    const major = match ? Number(match[1]) : NaN;
+    if (Number.isNaN(major)) {
+        return {
+            name: 'Node version',
+            status: 'WARN',
+            message: `Could not parse Node version string "${nodeVersion}".`,
+            hint: `aismemory requires Node >= ${minMajor}.`,
+        };
+    }
+    if (major < minMajor) {
+        return {
+            name: 'Node version',
+            status: 'FAIL',
+            message: `Node ${nodeVersion} is below the required minimum (>= ${minMajor}).`,
+            hint: `Upgrade Node (e.g. via nvm: "nvm install ${minMajor}") and retry.`,
+        };
+    }
+    return {
+        name: 'Node version',
+        status: 'PASS',
+        message: `Node ${nodeVersion} meets the minimum requirement (>= ${minMajor}).`,
+    };
+}
+export async function checkDnsResolution(host, lookup = dnsLookupDefault) {
+    try {
+        const { address } = await lookup(host);
+        return {
+            name: 'DNS resolution',
+            status: 'PASS',
+            message: `${host} resolves to ${address}.`,
+        };
+    }
+    catch (err) {
+        return {
+            name: 'DNS resolution',
+            status: 'FAIL',
+            message: `Could not resolve DNS for ${host}: ${errMsg(err)}.`,
+            hint: 'Check your internet connection and DNS settings (or /etc/resolv.conf).',
+        };
+    }
+}
+function defaultTlsProbe(host, port, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const socket = tlsConnectDefault({ host, port, servername: host, timeout: timeoutMs }, () => {
+            if (settled)
+                return;
+            settled = true;
+            socket.end();
+            resolve();
+        });
+        socket.on('error', (err) => {
+            if (settled)
+                return;
+            settled = true;
+            reject(err);
+        });
+        socket.on('timeout', () => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            reject(new Error(`connection to ${host}:${port} timed out after ${timeoutMs}ms`));
+        });
+    });
+}
+export async function checkTlsReachability(host, probe = defaultTlsProbe, port = 443, timeoutMs = 5000) {
+    try {
+        await probe(host, port, timeoutMs);
+        return {
+            name: 'TLS reachability',
+            status: 'PASS',
+            message: `${host}:${port} accepts TLS connections.`,
+        };
+    }
+    catch (err) {
+        return {
+            name: 'TLS reachability',
+            status: 'FAIL',
+            message: `Could not open a TLS connection to ${host}:${port}: ${errMsg(err)}.`,
+            hint: 'A firewall, VPN, or corporate proxy may be blocking outbound HTTPS. See the proxy check below.',
+        };
+    }
+}
+export async function checkRestHealth(baseUrl, fetchImpl = fetch) {
+    const url = `${baseUrl}/livez`;
+    try {
+        const res = await fetchImpl(url);
+        const dateHeader = res.headers.get('date') ?? undefined;
+        if (res.ok) {
+            return {
+                name: 'REST API health',
+                status: 'PASS',
+                message: `${url} responded HTTP ${res.status} (alive).`,
+                dateHeader,
+            };
+        }
+        return {
+            name: 'REST API health',
+            status: 'WARN',
+            message: `${url} responded HTTP ${res.status} — server reachable but reporting a problem.`,
+            hint: 'The AIS backend may be degraded. Check again shortly.',
+            dateHeader,
+        };
+    }
+    catch (err) {
+        return {
+            name: 'REST API health',
+            status: 'FAIL',
+            message: `Could not reach ${url}: ${errMsg(err)}.`,
+            hint: 'Check network connectivity — see the DNS/TLS checks above.',
+        };
+    }
+}
+export async function checkMcpEndpoint(baseUrl, fetchImpl = fetch) {
+    const url = `${baseUrl}/mcp`;
+    try {
+        const res = await fetchImpl(url);
+        // Any resolved HTTP response (even 401 "auth required") proves the MCP
+        // endpoint is reachable — only a network-level failure means "down".
+        const authNote = res.status === 401 || res.status === 403 ? ' (auth required, as expected without a key)' : '';
+        return {
+            name: 'MCP HTTP endpoint',
+            status: 'PASS',
+            message: `${url} responded HTTP ${res.status}${authNote}.`,
+        };
+    }
+    catch (err) {
+        return {
+            name: 'MCP HTTP endpoint',
+            status: 'FAIL',
+            message: `Could not reach ${url}: ${errMsg(err)}.`,
+            hint: 'Check network connectivity — see the DNS/TLS checks above.',
+        };
+    }
+}
+export async function checkCredentials(baseUrl, deps = {}) {
+    const load = deps.load ?? loadOAuthCredentials;
+    const now = deps.now ?? Date.now;
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const home = deps.home;
+    const path = credentialsFilePath(home);
+    const creds = load(home);
+    if (!creds) {
+        return {
+            name: 'Credentials',
+            status: 'WARN',
+            message: `No credentials found at ${path} — this device has not bonded to an agent yet.`,
+            hint: 'Run any aismemory tool from your MCP client once and follow the printed bond URL/code (takes ~30s).',
+        };
+    }
+    if (isCredsStale(creds.expiresAt, now())) {
+        return {
+            name: 'Credentials',
+            status: 'WARN',
+            message: `Credentials at ${path} are expired or expiring within 5 minutes (expiresAt: ${creds.expiresAt}).`,
+            hint: 'No action needed — the next tool call re-authenticates automatically (silently if a device key is enrolled).',
+        };
+    }
+    try {
+        const res = await fetchImpl(`${baseUrl}/v1/agents/${creds.agentId}`, {
+            headers: { Authorization: `Bearer ${creds.token}` },
+        });
+        if (res.ok) {
+            return {
+                name: 'Credentials',
+                status: 'PASS',
+                message: `Bonded as agent ${creds.agentId}; AIS accepted the saved token.`,
+            };
+        }
+        return {
+            name: 'Credentials',
+            status: 'WARN',
+            message: `Saved credentials found, but AIS returned HTTP ${res.status} for agent ${creds.agentId}.`,
+            hint: 'The token may be revoked or the agent archived. Re-run any aismemory tool to trigger re-authentication.',
+        };
+    }
+    catch (err) {
+        return {
+            name: 'Credentials',
+            status: 'FAIL',
+            message: `Could not verify saved credentials with AIS: ${errMsg(err)}.`,
+            hint: 'Check network connectivity — see the REST API health check above.',
+        };
+    }
+}
+export function checkProxyEnv(env = process.env) {
+    const set = PROXY_ENV_KEYS.filter((key) => Boolean(env[key]));
+    if (set.length === 0) {
+        return {
+            name: 'Proxy environment',
+            status: 'PASS',
+            message: 'No HTTP(S)_PROXY / NO_PROXY environment variables set.',
+        };
+    }
+    return {
+        name: 'Proxy environment',
+        status: 'WARN',
+        message: `Proxy environment variable(s) detected: ${set.join(', ')}.`,
+        hint: 'A corporate proxy can block or MITM TLS to ais.agentsandswarms.ai. If aismemory only fails on this network, ask IT to allowlist the host or trust the proxy CA.',
+    };
+}
+export function checkClockSkew(dateHeader, now = Date.now, warnThresholdMs = CLOCK_SKEW_WARN_MS) {
+    if (!dateHeader) {
+        return {
+            name: 'Clock skew',
+            status: 'WARN',
+            message: 'No server Date header available to compare (REST API health check did not return one).',
+        };
+    }
+    const remoteMs = Date.parse(dateHeader);
+    if (Number.isNaN(remoteMs)) {
+        return {
+            name: 'Clock skew',
+            status: 'WARN',
+            message: `Could not parse the server Date header: "${dateHeader}".`,
+        };
+    }
+    const skewMs = Math.abs(now() - remoteMs);
+    const skewMinutes = (skewMs / 60000).toFixed(1);
+    if (skewMs > warnThresholdMs) {
+        return {
+            name: 'Clock skew',
+            status: 'WARN',
+            message: `Local clock differs from the AIS server by ~${skewMinutes} minutes.`,
+            hint: 'Large clock skew can invalidate OAuth tokens. Sync your system clock (e.g. enable automatic time/NTP).',
+        };
+    }
+    return {
+        name: 'Clock skew',
+        status: 'PASS',
+        message: `Local clock is within ${skewMinutes} min of the AIS server.`,
+    };
+}
+export async function runDoctor(options = {}) {
+    const env = options.env ?? process.env;
+    const aisUrl = options.aisUrl ?? env['AIS_URL'] ?? 'https://ais.agentsandswarms.ai';
+    const host = new URL(aisUrl).hostname;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const now = options.now ?? Date.now;
+    const checks = [];
+    checks.push(checkNodeVersion(options.nodeVersion));
+    checks.push(await checkDnsResolution(host, options.dnsLookup));
+    checks.push(await checkTlsReachability(host, options.tlsProbe));
+    const health = await checkRestHealth(aisUrl, fetchImpl);
+    checks.push(health);
+    checks.push(await checkMcpEndpoint(aisUrl, fetchImpl));
+    checks.push(await checkCredentials(aisUrl, {
+        fetchImpl,
+        load: options.loadCreds,
+        home: options.home,
+        now,
+    }));
+    checks.push(checkProxyEnv(env));
+    checks.push(checkClockSkew(health.dateHeader, now));
+    const problemCount = checks.filter((c) => c.status !== 'PASS').length;
+    const hasFail = checks.some((c) => c.status === 'FAIL');
+    return {
+        aisUrl,
+        checks,
+        problemCount,
+        verdict: problemCount === 0 ? 'pass' : 'problems',
+        exitCode: hasFail ? 1 : 0,
+    };
+}
+// ── CLI formatting + entrypoint ──────────────────────────
+function formatText(report) {
+    const lines = [];
+    lines.push(`aismemory doctor — ${report.aisUrl}`);
+    lines.push('');
+    for (const c of report.checks) {
+        lines.push(`[${c.status}] ${c.name}: ${c.message}`);
+        if (c.hint && c.status !== 'PASS') {
+            lines.push(`       hint: ${c.hint}`);
+        }
+    }
+    lines.push('');
+    lines.push(report.problemCount === 0
+        ? 'doctor: all checks passed'
+        : `doctor: ${report.problemCount} problem(s) found`);
+    return lines.join('\n');
+}
+export async function main(argv = process.argv.slice(2)) {
+    const json = argv.includes('--json');
+    const report = await runDoctor();
+    if (json) {
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    }
+    else {
+        process.stdout.write(`${formatText(report)}\n`);
+    }
+    process.exit(report.exitCode);
+}
+main().catch((err) => {
+    process.stderr.write(`[aismemory doctor] Fatal: ${errMsg(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=doctor.js.map

package/dist/cli/doctor.js.map

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

package/dist/index.js

@@ -224,31 +224,31 @@ class BondPendingError extends Error {
     userCode;
     bondPending = true;
     constructor(verificationUri, userCode) {
-        super(`Memory bond required.\n\n` +
+        super(`Memory bond required — ask your human to approve now.\n\n` +
             `Visit: ${verificationUri}\n` +
             `Code: ${userCode}\n\n` +
-            `Enter your email and tap Approve, then retry this tool. Takes about 30 seconds.`);
+            `Enter your email and tap Approve, then retry this tool. Takes about 30 seconds.\n` +
+            `Heads up: this code expires in 30 minutes, and unclaimed agents (and their memories) are archived after 7 days.`);
         this.verificationUri = verificationUri;
         this.userCode = userCode;
         this.name = 'BondPendingError';
     }
 }
-async function startDeviceFlow() {
+async function startDeviceFlow(priorProvisionalToken) {
     emitTelemetry({ event: 'auth.device_flow.start' });
     stderr('Starting authentication...');
-    const authRes = (await aisPost('/v1/oauth/device/authorize', {
-        name: `agent-${homedir().split('/').pop() ?? 'user'}`,
-    }));
+    const authRes = (await aisPost('/v1/oauth/device/authorize', { name: `agent-${homedir().split('/').pop() ?? 'user'}` }, priorProvisionalToken));
     if (!authRes.success || !authRes.data) {
         throw new Error(`Authentication failed: ${authRes.error?.message ?? 'Unknown error'}`);
     }
-    const { device_code, user_code, verification_uri_complete, interval, agent_id, provisional_tenant_id } = authRes.data;
+    const { device_code, user_code, verification_uri_complete, interval, agent_id, provisional_tenant_id, provisional_token } = authRes.data;
     stderr('');
     stderr('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
     stderr('  aismemory — memory bond required');
     stderr('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
     stderr(`  Bond URL : ${verification_uri_complete}`);
     stderr(`  Code     : ${user_code}`);
+    stderr('  Code expires in 30 min; unclaimed agents are archived after 7 days.');
     stderr('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
     const flow = {
         device_code,
@@ -256,6 +256,7 @@ async function startDeviceFlow() {
         verification_uri_complete,
         agent_id,
         provisional_tenant_id,
+        provisional_token,
         // poll is assigned below after flowRef is captured so pollForToken holds
         // a reference to the live flow object for URL updates on auto-restart.
         dead: false,
@@ -276,7 +277,7 @@ async function startDeviceFlow() {
     return flow;
 }
 async function pollForToken(device_code, interval, agent_id, provisional_tenant_id, 
-/** Mutable ref so auto-restart can update the surfaced URL in ActiveDeviceFlow */
+/** Mutable ref so auto-restart can update the surfaced URL and provisional token in ActiveDeviceFlow */
 flowRef) {
     const pollIntervalMs = Math.max(interval, 5) * 1000;
     const handle = {
@@ -307,9 +308,7 @@ flowRef) {
             }
         },
         startNewFlow: async () => {
-            const authRes = (await aisPost('/v1/oauth/device/authorize', {
-                name: `agent-${homedir().split('/').pop() ?? 'user'}`,
-            }));
+            const authRes = (await aisPost('/v1/oauth/device/authorize', { name: `agent-${homedir().split('/').pop() ?? 'user'}` }, flowRef?.provisional_token));
             if (!authRes.success || !authRes.data) {
                 throw new Error(`Re-authorization failed: ${authRes.error?.message ?? 'Unknown error'}`);
             }
@@ -319,10 +318,13 @@ flowRef) {
                 user_code: authRes.data.user_code,
             };
             // Update the mutable ref so the caller (ensureCredentials) can surface
-            // the new URL to the human without restarting the MCP process.
+            // the new URL to the human without restarting the MCP process, and so
+            // a THIRD expiry in the same flow re-sends the latest provisional
+            // token rather than a stale, already-superseded one.
             if (flowRef) {
                 flowRef.verification_uri_complete = newHandle.verification_uri_complete;
                 flowRef.user_code = newHandle.user_code;
+                flowRef.provisional_token = authRes.data.provisional_token;
             }
             stderr('');
             stderr('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
@@ -404,7 +406,7 @@ const tools = [
     },
     {
         name: 'dream',
-        description: 'Trigger a memory consolidation dream cycle — promotes important memories and archives old ones.',
+        description: 'Trigger a memory consolidation dream cycle — promotes important memories and archives old ones. Promotion only scans the session tier; active-tier memories move via context-clear or handoff, not dream.',
         inputSchema: { type: 'object', properties: {} },
     },
     {
@@ -523,6 +525,10 @@ async function main() {
         await import('./cli/sync-memory.js');
         return; // sync-memory.ts calls process.exit() on failure
     }
+    if (process.argv[2] === 'doctor') {
+        await import('./cli/doctor.js');
+        return; // doctor.ts calls process.exit() itself
+    }
     // Agent API key auth mode (CORBOT-B1D3244C) — unattended machines. Checked
     // before any device-flow / OAuth-credential / DID-key-auth setup below so
     // this mode NEVER falls back to those paths (that fallback is what used to
@@ -609,7 +615,7 @@ async function main() {
             stderr(`Key auth failed: ${err instanceof Error ? err.message : String(err)}. Falling back to device flow.`);
         }
         if (!activeFlow || activeFlow.dead) {
-            activeFlow = await startDeviceFlow();
+            activeFlow = await startDeviceFlow(activeFlow?.provisional_token);
         }
         const sentinel = Symbol('bond-pending');
         // poll is always set by startDeviceFlow before it returns; this guard
@@ -630,7 +636,7 @@ async function main() {
             // Always say WHY the old flow died: a silent discard here hid three
             // weeks of broken cold-start bonding (CORBOT-9CE03C6E).
             stderr(`Device flow discarded (${err instanceof Error ? err.message : String(err)}); starting a fresh one.`);
-            activeFlow = await startDeviceFlow();
+            activeFlow = await startDeviceFlow(activeFlow.provisional_token);
             throw new BondPendingError(activeFlow.verification_uri_complete, activeFlow.user_code);
         }
         if (got === sentinel) {
@@ -766,8 +772,12 @@ async function main() {
                         const target = await resolveAgentForLoad(token, query);
                         agentId = target.id;
                         // Persist the switch so subsequent tool calls use the new agent.
+                        // saveCredentials() MUST be called here so that a process restart
+                        // (silent MCP reconnect) restores the switched agent from disk
+                        // instead of silently reverting to the default (CORBOT-497C7FA3).
                         if (creds) {
                             creds = { ...creds, agentId };
+                            saveCredentials(creds);
                         }
                         agentContext = await hydrateIdentity(AIS_URL, agentId, token);
                         applyMemoryRefresh(agentId, token);