mishmar 0.0.0-stage → 0.2.0

package/dist/signer.js

@@ -0,0 +1,392 @@
+/**
+ * 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 { execFile, spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import { access, chmod, mkdir, mkdtemp, readdir, rm, writeFile } from "node:fs/promises";
+import * as http from "node:http";
+import * as net from "node:net";
+import { arch, homedir, platform, tmpdir } from "node:os";
+import * as path from "node:path";
+import { EngineError, resolved } from "./client.js";
+export const RELEASES = "https://github.com/mishmar-io/mishmar/releases/download";
+const ENV_BINARY = "MISHMAR_BIN";
+const ENV_LOCAL_TOKEN = "MISHMAR_LOCAL_TOKEN";
+/** The release asset's os_arch for this machine: linux_amd64, darwin_arm64, … */
+export function platformName() {
+    const os = { linux: "linux", darwin: "darwin", win32: "windows" }[platform()];
+    const cpu = { x64: "amd64", arm64: "arm64" }[arch()];
+    if (!os || !cpu)
+        throw new Error(`no mishmar release for ${platform()}/${arch()}`);
+    return `${os}_${cpu}`;
+}
+function exe(name) {
+    return platform() === "win32" ? name + ".exe" : name;
+}
+async function executable(p) {
+    if (!p)
+        return false;
+    try {
+        await access(p, fsConstants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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 async function findBinary(explicit) {
+    const candidates = [explicit, process.env[ENV_BINARY]];
+    const name = exe("mishmar");
+    for (const dir of (process.env.PATH ?? "").split(path.delimiter))
+        if (dir)
+            candidates.push(path.join(dir, name));
+    const home = path.join(homedir(), ".mishmar", "bin");
+    try {
+        for (const version of (await readdir(home)).sort().reverse())
+            candidates.push(path.join(home, version, name));
+    }
+    catch {
+        // no downloads yet
+    }
+    for (const c of candidates)
+        if (await executable(c))
+            return c;
+    throw new Error("no mishmar binary: install it from https://github.com/mishmar-io/mishmar/releases (or call downloadBinary(version)), put it on the PATH or in MISHMAR_BIN");
+}
+/**
+ * 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 async function downloadBinary(version, destDir, fetchImpl = fetch) {
+    const name = `mishmar_${version}_${platformName()}`;
+    const base = `${RELEASES}/${version}`;
+    const sumsRes = await fetchImpl(`${base}/SHA256SUMS`);
+    if (!sumsRes.ok)
+        throw new Error(`${base}/SHA256SUMS: HTTP ${sumsRes.status}`);
+    let want;
+    for (const line of (await sumsRes.text()).split("\n")) {
+        const parts = line.trim().split(/\s+/);
+        if (parts.length === 2 && parts[1]?.replace(/^\*/, "") === `${name}.tar.gz`)
+            want = parts[0]?.toLowerCase();
+    }
+    if (!want)
+        throw new Error(`${name}.tar.gz is not in the release's SHA256SUMS`);
+    const res = await fetchImpl(`${base}/${name}.tar.gz`);
+    if (!res.ok)
+        throw new Error(`${base}/${name}.tar.gz: HTTP ${res.status}`);
+    const archive = Buffer.from(await res.arrayBuffer());
+    const got = createHash("sha256").update(archive).digest("hex");
+    if (got !== want)
+        throw new Error(`${name}.tar.gz: checksum ${got} is not the release's ${want}`);
+    const dir = destDir ?? path.join(homedir(), ".mishmar", "bin", version);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const work = await mkdtemp(path.join(tmpdir(), "mishmar-"));
+    try {
+        const file = path.join(work, `${name}.tar.gz`);
+        await writeFile(file, archive);
+        await new Promise((resolve, reject) => execFile("tar", ["-xzf", file, "-C", dir, exe("mishmar")], (err) => (err ? reject(err) : resolve())));
+    }
+    finally {
+        await rm(work, { recursive: true, force: true });
+    }
+    const out = path.join(dir, exe("mishmar"));
+    await chmod(out, 0o755);
+    return out;
+}
+/**
+ * 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 class Signer {
+    options;
+    address;
+    token;
+    process;
+    #dir;
+    #stderrTail = [];
+    #attached = false;
+    #ready = false;
+    constructor(options = {}) {
+        this.options = options;
+        this.address = options.address;
+    }
+    /**
+     * 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 async connect(address, options = {}) {
+        const s = new Signer({ address, startTimeoutMs: options.startTimeoutMs, timeoutMs: options.timeoutMs });
+        s.#attached = true;
+        if (!address.startsWith("unix:")) {
+            s.token = options.token ?? process.env[ENV_LOCAL_TOKEN];
+            if (!s.token)
+                throw new Error(`${address}: a signer on a TCP port needs its token: pass { token } or set ${ENV_LOCAL_TOKEN}`);
+        }
+        return s.start();
+    }
+    /** Start the child and wait until its local API answers; for a signer from `connect`, only wait until it answers. */
+    async start() {
+        if (this.#attached) {
+            if (!this.#ready) {
+                await this.#waitReady(() => undefined);
+                this.#ready = true;
+            }
+            return this;
+        }
+        if (this.process)
+            return this;
+        const binary = await findBinary(this.options.binary);
+        const env = { ...process.env };
+        if (!this.address) {
+            if (platform() === "win32") {
+                this.address = `127.0.0.1:${await freePort()}`;
+            }
+            else {
+                this.#dir = await mkdtemp(path.join(tmpdir(), "mishmar-"));
+                this.address = "unix:" + path.join(this.#dir, "signer.sock");
+            }
+        }
+        if (!this.address.startsWith("unix:")) {
+            this.token ??= randomBytes(32).toString("base64url");
+            env[ENV_LOCAL_TOKEN] = this.token;
+        }
+        // The child stops when its stdin closes: when this process exits, however
+        // it exits. Nothing is ever written to it.
+        const args = ["signer", "run", "--local", this.address, "--log-level", this.options.logLevel ?? "info", "--exit-on-stdin-close"];
+        if (this.options.config)
+            args.push("--config", this.options.config);
+        const child = spawn(binary, args, { env, stdio: ["pipe", "ignore", "pipe"] });
+        child.stdin?.on("error", () => { }); // a child that exits first may close it under us
+        this.process = child;
+        let exited;
+        child.on("exit", (code, signal) => {
+            exited = { code, signal };
+        });
+        const onLog = this.options.onLog ?? ((line) => process.stderr.write(line + "\n"));
+        let pending = "";
+        child.stderr?.on("data", (chunk) => {
+            pending += chunk.toString("utf8");
+            const lines = pending.split("\n");
+            pending = lines.pop() ?? "";
+            for (const line of lines) {
+                this.#stderrTail.push(line);
+                if (this.#stderrTail.length > 40)
+                    this.#stderrTail.shift();
+                onLog(line);
+            }
+        });
+        await this.#waitReady(() => exited);
+        return this;
+    }
+    async #waitReady(exitedOf) {
+        const deadline = Date.now() + (this.options.startTimeoutMs ?? 15_000);
+        for (;;) {
+            const exited = exitedOf();
+            if (exited) {
+                const tail = this.#stderrTail.join("\n");
+                await this.#cleanup();
+                throw new Error(`the signer exited with status ${exited.code ?? exited.signal} before it was ready:\n${tail}`);
+            }
+            try {
+                await this.#request("GET", "/health", { timeoutMs: 2_000 });
+                return;
+            }
+            catch (err) {
+                if (err instanceof EngineError)
+                    throw err;
+                if (Date.now() >= deadline) {
+                    await this.stop();
+                    throw new Error(`the signer did not answer on ${this.address} within ${this.options.startTimeoutMs ?? 15_000} ms`);
+                }
+                await new Promise((r) => setTimeout(r, 100));
+            }
+        }
+    }
+    /**
+     * 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.
+     */
+    async stop() {
+        if (this.#attached) {
+            this.#ready = false;
+            return;
+        }
+        const child = this.process;
+        if (!child)
+            return;
+        try {
+            child.stdin?.destroy();
+            if (child.exitCode === null && child.signalCode === null) {
+                const gone = new Promise((resolve) => child.once("exit", () => resolve()));
+                child.kill("SIGTERM");
+                const timer = new Promise((resolve) => setTimeout(() => resolve("timeout"), 5_000));
+                if ((await Promise.race([gone, timer])) === "timeout") {
+                    child.kill("SIGKILL");
+                    await gone;
+                }
+            }
+        }
+        finally {
+            await this.#cleanup();
+        }
+    }
+    async #cleanup() {
+        this.process = undefined;
+        if (this.#dir) {
+            await rm(this.#dir, { recursive: true, force: true });
+            this.#dir = undefined;
+            this.address = undefined;
+        }
+    }
+    // Proposals
+    /** Send an intent (the local API's ProposeRequest) and get the decision back. */
+    async propose(intent) {
+        return (await this.#request("POST", "/propose", { body: intent }));
+    }
+    /** Propose an order. A limit order needs a price; a market order is priced at the engine's mark. */
+    async order(intent) {
+        return this.propose({ orderType: "limit", reduceOnly: false, validForSeconds: 60, channel: false, ...intent });
+    }
+    /** Cancel a resting order this agent placed, by the clientOrderId its decision carries. */
+    async cancel(tradingAccountId, symbol, clientOrderId, validForSeconds = 60) {
+        return this.propose({ tradingAccountId, symbol, kind: "cancel", targetClientOrderId: clientOrderId, validForSeconds });
+    }
+    // Reads, through the child
+    async health() {
+        return (await this.#request("GET", "/health"));
+    }
+    async decision(decisionId) {
+        return (await this.#request("GET", `/decisions/${encodeURIComponent(decisionId)}`));
+    }
+    async decisions(query = {}) {
+        return (await this.#request("GET", "/decisions", { query }));
+    }
+    async approvals(status) {
+        return (await this.#request("GET", "/approvals", { query: { status } }));
+    }
+    async positions() {
+        return (await this.#request("GET", "/positions"));
+    }
+    async pnl(query = {}) {
+        return (await this.#request("GET", "/pnl", { query }));
+    }
+    async tradingAccount(tradingAccountId) {
+        return (await this.#request("GET", `/trading-accounts/${encodeURIComponent(tradingAccountId)}`));
+    }
+    async venueRules(tradingAccountId, symbol) {
+        return (await this.#request("GET", `/trading-accounts/${encodeURIComponent(tradingAccountId)}/venue-rules`, { query: { symbol } }));
+    }
+    /** Poll a decision until it no longer waits for a person, or until timeoutMs. */
+    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()))));
+        }
+    }
+    // Plumbing
+    #request(method, p, { body, query, timeoutMs } = {}) {
+        const address = this.address;
+        if (!address)
+            return Promise.reject(new Error("the signer is not started"));
+        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 data = body === undefined ? undefined : JSON.stringify(body);
+        const headers = { Accept: "application/json" };
+        if (data !== undefined)
+            headers["Content-Type"] = "application/json";
+        if (this.token)
+            headers["Authorization"] = "Bearer " + this.token;
+        const target = address.startsWith("unix:")
+            ? { socketPath: address.slice("unix:".length) }
+            : { host: address.slice(0, address.lastIndexOf(":")), port: Number(address.slice(address.lastIndexOf(":") + 1)) };
+        return new Promise((resolve, reject) => {
+            const req = http.request({ ...target, method, path: p + (queryText ? "?" + queryText : ""), headers, timeout: timeoutMs ?? this.options.timeoutMs ?? 40_000 }, (res) => {
+                const chunks = [];
+                res.on("data", (c) => chunks.push(c));
+                res.on("end", () => {
+                    const text = Buffer.concat(chunks).toString("utf8");
+                    if ((res.statusCode ?? 0) >= 400) {
+                        let code = "http_error";
+                        let message = res.statusMessage || 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
+                        }
+                        reject(new EngineError(res.statusCode ?? 0, code, message));
+                        return;
+                    }
+                    try {
+                        resolve(text ? JSON.parse(text) : null);
+                    }
+                    catch (err) {
+                        reject(err);
+                    }
+                });
+            });
+            req.on("timeout", () => req.destroy(new Error("the signer did not answer in time")));
+            req.on("error", reject);
+            if (data !== undefined)
+                req.write(data);
+            req.end();
+        });
+    }
+}
+function freePort() {
+    return new Promise((resolve, reject) => {
+        const srv = net.createServer();
+        srv.listen(0, "127.0.0.1", () => {
+            const port = srv.address().port;
+            srv.close(() => resolve(port));
+        });
+        srv.on("error", reject);
+    });
+}

package/dist/time.d.ts

@@ -0,0 +1,5 @@
+/** Times as the contract writes them. */
+/** Format a time as the contract wants it: UTC, Z suffix, fraction trimmed. */
+export declare function rfc3339(d: Date): string;
+/** A Date from an RFC 3339 string that carries an offset. */
+export declare function parseTime(s: string): Date;

package/dist/time.js

@@ -0,0 +1,17 @@
+/** Times as the contract writes them. */
+/** Format a time as the contract wants it: UTC, Z suffix, fraction trimmed. */
+export function rfc3339(d) {
+    const iso = d.toISOString(); // 2026-10-18T10:00:00.250Z
+    const [whole, rest] = iso.split(".");
+    const fraction = (rest ?? "").replace(/Z$/, "").replace(/0+$/, "");
+    return fraction ? `${whole}.${fraction}Z` : `${whole}Z`;
+}
+/** A Date from an RFC 3339 string that carries an offset. */
+export function parseTime(s) {
+    if (!/(Z|[+-]\d\d:\d\d)$/.test(s))
+        throw new Error(`time ${JSON.stringify(s)} has no offset`);
+    const d = new Date(s);
+    if (Number.isNaN(d.getTime()))
+        throw new Error(`not a time: ${JSON.stringify(s)}`);
+    return d;
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "mishmar",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Mishmar client: sign and submit proposals to the engine that guards your trading agent",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test \"tests/**/*.test.ts\""
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "typescript": "^5.9.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mishmar-io/mishmar.git",
+    "directory": "typescript"
+  },
+  "homepage": "https://mishmar.io",
+  "keywords": [
+    "trading",
+    "agents",
+    "risk",
+    "guardrails",
+    "hyperliquid",
+    "binance"
+  ]
+}