@engramx/client 0.15.0-rc.3 → 0.16.0-rc.2

package/dist/types.d.ts

@@ -2,18 +2,18 @@ import { Principal } from '@icp-sdk/core/principal';
 export type Role = {
     Owner: null;
 } | {
-    Operator: null;
+    Agent: null;
 } | {
     Guardian: null;
 };
-export type OperatorStatus = {
+export type AgentStatus = {
     Active: null;
 } | {
     Revoked: null;
 } | {
-    Expired: null;
+    Resigned: null;
 };
-export interface OperatorPermissions {
+export interface AgentPermissions {
     canReadMemory: boolean;
     canAppendMemory: boolean;
     canReadWallet: boolean;
@@ -26,16 +26,129 @@ export interface OperatorPermissions {
      */
     scopes: [] | [string[]];
 }
-export interface OperatorRecord {
+/** The stored form of an enrolment statement — see `AgentRecord.enrolment`. */
+export interface EnrolmentProof {
+    rootPubkey: Uint8Array;
+    enrolledKey: Principal;
+    inviteCode: string;
+    signature: Uint8Array;
+}
+/** ⟨2026-09-29⟩ Why an agent's engagement with an engram ended. Mirrors the engram's `AgentEndReason`. */
+export type AgentEndReason = {
+    OwnerRevoked: null;
+} | {
+    GuardianRevoked: null;
+} | {
+    KillSwitch: null;
+} | {
+    Reset: null;
+} | {
+    Resigned: null;
+};
+/** ⟨2026-09-29⟩ An ending as the engram keeps it — see `AgentRecord.ended`. */
+export interface AgentEnding {
+    reason: AgentEndReason;
+    day: bigint;
+}
+/**
+ * ⟨2026-09-29⟩ Whether the registry put a new engagement on the agent's track record. `NotRecorded`
+ * carries a plain sentence: why, whether it is expected, and what to do. The pairing itself
+ * has succeeded either way. Mirrors the engram's `TrackRecordNotice`.
+ */
+export type TrackRecordNotice = {
+    Recorded: null;
+} | {
+    NotRecorded: string;
+};
+/**
+ * ⟨2026-10-01, the owner's ruling 2 A⟩ How many engrams of its own an agent may still open through
+ * this engram, as the owner set it (`setChildAllowance`). `root` is the agent's lasting key — the key
+ * that will own what it opens. Mirrors the engram's `ChildAllowanceRow`.
+ */
+export interface ChildAllowanceRow {
+    root: Principal;
+    remaining: bigint;
+}
+/** ⟨2026-09-29⟩ `pairAgent`'s reply: the agent record and its track-record notice. */
+export interface Pairing {
+    agent: AgentRecord;
+    trackRecord: TrackRecordNotice;
+}
+export interface AgentRecord {
     principal: Principal;
+    /**
+     * The agent this key belongs to: the principal of the root key that enrolled it (2026-09-28,
+     * owner decision: one root key per agent, with an enrolled key per client). The registry keeps
+     * the agent's track record under this.
+     */
+    root: Principal;
+    /**
+     * The enrolment statement that admitted this key, as the engram keeps it (2026-09-28, review
+     * finding OPS-1): the engram forwards it with every start it reports, so the registry verifies
+     * the root's consent itself instead of trusting the engram's word for the root. The invite code
+     * in it was burned at pairing.
+     */
+    enrolment: EnrolmentProof;
     name: string;
-    registeredAt: bigint;
-    lastSeen: bigint;
-    permissions: OperatorPermissions;
-    status: OperatorStatus;
-    publicKeyHash: string | null;
-    keyRotatedAt: bigint;
+    /**
+     * When this key was paired (nanoseconds). Renamed from `registeredAt` 2026-09-29 by the
+     * vocabulary ruling: pairing is the one verb that admits an agent.
+     */
+    pairedAtNs: bigint;
+    lastSeenNs: bigint;
+    permissions: AgentPermissions;
+    status: AgentStatus;
+    /**
+     * ⟨2026-09-29⟩ How this key's engagement with the engram ended — why, and the start of the UTC day
+     * (nanoseconds) it ended — or empty while it is active. The engram keeps it so the owner's
+     * `resyncAgentEdges` can re-send an ending the registry never received. Candid `opt`.
+     */
+    ended: [] | [AgentEnding];
+    /**
+     * ⟨CORRECTED 2026-10-05⟩ Was `string | null`. The wire is Candid `opt text`, and this record is
+     * handed back as delivered, so a caller gets `[]` or `[hash]`, never null: `=== null` never
+     * fired and `?? fallback` never applied. The same correction was made that day on
+     * ApprovalRequest and BackupMetadata; the wire-mirror gate now compares option-ness too.
+     */
+    publicKeyHash: [] | [string];
+    /** ⟨2026-09-29⟩ Count a key replacement as well as a change of the recorded key hash. */
+    keyRotatedAtNs: bigint;
     keyRotationCount: bigint;
+    /**
+     * ⟨2026-09-29, the owner's ruling of that date (follow-up 10)⟩ A replacement key this agent has
+     * nominated (`EngramClient.nominateAgentKey`) that has not yet accepted, and when (nanoseconds);
+     * empty when there is none. It expires 24 hours after it was made. Candid `opt`.
+     */
+    keyNomination: [] | [KeyNomination];
+    /**
+     * ⟨2026-09-29, review PR-6⟩ Where the engram's two logs stood when the key in use began to hold
+     * this record (at pairing, or at the replacement that moved it here). The agent reads the entries
+     * this key caused from here on, and none from before.
+     */
+    keyHeldFrom: LogPosition;
+    /**
+     * ⟨2026-09-29, review PR-6⟩ The keys this agent held on this engram before the one in use, oldest
+     * first (at most 16), each with the stretch of the logs it held the record for. The agent reads
+     * the entries each caused within its stretch, so a key replacement does not hide what it did
+     * before.
+     */
+    earlierKeys: HeldKey[];
+}
+/** ⟨2026-09-29, review PR-6⟩ The ids the next entries of the chained record and the read log get. */
+export interface LogPosition {
+    record: bigint;
+    reads: bigint;
+}
+/** ⟨2026-09-29, review PR-6⟩ A key an agent held, from `from` (inclusive) to `until` (exclusive). */
+export interface HeldKey {
+    key: Principal;
+    from: LogPosition;
+    until: LogPosition;
+}
+/** ⟨2026-09-29, follow-up 10⟩ A pending key nomination — see `AgentRecord.keyNomination`. */
+export interface KeyNomination {
+    key: Principal;
+    atNs: bigint;
 }
 /** Internal wire type — raw bytes as stored on-canister (plaintext; see encryption.ts) */
 export interface RawMemoryFile {
@@ -43,7 +156,7 @@ export interface RawMemoryFile {
     content: Uint8Array;
     version: bigint;
     lastModifiedBy: Principal;
-    lastModifiedAt: bigint;
+    lastModifiedAtNs: bigint;
 }
 /** Public type — content decoded to a UTF-8 string (no decryption; see encryption.ts) */
 export interface MemoryFile {
@@ -51,12 +164,12 @@ export interface MemoryFile {
     content: string;
     version: bigint;
     lastModifiedBy: Principal;
-    lastModifiedAt: bigint;
+    lastModifiedAtNs: bigint;
 }
 export interface MemoryFileInfo {
     path: string;
     version: bigint;
-    lastModifiedAt: bigint;
+    lastModifiedAtNs: bigint;
 }
 /**
  * Result of `startSession()` — the engram's memory assembled for injection at the start of an agent
@@ -93,7 +206,7 @@ export interface MemoryVersionSummary {
         tombstone: null;
     };
     by: Principal;
-    at: bigint;
+    atNs: bigint;
     size: bigint;
     /** 32-byte hash the record commits to. Anyone holding the bytes can check them against it. */
     contentRoot: Uint8Array;
@@ -152,34 +265,116 @@ export interface Account {
 }
 export interface AuditEntry {
     id: bigint;
-    timestamp: bigint;
+    timestampNs: bigint;
     caller: Principal;
     callerRole: Role;
     operation: string;
     details: string;
     success: boolean;
 }
+/**
+ * A window of the engram's record, as the reader may see it. ⟨2026-09-29, owner ruling follow-up 16
+ * (B)⟩ An agent reads only the entries it caused; the owner and guardians read everything. So
+ * `withheld` counts the entries in the window this reader was not shown, and `items.length +
+ * withheld` is the window examined: a page with `withheld > 0` is not the whole record. `total` is
+ * how many entries the record has ever held (the same number the public certified head publishes).
+ * WHAT WOULD MAKE THIS WRONG: a reader handed only `items` — which is why `readAuditLog` returns this
+ * page and not the bare array it used to.
+ */
+export interface AuditPage {
+    items: AuditEntry[];
+    total: bigint;
+    withheld: bigint;
+}
+/**
+ * ⚠ **STALE AS OF 2026-08-24 — this type no longer describes what the canister returns, and the
+ * three fields below carrying that news are the reason.** `EngramClient.status()` calls
+ * `about()` (the engram's `status()` was split into `about()` + `getOwnerConsole()` in the 0.16.0
+ * cut), and `About` carries NO `owner`, NO `authorized` and NO `cyclesBalance`. Measured against
+ * `src/engram/engram.did` on 2026-08-24, not inferred.
+ *
+ * Left declared rather than retyped because the retype is not local: `migrate.ts`'s
+ * `hasValidPairing` returns `status.authorized`, which is now `undefined` — falsy — so every
+ * caller reads as UNPAIRED. Removing the field here without fixing that call site turns a silent
+ * wrong answer into a compile error in a file this change does not own; both need to move
+ * together. Named here so the next reader does not mistake this for a description of the wire.
+ *
+ * ⟨RESOLVED 2026-10-05⟩ The banner above describes a past state: all three fields are now gone.
+ * `authorized` went on 2026-08-25 (its note is below). `owner` and `cyclesBalance` stayed declared
+ * until the v0.16.0-rc.1 release workflow failed to build the OpenClaw plugin, which still read
+ * `status.authorized`. The same plugin command read `status.cyclesBalance.length`. Against a real
+ * `about()` reply that is a TypeError, not a blank line, and tsc could not see it, because the
+ * actor is `ActorSubclass<any>` and this declaration is the only thing standing between a reader
+ * and the wire. Every field left here is one `type About` serves, compared field by field with
+ * `src/engram/engram.did`. test/wire-mirror.test.ts checks the same thing against the generated
+ * factory and fails on any declared field the reply does not carry. Read the owner and the cycles
+ * from `getOwnerConsole()`, which refuses a caller with no role on the engram instead of masking.
+ */
 export interface EngramStatus {
-    owner: Principal | null;
     memoryFileCount: bigint;
     auditLogSize: bigint;
-    operatorCount: bigint;
-    /**
-     * D3 discriminator: when false, cyclesBalance is a MASK (0), owner is null, and the sensitive
-     * fields are hidden — do not read cyclesBalance=0 as "broke" without checking this first.
-     */
-    /** Present only on 0.12.0+ engrams (not wire-declared until the fleet serves it). */
-    authorized?: boolean;
-    cyclesBalance: bigint;
+    agentCount: bigint;
     version: string;
     guardianCount: bigint;
     paymentsFrozen: boolean;
     writesPaused: boolean;
     backupCount: bigint;
     totalBackupSize: bigint;
+    /**
+     * Whether NEW memory writes should be encrypted client-side. Ungated, and ⟨2026-08-24⟩ for a
+     * simpler reason than the one recorded here before: this said "`status()` redacts only `owner`
+     * and `cyclesBalance`", which described the masking that the 0.16.0 split removed. `about()`
+     * redacts NOTHING — the fields worth redacting left for `getOwnerConsole()` — so this reads the
+     * `memoryEncryptionEnabled` var for every caller including an anonymous one. Verified against
+     * `src/engram/engram.did` (`type About`), which carries `encryptionEnabled : bool`.
+     *
+     * DECLARED HERE ON 2026-08-17 because the SDK now READS it. The canister has always served it;
+     * this interface simply never named it, because the client asked the singleton
+     * `isEncryptionEnabled()` instead. The surface diet (R3) removed that method — one variable, one
+     * audience, two doors — so `ensureEncryptionMode()`, `isMemoryEncryptionEnabled()` and
+     * `auditLogSize()` all come through this record now, and a field the write path branches on may
+     * not be left off the type.
+     *
+     * `totalMemoryWrites` and `verifiedHuman` are still served-but-undeclared here, exactly as
+     * before: this type is a narrowing of the record, not a transcription of it, and nothing in this
+     * package reads those two.
+     */
+    encryptionEnabled: boolean;
+}
+/**
+ * ⟨0.16.0, L2.2⟩ The GATED half of the `status()` split — the fields `about()` shed because they
+ * identify the engram's people or its money, which an anonymous query must not hand out.
+ *
+ * SHAPE READ FROM `src/generated/engram.idl.ts` (`const OwnerConsole = IDL.Record({…})`), not
+ * inferred. `owner` is `IDL.Opt(IDL.Principal)`, which agent-js delivers as a 0-or-1-element
+ * ARRAY — the same option-as-array shape that, read as a bare value elsewhere in this package,
+ * silently corrupted a certificate witness (see `optBytes` in certifiedAudit.ts). `cyclesBalance`
+ * is a BARE bigint here and an option on `EngramStatus`: the widening exists only on the ungated
+ * half, and behind a gate there is nobody to mask it from.
+ * ⟨CORRECTED 2026-10-05⟩ There is no option on `EngramStatus`. `about()` never served
+ * `cyclesBalance` at 0.16.0, so the field "on the ungated half" was a declaration with no wire
+ * behind it, and it is now deleted. This is the only SDK type left with a `cyclesBalance` field.
+ *
+ * DESPITE THE NAME the gate is #anyRole — owner, active agent or active guardian — which is
+ * what makes this the right pairing probe for an agent SDK.
+ */
+export interface OwnerConsole {
+    owner: [] | [Principal];
+    cyclesBalance: bigint;
+    memoryKeyEpoch: bigint;
+    protectedPathCount: bigint;
+    agentRevisablePathCount: bigint;
+    pendingApprovalCount: bigint;
+    /**
+     * ⟨ADDED 2026-10-05⟩ Served since the paid-session rail began counting, never declared here, so
+     * an SDK caller could not read it while the repo's own integration suite read it off the raw
+     * actor. How many paid-session calls named a session this engram does not have: counted, not
+     * logged, so a flood of forged session ids cannot push real refusals out of the denial log. Zero
+     * is a real answer on a fresh engram. Measured that day against engram.did: with it, this type
+     * declares all seven fields the record serves.
+     */
+    unknownSessionRefusals: bigint;
 }
-/** @deprecated Use EngramStatus instead */
-export type VaultStatus = EngramStatus;
 export type EngramRecordStatus = {
     Active: null;
 } | {
@@ -187,16 +382,12 @@ export type EngramRecordStatus = {
 } | {
     Deleted: null;
 };
-/** @deprecated Use EngramRecordStatus instead */
-export type VaultRecordStatus = EngramRecordStatus;
 export interface EngramRecord {
     owner: Principal;
     canisterId: Principal;
-    createdAt: bigint;
+    createdAtNs: bigint;
     status: EngramRecordStatus;
 }
-/** @deprecated Use EngramRecord instead */
-export type VaultRecord = EngramRecord;
 export interface RegistryStatus {
     totalEngrams: bigint;
     activeEngrams: bigint;
@@ -204,7 +395,7 @@ export interface RegistryStatus {
     engramWasmHash: string;
 }
 export interface GuardianPermissions {
-    canRevokeOperators: boolean;
+    canRevokeAgents: boolean;
     canFreezePayments: boolean;
     canPauseWrites: boolean;
     /**
@@ -216,214 +407,9 @@ export interface GuardianPermissions {
 export interface GuardianRecord {
     principal: Principal;
     name: string;
-    addedAt: bigint;
+    addedAtNs: bigint;
     permissions: GuardianPermissions;
 }
-export type SessionStatus = {
-    open: null;
-} | {
-    closing: null;
-} | {
-    closed: null;
-} | {
-    expired: null;
-}
-/** Reserved catch-all: a future ic402 status arrives as `other`, never as a new tag. */
- | {
-    other: string;
-};
-export interface Eip3009Authorization {
-    from: string;
-    to: string;
-    value: bigint;
-    validAfter: bigint;
-    validBefore: bigint;
-    nonce: Uint8Array;
-    v: number;
-    r: Uint8Array;
-    s: Uint8Array;
-}
-export interface PaymentRequirement {
-    scheme: string;
-    network: string;
-    token: string;
-    amount: bigint;
-    recipient: string;
-    nonce: Uint8Array;
-    expiry: bigint;
-    tokenName: string | null;
-    tokenVersion: string | null;
-}
-export interface PaymentSignature {
-    scheme: string;
-    network: string;
-    signature: Uint8Array;
-    asset: string | null;
-    publicKey: Uint8Array | null;
-    sender: string;
-    nonce: Uint8Array;
-    authorization: Eip3009Authorization | null;
-}
-export interface SessionIntent {
-    network: string;
-    token: string;
-    recipient: string;
-    suggestedDeposit: bigint;
-    minDeposit: bigint | null;
-    expiry: bigint;
-    costPerCall: bigint | null;
-    description: string | null;
-}
-export interface SessionConfig {
-    maxDeposit: bigint;
-    autoClose: boolean;
-    idleTimeout: bigint | null;
-}
-export interface SessionState {
-    id: string;
-    payer: Principal;
-    deposited: bigint;
-    consumed: bigint;
-    remaining: bigint;
-    voucherCount: bigint;
-    status: SessionStatus;
-    openedAt: bigint;
-    lastActivityAt: bigint;
-}
-export interface Voucher {
-    sessionId: string;
-    cumulativeAmount: bigint;
-    sequence: bigint;
-    signature: Uint8Array;
-}
-export interface SpendingPolicy {
-    maxPerTransaction: bigint | null;
-    maxPerDay: bigint | null;
-    rateLimitPerMinute: bigint | null;
-    maxSessionDeposit: bigint | null;
-    maxConcurrentSessions: bigint | null;
-    maxSessionDuration: bigint | null;
-    sessionIdleTimeout: bigint | null;
-    allowedCallers: Principal[] | null;
-    blockedCallers: Principal[] | null;
-}
-export interface ContentEntry {
-    id: string;
-    mimeType: string;
-    totalSize: bigint;
-    chunkCount: bigint;
-    createdAt: bigint;
-}
-export interface ContentRef {
-    id: string;
-    mimeType: string | null;
-    sizeBytes: bigint | null;
-    metadata: Array<[string, string]> | null;
-}
-export interface AccessGrant {
-    grantId: string;
-    contentRef: ContentRef;
-    grantee: Principal;
-    receiptId: string;
-    issuedAt: bigint;
-    expiresAt: bigint;
-    hmac: Uint8Array;
-}
-export type AccessGrantResult = {
-    ok: null;
-} | {
-    expired: string;
-} | {
-    revoked: string;
-} | {
-    invalidGrant: string;
-};
-export interface ContentDelivery {
-    grant: AccessGrant;
-    /** EVM settle tx hash when the purchase settled on-chain (null-opt otherwise). */
-    settlementTxHash: [string] | [];
-    delivery: {
-        inline: Uint8Array;
-    } | {
-        canisterQuery: {
-            method: string;
-            chunkCount: bigint;
-        };
-    } | {
-        httpUrl: string;
-    } | {
-        assetCanister: {
-            canisterId: Principal;
-            path: string;
-        };
-    };
-}
-export type PaymentResult = {
-    ok: PaymentReceipt;
-} | {
-    insufficientFunds: string;
-} | {
-    invalidSignature: string;
-} | {
-    expired: string;
-} | {
-    policyDenied: string;
-} | {
-    tokenNotAccepted: string;
-} | {
-    networkNotSupported: string;
-} | {
-    settlementFailed: string;
-} | {
-    settlementPending: string;
-} | {
-    reputationTooLow: bigint;
-} | {
-    depositBelowMinimum: bigint;
-}
-/** Reserved catch-all: a future ic402 result arrives as `other`, never as a new tag. */
- | {
-    other: string;
-};
-export interface PaymentReceipt {
-    id: string;
-    amount: bigint;
-    token: string;
-    sender: string;
-    recipient: string;
-    network: string;
-    timestamp: bigint;
-    txHash: string | null;
-    sessionId: string | null;
-    refunded: bigint | null;
-}
-export interface AgentCard {
-    name: string;
-    description: string;
-    services: ServiceEntry[];
-    x402Support: boolean;
-}
-export interface ServiceEntry {
-    name: string;
-    endpoint: string;
-    version: string;
-    skills: string[];
-    domains: string[];
-}
-export type VerificationLevel = {
-    Orb: null;
-} | {
-    Device: null;
-} | {
-    Document: null;
-};
-export interface WorldIdProof {
-    nullifierHash: string;
-    merkleRoot: string;
-    proof: string;
-    verificationLevel: VerificationLevel;
-    verifiedAt: bigint;
-}
 export type BackupType = {
     FullSnapshot: null;
 } | {
@@ -458,83 +444,34 @@ export interface ApprovalRequest {
     policyLimit: bigint;
     policyField: string;
     rationale: string;
-    createdAt: bigint;
-    expiresAt: bigint;
+    createdAtNs: bigint;
+    expiresAtNs: bigint;
     status: ApprovalStatus;
-    approvedBy: Principal | null;
-    approvedAt: bigint | null;
-    denialReason: string | null;
-}
-export type EndpointType = {
-    Content: null;
-};
-export type EndpointStatus = {
-    Disabled: null;
-} | {
-    Enabled: null;
-} | {
-    Deleted: null;
-};
-export interface X402Endpoint {
-    id: string;
-    name: string;
-    description: string;
-    endpointType: EndpointType;
-    contentId: string | null;
-    suggestedPrice: bigint;
-    price: bigint;
-    createdBy: Principal;
-    createdAt: bigint;
-    status: EndpointStatus;
-    enabledBy: Principal | null;
-    enabledAt: bigint | null;
-    totalRevenue: bigint;
-    totalPurchases: bigint;
-}
-export interface PurchaseRecord {
-    id: string;
-    endpointId: string;
-    buyer: string;
-    amount: bigint;
-    network: string;
-    timestamp: bigint;
-    receiptId: string;
-    txHash: string | null;
-}
-export interface RevenueSummary {
-    totalRevenue: bigint;
-    totalPurchases: bigint;
-    endpointBreakdown: Array<{
-        endpointId: string;
-        name: string;
-        revenue: bigint;
-        purchases: bigint;
-    }>;
-}
-export interface StorageStats {
-    totalFiles: bigint;
-    totalContentSize: bigint;
-    memoryFilesSize: bigint;
-    memoryFilesCount: bigint;
-    sessionFilesSize: bigint;
-    sessionFilesCount: bigint;
-    versionHistorySize: bigint;
-    versionHistoryCount: bigint;
-    backupSize: bigint;
-    backupCount: bigint;
-    fileLimit: bigint;
-    auditLogSize: bigint;
+    /**
+     * ⟨CORRECTED 2026-10-05⟩ These three were `X | null`. The wire is Candid `opt`, and
+     * getMyApprovalRequests hands the rows back as delivered, so each is `[]` or `[value]`, never
+     * null (see AgentRecord.publicKeyHash).
+     */
+    approvedBy: [] | [Principal];
+    approvedAtNs: [] | [bigint];
+    denialReason: [] | [string];
 }
 export interface BackupMetadata {
     backupId: string;
     dbType: string;
     backupType: BackupType;
-    parentBackupId: string | null;
+    /**
+     * ⟨CORRECTED 2026-10-05⟩ This and `backupLabel` were `string | null`. The wire is Candid `opt
+     * text`, and getBackupMetadata and listBackups hand the record back as delivered, so each is `[]`
+     * or `[text]`, never null (see AgentRecord.publicKeyHash). The OpenClaw backups table printed
+     * the label correctly only because an array of one string prints as that string.
+     */
+    parentBackupId: [] | [string];
     totalSize: bigint;
     chunkCount: bigint;
     sha256: string;
-    createdAt: bigint;
+    createdAtNs: bigint;
     createdBy: Principal;
-    backupLabel: string | null;
+    backupLabel: [] | [string];
     status: BackupStatus;
 }

package/dist/version.d.ts

@@ -0,0 +1,8 @@
+/** Printed in place of a version this module could not read: a visible blank, never the bare form. */
+export declare const UNREAD_VERSION = "<version>";
+/** The version this package was built with (its package.json's), or UNREAD_VERSION. */
+export declare const VERSION: string;
+/** `npx @engramx/client@<version>` — the prefix of every command this package's help prints. */
+export declare const NPX_CLIENT: string;
+/** The pairing command, pinned to this build's version. */
+export declare function pairCommand(code?: string, engram?: string): string;