@mnemosyne_os/sdk 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -10,18 +10,30 @@ import { z } from 'zod';
  */
 /** Scopes disponibles pour une app tierce */
 type MnemoScope = 'vault:read:DEV' | 'vault:write:DEV' | 'vault:read:SOCIAL' | 'vault:write:SOCIAL' | 'vault:read:PERSONAL' | 'vault:write:PERSONAL' | 'vault:read:FINANCE' | 'vault:write:FINANCE' | 'vault:read:COOK' | 'vault:write:COOK' | 'share:request' | 'share:grant'
+/** Accès en lecture au git log du monorepo Mnemosyne OS */
+ | 'monorepo:read'
+/** Liste les agents SDK connectés */
+ | 'agents:read'
 /** Validation de licence NFT on-chain pour MnemoStore */
  | 'nft:validate'
 /** Accès en lecture au NeuralGraph (nœuds, arêtes, clusters) */
  | 'neural:graph:read'
 /** Requêtes LLM directes via le runtime Mnemosyne — scope premium */
  | 'llm:query';
-/** Intents IPC autorisés */
-type MnemoIntent = 'INGEST' | 'QUERY' | 'CORRELATE' | 'FORGET';
+/** Intents IPC autorisés dans le manifest */
+type MnemoIntent = 'INGEST' | 'QUERY' | 'CORRELATE' | 'FORGET' | 'GIT_LOG' | 'LIST_AGENTS';
 /** Vault cible */
 type MnemoVault = 'DEV' | 'SOCIAL' | 'PERSONAL' | 'FINANCE' | 'COOK';
-/** Types de spine */
-type SpineType = 'GIT' | 'ARCHITECTURE' | 'DECISION' | 'DEBUG' | 'FEATURE' | 'REDDIT_POST' | 'LINKEDIN_POST' | 'SOCIAL_NODE' | 'DOCUMENT' | 'NOTE' | 'CUSTOM';
+/** Types de spine sémantiques */
+type SpineType = 'GIT' | 'ARCHITECTURE' | 'DECISION' | 'DEBUG' | 'FEATURE' | 'REDDIT_POST' | 'LINKEDIN_POST' | 'SOCIAL_NODE' | 'DOCUMENT' | 'NOTE' | 'CUSTOM'
+/** Créé par le Cockpit ou via sdk.resonances.list */
+ | 'RESONANCE'
+/** Persistance de session / contexte de reprise */
+ | 'SESSION'
+/** Mise à jour de position (phase, état courant) */
+ | 'POSITION_UPDATE'
+/** Documentation API ou spec */
+ | 'API' | 'DOC' | 'ERROR';
 /** Manifest de l'application — fichier `app.manifest.json` */
 interface AppManifest {
     /** Identifiant unique stable de l'app (snake_case recommandé) */
@@ -98,7 +110,8 @@ interface QueryOptions {
 }
 interface Chronicle {
     id: string;
-    content: string;
+    /** Contenu textuel du chronicle. Peut être absent si seul le vecteur est stocké. */
+    content?: string;
     spineType: SpineType;
     score: number;
     timestamp: string;
@@ -127,6 +140,31 @@ interface RegisterResult {
     expiresAt: number;
     appId: string;
 }
+/**
+ * Un commit git retourné par MNEMOSYNE_METHODS.GIT_LOG.
+ * Le path du repo est hardcodé côté serveur (Zero-Trust).
+ */
+interface GitCommit {
+    hash: string;
+    fullHash?: string;
+    author: string;
+    message: string;
+    /** Type conventional commit (feat/fix/chore/…) */
+    type: string;
+    ts: number;
+    repo: string;
+}
+/**
+ * Un agent SDK retourné par MNEMOSYNE_METHODS.LIST_AGENTS.
+ */
+interface AgentInfo {
+    id: string;
+    name: string;
+    provider: string;
+    status: 'active' | 'idle' | 'offline';
+    resonanceId?: string;
+    sessionMs?: number;
+}
 /**
  * Paramètres pour valider une licence NFT.
  * La validation se fait on-chain via le runtime Mnemosyne OS (pas directement dans le SDK).
@@ -187,7 +225,14 @@ interface MnemoEvent<T = unknown> {
  * Format : base64url(header).base64url(payload).base64url(signature)
  * Algorithme : HMAC-SHA256 (symétrique, secret partagé OS ↔ app)
  *
- * [SDK][SECURITY][AUTH]
+ * ## Compat Browser (MN-005)
+ * `Buffer.toString('base64url')` n'est pas supporté par le polyfill npm `buffer`.
+ * Les helpers b64url() / parseB64url() utilisent une impl universelle :
+ *   - Node.js  : Buffer natif (supporte base64url)
+ *   - Browser  : btoa/atob + remplacement des caractères non-URL
+ * Cela permet d'importer les CONSTANTES du SDK dans un renderer Electron sans crash.
+ *
+ * [SDK][SECURITY][AUTH][MN-005]
  */
 interface JwtPayload {
     sub: string;
@@ -293,12 +338,154 @@ declare class MnemoClient {
     get isConnected(): boolean;
     get appId(): string;
     get appManifest(): AppManifest;
-    /** Inspecte le token actuel (décodé, sans vérification) */
+    /**
+     * Inspecte le token actuel (décodé, sans vérification cryptographique).
+     * Utilise un décodeur base64url universel (Node + Browser) — MN-005.
+     */
     get tokenInfo(): {
         sub: string;
         exp: number;
         scopes: string[];
     } | null;
+    /**
+     * [PHASE-50] Lit un fichier .md depuis le repo OS (docs/, packages/).
+     */
+    readFile(path: string): Promise<string>;
+}
+
+/**
+ * @mnemosyne_os/sdk — MnemoClientBrowser
+ *
+ * Client WebSocket 100% browser-native pour les apps Layer 2 qui tournent
+ * dans un renderer Electron ou un navigateur web.
+ * N'utilise PAS le package `ws` (Node-only) — uniquement l'API WebSocket native.
+ *
+ * Usage dans une app React/Vite :
+ * ```typescript
+ * import { MnemoClientBrowser } from '@mnemosyne_os/sdk';
+ *
+ * const client = await MnemoClientBrowser.connect();
+ * await client.register({ id: 'my-app', name: 'My App', version: '1.0.0',
+ *   mnemosyne_sdk: '^1.1.0', scopes: ['vault:read:DEV'], vaults: ['DEV'], intents: ['QUERY'] });
+ *
+ * const chronicles = await client.query('my search', 'DEV', 10);
+ * ```
+ *
+ * [SDK][LAYER-2][BROWSER][ZERO-TRUST]
+ */
+
+/**
+ * Client SDK browser-native. Communique avec le SDK WebSocket Server de
+ * Mnemosyne OS sur ws://127.0.0.1:7799 via l'API WebSocket standard.
+ *
+ * Compatible : Chrome, Firefox, Electron renderer, Safari, Vite, Next.js.
+ * Non compatible : Node.js (utiliser MnemoClient à la place).
+ */
+declare class MnemoClientBrowser {
+    private readonly ws;
+    private token;
+    private readonly pending;
+    private _onPush?;
+    private _onDisconnect?;
+    private readonly timeoutMs;
+    private constructor();
+    /**
+     * Crée une connexion WebSocket native vers le SDK server de Mnemosyne OS.
+     *
+     * @param host - Hostname du SDK server (défaut: '127.0.0.1')
+     * @param port - Port du SDK server (défaut: 7799)
+     * @param timeoutMs - Timeout de chaque RPC en ms (défaut: 15000)
+     */
+    static connect(host?: string, port?: number, timeoutMs?: number): Promise<MnemoClientBrowser>;
+    private _handleMsg;
+    private call;
+    /**
+     * Enregistre l'app auprès de Mnemosyne OS et obtient un JWT 24h.
+     * Doit être appelé avant toute autre méthode.
+     *
+     * @throws si le manifest est invalide ou si l'OS refuse l'enregistrement
+     */
+    register(manifest: AppManifest): Promise<RegisterResult>;
+    /**
+     * Ingère du contenu dans le vault Mnemosyne.
+     * Le contenu est vectorisé par le runtime OS (pas dans le SDK).
+     * Requiert le scope `vault:write:<vault>` et l'intent `INGEST`.
+     */
+    ingest(content: string, spineType: string, vault?: string, metadata?: Record<string, unknown>): Promise<IngestResult>;
+    /**
+     * Requête sémantique sur le vault — retourne les chronicles les plus proches.
+     * Requiert le scope `vault:read:<vault>` et l'intent `QUERY`.
+     *
+     * @param text  - Texte de recherche
+     * @param vault - Vault cible (défaut: 'DEV')
+     * @param limit - Nombre max de résultats (défaut: 10)
+     */
+    query(text: string, vault?: string, limit?: number): Promise<Chronicle[]>;
+    /**
+     * Retourne les Resonances actives (projets cognitifs) depuis le vault DEV.
+     * Requiert le scope `vault:read:DEV`.
+     */
+    resonancesList(): Promise<Record<string, unknown>[]>;
+    /**
+     * Persiste la position courante d'une Resonance dans le vault DEV.
+     * Requiert le scope `vault:write:DEV`.
+     *
+     * @param resonanceId - ID de la Resonance
+     * @param position    - Description de la position courante (ex: "Phase 51.2 — auto-poll")
+     * @param phase       - Phase courante (ex: "Phase 51")
+     */
+    updatePosition(resonanceId: string, position: string, phase: string): Promise<boolean>;
+    /**
+     * Retourne les commits récents du monorepo Mnemosyne OS.
+     * Requiert le scope `monorepo:read` et l'intent `GIT_LOG`.
+     * [SECURITY] Le chemin du repo est hardcodé côté serveur.
+     *
+     * @param limit - Nombre de commits max (défaut: 20)
+     * @param since - Date relative Git (ex: '30 days ago', '2024-01-01')
+     */
+    gitLog(limit?: number, since?: string): Promise<GitCommit[]>;
+    /**
+     * Lit un fichier `.md` depuis le repo Mnemosyne OS.
+     * Requiert le scope `monorepo:read`.
+     * [SECURITY] Seuls les fichiers `.md` sont accessibles, path sanitizé côté serveur.
+     *
+     * @param path - Chemin relatif au repo (ex: 'docs/ARCHITECTURE.md')
+     */
+    readFile(path: string): Promise<string>;
+    /**
+     * Liste les apps Layer 2 actuellement connectées au SDK WebSocket Server.
+     * Requiert le scope `agents:read` et l'intent `LIST_AGENTS`.
+     */
+    agentsList(): Promise<AgentInfo[]>;
+    /**
+     * Enregistre un handler pour les push events envoyés par l'OS.
+     * Déclenché par exemple quand un autre client ingère un chronicle (`chronicle:new`).
+     *
+     * @example
+     * ```typescript
+     * client.onPush((event) => {
+     *   if (event.type === 'chronicle:new') {
+     *     console.log('New chronicle from:', event.sourceApp);
+     *   }
+     * });
+     * ```
+     */
+    onPush(fn: (event: Record<string, unknown>) => void): void;
+    /**
+     * Enregistre un callback appelé quand la connexion WS est fermée par l'OS.
+     */
+    onDisconnect(fn: () => void): void;
+    /**
+     * Ferme la connexion WebSocket proprement.
+     */
+    close(): void;
+    get isConnected(): boolean;
+    /** Token JWT actuel (null avant register()) */
+    get currentToken(): string | null;
+    /**
+     * AppId extrait du JWT actuel, ou null si non enregistré.
+     */
+    get appId(): string | null;
 }
 
 /**
@@ -307,28 +494,44 @@ declare class MnemoClient {
  * Valide le fichier app.manifest.json avant toute connexion.
  * Utilise Zod pour un parsing strict — aucun champ inconnu passé au serveur.
  *
- * [SDK][ZERO-TRUST][AUDIT-TRAIL]
+ * ## Règle Zero-Trust (MN-004)
+ * Le GRANT utilisateur est TOUJOURS requis si l'app déclare un scope vault:*.
+ * Ce n'est PAS un flag que l'app contrôle — c'est l'OS qui décide en lisant les scopes.
+ * Un manifest avec `requires_grant: false` mais `scopes: ['vault:read:DEV']` DOIT
+ * quand même passer par le popup de consentement. L'OS appelle `requiresOsGrant(manifest)`.
+ *
+ * [SDK][ZERO-TRUST][AUDIT-TRAIL][MN-004]
  */
 
-declare const VALID_SCOPES: readonly ["vault:read:DEV", "vault:write:DEV", "vault:read:SOCIAL", "vault:write:SOCIAL", "vault:read:PERSONAL", "vault:write:PERSONAL", "vault:read:FINANCE", "vault:write:FINANCE", "vault:read:COOK", "vault:write:COOK", "share:request", "share:grant"];
+declare const VALID_SCOPES: readonly ["vault:read:DEV", "vault:write:DEV", "vault:read:SOCIAL", "vault:write:SOCIAL", "vault:read:PERSONAL", "vault:write:PERSONAL", "vault:read:FINANCE", "vault:write:FINANCE", "vault:read:COOK", "vault:write:COOK", "share:request", "share:grant", "nft:validate", "neural:graph:read", "llm:query"];
+/**
+ * Scopes qui requièrent TOUJOURS un GRANT utilisateur côté OS.
+ * Indépendant de tout flag déclaré par l'app.
+ * [MN-004]
+ */
+declare const GRANT_REQUIRED_SCOPE_PREFIXES: readonly ["vault:read:", "vault:write:", "share:request", "share:grant", "llm:query"];
 declare const AppManifestSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
     version: z.ZodString;
     author: z.ZodOptional<z.ZodString>;
     mnemosyne_sdk: z.ZodString;
-    scopes: z.ZodArray<z.ZodEnum<["vault:read:DEV", "vault:write:DEV", "vault:read:SOCIAL", "vault:write:SOCIAL", "vault:read:PERSONAL", "vault:write:PERSONAL", "vault:read:FINANCE", "vault:write:FINANCE", "vault:read:COOK", "vault:write:COOK", "share:request", "share:grant"]>, "many">;
+    scopes: z.ZodArray<z.ZodEnum<["vault:read:DEV", "vault:write:DEV", "vault:read:SOCIAL", "vault:write:SOCIAL", "vault:read:PERSONAL", "vault:write:PERSONAL", "vault:read:FINANCE", "vault:write:FINANCE", "vault:read:COOK", "vault:write:COOK", "share:request", "share:grant", "nft:validate", "neural:graph:read", "llm:query"]>, "many">;
     vaults: z.ZodArray<z.ZodEnum<["DEV", "SOCIAL", "PERSONAL", "FINANCE", "COOK"]>, "many">;
     intents: z.ZodArray<z.ZodEnum<["INGEST", "QUERY", "CORRELATE", "FORGET"]>, "many">;
     max_chronicle_size_kb: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    /**
+     * @deprecated Remplacé par requiresOsGrant() — ce flag n'a aucun effet sur la sécurité.
+     * L'OS décide toujours en fonction des scopes déclarés (MN-004).
+     */
     requires_consent: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     description: z.ZodOptional<z.ZodString>;
-}, "strict", z.ZodTypeAny, {
+}, "strip", z.ZodTypeAny, {
     id: string;
     name: string;
     version: string;
     mnemosyne_sdk: string;
-    scopes: ("vault:read:DEV" | "vault:write:DEV" | "vault:read:SOCIAL" | "vault:write:SOCIAL" | "vault:read:PERSONAL" | "vault:write:PERSONAL" | "vault:read:FINANCE" | "vault:write:FINANCE" | "vault:read:COOK" | "vault:write:COOK" | "share:request" | "share:grant")[];
+    scopes: ("vault:read:DEV" | "vault:write:DEV" | "vault:read:SOCIAL" | "vault:write:SOCIAL" | "vault:read:PERSONAL" | "vault:write:PERSONAL" | "vault:read:FINANCE" | "vault:write:FINANCE" | "vault:read:COOK" | "vault:write:COOK" | "share:request" | "share:grant" | "nft:validate" | "neural:graph:read" | "llm:query")[];
     vaults: ("DEV" | "SOCIAL" | "PERSONAL" | "FINANCE" | "COOK")[];
     intents: ("INGEST" | "QUERY" | "CORRELATE" | "FORGET")[];
     max_chronicle_size_kb: number;
@@ -340,7 +543,7 @@ declare const AppManifestSchema: z.ZodObject<{
     name: string;
     version: string;
     mnemosyne_sdk: string;
-    scopes: ("vault:read:DEV" | "vault:write:DEV" | "vault:read:SOCIAL" | "vault:write:SOCIAL" | "vault:read:PERSONAL" | "vault:write:PERSONAL" | "vault:read:FINANCE" | "vault:write:FINANCE" | "vault:read:COOK" | "vault:write:COOK" | "share:request" | "share:grant")[];
+    scopes: ("vault:read:DEV" | "vault:write:DEV" | "vault:read:SOCIAL" | "vault:write:SOCIAL" | "vault:read:PERSONAL" | "vault:write:PERSONAL" | "vault:read:FINANCE" | "vault:write:FINANCE" | "vault:read:COOK" | "vault:write:COOK" | "share:request" | "share:grant" | "nft:validate" | "neural:graph:read" | "llm:query")[];
     vaults: ("DEV" | "SOCIAL" | "PERSONAL" | "FINANCE" | "COOK")[];
     intents: ("INGEST" | "QUERY" | "CORRELATE" | "FORGET")[];
     author?: string | undefined;
@@ -367,6 +570,27 @@ declare function assertScope(manifest: AppManifest, scope: (typeof VALID_SCOPES)
  * Vérifie qu'un vault est accessible selon le manifest.
  */
 declare function assertVault(manifest: AppManifest, vault: string): void;
+/**
+ * [MN-004] Détermine si l'OS DOIT afficher un popup de consentement utilisateur
+ * AVANT d'autoriser cette app à s'exécuter.
+ *
+ * La décision est basée UNIQUEMENT sur les scopes déclarés dans le manifest.
+ * Elle est imperméable à tout flag (`requires_grant`, `requires_consent`) que
+ * l'app pourrait contrôler elle-même.
+ *
+ * Règle : tout scope avec préfixe `vault:*`, `share:*` ou `llm:query` → GRANT requis.
+ *
+ * @example
+ * ```typescript
+ * import { requiresOsGrant } from '@mnemosyne_os/sdk';
+ * // Dans LAUNCH_LAYER2_APP (main process) :
+ * if (requiresOsGrant(appManifest)) {
+ *   const granted = await showPermissionPrompt(appManifest);
+ *   if (!granted) return { success: false, error: 'GRANT_DENIED' };
+ * }
+ * ```
+ */
+declare function requiresOsGrant(manifest: Pick<AppManifest, 'scopes'>): boolean;
 
 /**
  * @mnemosyne_os/sdk — Public Constants
@@ -398,6 +622,35 @@ declare const MNEMOSYNE_METHODS: {
     readonly CORRELATE: "sdk.correlate";
     /** Supprime un chronicle par ID (scope vault:write requis) */
     readonly FORGET: "sdk.forget";
+    /**
+     * Liste les Resonances actives (projets cognitifs) depuis le vault DEV.
+     * Requiert le scope `vault:read:DEV`.
+     */
+    readonly RESONANCES_LIST: "sdk.resonances.list";
+    /**
+     * Met à jour la position courante d'une Resonance (phase, description).
+     * Persisté comme chronicle DECISION dans le vault DEV.
+     * Requiert le scope `vault:write:DEV`.
+     */
+    readonly UPDATE_POSITION: "sdk.resonance.updatePosition";
+    /**
+     * Lit le git log du monorepo Mnemosyne OS.
+     * Requiert le scope `monorepo:read` dans le manifest.
+     * Retourne les commits filtrés (hash, message, author, date).
+     * [SECURITY] Path hardcodé côté serveur — le client ne contrôle pas le repo.
+     */
+    readonly GIT_LOG: "sdk.git.log";
+    /**
+     * Lit un fichier .md depuis le repo Mnemosyne OS (docs/, packages/).
+     * Requiert le scope `monorepo:read`.
+     * [SECURITY] Seuls les .md sont lisibles, path sanitizé côté serveur.
+     */
+    readonly READ_FILE: "sdk.readFile";
+    /**
+     * Liste les agents actifs connectés au SDK WebSocket Server.
+     * Requiert le scope `agents:read` dans le manifest.
+     */
+    readonly LIST_AGENTS: "sdk.agents.list";
     /** Demande d'accès aux chronicles d'une autre app (popup consentement) */
     readonly SHARE: "sdk.share";
     /**
@@ -440,4 +693,4 @@ declare const MNEMOSYNE_CHAINS: {
 };
 type MnemoChain = keyof typeof MNEMOSYNE_CHAINS;
 
-export { type AppManifest, AppManifestSchema, type Chronicle, type GraphEdge, type GraphNode, type GraphQueryResult, type IngestPayload, type IngestResult, type JwtPayload, type JwtVerifyResult, MNEMOSYNE_CHAINS, MNEMOSYNE_METHODS, MNEMOSYNE_NFT_CACHE_TTL_MS, MNEMOSYNE_TOKEN_TTL_S, MNEMOSYNE_WS_HOST, MNEMOSYNE_WS_PORT, type MnemoChain, MnemoClient, type MnemoClientOptions, type MnemoEvent, type MnemoEventType, type MnemoIntent, type MnemoMethod, type MnemoScope, type MnemoVault, type NFTLicenseParams, type NFTValidation, type QueryOptions, type QueryResult, type RegisterResult, type ShareRequest, type ShareResult, type SpineType, assertScope, assertVault, generateAppToken, generateSecret, loadManifest, parseManifest, verifyToken };
+export { type AgentInfo, type AppManifest, AppManifestSchema, type Chronicle, GRANT_REQUIRED_SCOPE_PREFIXES, type GitCommit, type GraphEdge, type GraphNode, type GraphQueryResult, type IngestPayload, type IngestResult, type JwtPayload, type JwtVerifyResult, MNEMOSYNE_CHAINS, MNEMOSYNE_METHODS, MNEMOSYNE_NFT_CACHE_TTL_MS, MNEMOSYNE_TOKEN_TTL_S, MNEMOSYNE_WS_HOST, MNEMOSYNE_WS_PORT, type MnemoChain, MnemoClient, MnemoClientBrowser, type MnemoClientOptions, type MnemoEvent, type MnemoEventType, type MnemoIntent, type MnemoMethod, type MnemoScope, type MnemoVault, type NFTLicenseParams, type NFTValidation, type QueryOptions, type QueryResult, type RegisterResult, type ShareRequest, type ShareResult, type SpineType, assertScope, assertVault, generateAppToken, generateSecret, loadManifest, parseManifest, requiresOsGrant, verifyToken };