@ornexus/neocortex 4.0.1

package/packages/client/dist/resolvers/remote-resolver.js

@@ -0,0 +1,282 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+import { ResolverMode, NoOpCache, } from '../types/index.js';
+import { InMemoryAssetCache } from '../cache/in-memory-asset-cache.js';
+// ── Constants ────────────────────────────────────────────────────────────
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_RETRY_COUNT = 3;
+const BACKOFF_BASE_MS = 1_000;
+const BACKOFF_MAX_MS = 10_000;
+// ── Error Types ──────────────────────────────────────────────────────────
+export class RemoteResolverError extends Error {
+    statusCode;
+    endpoint;
+    constructor(message, statusCode, endpoint) {
+        super(message);
+        this.statusCode = statusCode;
+        this.endpoint = endpoint;
+        this.name = 'RemoteResolverError';
+    }
+}
+// ── RemoteResolver Implementation ───────────────────────────────────────
+export class RemoteResolver {
+    mode = ResolverMode.REMOTE;
+    serverUrl;
+    licenseKey;
+    timeout;
+    retryCount;
+    /**
+     * Persistent cache -- used for registry only.
+     * P70.06: NEVER used for step/skill/standard content (those live in
+     * `assetCache` and only in process memory).
+     */
+    cache;
+    /**
+     * In-memory LRU cache for asset content (Epic P70.06).
+     * Volatile: discarded on process exit. Never persisted to disk.
+     */
+    assetCache;
+    licenseClient;
+    constructor(options) {
+        this.serverUrl = options.serverUrl.replace(/\/+$/, '');
+        this.licenseKey = options.licenseKey;
+        this.timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+        this.retryCount = options.retryCount ?? DEFAULT_RETRY_COUNT;
+        this.cache = options.cacheProvider ?? new NoOpCache();
+        this.licenseClient = options.licenseClient ?? null;
+        // P70.06: asset content always lives in volatile memory cache.
+        this.assetCache = new InMemoryAssetCache();
+    }
+    async resolveStep(stepId, _context) {
+        // P70.06: step content in-memory only
+        const cacheKey = `step:${stepId}`;
+        return this.fetchWithInMemoryCache(cacheKey, {
+            method: 'GET',
+            path: `/api/v1/steps/${encodeURIComponent(stepId)}`,
+        });
+    }
+    async resolveSkill(skillId, _context) {
+        // P70.06: skill content in-memory only
+        const cacheKey = `skill:${skillId}`;
+        return this.fetchWithInMemoryCache(cacheKey, {
+            method: 'GET',
+            path: `/api/v1/skills/${encodeURIComponent(skillId)}`,
+        });
+    }
+    async resolveStandard(standardId) {
+        // P70.06: standard content in-memory only
+        const cacheKey = `standard:${standardId}`;
+        return this.fetchWithInMemoryCache(cacheKey, {
+            method: 'GET',
+            path: `/api/v1/standards/${encodeURIComponent(standardId)}`,
+        });
+    }
+    async resolveRegistry() {
+        // Registry is NOT asset content -- it's tokenized metadata (P70.02).
+        // Persistent cache is acceptable here.
+        const cacheKey = 'registry';
+        return this.fetchWithCacheFallback(cacheKey, {
+            method: 'GET',
+            path: '/api/v1/registry',
+        });
+    }
+    async assemblePrompt(stepId, context) {
+        // assemblePrompt is not cached because it depends on dynamic context
+        return this.fetchWithRetry({
+            method: 'POST',
+            path: '/api/v1/prompts/assemble',
+            body: {
+                stepId,
+                context,
+            },
+        });
+    }
+    async isAvailable() {
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), 5_000);
+            const response = await fetch(`${this.serverUrl}/api/v1/health`, {
+                method: 'GET',
+                headers: await this.buildHeaders(),
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            return response.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+    async dispose() {
+        await this.cache.clear();
+        // P70.06: explicit asset cache clear (defense-in-depth; process exit
+        // already releases it).
+        await this.assetCache.clear();
+    }
+    // ── Private Methods ─────────────────────────────────────────────────
+    /**
+     * Build authorization headers for API requests.
+     * When a LicenseClient is available, uses JWT token from it.
+     * Story 31.04: NEVER sends raw license key as Bearer token.
+     * If JWT is unavailable, omits Authorization header entirely.
+     * Server will return 401, which fetchWithRetry handles via forceRefresh.
+     */
+    async buildHeaders() {
+        const headers = {
+            'Content-Type': 'application/json',
+            'X-Client-Version': '0.1.0',
+        };
+        if (this.licenseClient) {
+            const jwt = await this.licenseClient.getToken();
+            if (jwt) {
+                headers['Authorization'] = `Bearer ${jwt}`;
+            }
+            // No JWT available: omit Authorization header entirely
+            // Server will return 401, which fetchWithRetry handles via forceRefresh
+        }
+        return headers;
+    }
+    /**
+     * Execute HTTP request with retry and exponential backoff.
+     * Handles 401 specially: if a licenseClient is available, attempts
+     * forceRefresh() and retries once with the new token.
+     */
+    async fetchWithRetry(options) {
+        let lastError;
+        let authRetried = false;
+        for (let attempt = 0; attempt <= this.retryCount; attempt++) {
+            try {
+                const controller = new AbortController();
+                const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+                const url = `${this.serverUrl}${options.path}`;
+                const fetchOptions = {
+                    method: options.method,
+                    headers: await this.buildHeaders(),
+                    signal: controller.signal,
+                };
+                if (options.body) {
+                    fetchOptions.body = JSON.stringify(options.body);
+                }
+                const response = await fetch(url, fetchOptions);
+                clearTimeout(timeoutId);
+                if (!response.ok) {
+                    const errorBody = await response.text().catch(() => 'Unknown error');
+                    // 401: attempt token refresh once if licenseClient is available
+                    if (response.status === 401 && !authRetried && this.licenseClient) {
+                        authRetried = true;
+                        const newToken = await this.licenseClient.forceRefresh();
+                        if (newToken) {
+                            // Retry immediately with the new token (don't count as a normal retry)
+                            attempt--; // offset the loop increment so this doesn't consume a retry
+                            continue;
+                        }
+                        // forceRefresh failed - throw immediately
+                        throw new RemoteResolverError(`API error: ${response.status} ${response.statusText} - ${errorBody}`, response.status, options.path);
+                    }
+                    // Don't retry on 4xx client errors (except 429 rate limit)
+                    if (response.status >= 400 && response.status < 500 && response.status !== 429) {
+                        throw new RemoteResolverError(`API error: ${response.status} ${response.statusText} - ${errorBody}`, response.status, options.path);
+                    }
+                    // Retry on 5xx server errors and 429 rate limit
+                    throw new RemoteResolverError(`Server error: ${response.status} ${response.statusText}`, response.status, options.path);
+                }
+                return (await response.json());
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                // Don't retry on non-retryable errors (4xx except 429)
+                if (error instanceof RemoteResolverError && error.statusCode && error.statusCode >= 400 && error.statusCode < 500 && error.statusCode !== 429) {
+                    throw error;
+                }
+                // Apply backoff before next retry (except on last attempt)
+                if (attempt < this.retryCount) {
+                    const backoff = Math.min(BACKOFF_BASE_MS * Math.pow(2, attempt), BACKOFF_MAX_MS);
+                    // Add jitter (0-25% of backoff)
+                    const jitter = Math.random() * backoff * 0.25;
+                    await this.sleep(backoff + jitter);
+                }
+            }
+        }
+        throw lastError ?? new RemoteResolverError('All retry attempts failed', undefined, options.path);
+    }
+    /**
+     * Fetch with persistent cache fallback: try HTTP first, fall back to cache
+     * on failure. On successful HTTP response, update the cache.
+     *
+     * P70.06: ONLY the registry uses this path. Asset content (step/skill/
+     * standard) uses {@link fetchWithInMemoryCache} so it never touches disk.
+     */
+    async fetchWithCacheFallback(cacheKey, options) {
+        try {
+            const result = await this.fetchWithRetry(options);
+            // Update cache with fresh data (fire-and-forget)
+            this.cache.set(cacheKey, JSON.stringify(result)).catch(() => {
+                // Cache write failures are non-critical
+            });
+            return result;
+        }
+        catch (error) {
+            // Try cache fallback
+            const cached = await this.cache.get(cacheKey);
+            if (cached !== null) {
+                try {
+                    return JSON.parse(cached);
+                }
+                catch {
+                    // Invalid cache data, rethrow original error
+                }
+            }
+            throw error;
+        }
+    }
+    /**
+     * P70.06: fetch with VOLATILE in-memory cache fallback.
+     *
+     * Identical structure to {@link fetchWithCacheFallback} but the backing
+     * store is {@link InMemoryAssetCache} -- entries live only in the running
+     * process memory, never written to disk.
+     *
+     * When the server is unreachable and the in-memory cache is empty (e.g.
+     * first invocation of a fresh CLI process), the original error is
+     * re-thrown instead of silently degrading to a stale disk cache.
+     */
+    async fetchWithInMemoryCache(cacheKey, options) {
+        try {
+            const result = await this.fetchWithRetry(options);
+            // Update volatile cache (fire-and-forget)
+            this.assetCache.set(cacheKey, JSON.stringify(result)).catch(() => {
+                // Cache write failures are non-critical
+            });
+            return result;
+        }
+        catch (error) {
+            // Try in-memory fallback -- NEVER fall back to disk cache
+            const cached = await this.assetCache.get(cacheKey);
+            if (cached !== null) {
+                try {
+                    return JSON.parse(cached);
+                }
+                catch {
+                    // Invalid cache data, rethrow original error
+                }
+            }
+            throw error;
+        }
+    }
+    /**
+     * Sleep for the specified duration.
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}

package/packages/client/dist/telemetry/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ */
+export { OfflineTelemetryQueue, type TelemetryEvent, type QueueConfig, type QueueStats, type FlushResult } from './offline-queue.js';

package/packages/client/dist/telemetry/index.js

@@ -0,0 +1,5 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ */
+export { OfflineTelemetryQueue } from './offline-queue.js';

package/packages/client/dist/telemetry/offline-queue.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+export interface TelemetryEvent {
+    type: string;
+    timestamp: number;
+    data: Record<string, unknown>;
+}
+export interface QueueConfig {
+    /** Path to queue file. Default: ~/.neocortex/.telemetry-queue */
+    queueFilePath: string;
+    /** Maximum number of events in queue. Default: 1000 */
+    maxEvents: number;
+    /** Maximum queue file size in bytes. Default: 5_242_880 (5MB) */
+    maxSizeBytes: number;
+}
+export interface QueueStats {
+    count: number;
+    sizeBytes: number;
+}
+export interface FlushResult {
+    sent: number;
+    failed: number;
+}
+export declare class OfflineTelemetryQueue {
+    private readonly config;
+    constructor(config?: Partial<QueueConfig>);
+    /**
+     * Add a telemetry event to the queue.
+     * Evicts oldest events if limits are reached.
+     */
+    enqueue(event: TelemetryEvent): Promise<void>;
+    /**
+     * Flush all queued events using the provided send function.
+     * Returns count of sent and failed events.
+     */
+    flush(sendFn: (events: TelemetryEvent[]) => Promise<boolean>): Promise<FlushResult>;
+    /**
+     * Get queue statistics.
+     */
+    getStats(): Promise<QueueStats>;
+    /**
+     * Clear all queued events.
+     */
+    clear(): Promise<void>;
+    private loadQueue;
+    private saveQueue;
+}

package/packages/client/dist/telemetry/offline-queue.js

@@ -0,0 +1,131 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+/**
+ * @neocortex/client - Offline Telemetry Queue
+ *
+ * Persistent FIFO queue for telemetry events when the CLI operates offline.
+ * Events are stored in a JSON file and flushed when connection is restored.
+ * Respects configurable limits on event count (1000) and file size (5MB).
+ *
+ * Story 42.9
+ */
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+// ── Defaults ──────────────────────────────────────────────────────────────
+const DEFAULT_CONFIG = {
+    queueFilePath: join(homedir(), '.neocortex', '.telemetry-queue'),
+    maxEvents: 1_000,
+    maxSizeBytes: 5_242_880, // 5MB
+};
+// ── OfflineTelemetryQueue ────────────────────────────────────────────────
+export class OfflineTelemetryQueue {
+    config;
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Add a telemetry event to the queue.
+     * Evicts oldest events if limits are reached.
+     */
+    async enqueue(event) {
+        try {
+            const events = await this.loadQueue();
+            events.push(event);
+            // Evict oldest events if count limit exceeded
+            while (events.length > this.config.maxEvents) {
+                events.shift();
+            }
+            // Evict oldest events if size limit exceeded
+            let serialized = JSON.stringify(events);
+            while (Buffer.byteLength(serialized, 'utf8') > this.config.maxSizeBytes && events.length > 0) {
+                events.shift();
+                serialized = JSON.stringify(events);
+            }
+            await this.saveQueue(events);
+        }
+        catch {
+            // Queue write failures are non-critical
+        }
+    }
+    /**
+     * Flush all queued events using the provided send function.
+     * Returns count of sent and failed events.
+     */
+    async flush(sendFn) {
+        try {
+            const events = await this.loadQueue();
+            if (events.length === 0) {
+                return { sent: 0, failed: 0 };
+            }
+            const success = await sendFn(events);
+            if (success) {
+                await this.saveQueue([]);
+                return { sent: events.length, failed: 0 };
+            }
+            return { sent: 0, failed: events.length };
+        }
+        catch {
+            return { sent: 0, failed: 0 };
+        }
+    }
+    /**
+     * Get queue statistics.
+     */
+    async getStats() {
+        try {
+            const events = await this.loadQueue();
+            const serialized = JSON.stringify(events);
+            return {
+                count: events.length,
+                sizeBytes: Buffer.byteLength(serialized, 'utf8'),
+            };
+        }
+        catch {
+            return { count: 0, sizeBytes: 0 };
+        }
+    }
+    /**
+     * Clear all queued events.
+     */
+    async clear() {
+        try {
+            await this.saveQueue([]);
+        }
+        catch {
+            // Clear failures are non-critical
+        }
+    }
+    // ── Private ─────────────────────────────────────────────────────────
+    async loadQueue() {
+        try {
+            const raw = await readFile(this.config.queueFilePath, 'utf8');
+            const data = JSON.parse(raw);
+            if (!Array.isArray(data))
+                return [];
+            return data;
+        }
+        catch {
+            return [];
+        }
+    }
+    async saveQueue(events) {
+        const dir = dirname(this.config.queueFilePath);
+        await mkdir(dir, { recursive: true });
+        const tmpPath = `${this.config.queueFilePath}.tmp`;
+        await writeFile(tmpPath, JSON.stringify(events), 'utf8');
+        const { rename } = await import('node:fs/promises');
+        await rename(tmpPath, this.config.queueFilePath);
+    }
+}

package/packages/client/dist/tier/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ */
+export { TierAwareClient, type TierAwareClientOptions, type PreFlightResult, type QuotaSnapshot, type SubscriptionTier, } from './tier-aware-client.js';

package/packages/client/dist/tier/index.js

@@ -0,0 +1,5 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ */
+export { TierAwareClient, } from './tier-aware-client.js';

package/packages/client/dist/tier/tier-aware-client.d.ts

@@ -0,0 +1,97 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+/**
+ * @neocortex/client - TierAwareClient
+ *
+ * Client-side tier awareness: JWT tier extraction, cached tier,
+ * pre-flight trigger checks, quota caching from response metadata,
+ * and offline enforcement via cached quota data.
+ *
+ * Follows the same "NEVER throws" pattern as LicenseClient.
+ * Fail-open: if anything fails, default to 'free' tier / allow operation.
+ * No stdout output (preserve pipe compatibility) -- stderr only.
+ *
+ * Epic 60
+ */
+import type { CacheProvider } from '../types/index.js';
+import type { LicenseClient } from '../license/license-client.js';
+/** Subscription tier (inlined to avoid import path issues) */
+export type SubscriptionTier = 'free' | 'pro' | 'enterprise';
+/** Result of a pre-flight trigger check */
+export interface PreFlightResult {
+    readonly allowed: boolean;
+    readonly message?: string;
+}
+/** Cached quota data from server response metadata */
+export interface QuotaSnapshot {
+    readonly stepsRemaining: number;
+    readonly invocationsRemaining: number;
+    readonly stepsLimit: number;
+    readonly invocationsLimit: number;
+    readonly cachedAt: number;
+}
+export interface TierAwareClientOptions {
+    readonly cacheProvider: CacheProvider;
+    readonly licenseClient: LicenseClient;
+}
+export declare class TierAwareClient {
+    private readonly cache;
+    private readonly licenseClient;
+    private cachedTier;
+    constructor(options: TierAwareClientOptions);
+    /**
+     * Get the current tier. Checks in-memory, then cache, then JWT token.
+     * NEVER throws - returns 'free' on failure (fail-open).
+     */
+    getCachedTier(): Promise<SubscriptionTier>;
+    /**
+     * Update cached tier (called when server returns tier info).
+     */
+    updateTier(tier: SubscriptionTier): Promise<void>;
+    /**
+     * Invalidate all tier and quota caches.
+     * Called when a tier change is detected to ensure fresh data.
+     * NEVER throws.
+     */
+    invalidateTierCache(): Promise<void>;
+    /**
+     * Check if a trigger is allowed for the current tier WITHOUT calling the server.
+     * Returns immediately (in-memory lookup).
+     * NEVER throws - returns { allowed: true } on failure (fail-open).
+     */
+    preFlightCheck(trigger: string, tier?: SubscriptionTier): Promise<PreFlightResult>;
+    /**
+     * Update cached quota from server response metadata.
+     * Called after each successful invoke.
+     */
+    updateQuotaFromResponse(metadata: Record<string, unknown>): Promise<void>;
+    /**
+     * Get cached quota for today.
+     * NEVER throws - returns null if cache empty or expired.
+     */
+    getCachedQuota(): Promise<QuotaSnapshot | null>;
+    /**
+     * Check quota in offline mode using cached data.
+     * NEVER throws - returns { allowed: true } on failure (fail-open).
+     *
+     * @param isOffline - Whether the circuit breaker is in L2+ degradation
+     */
+    offlineQuotaCheck(isOffline?: boolean): Promise<PreFlightResult>;
+    /**
+     * Extract tier from JWT payload via base64url decode.
+     * No cryptographic verification - client-side is UX only.
+     */
+    private extractTierFromJwt;
+    private buildUpgradeMessage;
+    private getQuotaCacheKey;
+}