@engramx/client 0.1.0 → 0.2.1

package/LICENSE

@@ -1,21 +1,190 @@
-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.
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025-2026 Vaughn Hew
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -22,25 +22,24 @@ import { EngramClient } from '@engramx/client';
 const engram = new EngramClient({
   canisterId: 'xxxxx-xxxxx-xxxxx-xxxxx-xxx',
   sessionKeyPath: '~/.engramx/session.key',
+  clientLabel: 'my-agent', // identifies this host in the engram's cross-model reuse set
 });
 
-// Read memory
-const file = await engram.readMemory('MEMORY.md');
-console.log(file.content);
+// At the START of a session: load everything the agent remembers, ready to inject as a
+// system prompt. This is the "read me back" that continuity depends on — prefer it over a
+// manual readMemoryBatch: it runs on the update path, so the read is recorded on-chain and
+// counts toward reuse. (Query reads can't — the IC discards query-path state changes.)
+const systemPrompt = await engram.sessionSystemPrompt();
+// ...or get the structured files instead of a formatted string:
+const ctx = await engram.startSession();
+console.log(`loaded ${ctx.includedFiles}/${ctx.totalFiles} files`);
 
-// Append to memory
+// AS THE AGENT WORKS: append (append-only; the canister concatenates the delta)
 const version = await engram.appendMemory('memory/daily.md', '## Notes\nSomething happened.');
 
-// Search memory
-const results = await engram.searchKeyword('authentication', 5);
-
-// Read session transcript
-const messages = await engram.readSession('session-key', 0, 50);
-
-// Append to session
-await engram.appendSession('session-key', [
-  { role: { User: null }, content: 'Hello', timestamp: BigInt(Date.now() * 1_000_000) },
-]);
+// Point reads: one file, or several at once
+const file = await engram.readMemory('MEMORY.md');
+const files = await engram.readMemoryBatch(['MEMORY.md', 'memory/daily.md']);
 
 // Check balance
 const balance = await engram.walletBalance();
@@ -51,16 +50,14 @@ const balance = await engram.walletBalance();
 Register your machine as an operator:
 
 ```bash
-# First host — push local memory files to the engram
-pnpm dlx @engramx/client pair <invite-code> --engram <canister-id> --openclaw
+# 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 — restore database backups from the engram
-pnpm dlx @engramx/client pair <invite-code> --engram <canister-id> --openclaw --recover
+# Replacement host — after pairing, restore memory from the engram
+pnpm dlx @engramx/client migrate --engram <canister-id> --recover
 ```
 
-Both modes generate `~/.engramx/session.key`, register the operator, and install the OpenClaw plugin. They save a local checkpoint first — run `engramx rollback` to undo.
-
-Migration (default) pushes local memory files to the engram. Recovery (`--recover`) restores database backups; memory files sync automatically on next OpenClaw startup.
+`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
 
@@ -101,7 +98,7 @@ const data = await engram.pullBackupChunk(backupId, 0);
 
 ## OpenClaw Integration
 
-The `--openclaw` flag on `pair` handles plugin installation and `openclaw.json` configuration automatically. For manual setup or customization, see [integrations/openclaw/README.md](../../integrations/openclaw/README.md).
+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
 

package/dist/EngramClient.d.ts

@@ -1,6 +1,7 @@
+import { type CertifiedAuditHead, type VerifiedAuditHead } from './certifiedAudit';
 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';
+import type { RawMemoryFile, MemoryFile, MemoryFileInfo, SessionContext, 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;
@@ -20,7 +21,13 @@ export interface EngramClientConfig {
      *  Enable for new/migrated engrams; the canister must support vetKD. Reads of
      *  legacy plaintext keep working regardless. */
     encryptMemory?: boolean;
+    /** Label identifying this host in the engram's distinct-reader set (drives cross-model reuse
+     *  metrics). Sent by `startSession()`. Default: 'sdk'. Use your product name, e.g. 'openclaw'. */
+    clientLabel?: string;
 }
+export declare const idlFactory: ({ IDL }: {
+    IDL: any;
+}) => any;
 export declare class EngramClient {
     private agent;
     private actor;
@@ -30,16 +37,68 @@ export declare class EngramClient {
     private canisterId;
     private encryption;
     private encryptionModeSynced;
+    private clientLabel;
     private unwrap;
     constructor(config: EngramClientConfig);
     readMemory(path: string): Promise<MemoryFile>;
+    /**
+     * Append `content` to a memory file (append-only; the canister concatenates the delta).
+     *
+     * @returns the new on-chain version. **Special case:** if an `offlineQueue` is configured and the
+     * network call fails with a transport error, the encoded delta is queued for a later
+     * `syncOfflineQueue()` and this returns `0n` — a "deferred, not yet committed" sentinel, NOT a real
+     * version. Callers that surface a version to users should treat `0n` as "queued". Deterministic
+     * errors (validation, permission, writes-paused, non-framed base in encrypted mode) always throw.
+     */
     appendMemory(path: string, content: string): Promise<bigint>;
     listMemoryFiles(): Promise<MemoryFileInfo[]>;
     readMemoryBatch(paths: string[]): Promise<[string, MemoryFile | Error][]>;
+    /**
+     * Load the engram's memory for injection at the START of an agent session — the automatic
+     * "read me back" that continuity depends on.
+     *
+     * Prefer this over a manual `readMemoryBatch` at session start: it runs on the canister's UPDATE
+     * path, so it registers the read on-chain and counts toward the engram's cross-model reuse metric
+     * (the north star). A query read cannot — the IC discards query-path state changes — so a session
+     * bootstrapped with queries is invisible to reuse accounting. Call this once per session; write with
+     * `appendMemory` as the agent works.
+     *
+     * Files come back newest-modified first and decrypted; `truncated` is true when the byte cap was hit
+     * and older files were omitted (page them with `readMemoryBatch`). Reserved `config/` and `secrets/`
+     * paths are excluded. Pass `clientLabel` in the constructor to identify this host in the reuse set.
+     *
+     * This is an update call, so it can fail transiently (rate limit) or deterministically (permission).
+     * By default it throws; pass `{ onError: 'empty' }` to degrade to an empty context instead — useful
+     * when a missing memory read should not abort the agent's session bootstrap.
+     */
+    startSession(opts?: {
+        onError?: 'throw' | 'empty';
+    }): Promise<SessionContext>;
+    private loadSessionContext;
+    /**
+     * Format a {@link SessionContext} into a single system-prompt string ready to prepend to an agent's
+     * messages. Convenience over `startSession` for the common "inject everything I remember" case — call
+     * `startSession()` yourself if you need the structured files instead. Accepts the same `onError`
+     * option as `startSession`.
+     *
+     * SECURITY: memory content is written by operators (AI hosts) and is UNTRUSTED input, not host
+     * instructions. Each file is wrapped in a delimited `<engram-memory>` block and the header tells the
+     * model to treat the blocks as data — so appended memory cannot masquerade as system-level directives
+     * (prompt-injection boundary). Do not strip the fences when embedding this in your own prompt.
+     */
+    sessionSystemPrompt(opts?: {
+        onError?: 'throw' | 'empty';
+    }): Promise<string>;
     getMemoryHistory(path: string): Promise<MemoryVersion[]>;
     walletBalance(): Promise<bigint>;
     readAuditLog(fromIndex?: number, limit?: number): Promise<AuditEntry[]>;
     auditLogSize(): Promise<bigint>;
+    /** The chained audit-log head plus the IC certificate over it (raw, unverified). Use
+     *  getVerifiedAuditHead() to verify it against the IC root key. */
+    getCertifiedAuditHead(): Promise<CertifiedAuditHead>;
+    /** Fetch the certified audit head and VERIFY it against the IC root key — returns the certified
+     *  head bytes and whether the replica's claim agrees, WITHOUT trusting this replica. */
+    getVerifiedAuditHead(): Promise<VerifiedAuditHead>;
     status(): Promise<EngramStatus>;
     listGuardians(): Promise<GuardianRecord[]>;
     rotateOperatorKey(newPublicKeyHash: string): Promise<void>;
@@ -47,19 +106,51 @@ export declare class EngramClient {
     getPaymentRequirements(amount: bigint): Promise<PaymentRequirement[]>;
     requestSession(): Promise<SessionIntent>;
     openSession(config: SessionConfig, sig: PaymentSignature, rationale?: string, approvalId?: string): Promise<SessionState | {
-        approvalPending: ApprovalRequest;
+        approvalPending: {
+            requestId: string;
+            reason: string;
+        };
     }>;
     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>;
+    private ownerAuthFor;
+    /**
+     * Withdraw a token balance to the owner's own principal (owner-only, destination-locked).
+     * Pass `{ receipt: true }` to attach an exportable owner-signed authorization (D1).
+     */
+    ownerWithdraw(token: string, amount: bigint, options?: {
+        receipt?: boolean;
+        nonce?: bigint;
+    }): Promise<{
+        Ok: bigint;
+    } | {
+        Err: string;
+    }>;
     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;
+        approvalPending?: {
+            requestId: string;
+            reason: string;
+        };
     }>;
     deleteContent(id: string): Promise<void>;
     createEndpoint(name: string, description: string, endpointType: EndpointType, contentId: string | null, suggestedPrice: bigint): Promise<X402Endpoint>;
@@ -79,6 +170,15 @@ export declare class EngramClient {
     getBackupMetadata(backupId: string): Promise<BackupMetadata>;
     deleteBackup(backupId: string): Promise<void>;
     latestBackupMatchesHash(dbType: string, sha256: string): Promise<BackupMetadata | null>;
+    /** Encrypt a backup payload IFF this engram is in Private mode — the SAME toggle that governs
+     *  memory files governs backups (encrypt files ⇒ encrypt backups). Produces a whole-blob
+     *  envelope (MAGIC|ciphertext); a passthrough (returns the input) in Connected mode. Compute the
+     *  dedup/integrity SHA-256 over the PLAINTEXT, then encrypt its result for upload. */
+    encryptBackupPayload(data: Uint8Array): Promise<Uint8Array>;
+    /** Reverse of encryptBackupPayload: decrypt a pulled backup blob when it carries the ENC magic.
+     *  Content-driven (not flag-driven), so a plaintext / legacy backup passes through unchanged
+     *  regardless of the current mode. Returns the original DB bytes, ready to write to disk. */
+    decryptBackupPayload(bytes: Uint8Array): Promise<Uint8Array>;
     storageStats(): Promise<StorageStats>;
     /** Warm the vetKeys memory-encryption key cache (one vetKD derivation). Optional —
      *  read/append derive lazily on first use. */
@@ -103,12 +203,27 @@ export declare class EngramClient {
         total: number;
         failed: string[];
     }>;
+    /** Owner-only: DECRYPT all existing memory files back to plaintext-at-rest — the reverse of
+     *  migrateMemoryToEncrypted(). Reads each file, and if it is encrypted (framed segments or a
+     *  legacy whole-file envelope), recovers the plaintext BYTES and rewrites it via writeMemory;
+     *  already-plaintext files are skipped. Idempotent + resumable. Run this BEFORE turning
+     *  encryption off so the hosted surface can serve the files. Decryption derives the key on
+     *  demand, so it works regardless of the canister flag for a read-authorized owner. */
+    migrateMemoryToPlaintext(): Promise<{
+        migrated: number;
+        total: number;
+        failed: string[];
+    }>;
     syncOfflineQueue(): Promise<{
         synced: number;
         failed: number;
     }>;
     registerOperator(inviteCode: string): Promise<OperatorRecord>;
     getProtectedPaths(): Promise<string[]>;
+    /** The caller's OWN payment approval requests (not owner-only listApprovalRequests). Poll this after an
+     *  over-limit payment returns approvalPending: when the owner raises the spending limit, the request
+     *  flips to `Approved` and the operation can be retried. Operator-safe (returns only your own requests). */
+    getMyApprovalRequests(): Promise<ApprovalRequest[]>;
     /**
      * Create a pre-configured Ic402Client for auto-payment operations.
      * The client handles 402 → ICRC-2 approve → retry automatically.
@@ -166,7 +281,7 @@ export declare class EngramClient {
         Callback: null;
     } | {
         Both: null;
-    }, timeout: bigint, verifierCanisterId?: string, verificationKey?: Uint8Array): Promise<string>;
+    }, 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[]>;
@@ -196,6 +311,12 @@ export declare class EngramClient {
     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[]>;