@engramx/client 0.1.0-rc.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 EngramX contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# @engramx/client
+
+TypeScript SDK for EngramX — persistent, decentralized memory for AI agents on the Internet Computer.
+
+## What is this
+
+EngramX (Engram Externalized) stores your AI agent's memory, identity, session history, and wallet in an ICP canister. If the host machine dies, gets hacked, or moves — the agent resumes on a new machine with full state intact.
+
+This package is the client SDK that agents use to read and write their engram.
+
+## Install
+
+```bash
+pnpm add @engramx/client
+```
+
+## Quickstart
+
+```typescript
+import { EngramClient } from '@engramx/client';
+
+const engram = new EngramClient({
+  canisterId: 'xxxxx-xxxxx-xxxxx-xxxxx-xxx',
+  sessionKeyPath: '~/.engramx/session.key',
+});
+
+// Read memory
+const file = await engram.readMemory('MEMORY.md');
+console.log(file.content);
+
+// Append to memory
+const version = await engram.appendMemory('memory/daily.md', '## Notes\nSomething happened.');
+
+// Read several files at once
+const files = await engram.readMemoryBatch(['MEMORY.md', 'memory/daily.md']);
+
+// Check balance
+const balance = await engram.walletBalance();
+```
+
+## Pairing
+
+Register your machine as an operator:
+
+```bash
+# Pair this host — register as operator and install the OpenClaw plugin
+pnpm dlx @engramx/client pair <invite-code> --engram <canister-id> --target openclaw
+
+# Replacement host — after pairing, restore memory from the engram
+pnpm dlx @engramx/client migrate --engram <canister-id> --recover
+```
+
+`pair` generates `~/.engramx/session.key`, registers the operator, and installs the OpenClaw plugin. `migrate` then moves memory, saving a local checkpoint first — run `npx @engramx/client rollback` to undo. Its default direction pushes local memory files to the engram; `--recover` instead restores database backups, and memory files sync automatically on next OpenClaw startup.
+
+## Guardian API
+
+Guardians are trusted principals who can take emergency actions. Adding/removing
+guardians is an owner-only operation done from the engramx.ai dashboard with
+Internet Identity authentication. The SDK exposes the read-only side:
+
+```typescript
+// List guardians
+const guardians = await engram.listGuardians();
+```
+
+The SDK runs on operator-credentialed agent hosts and intentionally does NOT
+expose owner-only methods (writeMemory, addGuardian, setProtectedPaths,
+setPaymentPolicy, signTypedData, etc.). Owner workflows belong in the
+dashboard at engramx.ai.
+
+## Backup API
+
+Store and retrieve external database snapshots:
+
+```typescript
+// Init a backup upload
+const backupId = await engram.initBackup('sqlite', { FullSnapshot: null }, null, sha256, 'daily-backup');
+
+// Upload in chunks
+await engram.pushBackupChunk(backupId, 0, chunkData);
+
+// Finalize
+await engram.finalizeBackup(backupId);
+
+// List backups
+const backups = await engram.listBackups('sqlite');
+
+// Download a chunk
+const data = await engram.pullBackupChunk(backupId, 0);
+```
+
+## OpenClaw Integration
+
+The `--target openclaw` option on `pair` handles plugin installation and `openclaw.json` configuration automatically. For manual setup or customization, see [integrations/openclaw/README.md](../../integrations/openclaw/README.md).
+
+## Roadmap
+
+These features are stubbed and available in the canister interface but not yet fully implemented:
+
+- **ERC-8004 Agent Identity** — threshold ECDSA-derived Ethereum address
+- **x402 Payment Protocol** — autonomous HTTP-based payments
+- **World ID** — proof-of-personhood for engram owners
+
+## License
+
+MIT

package/dist/EngramClient.d.ts

@@ -0,0 +1,223 @@
+import { Principal } from '@icp-sdk/core/principal';
+import { Ic402Client, type SessionHandle } from '@ic402/client';
+import type { RawMemoryFile, MemoryFile, MemoryFileInfo, MemoryVersion, OperatorRecord, AuditEntry, EngramStatus, GuardianRecord, WorldIdProof, BackupMetadata, BackupType, StorageStats, PaymentRequirement, PaymentSignature, PaymentResult, SessionIntent, SessionConfig, SessionState, Voucher, SpendingPolicy, ContentEntry, ContentDelivery, AgentCard, ApprovalRequest, EndpointType, EndpointStatus, X402Endpoint, PurchaseRecord, RevenueSummary } from './types';
+export interface EngramClientConfig {
+    /** The engram canister ID */
+    canisterId: string;
+    /** Path to the Ed25519 session key file */
+    sessionKeyPath?: string;
+    /** Or provide the key directly as a Uint8Array (32 bytes seed) */
+    sessionKeySeed?: Uint8Array;
+    /** ICP host. Default: 'https://ic0.app' for mainnet */
+    host?: string;
+    /** Cache duration in milliseconds for memory reads. Default: 60000 (1 minute) */
+    cacheMaxAge?: number;
+    /** Max cache entries. Default: 100 */
+    cacheMaxSize?: number;
+    /** Path for offline queue. Default: null (disabled) */
+    offlineQueuePath?: string;
+    /** Encrypt memory content client-side via vetKeys. Default: false (plaintext).
+     *  Enable for new/migrated engrams; the canister must support vetKD. Reads of
+     *  legacy plaintext keep working regardless. */
+    encryptMemory?: boolean;
+}
+export declare class EngramClient {
+    private agent;
+    private actor;
+    private cache;
+    private offlineQueue?;
+    private identity;
+    private canisterId;
+    private encryption;
+    private encryptionModeSynced;
+    private unwrap;
+    constructor(config: EngramClientConfig);
+    readMemory(path: string): Promise<MemoryFile>;
+    appendMemory(path: string, content: string): Promise<bigint>;
+    listMemoryFiles(): Promise<MemoryFileInfo[]>;
+    readMemoryBatch(paths: string[]): Promise<[string, MemoryFile | Error][]>;
+    getMemoryHistory(path: string): Promise<MemoryVersion[]>;
+    walletBalance(): Promise<bigint>;
+    readAuditLog(fromIndex?: number, limit?: number): Promise<AuditEntry[]>;
+    auditLogSize(): Promise<bigint>;
+    status(): Promise<EngramStatus>;
+    listGuardians(): Promise<GuardianRecord[]>;
+    rotateOperatorKey(newPublicKeyHash: string): Promise<void>;
+    getWorldIdProof(): Promise<WorldIdProof | null>;
+    getPaymentRequirements(amount: bigint): Promise<PaymentRequirement[]>;
+    requestSession(): Promise<SessionIntent>;
+    openSession(config: SessionConfig, sig: PaymentSignature, rationale?: string, approvalId?: string): Promise<SessionState | {
+        approvalPending: ApprovalRequest;
+    }>;
+    sessionReadMemory(voucher: Voucher, path: string): Promise<RawMemoryFile>;
+    sessionAppendMemory(voucher: Voucher, path: string, content: Uint8Array): Promise<bigint>;
+    endSession(sessionId: string): Promise<PaymentResult>;
+    forceCloseSession(sessionId: string): Promise<PaymentResult>;
+    uploadContent(id: string, mimeType: string, data: Uint8Array): Promise<void>;
+    /**
+     * E8: upload content larger than the ~2 MB single-shot ingress limit by streaming it through the
+     * canister's chunked path (uploadContentInit + uploadContentChunk). Chunk size is 1.5 MB — the
+     * ContentStore MAX_CHUNK_SIZE, enforced as a hard cap and safely under ICP's 2 MB ingress limit once
+     * Candid framing is added.
+     *
+     * There is NO finalize step: content is complete and readable once every chunk is written (the store
+     * reassembles on read). Chunks are write-once server-side (CTR keystream-reuse guard), so a mid-upload
+     * failure leaves a stuck, un-overwritable entry; on any error this helper best-effort deletes the
+     * partial entry so the caller can retry from scratch (set cleanupOnError=false to keep it for a manual
+     * resume). Payloads at or under one chunk delegate to single-shot uploadContent.
+     */
+    uploadContentChunked(id: string, mimeType: string, data: Uint8Array, cleanupOnError?: boolean): Promise<void>;
+    listContent(): Promise<ContentEntry[]>;
+    getContent(contentId: string, paymentSig?: PaymentSignature, rationale?: string, approvalId?: string): Promise<{
+        paymentRequired?: PaymentRequirement[];
+        delivery?: ContentDelivery;
+        error?: string;
+        approvalPending?: ApprovalRequest;
+    }>;
+    deleteContent(id: string): Promise<void>;
+    createEndpoint(name: string, description: string, endpointType: EndpointType, contentId: string | null, suggestedPrice: bigint): Promise<X402Endpoint>;
+    listEndpoints(statusFilter?: EndpointStatus): Promise<X402Endpoint[]>;
+    getEndpointPurchases(endpointId: string, fromIndex: bigint, limit: bigint): Promise<PurchaseRecord[]>;
+    getRevenueSummary(): Promise<RevenueSummary>;
+    getPaymentPolicy(): Promise<SpendingPolicy>;
+    getAgentCard(): Promise<AgentCard>;
+    getEvmAddress(): Promise<string>;
+    getOwnerEvmAddress(): Promise<string | null>;
+    initBackup(dbType: string, backupType: BackupType, parentBackupId: string | null, sha256: string, backupLabel: string | null): Promise<string>;
+    pushBackupChunk(backupId: string, chunkIndex: number, data: Uint8Array): Promise<void>;
+    finalizeBackup(backupId: string): Promise<void>;
+    abortBackup(backupId: string): Promise<void>;
+    listBackups(dbTypeFilter?: string): Promise<BackupMetadata[]>;
+    pullBackupChunk(backupId: string, chunkIndex: number): Promise<Uint8Array>;
+    getBackupMetadata(backupId: string): Promise<BackupMetadata>;
+    deleteBackup(backupId: string): Promise<void>;
+    latestBackupMatchesHash(dbType: string, sha256: string): Promise<BackupMetadata | null>;
+    storageStats(): Promise<StorageStats>;
+    /** Warm the vetKeys memory-encryption key cache (one vetKD derivation). Optional —
+     *  read/append derive lazily on first use. */
+    initEncryption(): Promise<void>;
+    clearEncryptionCache(): void;
+    /** Sync the write-time encryption mode from the canister flag (once, cached),
+     *  unless an explicit `encryptMemory` was given at construction. */
+    private ensureEncryptionMode;
+    /** Whether this engram has memory encryption enabled (reads the canister flag). */
+    isMemoryEncryptionEnabled(): Promise<boolean>;
+    /** Owner-only: turn memory encryption on/off on the canister. Updates the local
+     *  write mode immediately. Turning ON does not re-encrypt existing files — call
+     *  migrateMemoryToEncrypted() for that. */
+    setMemoryEncryption(enabled: boolean): Promise<void>;
+    /** Owner-only: re-encrypt all existing memory files under the current key. Reads
+     *  each file (decrypting any that are already encrypted), then rewrites it via
+     *  writeMemory so it is stored as ciphertext. Idempotent and resumable — files
+     *  already encrypted are simply re-written identically. Requires encryption to be
+     *  enabled (canister flag) and an owner identity (writeMemory is owner-only). */
+    migrateMemoryToEncrypted(): Promise<{
+        migrated: number;
+        total: number;
+        failed: string[];
+    }>;
+    syncOfflineQueue(): Promise<{
+        synced: number;
+        failed: number;
+    }>;
+    registerOperator(inviteCode: string): Promise<OperatorRecord>;
+    getProtectedPaths(): Promise<string[]>;
+    /**
+     * Create a pre-configured Ic402Client for auto-payment operations.
+     * The client handles 402 → ICRC-2 approve → retry automatically.
+     */
+    createPaymentClient(options?: {
+        autoPayment?: boolean;
+        ledger?: string;
+    }): Ic402Client;
+    /**
+     * Auto-pay bridge for the engramx x402 methods. The stock ic402 client injects the
+     * payment signature into the LAST argument, but the engramx canister appends
+     * `rationale` + `approvalId` AFTER `paymentSig` (for the owner approval workflow), so the
+     * signature must land at a FIXED index, not last. Flow: call with no sig → on
+     * #paymentRequired, icrc2_approve the amount (+ fee buffer) → build the ICP payment
+     * signature (a nonce-carrier; the real authorization is the ICRC-2 allowance the canister
+     * spends via transfer_from) → retry with the sig at `sigIndex`. Returns the raw canister
+     * result; the caller unwraps ok/error/approvalPending.
+     */
+    private payAndCall;
+    /**
+     * Get paid content with auto-payment. Handles #paymentRequired → approve → retry.
+     * @param contentId Content identifier
+     * @param options Optional ledger override
+     */
+    getContentWithPayment(contentId: string, options?: {
+        ledger?: string;
+    }): Promise<ContentDelivery>;
+    /**
+     * Open a streaming payment session with auto-escrow and voucher signing.
+     * Returns a SessionHandle that auto-signs vouchers on each call.
+     *
+     * Usage:
+     *   const session = await engram.openPaymentSession({ maxDeposit: 50_000n });
+     *   const file = await session.call('sessionReadMemory', ['SOUL.md']);
+     *   const receipt = await session.close();
+     */
+    openPaymentSession(options?: {
+        maxDeposit?: bigint;
+        autoClose?: boolean;
+        ledger?: string;
+    }): Promise<SessionHandle>;
+    registerService(name: string, description: string, serviceType: {
+        Sync: null;
+    } | {
+        Async: null;
+    }, pricing: {
+        Exact: bigint;
+    } | {
+        Upto: bigint;
+    } | {
+        Session: null;
+    }, verificationMethod: string, delivery: {
+        Poll: null;
+    } | {
+        Callback: null;
+    } | {
+        Both: null;
+    }, timeout: bigint, verifierCanisterId?: string, verificationKey?: Uint8Array, bindResult?: boolean): Promise<string>;
+    listServices(): Promise<unknown[]>;
+    /** Owner/operator view — includes disabled service drafts (others get enabled-only). */
+    listAllServices(): Promise<unknown[]>;
+    submitServiceRequest(serviceId: string, params: Uint8Array, paymentSig?: unknown, rationale?: string, approvalId?: string): Promise<{
+        jobId: string;
+    } | {
+        approvalPending: unknown;
+    }>;
+    /**
+     * Submit a paid service request with auto-payment (the marketplace counterpart of
+     * getContentWithPayment). Handles #paymentRequired → approve → retry, injecting the
+     * signature at the correct index for the engramx submitServiceRequest signature
+     * (serviceId, params, paymentSig, rationale, approvalId). Returns the jobId, or an
+     * approval-pending handle when the charge exceeds policy and the owner must approve.
+     */
+    submitServiceRequestWithPayment(serviceId: string, params: Uint8Array, options?: {
+        ledger?: string;
+        rationale?: string;
+    }): Promise<{
+        jobId: string;
+    } | {
+        approvalPending: unknown;
+    }>;
+    claimJob(jobId: string): Promise<void>;
+    submitJobResult(jobId: string, result: Uint8Array, proof?: Uint8Array, actualCost?: bigint): Promise<void>;
+    confirmJob(jobId: string): Promise<void>;
+    disputeJob(jobId: string, reason: string): Promise<void>;
+    getJobStatus(jobId: string): Promise<unknown | null>;
+    getJob(jobId: string): Promise<unknown | null>;
+    /**
+     * E1: enumerate a service's job summaries. Owner OR the service's own operator only — any other
+     * caller gets []. Summaries omit params/result/proof blobs (use getJob(jobId) for a full payload).
+     * Pass a statusFilter like `{ Pending: null }` to filter, or omit for all statuses.
+     */
+    listJobs(serviceId: string, statusFilter?: unknown): Promise<unknown[]>;
+    getJobResult(jobId: string): Promise<Uint8Array | null>;
+    pollJobResult(jobId: string, maxAttempts?: number, intervalMs?: number): Promise<unknown>;
+    keccak256(data: number[]): Promise<number[]>;
+    clearCache(): void;
+    getPrincipal(): Principal;
+}