@usepraxis/sdk 0.2.0 → 0.5.0

package/dist/index.d.cts

@@ -130,6 +130,14 @@ interface TransferDetail {
     recipientName: string;
     recipientAddress: Address;
     recipientNote?: string;
+    /** The destination is the owner's own wallet (derived from the address). */
+    toSelf?: true;
+    /**
+     * Server-computed USD value of `amount`, as a decimal string, when a real
+     * price is available. Absent means "not known" — display only, and never an
+     * input to base-unit math.
+     */
+    usdEstimate?: string;
 }
 interface SwapDetail {
     kind: "swap";
@@ -144,6 +152,14 @@ type ProposalDetail = TransferDetail | SwapDetail;
 type ProposalState = "pending" | "signing" | "signed" | "blocked" | "cancelled";
 interface ActionProposal {
     id: string;
+    /**
+     * Unix seconds when the proposal was produced. The signature gate refuses a
+     * proposal older than a week: the amount is fixed and Aegis enforces the
+     * envelope live, but the readings on it (fee, simulation, remaining
+     * envelope, USD figure) drift. Ask again for a fresh one. Absent on
+     * proposals created before this field existed.
+     */
+    createdAt?: number;
     detail: ProposalDetail;
     networkFee: BaseUnitString;
     simulation: string;
@@ -158,15 +174,46 @@ interface ClarifyOption {
 }
 interface ResearchMetric {
     label: string;
+    /** Already display-formatted, and abbreviated where a raw figure is unreadable. */
     value: string;
+    /** The full-precision figure behind an abbreviated `value`, when one was cut. */
+    exact?: string;
+    /** Why the metric is missing, or what it measures. */
+    note?: string;
     trend?: "up" | "down" | "flat";
 }
+/**
+ * One step in how a research card was produced. A card whose whole claim is
+ * "data, no advice" has to be able to show its working: "unavailable" means
+ * something different when an indexer has no pair than when an RPC refused
+ * the query.
+ */
+interface ResearchSource {
+    /** "Solana RPC", "Market data (…)", "PreStocks", "Token resolution". */
+    label: string;
+    status: "ok" | "partial" | "unavailable";
+    detail: string;
+}
 interface ResearchData {
     token: string;
+    /** Project name from the indexer, when it differs from the ticker. */
+    name?: string;
     mint: Address;
     metrics: ResearchMetric[];
+    /** How the card was produced, in the order the steps ran. */
+    sources?: ResearchSource[];
     summary: string;
 }
+/**
+ * Stocklana C07: one PreStocks entry from `GET /get-stock-universe`.
+ * Empty unless the server runs with `PRAXIS_STOCKS_ENABLED=1`.
+ */
+interface StockUniverseEntry {
+    symbol: string;
+    name: string;
+    mint: Address;
+    decimals: number;
+}
 interface PolicyChangeRow {
     label: string;
     from: string;
@@ -221,6 +268,8 @@ interface ActivityEntry {
     id: string;
     kind: "transfer" | "swap";
     label: string;
+    /** Destination address for a transfer. Stable where `label` is a lookup. */
+    target?: Address;
     asset: string;
     amount: BaseUnitString;
     decimals: number;
@@ -230,11 +279,46 @@ interface ActivityEntry {
     ts: number;
     sig?: string;
 }
+/** When a recurring buy fires. `weekday`: 0=Sunday..6=Saturday (UTC). */
+type DcaCadence = {
+    type: "daily";
+} | {
+    type: "weekly";
+    weekday: number;
+} | {
+    type: "monthly";
+    day: number;
+};
+/**
+ * One recurring-buy schedule from `GET /get-schedules`. Each fire emits one
+ * transfer proposal through the same policy checks as a one-off buy — nothing
+ * ever auto-signs. Money is a base-unit string per the money rule above.
+ */
+interface DcaSchedule {
+    id: string;
+    asset: string;
+    amount: BaseUnitString;
+    decimals: number;
+    recipientAddress: Address;
+    recipientName: string;
+    cadence: DcaCadence;
+    /** Unix milliseconds of the next fire. */
+    nextFireTs: number;
+    createdAt: number;
+    threadId: string;
+}
 interface UnsignedOwnerTransaction {
     /** base64-encoded unsigned transaction for the owner wallet to sign. */
     transaction: string;
     blockhash: string;
     lastValidBlockHeight: number;
+    /**
+     * Opaque, backend-signed fingerprint of this draft. Echo it back verbatim in
+     * {@link SignedOwnerTransaction}: the relay refuses any transaction that is
+     * not the one Praxis built, which is what keeps the server-side checks for
+     * this action from being skippable.
+     */
+    draft: string;
 }
 /**
  * An {@link UnsignedOwnerTransaction} after the owner wallet has signed it — the
@@ -268,6 +352,14 @@ type OwnerAction = {
     listKind: AllowListKind;
     address: Address;
     mode: "add" | "remove";
+} | {
+    kind: "configureToken";
+    tokenMint: Address;
+    tokenMaxPerTx: BaseUnitString;
+    tokenDailyLimit: BaseUnitString;
+} | {
+    kind: "prepareTokenAccounts";
+    recipientAddresses?: Address[];
 };
 
 type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
@@ -349,14 +441,39 @@ declare class PraxisClient {
     }>;
     signProposal(proposalId: string): Promise<void>;
     cancelProposal(proposalId: string): Promise<void>;
+    /** List recurring-buy schedules (each fire emits one proposal; never signs). */
+    getSchedules(): Promise<DcaSchedule[]>;
+    /** Stop a recurring-buy schedule. Unknown ids are a no-op (idempotent). */
+    cancelSchedule(scheduleId: string): Promise<void>;
+    /** Save (or rename) an address-book contact. Labels have no signing power. */
+    addContact(label: string, address: string): Promise<void>;
+    /** Remove a contact by address or label (case-insensitive, idempotent). */
+    removeContact(key: string): Promise<void>;
     getThreads(): Promise<Thread[]>;
     getThread(id: string): Promise<Thread>;
     getProposal(id: string): Promise<ActionProposal>;
+    /**
+     * Every proposal this wallet holds, in one request. Prefer this over a loop
+     * of {@link getProposal}: a per-id fetch is what trips the read rate limit
+     * on a busy thread.
+     */
+    getProposals(): Promise<ActionProposal[]>;
     getPolicy(): Promise<PolicyView>;
     getActivity(): Promise<ActivityEntry[]>;
     getAddressBook(): Promise<AddressBookEntry[]>;
-    isThinking(threadId: string): Promise<boolean>;
     getVersion(): Promise<number>;
+    /**
+     * The server's stock universe (`[]` when `PRAXIS_STOCKS_ENABLED` is off).
+     * Read-only; symbols/mints here are the only pre-IPO stocks Praxis will
+     * touch (bounty exclusivity is enforced server-side).
+     */
+    getTokenUniverse(): Promise<StockUniverseEntry[]>;
+    /**
+     * Read-only research for a stock symbol, via the agent (`research <symbol>`).
+     * Returns neutral market data — never advice. Throws when the agent has no
+     * research to show (unknown symbol or unavailable quotes).
+     */
+    getStockResearch(symbol: string): Promise<ResearchData>;
     bootstrapPolicy(fundLamports?: BaseUnitString): Promise<void>;
     /** Deposit SOL (lamports, base-unit string) from the owner into the vault. */
     fundVault(amount: BaseUnitString): Promise<void>;
@@ -384,21 +501,51 @@ declare class PraxisClient {
     }>;
     private get;
     private post;
+    /**
+     * Run a request, and if the session has expired, sign in again and retry it
+     * once.
+     *
+     * Sessions are deliberately short — holding one is enough to move value
+     * within the Aegis envelope — so a long-lived agent process WILL outlive its
+     * cookie. Without this, every caller writes the same catch-401-and-reconnect
+     * block, and the ones who do not simply stop working after a day. Retried
+     * once only, never for the auth endpoints themselves, and only when a signer
+     * is configured; without one there is nothing to re-authenticate with and the
+     * 401 is the honest answer.
+     */
     private request;
+    private send1;
     private captureCookie;
 }
 
+/**
+ * A stable, machine-readable classification of a backend failure. Branch on
+ * this rather than on `message`, which is human prose and free to change.
+ * `client_error` is synthesized SDK-side for failures with no HTTP response
+ * (timeout, DNS, TLS).
+ */
+type PraxisErrorCode = "config_error" | "unauthorized" | "invalid_input" | "not_found"
+/** The wallet has no Aegis policy account yet — call `bootstrapPolicy`. */
+ | "policy_not_found" | "rate_limited"
+/** A concurrent writer changed this wallet's state first; reload and retry. */
+ | "conflict" | "internal_error" | "client_error";
 /**
  * Thrown when the Praxis API returns a non-2xx response. The backend's error
- * envelope is `{ error: string, type: string }` with a meaningful HTTP status
+ * envelope is `{ error, type, code, details? }` with a meaningful HTTP status
  * (400 input, 401 auth, 404 not-found, 429 rate-limit, 503 config, 500 other).
  */
 declare class PraxisApiError extends Error {
     readonly status: number;
     /** The backend error class name, e.g. "PraxisAuthError", "PraxisRateLimitError". */
     readonly type: string;
+    /** Stable error classification — the field to branch on. */
+    readonly code: PraxisErrorCode;
+    /** Structured facts about the failure, e.g. `{ policyAddress }` for `policy_not_found`. */
+    readonly details?: Record<string, string | number | boolean>;
     constructor(status: number, type: string, message: string, options?: {
         cause?: unknown;
+        code?: PraxisErrorCode;
+        details?: Record<string, string | number | boolean>;
     });
     get isAuth(): boolean;
     get isRateLimited(): boolean;
@@ -413,6 +560,10 @@ declare class PraxisApiError extends Error {
     get isNetwork(): boolean;
     /** Any server-side failure (HTTP >= 500). */
     get isServer(): boolean;
+    /** The wallet has no Aegis policy yet — the first-run state, not a fault. */
+    get isPolicyNotFound(): boolean;
+    /** A concurrent writer won; the call is safe to retry after a reload. */
+    get isConflict(): boolean;
 }
 /** Thrown for SDK-side misconfiguration (no fetch, no signer, bad key, …). */
 declare class PraxisConfigError extends Error {
@@ -443,4 +594,4 @@ declare function humanToBaseUnits(amount: string, decimals: number): string;
 /** Convert base units into a human decimal string for `decimals` places. */
 declare function baseUnitsToHuman(value: string | bigint, decimals: number): string;
 
-export { ActionKind, type ActionProposal, type ActivityEntry, type Address, type AddressBookEntry, type AgentBlock, type AgentMessage, type AllowListKind, type AskResult, type BaseUnitString, type ClarifyOption, type FetchLike, type Message, type OwnerAction, type PolicyChangeRow, type PolicyCheckResult, type PolicyUpdate, type PolicyView, PraxisApiError, PraxisClient, type PraxisClientOptions, PraxisConfigError, type PraxisSigner, type ProposalDetail, type ProposalState, RejectReason, type ResearchData, type ResearchMetric, type SecretKeyInput, type SessionInfo, type SignedOwnerTransaction, type SwapDetail, type Thread, type TokenEnvelopeConfig, type TokenInfo, type TransferDetail, type UnsignedOwnerTransaction, type UserMessage, type WalletChallenge, baseUnitsToHuman, fromBaseUnits, humanToBaseUnits, keypairSigner, toBaseUnits };
+export { ActionKind, type ActionProposal, type ActivityEntry, type Address, type AddressBookEntry, type AgentBlock, type AgentMessage, type AllowListKind, type AskResult, type BaseUnitString, type ClarifyOption, type DcaCadence, type DcaSchedule, type FetchLike, type Message, type OwnerAction, type PolicyChangeRow, type PolicyCheckResult, type PolicyUpdate, type PolicyView, PraxisApiError, PraxisClient, type PraxisClientOptions, PraxisConfigError, type PraxisErrorCode, type PraxisSigner, type ProposalDetail, type ProposalState, RejectReason, type ResearchData, type ResearchMetric, type ResearchSource, type SecretKeyInput, type SessionInfo, type SignedOwnerTransaction, type StockUniverseEntry, type SwapDetail, type Thread, type TokenEnvelopeConfig, type TokenInfo, type TransferDetail, type UnsignedOwnerTransaction, type UserMessage, type WalletChallenge, baseUnitsToHuman, fromBaseUnits, humanToBaseUnits, keypairSigner, toBaseUnits };

package/dist/index.d.ts

@@ -130,6 +130,14 @@ interface TransferDetail {
     recipientName: string;
     recipientAddress: Address;
     recipientNote?: string;
+    /** The destination is the owner's own wallet (derived from the address). */
+    toSelf?: true;
+    /**
+     * Server-computed USD value of `amount`, as a decimal string, when a real
+     * price is available. Absent means "not known" — display only, and never an
+     * input to base-unit math.
+     */
+    usdEstimate?: string;
 }
 interface SwapDetail {
     kind: "swap";
@@ -144,6 +152,14 @@ type ProposalDetail = TransferDetail | SwapDetail;
 type ProposalState = "pending" | "signing" | "signed" | "blocked" | "cancelled";
 interface ActionProposal {
     id: string;
+    /**
+     * Unix seconds when the proposal was produced. The signature gate refuses a
+     * proposal older than a week: the amount is fixed and Aegis enforces the
+     * envelope live, but the readings on it (fee, simulation, remaining
+     * envelope, USD figure) drift. Ask again for a fresh one. Absent on
+     * proposals created before this field existed.
+     */
+    createdAt?: number;
     detail: ProposalDetail;
     networkFee: BaseUnitString;
     simulation: string;
@@ -158,15 +174,46 @@ interface ClarifyOption {
 }
 interface ResearchMetric {
     label: string;
+    /** Already display-formatted, and abbreviated where a raw figure is unreadable. */
     value: string;
+    /** The full-precision figure behind an abbreviated `value`, when one was cut. */
+    exact?: string;
+    /** Why the metric is missing, or what it measures. */
+    note?: string;
     trend?: "up" | "down" | "flat";
 }
+/**
+ * One step in how a research card was produced. A card whose whole claim is
+ * "data, no advice" has to be able to show its working: "unavailable" means
+ * something different when an indexer has no pair than when an RPC refused
+ * the query.
+ */
+interface ResearchSource {
+    /** "Solana RPC", "Market data (…)", "PreStocks", "Token resolution". */
+    label: string;
+    status: "ok" | "partial" | "unavailable";
+    detail: string;
+}
 interface ResearchData {
     token: string;
+    /** Project name from the indexer, when it differs from the ticker. */
+    name?: string;
     mint: Address;
     metrics: ResearchMetric[];
+    /** How the card was produced, in the order the steps ran. */
+    sources?: ResearchSource[];
     summary: string;
 }
+/**
+ * Stocklana C07: one PreStocks entry from `GET /get-stock-universe`.
+ * Empty unless the server runs with `PRAXIS_STOCKS_ENABLED=1`.
+ */
+interface StockUniverseEntry {
+    symbol: string;
+    name: string;
+    mint: Address;
+    decimals: number;
+}
 interface PolicyChangeRow {
     label: string;
     from: string;
@@ -221,6 +268,8 @@ interface ActivityEntry {
     id: string;
     kind: "transfer" | "swap";
     label: string;
+    /** Destination address for a transfer. Stable where `label` is a lookup. */
+    target?: Address;
     asset: string;
     amount: BaseUnitString;
     decimals: number;
@@ -230,11 +279,46 @@ interface ActivityEntry {
     ts: number;
     sig?: string;
 }
+/** When a recurring buy fires. `weekday`: 0=Sunday..6=Saturday (UTC). */
+type DcaCadence = {
+    type: "daily";
+} | {
+    type: "weekly";
+    weekday: number;
+} | {
+    type: "monthly";
+    day: number;
+};
+/**
+ * One recurring-buy schedule from `GET /get-schedules`. Each fire emits one
+ * transfer proposal through the same policy checks as a one-off buy — nothing
+ * ever auto-signs. Money is a base-unit string per the money rule above.
+ */
+interface DcaSchedule {
+    id: string;
+    asset: string;
+    amount: BaseUnitString;
+    decimals: number;
+    recipientAddress: Address;
+    recipientName: string;
+    cadence: DcaCadence;
+    /** Unix milliseconds of the next fire. */
+    nextFireTs: number;
+    createdAt: number;
+    threadId: string;
+}
 interface UnsignedOwnerTransaction {
     /** base64-encoded unsigned transaction for the owner wallet to sign. */
     transaction: string;
     blockhash: string;
     lastValidBlockHeight: number;
+    /**
+     * Opaque, backend-signed fingerprint of this draft. Echo it back verbatim in
+     * {@link SignedOwnerTransaction}: the relay refuses any transaction that is
+     * not the one Praxis built, which is what keeps the server-side checks for
+     * this action from being skippable.
+     */
+    draft: string;
 }
 /**
  * An {@link UnsignedOwnerTransaction} after the owner wallet has signed it — the
@@ -268,6 +352,14 @@ type OwnerAction = {
     listKind: AllowListKind;
     address: Address;
     mode: "add" | "remove";
+} | {
+    kind: "configureToken";
+    tokenMint: Address;
+    tokenMaxPerTx: BaseUnitString;
+    tokenDailyLimit: BaseUnitString;
+} | {
+    kind: "prepareTokenAccounts";
+    recipientAddresses?: Address[];
 };
 
 type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
@@ -349,14 +441,39 @@ declare class PraxisClient {
     }>;
     signProposal(proposalId: string): Promise<void>;
     cancelProposal(proposalId: string): Promise<void>;
+    /** List recurring-buy schedules (each fire emits one proposal; never signs). */
+    getSchedules(): Promise<DcaSchedule[]>;
+    /** Stop a recurring-buy schedule. Unknown ids are a no-op (idempotent). */
+    cancelSchedule(scheduleId: string): Promise<void>;
+    /** Save (or rename) an address-book contact. Labels have no signing power. */
+    addContact(label: string, address: string): Promise<void>;
+    /** Remove a contact by address or label (case-insensitive, idempotent). */
+    removeContact(key: string): Promise<void>;
     getThreads(): Promise<Thread[]>;
     getThread(id: string): Promise<Thread>;
     getProposal(id: string): Promise<ActionProposal>;
+    /**
+     * Every proposal this wallet holds, in one request. Prefer this over a loop
+     * of {@link getProposal}: a per-id fetch is what trips the read rate limit
+     * on a busy thread.
+     */
+    getProposals(): Promise<ActionProposal[]>;
     getPolicy(): Promise<PolicyView>;
     getActivity(): Promise<ActivityEntry[]>;
     getAddressBook(): Promise<AddressBookEntry[]>;
-    isThinking(threadId: string): Promise<boolean>;
     getVersion(): Promise<number>;
+    /**
+     * The server's stock universe (`[]` when `PRAXIS_STOCKS_ENABLED` is off).
+     * Read-only; symbols/mints here are the only pre-IPO stocks Praxis will
+     * touch (bounty exclusivity is enforced server-side).
+     */
+    getTokenUniverse(): Promise<StockUniverseEntry[]>;
+    /**
+     * Read-only research for a stock symbol, via the agent (`research <symbol>`).
+     * Returns neutral market data — never advice. Throws when the agent has no
+     * research to show (unknown symbol or unavailable quotes).
+     */
+    getStockResearch(symbol: string): Promise<ResearchData>;
     bootstrapPolicy(fundLamports?: BaseUnitString): Promise<void>;
     /** Deposit SOL (lamports, base-unit string) from the owner into the vault. */
     fundVault(amount: BaseUnitString): Promise<void>;
@@ -384,21 +501,51 @@ declare class PraxisClient {
     }>;
     private get;
     private post;
+    /**
+     * Run a request, and if the session has expired, sign in again and retry it
+     * once.
+     *
+     * Sessions are deliberately short — holding one is enough to move value
+     * within the Aegis envelope — so a long-lived agent process WILL outlive its
+     * cookie. Without this, every caller writes the same catch-401-and-reconnect
+     * block, and the ones who do not simply stop working after a day. Retried
+     * once only, never for the auth endpoints themselves, and only when a signer
+     * is configured; without one there is nothing to re-authenticate with and the
+     * 401 is the honest answer.
+     */
     private request;
+    private send1;
     private captureCookie;
 }
 
+/**
+ * A stable, machine-readable classification of a backend failure. Branch on
+ * this rather than on `message`, which is human prose and free to change.
+ * `client_error` is synthesized SDK-side for failures with no HTTP response
+ * (timeout, DNS, TLS).
+ */
+type PraxisErrorCode = "config_error" | "unauthorized" | "invalid_input" | "not_found"
+/** The wallet has no Aegis policy account yet — call `bootstrapPolicy`. */
+ | "policy_not_found" | "rate_limited"
+/** A concurrent writer changed this wallet's state first; reload and retry. */
+ | "conflict" | "internal_error" | "client_error";
 /**
  * Thrown when the Praxis API returns a non-2xx response. The backend's error
- * envelope is `{ error: string, type: string }` with a meaningful HTTP status
+ * envelope is `{ error, type, code, details? }` with a meaningful HTTP status
  * (400 input, 401 auth, 404 not-found, 429 rate-limit, 503 config, 500 other).
  */
 declare class PraxisApiError extends Error {
     readonly status: number;
     /** The backend error class name, e.g. "PraxisAuthError", "PraxisRateLimitError". */
     readonly type: string;
+    /** Stable error classification — the field to branch on. */
+    readonly code: PraxisErrorCode;
+    /** Structured facts about the failure, e.g. `{ policyAddress }` for `policy_not_found`. */
+    readonly details?: Record<string, string | number | boolean>;
     constructor(status: number, type: string, message: string, options?: {
         cause?: unknown;
+        code?: PraxisErrorCode;
+        details?: Record<string, string | number | boolean>;
     });
     get isAuth(): boolean;
     get isRateLimited(): boolean;
@@ -413,6 +560,10 @@ declare class PraxisApiError extends Error {
     get isNetwork(): boolean;
     /** Any server-side failure (HTTP >= 500). */
     get isServer(): boolean;
+    /** The wallet has no Aegis policy yet — the first-run state, not a fault. */
+    get isPolicyNotFound(): boolean;
+    /** A concurrent writer won; the call is safe to retry after a reload. */
+    get isConflict(): boolean;
 }
 /** Thrown for SDK-side misconfiguration (no fetch, no signer, bad key, …). */
 declare class PraxisConfigError extends Error {
@@ -443,4 +594,4 @@ declare function humanToBaseUnits(amount: string, decimals: number): string;
 /** Convert base units into a human decimal string for `decimals` places. */
 declare function baseUnitsToHuman(value: string | bigint, decimals: number): string;
 
-export { ActionKind, type ActionProposal, type ActivityEntry, type Address, type AddressBookEntry, type AgentBlock, type AgentMessage, type AllowListKind, type AskResult, type BaseUnitString, type ClarifyOption, type FetchLike, type Message, type OwnerAction, type PolicyChangeRow, type PolicyCheckResult, type PolicyUpdate, type PolicyView, PraxisApiError, PraxisClient, type PraxisClientOptions, PraxisConfigError, type PraxisSigner, type ProposalDetail, type ProposalState, RejectReason, type ResearchData, type ResearchMetric, type SecretKeyInput, type SessionInfo, type SignedOwnerTransaction, type SwapDetail, type Thread, type TokenEnvelopeConfig, type TokenInfo, type TransferDetail, type UnsignedOwnerTransaction, type UserMessage, type WalletChallenge, baseUnitsToHuman, fromBaseUnits, humanToBaseUnits, keypairSigner, toBaseUnits };
+export { ActionKind, type ActionProposal, type ActivityEntry, type Address, type AddressBookEntry, type AgentBlock, type AgentMessage, type AllowListKind, type AskResult, type BaseUnitString, type ClarifyOption, type DcaCadence, type DcaSchedule, type FetchLike, type Message, type OwnerAction, type PolicyChangeRow, type PolicyCheckResult, type PolicyUpdate, type PolicyView, PraxisApiError, PraxisClient, type PraxisClientOptions, PraxisConfigError, type PraxisErrorCode, type PraxisSigner, type ProposalDetail, type ProposalState, RejectReason, type ResearchData, type ResearchMetric, type ResearchSource, type SecretKeyInput, type SessionInfo, type SignedOwnerTransaction, type StockUniverseEntry, type SwapDetail, type Thread, type TokenEnvelopeConfig, type TokenInfo, type TransferDetail, type UnsignedOwnerTransaction, type UserMessage, type WalletChallenge, baseUnitsToHuman, fromBaseUnits, humanToBaseUnits, keypairSigner, toBaseUnits };

package/dist/index.js

@@ -8,11 +8,17 @@ var PraxisApiError = class _PraxisApiError extends Error {
   status;
   /** The backend error class name, e.g. "PraxisAuthError", "PraxisRateLimitError". */
   type;
+  /** Stable error classification — the field to branch on. */
+  code;
+  /** Structured facts about the failure, e.g. `{ policyAddress }` for `policy_not_found`. */
+  details;
   constructor(status, type, message, options) {
     super(message, options);
     this.name = "PraxisApiError";
     this.status = status;
     this.type = type;
+    this.code = options?.code ?? codeFromStatus(status);
+    this.details = options?.details;
     Object.setPrototypeOf(this, _PraxisApiError.prototype);
   }
   get isAuth() {
@@ -44,7 +50,25 @@ var PraxisApiError = class _PraxisApiError extends Error {
   get isServer() {
     return this.status >= 500;
   }
+  /** The wallet has no Aegis policy yet — the first-run state, not a fault. */
+  get isPolicyNotFound() {
+    return this.code === "policy_not_found";
+  }
+  /** A concurrent writer won; the call is safe to retry after a reload. */
+  get isConflict() {
+    return this.code === "conflict";
+  }
 };
+function codeFromStatus(status) {
+  if (status === 400) return "invalid_input";
+  if (status === 401) return "unauthorized";
+  if (status === 404) return "not_found";
+  if (status === 409) return "conflict";
+  if (status === 429) return "rate_limited";
+  if (status === 503) return "config_error";
+  if (status === 0) return "client_error";
+  return "internal_error";
+}
 var PraxisConfigError = class _PraxisConfigError extends Error {
   constructor(message, options) {
     super(message, options);
@@ -143,7 +167,9 @@ var PraxisClient = class {
       throw new PraxisApiError(500, "Error", "Agent produced no reply message.");
     }
     const proposalIds = message.blocks.filter((b) => b.type === "proposal").map((b) => b.proposalId);
-    const proposals = await Promise.all(proposalIds.map((id) => this.getProposal(id)));
+    if (proposalIds.length === 0) return { threadId: tid, message, proposals: [] };
+    const byId = new Map((await this.getProposals()).map((p) => [p.id, p]));
+    const proposals = proposalIds.map((id) => byId.get(id)).filter((p) => p !== void 0);
     return { threadId: tid, message, proposals };
   }
   newThread(threadId) {
@@ -155,6 +181,22 @@ var PraxisClient = class {
   cancelProposal(proposalId) {
     return this.post("/cancel-proposal", { proposalId });
   }
+  /** List recurring-buy schedules (each fire emits one proposal; never signs). */
+  getSchedules() {
+    return this.get("/get-schedules");
+  }
+  /** Stop a recurring-buy schedule. Unknown ids are a no-op (idempotent). */
+  cancelSchedule(scheduleId) {
+    return this.post("/cancel-schedule", { scheduleId });
+  }
+  /** Save (or rename) an address-book contact. Labels have no signing power. */
+  addContact(label, address) {
+    return this.post("/add-contact", { label, address });
+  }
+  /** Remove a contact by address or label (case-insensitive, idempotent). */
+  removeContact(key) {
+    return this.post("/remove-contact", { key });
+  }
   // --- reads ---------------------------------------------------------------
   getThreads() {
     return this.get("/get-threads");
@@ -165,6 +207,14 @@ var PraxisClient = class {
   getProposal(id) {
     return this.get("/get-proposal", { id });
   }
+  /**
+   * Every proposal this wallet holds, in one request. Prefer this over a loop
+   * of {@link getProposal}: a per-id fetch is what trips the read rate limit
+   * on a busy thread.
+   */
+  getProposals() {
+    return this.get("/get-proposals");
+  }
   getPolicy() {
     return this.get("/get-policy");
   }
@@ -174,12 +224,31 @@ var PraxisClient = class {
   getAddressBook() {
     return this.get("/get-address-book");
   }
-  isThinking(threadId) {
-    return this.get("/is-thinking", { threadId });
-  }
   getVersion() {
     return this.get("/get-version");
   }
+  // --- stocks (PreStocks universe; empty unless the server enables it) ------
+  /**
+   * The server's stock universe (`[]` when `PRAXIS_STOCKS_ENABLED` is off).
+   * Read-only; symbols/mints here are the only pre-IPO stocks Praxis will
+   * touch (bounty exclusivity is enforced server-side).
+   */
+  getTokenUniverse() {
+    return this.get("/get-stock-universe");
+  }
+  /**
+   * Read-only research for a stock symbol, via the agent (`research <symbol>`).
+   * Returns neutral market data — never advice. Throws when the agent has no
+   * research to show (unknown symbol or unavailable quotes).
+   */
+  async getStockResearch(symbol) {
+    const { message } = await this.ask(`research ${symbol}`);
+    const block = message.blocks.find((b) => b.type === "research");
+    if (!block || block.type !== "research") {
+      throw new PraxisApiError(404, "NotFound", `No research available for ${symbol}.`);
+    }
+    return block.data;
+  }
   // --- policy / owner mutations (server-key mode) --------------------------
   bootstrapPolicy(fundLamports) {
     return this.post("/bootstrap-policy", fundLamports ? { fundLamports } : {});
@@ -238,7 +307,30 @@ var PraxisClient = class {
   post(path, body, timeoutMs) {
     return this.request("POST", path, { body, timeoutMs });
   }
+  /**
+   * Run a request, and if the session has expired, sign in again and retry it
+   * once.
+   *
+   * Sessions are deliberately short — holding one is enough to move value
+   * within the Aegis envelope — so a long-lived agent process WILL outlive its
+   * cookie. Without this, every caller writes the same catch-401-and-reconnect
+   * block, and the ones who do not simply stop working after a day. Retried
+   * once only, never for the auth endpoints themselves, and only when a signer
+   * is configured; without one there is nothing to re-authenticate with and the
+   * 401 is the honest answer.
+   */
   async request(method, path, opts = {}) {
+    try {
+      return await this.send1(method, path, opts);
+    } catch (error) {
+      const recoverable = error instanceof PraxisApiError && error.isAuth && Boolean(this.signer) && !path.startsWith("/auth/");
+      if (!recoverable) throw error;
+      this.sessionCookie = void 0;
+      await this.connect();
+      return this.send1(method, path, opts);
+    }
+  }
+  async send1(method, path, opts = {}) {
     const url = new URL(this.baseUrl + API_PREFIX + path);
     for (const [k, v] of Object.entries(opts.query ?? {})) url.searchParams.set(k, v);
     const headers = { accept: "application/json" };
@@ -275,7 +367,10 @@ var PraxisClient = class {
     if (!res.ok) {
       const message = (parsed && typeof parsed === "object" && "error" in parsed && typeof parsed.error === "string" ? parsed.error : void 0) ?? `Praxis API error ${res.status}`;
       const type = parsed && typeof parsed === "object" && "type" in parsed && typeof parsed.type === "string" ? parsed.type : "Error";
-      throw new PraxisApiError(res.status, type, message);
+      const record = parsed && typeof parsed === "object" ? parsed : void 0;
+      const code = typeof record?.code === "string" ? record.code : void 0;
+      const details = record?.details && typeof record.details === "object" && !Array.isArray(record.details) ? record.details : void 0;
+      throw new PraxisApiError(res.status, type, message, { code, details });
     }
     return parsed;
   }