mishmar 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,174 @@
+                                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 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 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 those 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.

package/README.md

@@ -1,3 +1,90 @@
-# Temporary Holding Version
+# mishmar (TypeScript)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[Mishmar](https://mishmar.io) is a risk management layer for trading bots
+and AI agents: every order is checked against your limits before it reaches
+the exchange, large orders wait for your approval, and no key can trade
+alone.
+
+This is the TypeScript client: build a proposal, sign it with the agent's
+key, send it to the engine, read the decision. No runtime dependencies; Node
+20 or later.
+
+```sh
+npm install mishmar
+```
+
+The package also puts `mishmar` on the path, so `npx -y mishmar mcp` runs
+the MCP server and `npx -y mishmar signer run` the signer without the CLI
+installed: the command runs the binary found through `MISHMAR_BIN`, the
+PATH or `~/.mishmar/bin`, and when there is none fetches the pinned release
+(v0.2.2) into `~/.mishmar/bin` first, checked against the release's
+checksums.
+
+```ts
+import { AgentKey, Client } from "mishmar";
+
+const key = AgentKey.parse("msk_…"); // shown once when the engine issued the key
+const client = new Client("http://localhost:8080/v1", key, "key_…");
+
+const decision = await client.propose({
+  tradingAccountId: "ta_…", symbol: "BTC", side: "buy", size: "0.25",
+  orderType: "market", validForMs: 5 * 60_000,
+});
+console.log(decision.verdict); // allow | require_approval | block
+
+// Pull a resting order this agent placed through Mishmar: a cancel names the
+// order by the clientOrderId its decision carries, and has no side or size.
+const { clientOrderId } = decision.proposal as { clientOrderId: string };
+await client.propose({
+  tradingAccountId: "ta_…", symbol: "BTC", kind: "cancel",
+  targetClientOrderId: clientOrderId,
+});
+```
+
+Sizes, prices and leverage are decimal **strings** and are signed exactly as
+written: `"0.5"` and `"0.50"` are the same quantity but different signatures.
+Never pass a number.
+
+A call the engine did nothing with goes again by itself: `503 unavailable`
+while the engine restarts and `429 rate_limited` (after its `Retry-After`),
+for up to 45 s, then the last answer is thrown as `EngineError`. Nothing else
+is retried. `new Client(url, key, keyId, { retries: false })` turns that off;
+`{ retries: { budgetMs: 90_000 } }` tunes it.
+
+Run the tests, which include the cross-language vectors in `../spec/vectors`:
+
+```
+npm install
+npm test
+```
+
+## The signer as a child process
+
+With the `mishmar` binary installed (or fetched with `downloadBinary`),
+`Signer` runs it as a child process and the bot holds no secret: the child
+has the agent's key and shares, signs each proposal, and sends it one-shot
+where it can. Reads go through the child too.
+
+```ts
+import { Signer } from "mishmar";
+
+const s = await new Signer().start(); // ~/.mishmar/agent.json
+try {
+  let d = await s.order({ tradingAccountId: "ta_…", symbol: "BTC", side: "buy", size: "0.001", price: "79500" });
+  if (d.verdict === "require_approval") d = await s.wait(d.id);
+  const { clientOrderId } = d.proposal as { clientOrderId: string };
+  await s.cancel("ta_…", "BTC", clientOrderId);
+} finally {
+  await s.stop();
+}
+```
+
+The child stops when this process ends, however it ends. To share one signer
+among several processes, or keep it connected across restarts, run it on its
+own (`mishmar signer run --local unix:/run/mishmar/signer.sock`) and attach
+with `await Signer.connect("unix:/run/mishmar/signer.sock")`; `stop()` then
+leaves it running. One signer runs per config, so a second `Signer` on a
+config in use fails and names the process that holds it.
+
+The guides at [docs.mishmar.io](https://docs.mishmar.io) set up the agent,
+its trading keys and the signer.

package/dist/agentkey.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The agent's identity: an Ed25519 key whose public half the engine stores.
+ *
+ * The engine shows the secret once, as `msk_<prefix>_<seed>`: a label, then
+ * the 32-byte seed in base64url without padding. The key id (`key_…`) is
+ * separate and public.
+ *
+ * The key signs two things: proposals (proposal.ts) and, under the
+ * contract's agentAuth scheme, every other agent-facing request: four headers
+ * carry the key id, the time, a nonce and an Ed25519 signature over the
+ * canonical JSON of `{bodySha256, keyId, method, nonce, path, query,
+ * signedAt}`. The bytes are pinned in spec/vectors/agent-request-signing.json.
+ */
+export declare const HEADER_KEY_ID = "X-Mishmar-Key-Id";
+export declare const HEADER_SIGNED_AT = "X-Mishmar-Signed-At";
+export declare const HEADER_NONCE = "X-Mishmar-Nonce";
+export declare const HEADER_SIGNATURE = "X-Mishmar-Signature";
+/** A fresh nonce: 16 random bytes, hex. */
+export declare function newNonce(): string;
+/** One HTTP request as the agentAuth scheme sees it. */
+export interface RequestToSign {
+    /** In any case; signed upper case. */
+    method: string;
+    /** Without the server prefix: "/agent/decisions", not "/v1/agent/decisions". */
+    path: string;
+    /** The raw query string without the "?"; empty or absent when none. */
+    query?: string;
+    /** The request body; absent when none. */
+    body?: Uint8Array | string;
+    keyId: string;
+    nonce: string;
+    /** Exactly as sent in X-Mishmar-Signed-At. */
+    signedAt: string;
+}
+/** What the agent signs for a request. */
+export declare function requestSigningBytes(r: RequestToSign): Uint8Array;
+/** The agent's private key. */
+export declare class AgentKey {
+    #private;
+    private constructor();
+    /** Read the secret the engine showed when the key was issued. */
+    static parse(secret: string): AgentKey;
+    static fromSeed(seed: Uint8Array): AgentKey;
+    /** A fresh key, for tests and tools; the engine issues the real ones. */
+    static generate(): AgentKey;
+    /** The base64 (standard, padded) Ed25519 signature of message. */
+    sign(message: Uint8Array): string;
+    /** The four agentAuth headers for a request; the nonce and the time are made here when not given. */
+    signRequest(r: Omit<RequestToSign, "nonce" | "signedAt"> & {
+        nonce?: string;
+        signedAt?: Date;
+    }): Record<string, string>;
+    /** The public half, raw 32 bytes. */
+    get publicKey(): Uint8Array;
+    /** The public half as the API stores and returns it. */
+    get publicKeyB64(): string;
+}
+/** Render a seed the way the engine shows it, with the given prefix. */
+export declare function secret(prefix: string, seed: Uint8Array): string;
+/** Check a base64 signature over message with a public key in the API's form. */
+export declare function verify(publicKeyB64: string, message: Uint8Array, signatureB64: string): boolean;
+/** The engine's side of agentAuth. Freshness and nonce replay are the caller's checks. */
+export declare function verifyRequest(publicKeyB64: string, r: RequestToSign, signatureB64: string): boolean;

package/dist/agentkey.js

@@ -0,0 +1,118 @@
+/**
+ * The agent's identity: an Ed25519 key whose public half the engine stores.
+ *
+ * The engine shows the secret once, as `msk_<prefix>_<seed>`: a label, then
+ * the 32-byte seed in base64url without padding. The key id (`key_…`) is
+ * separate and public.
+ *
+ * The key signs two things: proposals (proposal.ts) and, under the
+ * contract's agentAuth scheme, every other agent-facing request: four headers
+ * carry the key id, the time, a nonce and an Ed25519 signature over the
+ * canonical JSON of `{bodySha256, keyId, method, nonce, path, query,
+ * signedAt}`. The bytes are pinned in spec/vectors/agent-request-signing.json.
+ */
+import { createHash, createPrivateKey, createPublicKey, randomBytes, sign as edSign, verify as edVerify } from "node:crypto";
+import { canonicalBytes } from "./canon.js";
+import { rfc3339 } from "./time.js";
+const SEED_SIZE = 32;
+// DER wrappers for a raw Ed25519 seed and public key, so node:crypto can load them.
+const PKCS8_PREFIX = Buffer.from("302e020100300506032b657004220420", "hex");
+const SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+export const HEADER_KEY_ID = "X-Mishmar-Key-Id";
+export const HEADER_SIGNED_AT = "X-Mishmar-Signed-At";
+export const HEADER_NONCE = "X-Mishmar-Nonce";
+export const HEADER_SIGNATURE = "X-Mishmar-Signature";
+/** A fresh nonce: 16 random bytes, hex. */
+export function newNonce() {
+    return randomBytes(16).toString("hex");
+}
+/** What the agent signs for a request. */
+export function requestSigningBytes(r) {
+    const fields = {
+        keyId: r.keyId,
+        method: r.method.toUpperCase(),
+        nonce: r.nonce,
+        path: r.path,
+        signedAt: r.signedAt,
+    };
+    if (r.query)
+        fields.query = r.query;
+    const body = typeof r.body === "string" ? Buffer.from(r.body, "utf8") : r.body;
+    if (body && body.length > 0)
+        fields.bodySha256 = createHash("sha256").update(body).digest("hex");
+    return canonicalBytes(fields);
+}
+/** The agent's private key. */
+export class AgentKey {
+    #key;
+    constructor(key) {
+        this.#key = key;
+    }
+    /** Read the secret the engine showed when the key was issued. */
+    static parse(secret) {
+        // msk_<prefix>_<seed>: the seed is base64url and may itself contain '_',
+        // so split on the first two underscores only.
+        const s = secret.trim();
+        const first = s.indexOf("_");
+        const second = first < 0 ? -1 : s.indexOf("_", first + 1);
+        if (first < 0 || second < 0 || s.slice(0, first) !== "msk") {
+            throw new Error("malformed agent secret: expected msk_<prefix>_<seed>");
+        }
+        const seed = Buffer.from(s.slice(second + 1), "base64url");
+        if (seed.length !== SEED_SIZE || seed.toString("base64url") !== s.slice(second + 1)) {
+            throw new Error("malformed agent secret: the seed is not 32 base64url bytes");
+        }
+        return AgentKey.fromSeed(seed);
+    }
+    static fromSeed(seed) {
+        if (seed.length !== SEED_SIZE)
+            throw new Error("an Ed25519 seed is 32 bytes");
+        const der = Buffer.concat([PKCS8_PREFIX, Buffer.from(seed)]);
+        return new AgentKey(createPrivateKey({ key: der, format: "der", type: "pkcs8" }));
+    }
+    /** A fresh key, for tests and tools; the engine issues the real ones. */
+    static generate() {
+        return AgentKey.fromSeed(randomBytes(SEED_SIZE));
+    }
+    /** The base64 (standard, padded) Ed25519 signature of message. */
+    sign(message) {
+        return edSign(null, message, this.#key).toString("base64");
+    }
+    /** The four agentAuth headers for a request; the nonce and the time are made here when not given. */
+    signRequest(r) {
+        const nonce = r.nonce ?? newNonce();
+        const signedAt = rfc3339(r.signedAt ?? new Date());
+        const signature = this.sign(requestSigningBytes({ ...r, nonce, signedAt }));
+        return { [HEADER_KEY_ID]: r.keyId, [HEADER_SIGNED_AT]: signedAt, [HEADER_NONCE]: nonce, [HEADER_SIGNATURE]: signature };
+    }
+    /** The public half, raw 32 bytes. */
+    get publicKey() {
+        const spki = createPublicKey(this.#key).export({ format: "der", type: "spki" });
+        return new Uint8Array(spki.subarray(spki.length - SEED_SIZE));
+    }
+    /** The public half as the API stores and returns it. */
+    get publicKeyB64() {
+        return Buffer.from(this.publicKey).toString("base64");
+    }
+}
+/** Render a seed the way the engine shows it, with the given prefix. */
+export function secret(prefix, seed) {
+    return prefix + "_" + Buffer.from(seed).toString("base64url");
+}
+/** Check a base64 signature over message with a public key in the API's form. */
+export function verify(publicKeyB64, message, signatureB64) {
+    try {
+        const raw = Buffer.from(publicKeyB64, "base64");
+        if (raw.length !== SEED_SIZE)
+            return false;
+        const key = createPublicKey({ key: Buffer.concat([SPKI_PREFIX, raw]), format: "der", type: "spki" });
+        return edVerify(null, message, key, Buffer.from(signatureB64, "base64"));
+    }
+    catch {
+        return false;
+    }
+}
+/** The engine's side of agentAuth. Freshness and nonce replay are the caller's checks. */
+export function verifyRequest(publicKeyB64, r, signatureB64) {
+    return verify(publicKeyB64, requestSigningBytes(r), signatureB64);
+}

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// `mishmar` on npm: runs the real binary with these arguments (see wrapper.ts).
+import { main } from "./wrapper.js";
+process.exitCode = await main(import.meta.url);

package/dist/canon.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Canonical JSON: the bytes an agent signs and the engine verifies.
+ *
+ * The rules match Go's encoding/json, which the engine uses (see canon/ in
+ * the repo root and spec/vectors): one object, keys sorted by code point, no
+ * whitespace, keys whose value is null or undefined left out at every depth,
+ * strings with Go's escapes. JSON.stringify agrees on everything but the
+ * HTML-safe escapes, which are added here. Numbers never appear in what
+ * Mishmar signs, so they are refused rather than formatted differently.
+ */
+/** The canonical encoding of value, as a string (UTF-8 it before signing). */
+export declare function canonicalJson(value: unknown): string;
+/** The canonical encoding of value as the bytes to sign. */
+export declare function canonicalBytes(value: unknown): Uint8Array;

package/dist/canon.js

@@ -0,0 +1,64 @@
+/**
+ * Canonical JSON: the bytes an agent signs and the engine verifies.
+ *
+ * The rules match Go's encoding/json, which the engine uses (see canon/ in
+ * the repo root and spec/vectors): one object, keys sorted by code point, no
+ * whitespace, keys whose value is null or undefined left out at every depth,
+ * strings with Go's escapes. JSON.stringify agrees on everything but the
+ * HTML-safe escapes, which are added here. Numbers never appear in what
+ * Mishmar signs, so they are refused rather than formatted differently.
+ */
+const GO_ESCAPES = [
+    [/</g, "\\u003c"],
+    [/>/g, "\\u003e"],
+    [/&/g, "\\u0026"],
+    // Built from char codes: a literal U+2028/9 in a regex is a line break to JavaScript.
+    [new RegExp(String.fromCharCode(0x2028), "g"), "\\u2028"],
+    [new RegExp(String.fromCharCode(0x2029), "g"), "\\u2029"],
+];
+function quote(s) {
+    let out = JSON.stringify(s);
+    for (const [re, esc] of GO_ESCAPES)
+        out = out.replace(re, esc);
+    return out;
+}
+/** Go sorts keys as bytes, which for UTF-8 is code-point order; JS's default sort is UTF-16 order. */
+function byCodePoint(a, b) {
+    const x = Array.from(a, (c) => c.codePointAt(0) ?? 0);
+    const y = Array.from(b, (c) => c.codePointAt(0) ?? 0);
+    for (let i = 0; i < Math.min(x.length, y.length); i++) {
+        const d = (x[i] ?? 0) - (y[i] ?? 0);
+        if (d !== 0)
+            return d;
+    }
+    return x.length - y.length;
+}
+function encode(v) {
+    if (v === null || v === undefined)
+        return "null";
+    if (typeof v === "string")
+        return quote(v);
+    if (typeof v === "boolean")
+        return v ? "true" : "false";
+    if (typeof v === "number" || typeof v === "bigint") {
+        throw new TypeError(`canonicalJson: numbers are not signed by Mishmar; send ${String(v)} as a decimal string`);
+    }
+    if (Array.isArray(v))
+        return "[" + v.map(encode).join(",") + "]";
+    if (typeof v === "object") {
+        const o = v;
+        const keys = Object.keys(o)
+            .filter((k) => o[k] !== null && o[k] !== undefined)
+            .sort(byCodePoint);
+        return "{" + keys.map((k) => quote(k) + ":" + encode(o[k])).join(",") + "}";
+    }
+    throw new TypeError(`canonicalJson: cannot encode a ${typeof v}`);
+}
+/** The canonical encoding of value, as a string (UTF-8 it before signing). */
+export function canonicalJson(value) {
+    return encode(value);
+}
+/** The canonical encoding of value as the bytes to sign. */
+export function canonicalBytes(value) {
+    return new TextEncoder().encode(encode(value));
+}

package/dist/client.d.ts

@@ -0,0 +1,119 @@
+/**
+ * A small client for the engine, on fetch.
+ *
+ * Proposals go to POST /proposals with the signature in the body. Everything
+ * else an agent may call (its own decisions, approvals, positions, PnL,
+ * trading accounts, and the signer channel) is under /agent and signed with the
+ * agentAuth headers, so a bot can function without an operator token and
+ * cannot act on the account.
+ */
+import type { AgentKey } from "./agentkey.ts";
+import type { Proposal } from "./proposal.ts";
+/** A decision as the engine returns it; the contract (spec/openapi.yaml) has the full shape. */
+export type Decision = {
+    id: string;
+    verdict: "allow" | "require_approval" | "block";
+    approval?: {
+        status?: string;
+    } & Record<string, unknown>;
+} & Record<string, unknown>;
+/** A page of decisions. */
+export type DecisionPage = {
+    items: Decision[];
+    nextCursor?: string | null;
+} & Record<string, unknown>;
+/** A request the agent's signer must answer (SignRequest in the contract). */
+export type SignRequest = {
+    id: string;
+    scheme: string;
+} & Record<string, unknown>;
+/** The signer's answer (SignerAnswer in the contract). */
+export type SignerAnswer = {
+    kind: "share" | "signature" | "venue_response" | "refusal";
+} & Record<string, unknown>;
+/** The engine answered with an error: the HTTP status and the code and message from its body. */
+export declare class EngineError extends Error {
+    readonly status: number;
+    readonly code: string;
+    /** The `Retry-After` header of a 429, when the engine sent one. */
+    readonly retryAfter?: string;
+    constructor(status: number, code: string, message: string, retryAfter?: string);
+}
+/**
+ * How a call the engine did nothing with goes again: 503 `unavailable` while
+ * the engine restarts (its drain is 28 s) and 429 `rate_limited`. The same
+ * request is sent again after the seconds in `Retry-After` when the engine
+ * names them, otherwise after a wait that doubles from `minWaitMs` to
+ * `maxWaitMs` with jitter, until `budgetMs` have passed since the first
+ * attempt; then the last answer is thrown. Nothing else is retried: a 413
+ * `too_large` would come back the same, and any other answer means the
+ * request was taken. The defaults cover a restart.
+ */
+export interface Retries {
+    budgetMs?: number;
+    minWaitMs?: number;
+    maxWaitMs?: number;
+}
+export declare const DEFAULT_RETRIES: Required<Retries>;
+export interface ClientOptions {
+    timeoutMs?: number;
+    /** Retries of a call the engine did nothing with; on by default, `false` turns them off. */
+    retries?: Retries | false;
+    /** For tests: a fetch to use instead of the global one. */
+    fetch?: typeof fetch;
+    /** For tests: how to wait between attempts instead of a timer. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Milliseconds to wait before attempt `attempt + 1` (from 0) after an answer
+ * with the status and Retry-After header, `elapsedMs` after the first attempt
+ * began; `undefined` means stop and throw the answer.
+ */
+export declare function retryWait(retries: Retries, attempt: number, status: number, retryAfter: string | null, elapsedMs: number): number | undefined;
+/**
+ * Talks to one engine as one agent. The trading key's share lives in the
+ * agent's signer, never here: this client proposes, reads, and relays the
+ * signer channel.
+ */
+export declare class Client {
+    #private;
+    readonly engineUrl: string;
+    readonly agentKey: AgentKey;
+    readonly keyId: string;
+    constructor(engineUrl: string, agentKey: AgentKey, keyId: string, options?: ClientOptions);
+    /** Sign the proposal with the agent's key (unless already signed) and submit it. */
+    propose(proposal: Proposal): Promise<Decision>;
+    /** A page of this agent's decisions, newest first. */
+    decisions(query?: {
+        tradingAccountId?: string;
+        verdict?: string;
+        from?: string;
+        to?: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<DecisionPage>;
+    decision(decisionId: string): Promise<Decision>;
+    approvals(status?: string): Promise<Record<string, unknown>[]>;
+    positions(): Promise<Record<string, unknown>[]>;
+    /** Daily PnL of this agent; `from` and `to` are dates (YYYY-MM-DD). */
+    pnl(query?: {
+        from?: string;
+        to?: string;
+    }): Promise<Record<string, unknown>>;
+    tradingAccount(tradingAccountId: string): Promise<Record<string, unknown>>;
+    /** Poll a decision until it no longer waits for a person, or until timeoutMs; returns the last read. */
+    /** What the trading account's venue accepts per symbol (tick, step, minimums), as the engine last read it. */
+    venueRules(tradingAccountId: string, symbol?: string): Promise<Record<string, unknown>>;
+    wait(decisionId: string, { timeoutMs, intervalMs }?: {
+        timeoutMs?: number | undefined;
+        intervalMs?: number | undefined;
+    }): Promise<Decision>;
+    /** Wait up to waitSeconds for requests this agent's signer must sign. */
+    signerPoll(waitSeconds?: number): Promise<SignRequest[]>;
+    /** Answer a sign request: a share, a signature, a venue response or a refusal. */
+    /** Take up to `count` of the engine's single-use FROST commitments for one-shot signing with a venue key (CommitmentBatch). */
+    signerCommitments(venueKeyId: string, count?: number): Promise<Record<string, unknown>>;
+    signerAnswer(requestId: string, answer: SignerAnswer): Promise<void>;
+}
+/** Whether the decision no longer waits for a person. */
+export declare function resolved(d: Decision): boolean;