mishmar 0.0.0-stage → 0.2.0

package/dist/client.js

@@ -0,0 +1,188 @@
+/**
+ * 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 { sign, toWire } from "./proposal.js";
+const RESOLVED_APPROVAL = new Set(["approved", "rejected", "expired"]);
+/** The engine answered with an error: the HTTP status and the code and message from its body. */
+export class EngineError extends Error {
+    status;
+    code;
+    /** The `Retry-After` header of a 429, when the engine sent one. */
+    retryAfter;
+    constructor(status, code, message, retryAfter) {
+        super(`${status} ${code}: ${message}`);
+        this.name = "EngineError";
+        this.status = status;
+        this.code = code;
+        this.retryAfter = retryAfter;
+    }
+}
+export const DEFAULT_RETRIES = { budgetMs: 45_000, minWaitMs: 250, maxWaitMs: 8_000 };
+/** The answers that mean the request did nothing and may go again. */
+const RETRYABLE = new Set([503, 429]);
+/**
+ * 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 function retryWait(retries, attempt, status, retryAfter, elapsedMs) {
+    if (!RETRYABLE.has(status))
+        return undefined;
+    const budget = retries.budgetMs ?? DEFAULT_RETRIES.budgetMs;
+    const minWait = retries.minWaitMs ?? DEFAULT_RETRIES.minWaitMs;
+    const maxWait = Math.max(retries.maxWaitMs ?? DEFAULT_RETRIES.maxWaitMs, minWait);
+    let wait = parseRetryAfter(retryAfter);
+    if (wait === undefined) {
+        const step = Math.min(minWait * 2 ** Math.min(attempt, 20), maxWait);
+        wait = step / 2 + Math.random() * (step / 2);
+    }
+    return elapsedMs + wait > budget ? undefined : wait;
+}
+function parseRetryAfter(value) {
+    if (!value)
+        return undefined;
+    if (/^\d+$/.test(value.trim()))
+        return Number(value) * 1000;
+    const at = Date.parse(value);
+    return Number.isNaN(at) ? undefined : Math.max(at - Date.now(), 0);
+}
+/**
+ * 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 class Client {
+    engineUrl;
+    agentKey;
+    keyId;
+    #options;
+    constructor(engineUrl, agentKey, keyId, options = {}) {
+        this.engineUrl = engineUrl.replace(/\/+$/, "");
+        this.agentKey = agentKey;
+        this.keyId = keyId;
+        this.#options = options;
+    }
+    // Proposals
+    /** Sign the proposal with the agent's key (unless already signed) and submit it. */
+    async propose(proposal) {
+        const withKey = proposal.keyId ? proposal : { ...proposal, keyId: this.keyId };
+        const signed = withKey.signature ? withKey : sign(withKey, this.agentKey);
+        return (await this.#call("POST", "/proposals", toWire(signed)));
+    }
+    // Reads, scoped to this agent
+    /** A page of this agent's decisions, newest first. */
+    async decisions(query = {}) {
+        return (await this.#agentCall("GET", "/agent/decisions", { query }));
+    }
+    async decision(decisionId) {
+        return (await this.#agentCall("GET", `/agent/decisions/${encodeURIComponent(decisionId)}`));
+    }
+    async approvals(status) {
+        return (await this.#agentCall("GET", "/agent/approvals", { query: { status } }));
+    }
+    async positions() {
+        return (await this.#agentCall("GET", "/agent/positions"));
+    }
+    /** Daily PnL of this agent; `from` and `to` are dates (YYYY-MM-DD). */
+    async pnl(query = {}) {
+        return (await this.#agentCall("GET", "/agent/pnl", { query }));
+    }
+    async tradingAccount(tradingAccountId) {
+        return (await this.#agentCall("GET", `/agent/trading-accounts/${encodeURIComponent(tradingAccountId)}`));
+    }
+    /** 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. */
+    async venueRules(tradingAccountId, symbol) {
+        return (await this.#agentCall("GET", `/agent/trading-accounts/${encodeURIComponent(tradingAccountId)}/venue-rules`, { query: { symbol } }));
+    }
+    async wait(decisionId, { timeoutMs = 60_000, intervalMs = 1_000 } = {}) {
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            const d = await this.decision(decisionId);
+            if (resolved(d) || Date.now() >= deadline)
+                return d;
+            await new Promise((r) => setTimeout(r, Math.min(intervalMs, Math.max(0, deadline - Date.now()))));
+        }
+    }
+    // The signer channel
+    /** Wait up to waitSeconds for requests this agent's signer must sign. */
+    async signerPoll(waitSeconds = 25) {
+        const timeoutMs = (this.#options.timeoutMs ?? 10_000) + waitSeconds * 1000;
+        return (await this.#agentCall("POST", "/agent/signer/poll", { body: { waitSeconds }, timeoutMs }));
+    }
+    /** 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). */
+    async signerCommitments(venueKeyId, count) {
+        const body = { venueKeyId };
+        if (count !== undefined)
+            body.count = count;
+        return (await this.#agentCall("POST", "/agent/signer/commitments", { body }));
+    }
+    async signerAnswer(requestId, answer) {
+        await this.#agentCall("POST", `/agent/signer/requests/${encodeURIComponent(requestId)}/answer`, { body: answer });
+    }
+    // Plumbing
+    async #agentCall(method, path, { query, body, timeoutMs } = {}) {
+        const params = new URLSearchParams();
+        for (const [k, v] of Object.entries(query ?? {}))
+            if (v !== undefined)
+                params.set(k, String(v));
+        const queryText = params.toString();
+        const bodyText = body === undefined ? undefined : JSON.stringify(body);
+        // Each attempt is signed anew, with its own nonce and time, so a retry is never a replay.
+        const sign = () => this.agentKey.signRequest({ keyId: this.keyId, method, path, query: queryText, body: bodyText });
+        return this.#call(method, path + (queryText ? "?" + queryText : ""), body, sign, timeoutMs);
+    }
+    /** Sends the request, again after an answer that did nothing (`retries`), and returns the final answer decoded; `sign` makes each attempt's headers. */
+    async #call(method, path, body, sign, timeoutMs) {
+        const retries = this.#options.retries ?? {};
+        const start = Date.now();
+        for (let attempt = 0;; attempt++) {
+            const { res, text } = await this.#once(method, path, body, sign?.() ?? {}, timeoutMs);
+            if (res.ok)
+                return text ? JSON.parse(text) : null;
+            let code = "http_error";
+            let message = res.statusText || text.slice(0, 200);
+            try {
+                const parsed = JSON.parse(text);
+                if (typeof parsed.code === "string")
+                    code = parsed.code;
+                if (typeof parsed.message === "string")
+                    message = parsed.message;
+            }
+            catch {
+                // not JSON: keep the text
+            }
+            const err = new EngineError(res.status, code, message, res.headers.get("retry-after") ?? undefined);
+            const wait = retries === false ? undefined : retryWait(retries, attempt, res.status, err.retryAfter ?? null, Date.now() - start);
+            if (wait === undefined)
+                throw err;
+            await (this.#options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms))))(wait);
+        }
+    }
+    async #once(method, path, body, headers, timeoutMs) {
+        const h = { Accept: "application/json", ...headers };
+        if (body !== undefined)
+            h["Content-Type"] = "application/json";
+        const doFetch = this.#options.fetch ?? fetch;
+        const res = await doFetch(this.engineUrl + path, {
+            method,
+            headers: h,
+            body: body === undefined ? undefined : JSON.stringify(body),
+            signal: AbortSignal.timeout(timeoutMs ?? this.#options.timeoutMs ?? 10_000),
+        });
+        return { res, text: await res.text() };
+    }
+}
+/** Whether the decision no longer waits for a person. */
+export function resolved(d) {
+    if (d.verdict !== "require_approval")
+        return true;
+    return RESOLVED_APPROVAL.has(d.approval?.status ?? "");
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { AgentKey, HEADER_KEY_ID, HEADER_NONCE, HEADER_SIGNATURE, HEADER_SIGNED_AT, newNonce, requestSigningBytes, secret, verify, verifyRequest, } from "./agentkey.ts";
+export type { RequestToSign } from "./agentkey.ts";
+export { canonicalBytes, canonicalJson } from "./canon.ts";
+export { Client, DEFAULT_RETRIES, EngineError, resolved, retryWait } from "./client.ts";
+export type { ClientOptions, Decision, DecisionPage, Retries, SignRequest, SignerAnswer } from "./client.ts";
+export { fromWire, isDecimal, rfc3339, sign, signingBytes, toWire, validate } from "./proposal.ts";
+export type { Kind, OrderType, Proposal, Scheme, Side, VenueMessage, WireProposal } from "./proposal.ts";
+export { Signer, downloadBinary, findBinary, platformName, RELEASES } from "./signer.ts";
+export type { ConnectOptions, OrderIntent, SignerOptions } from "./signer.ts";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { AgentKey, HEADER_KEY_ID, HEADER_NONCE, HEADER_SIGNATURE, HEADER_SIGNED_AT, newNonce, requestSigningBytes, secret, verify, verifyRequest, } from "./agentkey.js";
+export { canonicalBytes, canonicalJson } from "./canon.js";
+export { Client, DEFAULT_RETRIES, EngineError, resolved, retryWait } from "./client.js";
+export { fromWire, isDecimal, rfc3339, sign, signingBytes, toWire, validate } from "./proposal.js";
+export { Signer, downloadBinary, findBinary, platformName, RELEASES } from "./signer.js";

package/dist/proposal.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Build and sign what an agent sends to POST /v1/proposals.
+ *
+ * The engine authenticates a proposal by its signature alone: the canonical
+ * JSON of the submitted object without `signature`, signed with the agent's
+ * key. The bytes are pinned in spec/vectors/proposal-signing.json, which the
+ * tests here run.
+ *
+ * Rules: size, price and leverage are decimal strings signed as written (no
+ * number ever touches them); times are RFC 3339 UTC with a Z suffix and the
+ * fraction trimmed; optional fields are present only when set, never null.
+ * A cancel (kind "cancel") carries targetClientOrderId and none of the order
+ * fields; every other kind carries side, size, orderType and reduceOnly. A
+ * venueMessage, when the signer built the venue request itself, is nested
+ * and canonicalised the same way, keys sorted.
+ */
+import type { AgentKey } from "./agentkey.ts";
+import { newNonce } from "./agentkey.ts";
+import { rfc3339 } from "./time.ts";
+export { newNonce, rfc3339 };
+export type Kind = "order" | "transaction" | "signed_message" | "cancel";
+export type Side = "buy" | "sell";
+export type OrderType = "limit" | "market";
+export type Scheme = "frost-ed25519" | "ecdsa-2p";
+/**
+ * The venue request the agent's signer built, with its half of the
+ * signature, for the one-shot path (the contract's ProposalVenueMessage).
+ * Base64 throughout.
+ */
+export interface VenueMessage {
+    venueKeyId: string;
+    scheme: Scheme;
+    message: string;
+    engineCommitmentId: string;
+    /** FROST only: the signer's own nonce commitment. */
+    commitment?: string;
+    share: string;
+}
+/**
+ * A proposal as the agent means it. `sign` fills what is left out. A cancel
+ * names the order to pull and leaves the order fields out:
+ * `{ kind: "cancel", tradingAccountId, symbol, targetClientOrderId }`.
+ */
+export interface Proposal {
+    tradingAccountId: string;
+    symbol: string;
+    /** Required for every kind but cancel. */
+    side?: Side;
+    /** Decimal string, e.g. "0.25". Required for every kind but cancel. */
+    size?: string;
+    /** Default "limit". */
+    orderType?: OrderType;
+    /** Decimal string; required for a limit order, absent for a market order. */
+    price?: string;
+    /** Decimal string. */
+    leverage?: string;
+    /** Default false; never sent on a cancel. */
+    reduceOnly?: boolean;
+    /** Default "order". */
+    kind?: Kind;
+    /** Cancels only: the clientOrderId of the order to pull. */
+    targetClientOrderId?: string;
+    venueMessage?: VenueMessage;
+    /** The Client fills this in. */
+    keyId?: string;
+    nonce?: string;
+    proposedAt?: Date;
+    expiresAt?: Date;
+    /** How long the agent gives the order, when expiresAt is not set. Default one minute. */
+    validForMs?: number;
+    signature?: string;
+}
+/** The request body as the contract names it. */
+export interface WireProposal {
+    keyId: string;
+    kind: Kind;
+    nonce: string;
+    orderType?: OrderType;
+    proposedAt: string;
+    expiresAt: string;
+    reduceOnly?: boolean;
+    tradingAccountId: string;
+    side?: Side;
+    size?: string;
+    symbol: string;
+    price?: string;
+    leverage?: string;
+    targetClientOrderId?: string;
+    venueMessage?: VenueMessage;
+    signature?: string;
+}
+/** Whether s is a decimal string the contract accepts ("0.5", "-12", "98000.25"). */
+export declare function isDecimal(s: unknown): s is string;
+/** The proposal's times, defaulting to now and now plus validForMs. */
+export declare function times(p: Proposal): {
+    proposedAt: Date;
+    expiresAt: Date;
+};
+/** Throw naming the first field the engine would refuse. */
+export declare function validate(p: Proposal): void;
+/** The request body for the proposal (the signature included once signed). */
+export declare function toWire(p: Proposal): WireProposal;
+/** The inverse of toWire, for vectors and for replaying a stored proposal. */
+export declare function fromWire(w: WireProposal): Proposal;
+/** What the agent signs: the canonical JSON of the proposal without the signature. */
+export declare function signingBytes(p: Proposal): Uint8Array;
+/** Pin the times, validate, and return the proposal with its signature set. */
+export declare function sign(p: Proposal, key: AgentKey): Proposal;

package/dist/proposal.js

@@ -0,0 +1,159 @@
+/**
+ * Build and sign what an agent sends to POST /v1/proposals.
+ *
+ * The engine authenticates a proposal by its signature alone: the canonical
+ * JSON of the submitted object without `signature`, signed with the agent's
+ * key. The bytes are pinned in spec/vectors/proposal-signing.json, which the
+ * tests here run.
+ *
+ * Rules: size, price and leverage are decimal strings signed as written (no
+ * number ever touches them); times are RFC 3339 UTC with a Z suffix and the
+ * fraction trimmed; optional fields are present only when set, never null.
+ * A cancel (kind "cancel") carries targetClientOrderId and none of the order
+ * fields; every other kind carries side, size, orderType and reduceOnly. A
+ * venueMessage, when the signer built the venue request itself, is nested
+ * and canonicalised the same way, keys sorted.
+ */
+import { newNonce } from "./agentkey.js";
+import { canonicalBytes } from "./canon.js";
+import { parseTime, rfc3339 } from "./time.js";
+export { newNonce, rfc3339 };
+const DECIMAL = /^-?[0-9]+(\.[0-9]+)?$/;
+/** Whether s is a decimal string the contract accepts ("0.5", "-12", "98000.25"). */
+export function isDecimal(s) {
+    return typeof s === "string" && DECIMAL.test(s);
+}
+/** The proposal's times, defaulting to now and now plus validForMs. */
+export function times(p) {
+    const proposedAt = p.proposedAt ?? new Date();
+    const expiresAt = p.expiresAt ?? new Date(proposedAt.getTime() + (p.validForMs ?? 60_000));
+    return { proposedAt, expiresAt };
+}
+/** Throw naming the first field the engine would refuse. */
+export function validate(p) {
+    const orderType = p.orderType ?? "limit";
+    const kind = p.kind ?? "order";
+    if (!p.keyId)
+        throw new Error("keyId is required (the Client fills it in)");
+    if (!p.tradingAccountId)
+        throw new Error("tradingAccountId is required");
+    if (!p.symbol)
+        throw new Error("symbol is required");
+    if (!p.nonce)
+        throw new Error("nonce is required");
+    if (!["order", "transaction", "signed_message", "cancel"].includes(kind))
+        throw new Error("kind must be order, transaction, signed_message or cancel");
+    if (p.venueMessage !== undefined)
+        validateVenueMessage(p.venueMessage);
+    const { proposedAt, expiresAt } = times(p);
+    if (expiresAt.getTime() <= proposedAt.getTime())
+        throw new Error("expiresAt must be after proposedAt");
+    if (kind === "cancel") {
+        if (!p.targetClientOrderId)
+            throw new Error("a cancel needs targetClientOrderId, the clientOrderId of the order to pull");
+        if (p.side !== undefined || p.size !== undefined || p.price !== undefined || p.orderType !== undefined || p.leverage !== undefined || p.reduceOnly !== undefined) {
+            throw new Error("a cancel carries no order fields (side, size, price, orderType, leverage, reduceOnly)");
+        }
+        return;
+    }
+    if (p.targetClientOrderId !== undefined)
+        throw new Error("targetClientOrderId is for cancels only");
+    if (p.side !== "buy" && p.side !== "sell")
+        throw new Error("side must be buy or sell");
+    if (orderType !== "limit" && orderType !== "market")
+        throw new Error("orderType must be limit or market");
+    if (!isDecimal(p.size))
+        throw new Error('size must be a decimal string such as "0.5"');
+    if (orderType === "limit" && !isDecimal(p.price))
+        throw new Error("a limit order needs a decimal price string");
+    if (orderType === "market" && p.price !== undefined)
+        throw new Error("a market order carries no price");
+    if (p.leverage !== undefined && !isDecimal(p.leverage))
+        throw new Error("leverage must be a decimal string");
+    if (p.reduceOnly !== undefined && typeof p.reduceOnly !== "boolean")
+        throw new Error("reduceOnly must be a boolean");
+}
+function validateVenueMessage(m) {
+    if (!m.venueKeyId || !m.scheme || !m.message || !m.engineCommitmentId || !m.share) {
+        throw new Error("venueMessage needs venueKeyId, scheme, message, engineCommitmentId and share");
+    }
+    if (m.scheme !== "frost-ed25519" && m.scheme !== "ecdsa-2p")
+        throw new Error("venueMessage.scheme must be frost-ed25519 or ecdsa-2p");
+    if (m.scheme === "frost-ed25519" && !m.commitment)
+        throw new Error("a FROST venueMessage needs the signer's commitment");
+}
+/** The request body for the proposal (the signature included once signed). */
+export function toWire(p) {
+    const { proposedAt, expiresAt } = times(p);
+    const kind = p.kind ?? "order";
+    const w = {
+        keyId: p.keyId ?? "",
+        kind,
+        nonce: p.nonce ?? "",
+        proposedAt: rfc3339(proposedAt),
+        expiresAt: rfc3339(expiresAt),
+        tradingAccountId: p.tradingAccountId,
+        symbol: p.symbol,
+    };
+    if (kind !== "cancel") {
+        w.orderType = p.orderType ?? "limit";
+        w.reduceOnly = p.reduceOnly ?? false;
+        if (p.side !== undefined)
+            w.side = p.side;
+        if (p.size !== undefined)
+            w.size = p.size;
+        if (p.price !== undefined)
+            w.price = p.price;
+        if (p.leverage !== undefined)
+            w.leverage = p.leverage;
+    }
+    if (p.targetClientOrderId !== undefined)
+        w.targetClientOrderId = p.targetClientOrderId;
+    if (p.venueMessage !== undefined)
+        w.venueMessage = { ...p.venueMessage };
+    if (p.signature !== undefined)
+        w.signature = p.signature;
+    return w;
+}
+/** The inverse of toWire, for vectors and for replaying a stored proposal. */
+export function fromWire(w) {
+    const p = {
+        keyId: w.keyId,
+        kind: w.kind,
+        nonce: w.nonce,
+        proposedAt: parseTime(w.proposedAt),
+        expiresAt: parseTime(w.expiresAt),
+        tradingAccountId: w.tradingAccountId,
+        symbol: w.symbol,
+    };
+    if (w.orderType !== undefined)
+        p.orderType = w.orderType;
+    if (w.reduceOnly !== undefined)
+        p.reduceOnly = w.reduceOnly;
+    if (w.side !== undefined)
+        p.side = w.side;
+    if (w.size !== undefined)
+        p.size = w.size;
+    if (w.price !== undefined)
+        p.price = w.price;
+    if (w.leverage !== undefined)
+        p.leverage = w.leverage;
+    if (w.targetClientOrderId !== undefined)
+        p.targetClientOrderId = w.targetClientOrderId;
+    if (w.venueMessage !== undefined)
+        p.venueMessage = { ...w.venueMessage };
+    if (w.signature !== undefined)
+        p.signature = w.signature;
+    return p;
+}
+/** What the agent signs: the canonical JSON of the proposal without the signature. */
+export function signingBytes(p) {
+    const { signature: _signature, ...unsigned } = toWire(p);
+    return canonicalBytes(unsigned);
+}
+/** Pin the times, validate, and return the proposal with its signature set. */
+export function sign(p, key) {
+    const pinned = { ...p, nonce: p.nonce ?? newNonce(), ...times(p) };
+    validate(pinned);
+    return { ...pinned, signature: key.sign(signingBytes(pinned)) };
+}

package/dist/signer.d.ts

@@ -0,0 +1,139 @@
+/**
+ * The signer as a child process, or one already running.
+ *
+ * `Signer` starts `mishmar signer run --local …` with the agent's config and
+ * talks to it over a Unix socket (or, on Windows, localhost with a token).
+ * The child holds the agent's key and its halves of the venue keys; this
+ * process holds no secret at all. An order is an intent: the child turns it
+ * into a proposal signed with the agent's key, sends it one-shot where it can
+ * build the venue's message, through the channel otherwise, and hands back
+ * the decision as the engine recorded it. The agent's reads pass through the
+ * child the same way.
+ *
+ *     const s = await new Signer().start();          // ~/.mishmar/agent.json, mishmar on PATH
+ *     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);
+ *     await s.stop();
+ *
+ * The child lives and dies with this process: it gets a pipe on stdin that
+ * is never written to and stops when the pipe closes, so it does not outlive
+ * a bot that crashed or was killed. A signer run on its own instead (systemd,
+ * launchd, Docker: `mishmar signer run --local unix:/path`) is reached with
+ * `Signer.connect`, which never starts or stops it; that is the way for
+ * several processes of one agent, or to keep the signer connected across bot
+ * restarts. One signer runs per config: a second one on the same config
+ * stops at once and says which process holds it.
+ *
+ * The binary is found through `MISHMAR_BIN`, the PATH, or
+ * `~/.mishmar/bin/<version>/mishmar`; `downloadBinary` fetches a release from
+ * GitHub and checks it against the release's checksums.
+ */
+import type { ChildProcess } from "node:child_process";
+import type { Decision, DecisionPage } from "./client.ts";
+export declare const RELEASES = "https://github.com/mishmar-io/mishmar/releases/download";
+/** The release asset's os_arch for this machine: linux_amd64, darwin_arm64, … */
+export declare function platformName(): string;
+/**
+ * Where the mishmar binary is: the argument, `MISHMAR_BIN`, the PATH, or a
+ * release `downloadBinary` fetched. Throws with what to do when there is none.
+ */
+export declare function findBinary(explicit?: string): Promise<string>;
+/**
+ * Fetch the release `version` (a tag, v0.1.0) for this machine into `destDir`
+ * (default `~/.mishmar/bin/<version>`), after checking its SHA-256 against the
+ * release's SHA256SUMS. Returns the binary's path.
+ */
+export declare function downloadBinary(version: string, destDir?: string, fetchImpl?: typeof fetch): Promise<string>;
+/** An order to propose. Sizes and prices are decimal strings as the venue quotes them. */
+export interface OrderIntent {
+    tradingAccountId: string;
+    symbol: string;
+    side: "buy" | "sell";
+    size: string;
+    /** limit (the default; needs price) or market (priced at the engine's mark). */
+    orderType?: "limit" | "market";
+    price?: string;
+    reduceOnly?: boolean;
+    leverage?: string;
+    /** How long the proposal stands, at most 86400; default 60. */
+    validForSeconds?: number;
+    /** Leave the venue request to the engine and the signer's poller even where one-shot is possible. */
+    channel?: boolean;
+}
+export interface SignerOptions {
+    /** The signer's config file; default $MISHMAR_AGENT_CONFIG or ~/.mishmar/agent.json. */
+    config?: string;
+    /** The mishmar binary; default what findBinary finds. */
+    binary?: string;
+    /** Where the child listens: unix:/path, or host:port on a loopback address (with a token); default a private socket. */
+    address?: string;
+    startTimeoutMs?: number;
+    timeoutMs?: number;
+    logLevel?: "debug" | "info" | "warn" | "error";
+    /** Where the child's log lines go; default stderr. */
+    onLog?: (line: string) => void;
+}
+/** How to reach a signer that runs on its own (`Signer.connect`). */
+export interface ConnectOptions {
+    /** The signer's token, for a loopback host:port; default $MISHMAR_LOCAL_TOKEN. */
+    token?: string;
+    startTimeoutMs?: number;
+    timeoutMs?: number;
+}
+/**
+ * The agent's signer, run as a child process and spoken to over its local API.
+ * The child stops when this process exits, however it exits. `Signer.connect`
+ * speaks to a signer that runs on its own instead.
+ */
+export declare class Signer {
+    #private;
+    readonly options: SignerOptions;
+    address: string | undefined;
+    token: string | undefined;
+    process: ChildProcess | undefined;
+    constructor(options?: SignerOptions);
+    /**
+     * Speak to a signer that already runs on its own (`mishmar signer run
+     * --local ADDRESS`, kept up by systemd, launchd or Docker), and wait until it
+     * answers. `address` is `unix:/path`, or a loopback host:port with the
+     * signer's token. Nothing is started, and `stop` leaves the signer running.
+     */
+    static connect(address: string, options?: ConnectOptions): Promise<Signer>;
+    /** Start the child and wait until its local API answers; for a signer from `connect`, only wait until it answers. */
+    start(): Promise<Signer>;
+    /**
+     * Stop the child, gently then not: its stdin closes, which stops it, and it
+     * gets SIGTERM, then SIGKILL after 5 s. A signer from `connect` keeps
+     * running; this only forgets it was ready.
+     */
+    stop(): Promise<void>;
+    /** Send an intent (the local API's ProposeRequest) and get the decision back. */
+    propose(intent: Record<string, unknown>): Promise<Decision>;
+    /** Propose an order. A limit order needs a price; a market order is priced at the engine's mark. */
+    order(intent: OrderIntent): Promise<Decision>;
+    /** Cancel a resting order this agent placed, by the clientOrderId its decision carries. */
+    cancel(tradingAccountId: string, symbol: string, clientOrderId: string, validForSeconds?: number): Promise<Decision>;
+    health(): Promise<Record<string, unknown>>;
+    decision(decisionId: string): Promise<Decision>;
+    decisions(query?: {
+        tradingAccountId?: string;
+        verdict?: string;
+        from?: string;
+        to?: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<DecisionPage>;
+    approvals(status?: string): Promise<Record<string, unknown>[]>;
+    positions(): Promise<Record<string, unknown>[]>;
+    pnl(query?: {
+        from?: string;
+        to?: string;
+    }): Promise<Record<string, unknown>>;
+    tradingAccount(tradingAccountId: string): Promise<Record<string, unknown>>;
+    venueRules(tradingAccountId: string, symbol?: string): Promise<Record<string, unknown>>;
+    /** Poll a decision until it no longer waits for a person, or until timeoutMs. */
+    wait(decisionId: string, { timeoutMs, intervalMs }?: {
+        timeoutMs?: number | undefined;
+        intervalMs?: number | undefined;
+    }): Promise<Decision>;
+}