@multiagency/sdk 0.3.1 → 0.4.0

package/CHANGES.md

@@ -5,6 +5,31 @@ wire change all apps must update for together. The first change after a release
 version, so a package staged or packed from changed sources never carries a released version's number. The release
 candidate dates the heading. Under 0.x, any public-interface change bumps at least the minor version.
 
+## 0.4.0 (2026-11-02)
+
+Additive: 0.3.x apps keep working, and a consent signed without the new scopes stays valid.
+
+- **Treasury proposals** (`proposals/create`, `get`, `list`, `approve`, `reject`, `withdraw`, `execute`): an app proposes
+  swaps under its own `requestId`; the owner approves the exact terms later by signing `proposalText(proposal, "approve")`
+  (NEP-413, recipient the platform host); the app then asks for one execution, which re-quotes every swap and sends each
+  with a floor at least the signed one, through the same plan execution as any saved plan. A proposal lasts at most 7
+  days. New exports: `proposalCreateInput`, `proposalSigned`, `proposalRef`, `proposalView`, `proposalList`,
+  `ProposalState`, `proposalText`, `tokenAmount`, `PROPOSAL_TOKENS`, `MAX_PROPOSAL_MS`, `MAX_OPEN_PROPOSALS`,
+  `MAX_PROPOSAL_LEGS`.
+- **Consent scopes `treasury` and `treasury-execute`** (`AppScope`, `APP_TREASURY`, `APP_TREASURY_EXECUTE`): `treasury`
+  reaches Treasury reads, strategy settings, autopilot on and off, sweep and proposals; `treasury-execute`, only beside
+  `treasury`, adds `rebalance`, `externalPlan` and `executePlan`, which run for an app only while the owner's live grant
+  binds the plan's strategy.
+- **`appClient(...).agent(...).stream`**: an app reads the stream procedures its consent covers (`sweep`, and with
+  `treasury-execute` `rebalance` and `executePlan`), as `ownerClient.stream` does. `call` takes the other procedures.
+- **Machine route (platform, not an SDK type):** `executePlan` through a Treasury machine credential (`tmc_`) now runs
+  only while the owner's live grant binds the plan's strategy, as an app's does; under a plain `treasury` grant it is
+  refused before anything is claimed. The owner signs the strategy-bound grant once per saved strategy. Clients of the
+  machine route (the treasury app's helper) need that grant before upgrading the platform.
+- **Plans:** a plan's `source` may be `proposal`, with its `proposalId`; such a plan runs only as its proposal.
+- **Owner capability** `treasury-proposals-v1`.
+- **treasury-app skill.**
+
 ## 0.3.1 (2026-10-31)
 
 No code, type or wire change.

package/dist/contract/app-access.d.ts

@@ -16,7 +16,19 @@ export declare const APP_OWNER: readonly ["owner/prepare", "owner/submit", "owne
  * nothing out.
  */
 export declare const APP_PAYOUT: readonly ["payouts/request", "payouts/status", "held", "deposit"];
-export type AppProcedure = (typeof APP_READS)[number] | (typeof APP_OWNER)[number] | (typeof APP_PAYOUT)[number];
+/**
+ * Treasury with `treasury` consent (docs/enforcement.md, "Treasury proposals"): reads; strategy settings, which an
+ * app's plans, a machine credential's plans and the autopilot use only under a grant binding their digest; autopilot on
+ * (under such a grant) and off; sweeping public balances into the confidential one; and proposals, whose swaps execute
+ * only after the owner signs their exact terms.
+ */
+export declare const APP_TREASURY: readonly ["strategy/get", "autopilot/get", "autopilot/evidence", "autopilot/log", "treasury/get", "strategy/save", "autopilot/enable", "autopilot/stop", "sweep", "proposals/create", "proposals/get", "proposals/list", "proposals/approve", "proposals/reject", "proposals/withdraw", "proposals/execute"];
+/**
+ * With `treasury-execute` as well: plans prepared and executed within the owner's policy and the strategy's cost limit,
+ * without a signature per swap, and only under a grant binding the plan's strategy (src/planning/strategy-grant.ts).
+ */
+export declare const APP_TREASURY_EXECUTE: readonly ["rebalance", "externalPlan", "executePlan"];
+export type AppProcedure = (typeof APP_READS)[number] | (typeof APP_OWNER)[number] | (typeof APP_PAYOUT)[number] | (typeof APP_TREASURY)[number] | (typeof APP_TREASURY_EXECUTE)[number];
 /** Whether consent scopes cover a procedure (the gateway also requires the owner's own access to it). */
 export declare const appScopesCover: (scopes: readonly AppScope[], path: string) => boolean;
 /** Whether a parsed owner action is one the app may prepare (signer `wallet` is checked separately). */
@@ -63,6 +75,8 @@ export declare const appConsentView: z.ZodObject<{
         owner: "owner";
         payout: "payout";
         read: "read";
+        treasury: "treasury";
+        "treasury-execute": "treasury-execute";
     }>>;
     expiresAt: z.ZodNumber;
     createdAt: z.ZodNumber;
@@ -83,6 +97,8 @@ export declare const appConsentList: z.ZodObject<{
             owner: "owner";
             payout: "payout";
             read: "read";
+            treasury: "treasury";
+            "treasury-execute": "treasury-execute";
         }>>;
         expiresAt: z.ZodNumber;
         createdAt: z.ZodNumber;
@@ -104,6 +120,8 @@ export declare const appConsentStored: z.ZodObject<{
             owner: "owner";
             payout: "payout";
             read: "read";
+            treasury: "treasury";
+            "treasury-execute": "treasury-execute";
         }>>;
         expiresAt: z.ZodNumber;
         createdAt: z.ZodNumber;
@@ -127,6 +145,8 @@ export declare const appSetupStored: z.ZodObject<{
             owner: "owner";
             payout: "payout";
             read: "read";
+            treasury: "treasury";
+            "treasury-execute": "treasury-execute";
         }>>;
         expiresAt: z.ZodNumber;
         createdAt: z.ZodNumber;

package/dist/contract/app-access.js

@@ -16,9 +16,25 @@ export const APP_OWNER = ["owner/prepare", "owner/submit", "owner/status", "owne
  * nothing out.
  */
 export const APP_PAYOUT = ["payouts/request", "payouts/status", "held", "deposit"];
-const READS = new Set(APP_READS), OWNER = new Set(APP_OWNER), PAYOUT = new Set(APP_PAYOUT);
+/**
+ * Treasury with `treasury` consent (docs/enforcement.md, "Treasury proposals"): reads; strategy settings, which an
+ * app's plans, a machine credential's plans and the autopilot use only under a grant binding their digest; autopilot on
+ * (under such a grant) and off; sweeping public balances into the confidential one; and proposals, whose swaps execute
+ * only after the owner signs their exact terms.
+ */
+export const APP_TREASURY = ["strategy/get", "autopilot/get", "autopilot/evidence", "autopilot/log", "treasury/get", "strategy/save",
+    "autopilot/enable", "autopilot/stop", "sweep", "proposals/create", "proposals/get", "proposals/list", "proposals/approve",
+    "proposals/reject", "proposals/withdraw", "proposals/execute"];
+/**
+ * With `treasury-execute` as well: plans prepared and executed within the owner's policy and the strategy's cost limit,
+ * without a signature per swap, and only under a grant binding the plan's strategy (src/planning/strategy-grant.ts).
+ */
+export const APP_TREASURY_EXECUTE = ["rebalance", "externalPlan", "executePlan"];
+const READS = new Set(APP_READS), OWNER = new Set(APP_OWNER), PAYOUT = new Set(APP_PAYOUT), TREASURY = new Set(APP_TREASURY), TREASURY_EXECUTE = new Set(APP_TREASURY_EXECUTE);
 /** Whether consent scopes cover a procedure (the gateway also requires the owner's own access to it). */
-export const appScopesCover = (scopes, path) => (scopes.includes("read") && READS.has(path)) || (scopes.includes("owner") && OWNER.has(path)) || (scopes.includes("payout") && PAYOUT.has(path));
+export const appScopesCover = (scopes, path) => (scopes.includes("read") && READS.has(path)) || (scopes.includes("owner") && OWNER.has(path)) || (scopes.includes("payout") && PAYOUT.has(path))
+    || (scopes.includes("treasury") && TREASURY.has(path))
+    || (scopes.includes("treasury") && scopes.includes("treasury-execute") && TREASURY_EXECUTE.has(path));
 /**
  * What the app may ask an owner to sign. The app chooses what it asks for, but never what the owner reads: a prepared
  * intent reaches the app only when it is NEP-413, whose text the owner's wallet shows. A NEP-366 intent (creation,

package/dist/contract/app-client.d.ts

@@ -1,7 +1,8 @@
 import type { z } from "zod";
 import { type AppOwnerAction, type AppProcedure } from "./app-access.js";
 import type { appConsentSubmission } from "./app-consent.js";
-import { type OwnerCallOptions, type OwnerOutput, type OwnerResult } from "./owner-client.js";
+import { type OwnerCallOptions, type OwnerFailure, type OwnerOutput, type OwnerResult } from "./owner-client.js";
+import type { ownerStreams } from "./owner-outputs.js";
 import type { OwnerInputs } from "./owner-inputs.js";
 type Fetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 export type AppBase = `https://${string}` | `http://${string}`;
@@ -45,6 +46,8 @@ export type AppInputs = {
         signer: "wallet";
     } : OwnerInputs[P];
 };
+/** The app procedures that answer an event stream. */
+type AppStream = Extract<AppProcedure, (typeof ownerStreams)[number]>;
 /**
  * A server-side client for an app deployment's routes under `/apps/v1` on the platform host. It adds the deployment's
  * service credential (a server secret: never give it to a browser). Agent calls go through `ownerClient`, with its result
@@ -78,7 +81,7 @@ export declare function appClient({ base, credential, fetch: send }: {
             owner: string;
             agent: string;
             agentId: string;
-            scopes: ("owner" | "payout" | "read")[];
+            scopes: ("owner" | "payout" | "read" | "treasury" | "treasury-execute")[];
             expiresAt: number;
             createdAt: number;
             publicKey: string;
@@ -98,7 +101,7 @@ export declare function appClient({ base, credential, fetch: send }: {
                 owner: string;
                 agent: string;
                 agentId: string;
-                scopes: ("owner" | "payout" | "read")[];
+                scopes: ("owner" | "payout" | "read" | "treasury" | "treasury-execute")[];
                 expiresAt: number;
                 createdAt: number;
                 publicKey: string;
@@ -117,7 +120,7 @@ export declare function appClient({ base, credential, fetch: send }: {
                 owner: string;
                 agent: string;
                 agentId: string;
-                scopes: ("owner" | "payout" | "read")[];
+                scopes: ("owner" | "payout" | "read" | "treasury" | "treasury-execute")[];
                 expiresAt: number;
                 createdAt: number;
                 publicKey: string;
@@ -131,9 +134,11 @@ export declare function appClient({ base, credential, fetch: send }: {
             revoked: true;
         }>>;
     };
-    /** One Organization's agent: reads and owner actions its live consents cover. */
+    /** One Organization's agent: reads, owner actions and Treasury procedures its live consents cover. */
     agent(organization: string, agent: string): {
-        call<P extends AppProcedure>(path: P, ...[input, options]: undefined extends AppInputs[P] ? [input?: AppInputs[P], options?: OwnerCallOptions] : [input: AppInputs[P], options?: OwnerCallOptions]): Promise<OwnerResult<OwnerOutput<P>>>;
+        call<P extends Exclude<AppProcedure, AppStream>>(path: P, ...[input, options]: undefined extends AppInputs[P] ? [input?: AppInputs[P], options?: OwnerCallOptions] : [input: AppInputs[P], options?: OwnerCallOptions]): Promise<OwnerResult<OwnerOutput<P>>>;
+        /** A stream's events (`sweep`, and with `treasury-execute` `rebalance` and `executePlan`), as `ownerClient.stream` reads them. */
+        stream<P extends AppStream>(path: P, input: AppInputs[P], options?: OwnerCallOptions): AsyncGenerator<OwnerOutput<P>, OwnerFailure | undefined>;
     };
 };
 export type AppClient = ReturnType<typeof appClient>;

package/dist/contract/app-client.js

@@ -48,13 +48,17 @@ export function appClient({ base, credential, fetch: send = globalThis.fetch })
             /** Permanent: the owner signs a new consent to restore access. */
             revoke: (id) => route(`/consents/${encodeURIComponent(id)}`, appRevoked, { method: "DELETE" }),
         },
-        /** One Organization's agent: reads and owner actions its live consents cover. */
+        /** One Organization's agent: reads, owner actions and Treasury procedures its live consents cover. */
         agent(organization, agent) {
             const owner = ownerClient({ base: `${root}/apps/v1/o/${encodeURIComponent(organization)}/a/${encodeURIComponent(agent)}`, fetch: authorized });
             return {
                 call(path, ...[input, options]) {
                     return owner.call(path, input, options);
                 },
+                /** A stream's events (`sweep`, and with `treasury-execute` `rebalance` and `executePlan`), as `ownerClient.stream` reads them. */
+                stream(path, input, options) {
+                    return owner.stream(path, input, options);
+                },
             };
         },
     };

package/dist/contract/app-consent.d.ts

@@ -1,7 +1,9 @@
 import { z } from "zod";
 /**
  * An agent owner's consent for one app deployment to act for one Organization on one agent: `read` for the listed
- * reads, `owner` to prepare and submit owner actions that only the owner's own wallet signature completes.
+ * reads, `owner` to prepare and submit owner actions that only the owner's own wallet signature completes, `payout` for
+ * payout requests, `treasury` for Treasury reads, settings and proposals the owner approves later, and
+ * `treasury-execute` (only with `treasury`) to prepare and execute plans within the policy without a signature per swap.
  * The owner signs `consentMessage(...)` with NEP-413, recipient the platform host. The platform accepts only the exact
  * canonical text, so what was signed and what is stored are the same bytes.
  */
@@ -10,6 +12,8 @@ export declare const AppScope: z.ZodEnum<{
     owner: "owner";
     payout: "payout";
     read: "read";
+    treasury: "treasury";
+    "treasury-execute": "treasury-execute";
 }>;
 export type AppScope = z.infer<typeof AppScope>;
 /** Stands for an agent its server reports not created yet; only the platform's setup consent carries it, never a signed text. */
@@ -27,6 +31,8 @@ export declare const appConsent: z.ZodObject<{
         owner: "owner";
         payout: "payout";
         read: "read";
+        treasury: "treasury";
+        "treasury-execute": "treasury-execute";
     }>>;
     expiresAt: z.ZodISODateTime;
 }, z.core.$strict>;

package/dist/contract/app-consent.js

@@ -1,12 +1,14 @@
 import { z } from "zod";
 /**
  * An agent owner's consent for one app deployment to act for one Organization on one agent: `read` for the listed
- * reads, `owner` to prepare and submit owner actions that only the owner's own wallet signature completes.
+ * reads, `owner` to prepare and submit owner actions that only the owner's own wallet signature completes, `payout` for
+ * payout requests, `treasury` for Treasury reads, settings and proposals the owner approves later, and
+ * `treasury-execute` (only with `treasury`) to prepare and execute plans within the policy without a signature per swap.
  * The owner signs `consentMessage(...)` with NEP-413, recipient the platform host. The platform accepts only the exact
  * canonical text, so what was signed and what is stored are the same bytes.
  */
 export const APP_CONSENT_TYPE = "multiagency.app-consent";
-export const AppScope = z.enum(["owner", "payout", "read"]);
+export const AppScope = z.enum(["owner", "payout", "read", "treasury", "treasury-execute"]);
 const name = z.string().regex(/^[a-z0-9-]{1,32}$/);
 /** Stands for an agent its server reports not created yet; only the platform's setup consent carries it, never a signed text. */
 export const UNBORN_AGENT = "unborn";
@@ -21,7 +23,8 @@ export const appConsent = z.strictObject({
     agent: name,
     /** The agent's provider ID when the owner signs: a replacement agent under the same name isn't covered. */
     agentId: z.string().min(1).max(128).refine(id => id !== UNBORN_AGENT, "Not an agent ID"),
-    scopes: z.array(AppScope).min(1).refine(values => new Set(values).size === values.length, "Scopes must be distinct"),
+    scopes: z.array(AppScope).min(1).refine(values => new Set(values).size === values.length, "Scopes must be distinct")
+        .refine(values => !values.includes("treasury-execute") || values.includes("treasury"), "treasury-execute needs treasury"),
     expiresAt: z.iso.datetime(),
 });
 /** The canonical text to sign: fixed key order, sorted scopes, no whitespace. */

package/dist/contract/index.d.ts

@@ -22,5 +22,6 @@ export { intentsAccount, isNearcomAddress, validIntentsAccount } from "./intents
 export { mayCall, type Access } from "./permissions.js";
 export * from "./gateway.js";
 export * from "./proposals.js";
+export * from "./treasury-proposals.js";
 export * from "./run-progress-schema.js";
 export { RecordingSchema, MAX_RECORDING_BYTES, AGUI_VERSION, AGUI_PROTOCOL_VERSION, type Recording, type RunLogEvent } from "./run-log-schema.js";

package/dist/contract/index.js

@@ -21,5 +21,6 @@ export { intentsAccount, isNearcomAddress, validIntentsAccount } from "./intents
 export { mayCall } from "./permissions.js";
 export * from "./gateway.js";
 export * from "./proposals.js";
+export * from "./treasury-proposals.js";
 export * from "./run-progress-schema.js";
 export { RecordingSchema, MAX_RECORDING_BYTES, AGUI_VERSION, AGUI_PROTOCOL_VERSION } from "./run-log-schema.js";

package/dist/contract/owner-capabilities.d.ts

@@ -42,6 +42,11 @@ export declare const ownerCapabilities: {
         readonly routes: readonly [];
         readonly procedures: readonly ["rebalance", "externalPlan", "executePlan", "steward/propose"];
     };
+    /** Proposals an app makes and the owner approves later (docs/enforcement.md, "Treasury proposals"); apps only. */
+    readonly "treasury-proposals-v1": {
+        readonly routes: readonly [];
+        readonly procedures: readonly ["proposals/create", "proposals/get", "proposals/list", "proposals/approve", "proposals/reject", "proposals/withdraw", "proposals/execute"];
+    };
     readonly "treasury-recovery-v1": {
         readonly routes: readonly [];
         readonly procedures: readonly ["recover"];

package/dist/contract/owner-capabilities.js

@@ -15,6 +15,8 @@ export const ownerCapabilities = {
     "treasury-observe-v1": { routes: [], procedures: ["strategy/get", "autopilot/evidence", "autopilot/log", "ledger", "ledgerCsv", "reconcileBooks"] },
     "treasury-strategy-v1": { routes: [], procedures: ["strategy/save", "autopilot/set", "autopilot/enable", "autopilot/tick"] },
     "treasury-plans-v1": { routes: [], procedures: ["rebalance", "externalPlan", "executePlan", "steward/propose"] },
+    /** Proposals an app makes and the owner approves later (docs/enforcement.md, "Treasury proposals"); apps only. */
+    "treasury-proposals-v1": { routes: [], procedures: ["proposals/create", "proposals/get", "proposals/list", "proposals/approve", "proposals/reject", "proposals/withdraw", "proposals/execute"] },
     "treasury-recovery-v1": { routes: [], procedures: ["recover"] },
     "payables-payments-v1": { routes: [], procedures: ["pay", "paymentHistory", "paymentStatus", "invoices", "cancelPreparedInvoice", "ledger", "ledgerCsv", "reconcileBooks"] },
     "payables-payout-requests-v1": { routes: [], procedures: ["payouts/request", "payouts/status"] },

package/dist/contract/owner-contract.d.ts

@@ -912,7 +912,7 @@ export declare const ownerContract: {
         plan: {
             [x: string]: unknown;
             id: string;
-            source: "external" | "rebalance" | "steward";
+            source: "external" | "proposal" | "rebalance" | "steward";
             createdAt: string;
             expiresAt: string;
             instruction: string;
@@ -940,6 +940,7 @@ export declare const ownerContract: {
                 public: string;
                 confidential: string;
             }>;
+            proposalId?: string | undefined;
         };
         steps: (number | undefined)[];
     }, unknown, void>, import("@orpc/contract").AsyncIteratorClass<{
@@ -1008,7 +1009,7 @@ export declare const ownerContract: {
         plan: {
             [x: string]: unknown;
             id: string;
-            source: "external" | "rebalance" | "steward";
+            source: "external" | "proposal" | "rebalance" | "steward";
             createdAt: string;
             expiresAt: string;
             instruction: string;
@@ -1036,6 +1037,7 @@ export declare const ownerContract: {
                 public: string;
                 confidential: string;
             }>;
+            proposalId?: string | undefined;
         };
         steps: (number | undefined)[];
     }, unknown, void>>, {

package/dist/contract/owner-inputs.d.ts

@@ -1,5 +1,6 @@
 import type { z } from "zod";
 import type { agreementCommand, compensationSend, paymentPreparation, reviewCommand } from "../compensation-contract.js";
+import type { proposalCreateInput, proposalRef, proposalSigned } from "./treasury-proposals.js";
 import type { depositInput, executePlanInput, ownerAction, ownerPrepareInput, ownerStatusInput, ownerSubmitInput, payoutRequestInput, payoutStatusInput } from "./inputs.js";
 /**
  * Owner procedure inputs as the router accepts them (before server-side parsing). Procedures in the owner contract
@@ -154,6 +155,13 @@ export type OwnerInputs = {
             minAmountOut?: string;
         }[];
     };
+    "proposals/create": In<typeof proposalCreateInput>;
+    "proposals/get": In<typeof proposalRef>;
+    "proposals/list": undefined;
+    "proposals/approve": In<typeof proposalSigned>;
+    "proposals/reject": In<typeof proposalSigned>;
+    "proposals/withdraw": In<typeof proposalRef>;
+    "proposals/execute": In<typeof proposalRef>;
     rebalance: undefined;
     executePlan: In<typeof executePlanInput>;
     sweep: {