openbroker 1.9.4 → 1.9.6

package/dist/operations/execution.js

@@ -0,0 +1,106 @@
+import { WebSocketManager } from '../core/ws.js';
+import { sleep } from '../core/utils.js';
+export class UserFillWatcher {
+    client;
+    fills = new Map();
+    seenFills = new Set();
+    ws;
+    ownsWs;
+    started = false;
+    sinceMs;
+    user;
+    onFill = (fill) => {
+        this.recordFill({
+            oid: fill.oid,
+            coin: fill.coin,
+            px: fill.px,
+            sz: fill.sz,
+            time: fill.time,
+        });
+    };
+    constructor(client, options = {}) {
+        this.client = client;
+        this.ws = options.ws === undefined ? new WebSocketManager(client.verbose) : options.ws;
+        this.ownsWs = options.ws === undefined;
+        this.sinceMs = options.sinceMs ?? Date.now();
+        this.user = (options.user ?? client.address);
+    }
+    async start() {
+        if (this.started)
+            return;
+        this.started = true;
+        if (!this.ws)
+            return;
+        try {
+            await this.ws.connect();
+            this.ws.on('userFill', this.onFill);
+            await this.ws.subscribeUserFills(this.user);
+        }
+        catch {
+            this.ws.off('userFill', this.onFill);
+            if (this.ownsWs)
+                await this.ws.close().catch(() => { });
+            this.ws = null;
+        }
+    }
+    async stop() {
+        if (!this.started)
+            return;
+        this.started = false;
+        if (!this.ws)
+            return;
+        this.ws.off('userFill', this.onFill);
+        if (this.ownsWs)
+            await this.ws.close().catch(() => { });
+    }
+    getFilled(oid) {
+        return this.fills.get(oid) ?? { size: 0, notional: 0 };
+    }
+    async waitForFill(oid, targetSize, timeoutMs, options = {}) {
+        const deadline = Date.now() + Math.max(0, timeoutMs);
+        const pollMs = Math.max(250, options.pollMs ?? 1000);
+        while (Date.now() <= deadline) {
+            await this.refreshRestFills(options.coin);
+            const filled = this.getFilled(oid);
+            if (filled.size >= targetSize * 0.999)
+                return filled;
+            await sleep(Math.min(pollMs, Math.max(0, deadline - Date.now())));
+        }
+        await this.refreshRestFills(options.coin);
+        return this.getFilled(oid);
+    }
+    async refreshRestFills(coin) {
+        try {
+            const fills = await this.client.getUserFills(this.user);
+            for (const fill of fills) {
+                this.recordFill(fill, coin);
+            }
+        }
+        catch {
+            // WebSocket is the primary path; REST polling is best-effort fallback.
+        }
+    }
+    recordFill(fill, expectedCoin) {
+        if (expectedCoin && fill.coin !== expectedCoin)
+            return;
+        if (fill.time < this.sinceMs)
+            return;
+        const key = `${fill.oid}:${fill.time}:${fill.px}:${fill.sz}`;
+        if (this.seenFills.has(key))
+            return;
+        const size = parseFloat(fill.sz);
+        const price = parseFloat(fill.px);
+        if (!Number.isFinite(size) || size <= 0 || !Number.isFinite(price) || price <= 0)
+            return;
+        this.seenFills.add(key);
+        const prev = this.fills.get(fill.oid) ?? { size: 0, notional: 0 };
+        const next = {
+            size: prev.size + size,
+            notional: prev.notional + size * price,
+        };
+        this.fills.set(fill.oid, {
+            ...next,
+            avgPrice: next.notional / next.size,
+        });
+    }
+}

package/dist/operations/scale.d.ts

@@ -1,3 +1,52 @@
 #!/usr/bin/env npx tsx
-export {};
+import type { CancelResponse, OrderResponse } from '../core/types.js';
+export interface OrderLevel {
+    level: number;
+    price: number;
+    size: number;
+    distanceFromMid: number;
+}
+export interface ScaleClient {
+    verbose: boolean;
+    getAllMids(): Promise<Record<string, string>>;
+    bulkOrder(orders: Array<{
+        coin: string;
+        isBuy: boolean;
+        size: number;
+        price: number;
+        tif?: 'Gtc' | 'Alo';
+        reduceOnly?: boolean;
+        leverage?: number;
+    }>): Promise<OrderResponse>;
+    bulkCancel(cancels: Array<{
+        coin: string;
+        oid: number;
+    }>): Promise<CancelResponse>;
+}
+export interface ScaleOptions {
+    coin: string;
+    side: 'buy' | 'sell';
+    size: number;
+    levels: number;
+    rangePct: number;
+    distribution?: 'linear' | 'exponential' | 'flat';
+    leverage?: number;
+    reduceOnly?: boolean;
+    tif?: 'Gtc' | 'Alo';
+    dryRun?: boolean;
+    verbose?: boolean;
+    rollbackOnPartial?: boolean;
+    client?: ScaleClient;
+    output?: (line: string) => void;
+}
+export interface ScaleResult {
+    status: 'dry' | 'complete' | 'partial' | 'failed';
+    levels: OrderLevel[];
+    restingOids: number[];
+    filledOids: number[];
+    errors: string[];
+    rolledBack: boolean;
+}
+export declare function calculateLevels(midPrice: number, isBuy: boolean, totalSize: number, numLevels: number, rangePct: number, distribution: 'linear' | 'exponential' | 'flat'): OrderLevel[];
+export declare function runScale(opts: ScaleOptions): Promise<ScaleResult>;
 //# sourceMappingURL=scale.d.ts.map

package/dist/operations/scale.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scale.d.ts","sourceRoot":"","sources":["../../scripts/operations/scale.ts"],"names":[],"mappings":""}
+{"version":3,"file":"scale.d.ts","sourceRoot":"","sources":["../../scripts/operations/scale.ts"],"names":[],"mappings":";AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAyCtE,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC9C,SAAS,CACP,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,GACzI,OAAO,CAAC,aAAa,CAAC,CAAC;IAC1B,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CACpF;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,KAAK,GAAG,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,QAAQ,GAAG,aAAa,GAAG,MAAM,CAAC;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,KAAK,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;IAClD,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,QAAQ,GAAG,aAAa,GAAG,MAAM,GAC9C,UAAU,EAAE,CA0Cd;AAED,wBAAsB,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CA6HvE"}

package/dist/operations/scale.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env npx tsx
 // Scale In/Out - Place a grid of limit orders
+import { fileURLToPath } from 'url';
 import { getClient } from '../core/client.js';
-import { formatUsd, parseArgs, sleep } from '../core/utils.js';
+import { formatUsd, parseArgs } from '../core/utils.js';
 function printUsage() {
     console.log(`
 Open Broker - Scale In/Out
@@ -39,7 +40,7 @@ Examples:
   npx tsx scripts/operations/scale.ts --coin ETH --side buy --size 2 --levels 8 --range 5 --distribution exponential
 `);
 }
-function calculateLevels(midPrice, isBuy, totalSize, numLevels, rangePct, distribution) {
+export function calculateLevels(midPrice, isBuy, totalSize, numLevels, rangePct, distribution) {
     const levels = [];
     // Calculate weights based on distribution
     let weights = [];
@@ -75,6 +76,127 @@ function calculateLevels(midPrice, isBuy, totalSize, numLevels, rangePct, distri
     }
     return levels;
 }
+export async function runScale(opts) {
+    const out = opts.output ?? ((line) => console.log(line));
+    const distribution = opts.distribution ?? 'linear';
+    const reduceOnly = opts.reduceOnly ?? false;
+    const tif = opts.tif ?? 'Gtc';
+    const rollbackOnPartial = opts.rollbackOnPartial ?? true;
+    const isBuy = opts.side === 'buy';
+    if (!opts.coin)
+        throw new Error('coin is required');
+    if (opts.side !== 'buy' && opts.side !== 'sell')
+        throw new Error('side must be buy or sell');
+    if (!Number.isFinite(opts.size) || opts.size <= 0)
+        throw new Error('size must be positive');
+    if (!Number.isInteger(opts.levels) || opts.levels <= 0)
+        throw new Error('levels must be a positive integer');
+    if (!Number.isFinite(opts.rangePct) || opts.rangePct <= 0)
+        throw new Error('rangePct must be positive');
+    if (!['linear', 'exponential', 'flat'].includes(distribution))
+        throw new Error('distribution must be linear, exponential, or flat');
+    const client = opts.client ?? getClient();
+    if (opts.verbose)
+        client.verbose = true;
+    out('Open Broker - Scale In/Out');
+    out('==========================\n');
+    const mids = await client.getAllMids();
+    const midPrice = parseFloat(mids[opts.coin]);
+    if (!midPrice)
+        throw new Error(`No market data for ${opts.coin}`);
+    const levels = calculateLevels(midPrice, isBuy, opts.size, opts.levels, opts.rangePct, distribution);
+    const notional = levels.reduce((sum, l) => sum + l.price * l.size, 0);
+    const avgPrice = notional / opts.size;
+    out('Order Plan');
+    out('----------');
+    out(`Coin:           ${opts.coin}`);
+    out(`Side:           ${isBuy ? 'BUY' : 'SELL'}`);
+    out(`Total Size:     ${opts.size}`);
+    out(`Current Mid:    ${formatUsd(midPrice)}`);
+    out(`Levels:         ${opts.levels}`);
+    out(`Range:          ${opts.rangePct}% ${isBuy ? 'below' : 'above'} mid`);
+    out(`Distribution:   ${distribution}`);
+    out(`Time in Force:  ${tif}`);
+    out(`Reduce Only:    ${reduceOnly ? 'Yes' : 'No'}`);
+    out(`Est. Notional:  ${formatUsd(notional)}`);
+    out(`Avg Price:      ${formatUsd(avgPrice)}`);
+    out('\nOrder Grid');
+    out('----------');
+    out('Level | Price        | Size       | Distance');
+    out('------|--------------|------------|----------');
+    for (const level of levels) {
+        out(`  ${level.level.toString().padStart(2)}  | ` +
+            `${formatUsd(level.price).padStart(12)} | ` +
+            `${level.size.toFixed(6).padStart(10)} | ` +
+            `${level.distanceFromMid.toFixed(2)}%`);
+    }
+    if (opts.dryRun) {
+        out('\n🔍 Dry run - orders not placed');
+        return { status: 'dry', levels, restingOids: [], filledOids: [], errors: [], rolledBack: false };
+    }
+    out('\nPlacing ladder as a bulk order...\n');
+    const response = await client.bulkOrder(levels.map((level) => ({
+        coin: opts.coin,
+        isBuy,
+        size: level.size,
+        price: level.price,
+        tif,
+        reduceOnly,
+        leverage: opts.leverage,
+    })));
+    const restingOids = [];
+    const filledOids = [];
+    const errors = [];
+    if (response.status === 'ok' && response.response && typeof response.response === 'object') {
+        response.response.data.statuses.forEach((status, index) => {
+            const level = levels[index];
+            if (status?.resting) {
+                restingOids.push(status.resting.oid);
+                out(`Level ${level.level}: ✅ OID ${status.resting.oid}`);
+            }
+            else if (status?.filled) {
+                filledOids.push(status.filled.oid);
+                out(`Level ${level.level}: ✅ Filled ${status.filled.totalSz} @ ${formatUsd(parseFloat(status.filled.avgPx))}`);
+            }
+            else if (status?.error) {
+                errors.push(`Level ${level.level}: ${status.error}`);
+                out(`Level ${level.level}: ❌ ${status.error}`);
+            }
+            else {
+                errors.push(`Level ${level.level}: Unknown status`);
+                out(`Level ${level.level}: ⚠️ Unknown status`);
+            }
+        });
+    }
+    else {
+        const reason = typeof response.response === 'string' ? response.response : 'Bulk order failed';
+        errors.push(reason);
+        out(`❌ ${reason}`);
+    }
+    let rolledBack = false;
+    if (errors.length > 0 && rollbackOnPartial && restingOids.length > 0) {
+        out('\nPartial ladder placement detected; cancelling resting ladder orders...');
+        await client.bulkCancel(restingOids.map((oid) => ({ coin: opts.coin, oid })));
+        rolledBack = true;
+        out(`Cancelled ${restingOids.length} resting order(s).`);
+    }
+    out('\n========== Summary ==========');
+    out(`Orders Placed:  ${restingOids.length + filledOids.length}/${opts.levels}`);
+    if (errors.length > 0)
+        out(`Failed:         ${errors.length}`);
+    if (restingOids.length > 0)
+        out(`Resting OIDs:   ${restingOids.join(', ')}`);
+    if (filledOids.length > 0)
+        out(`Filled OIDs:    ${filledOids.join(', ')}`);
+    if (rolledBack)
+        out('Rollback:       Resting orders cancelled');
+    const status = errors.length === 0
+        ? 'complete'
+        : restingOids.length + filledOids.length > 0
+            ? 'partial'
+            : 'failed';
+    return { status, levels, restingOids, filledOids, errors, rolledBack };
+}
 async function main() {
     const args = parseArgs(process.argv.slice(2));
     const coin = args.coin;
@@ -91,15 +213,6 @@ async function main() {
         printUsage();
         process.exit(1);
     }
-    if (side !== 'buy' && side !== 'sell') {
-        console.error('Error: --side must be "buy" or "sell"');
-        process.exit(1);
-    }
-    if (!['linear', 'exponential', 'flat'].includes(distribution)) {
-        console.error('Error: --distribution must be linear, exponential, or flat');
-        process.exit(1);
-    }
-    // Map uppercase CLI input to Pascal case for SDK
     const tifMap = {
         'GTC': 'Gtc',
         'ALO': 'Alo'
@@ -109,104 +222,29 @@ async function main() {
         console.error('Error: --tif must be GTC or ALO');
         process.exit(1);
     }
-    const isBuy = side === 'buy';
-    const client = getClient();
-    if (args.verbose) {
-        client.verbose = true;
-    }
-    console.log('Open Broker - Scale In/Out');
-    console.log('==========================\n');
     try {
-        const mids = await client.getAllMids();
-        const midPrice = parseFloat(mids[coin]);
-        if (!midPrice) {
-            console.error(`Error: No market data for ${coin}`);
+        const result = await runScale({
+            coin,
+            side: side,
+            size: totalSize,
+            levels: numLevels,
+            rangePct,
+            distribution,
+            leverage,
+            reduceOnly,
+            tif,
+            dryRun,
+            verbose: args.verbose,
+        });
+        if (result.status === 'failed')
             process.exit(1);
-        }
-        const levels = calculateLevels(midPrice, isBuy, totalSize, numLevels, rangePct, distribution);
-        const notional = levels.reduce((sum, l) => sum + l.price * l.size, 0);
-        const avgPrice = notional / totalSize;
-        console.log('Order Plan');
-        console.log('----------');
-        console.log(`Coin:           ${coin}`);
-        console.log(`Side:           ${isBuy ? 'BUY' : 'SELL'}`);
-        console.log(`Total Size:     ${totalSize}`);
-        console.log(`Current Mid:    ${formatUsd(midPrice)}`);
-        console.log(`Levels:         ${numLevels}`);
-        console.log(`Range:          ${rangePct}% ${isBuy ? 'below' : 'above'} mid`);
-        console.log(`Distribution:   ${distribution}`);
-        console.log(`Time in Force:  ${tif}`);
-        console.log(`Reduce Only:    ${reduceOnly ? 'Yes' : 'No'}`);
-        console.log(`Est. Notional:  ${formatUsd(notional)}`);
-        console.log(`Avg Price:      ${formatUsd(avgPrice)}`);
-        console.log('\nOrder Grid');
-        console.log('----------');
-        console.log('Level | Price        | Size       | Distance');
-        console.log('------|--------------|------------|----------');
-        for (const level of levels) {
-            console.log(`  ${level.level.toString().padStart(2)}  | ` +
-                `${formatUsd(level.price).padStart(12)} | ` +
-                `${level.size.toFixed(6).padStart(10)} | ` +
-                `${level.distanceFromMid.toFixed(2)}%`);
-        }
-        if (dryRun) {
-            console.log('\n🔍 Dry run - orders not placed');
-            return;
-        }
-        console.log('\nPlacing orders...\n');
-        const results = [];
-        for (const level of levels) {
-            process.stdout.write(`Level ${level.level}: ${formatUsd(level.price)} x ${level.size.toFixed(6)}... `);
-            try {
-                const response = await client.limitOrder(coin, isBuy, level.size, level.price, tif, reduceOnly, leverage);
-                if (response.status === 'ok' && response.response && typeof response.response === 'object') {
-                    const status = response.response.data.statuses[0];
-                    if (status?.resting) {
-                        console.log(`✅ OID: ${status.resting.oid}`);
-                        results.push({ level: level.level, oid: status.resting.oid });
-                    }
-                    else if (status?.filled) {
-                        console.log(`✅ Filled immediately @ ${formatUsd(parseFloat(status.filled.avgPx))}`);
-                        results.push({ level: level.level, oid: status.filled.oid });
-                    }
-                    else if (status?.error) {
-                        console.log(`❌ ${status.error}`);
-                        results.push({ level: level.level, error: status.error });
-                    }
-                    else {
-                        console.log(`⚠️ Unknown status`);
-                        results.push({ level: level.level, error: 'Unknown status' });
-                    }
-                }
-                else {
-                    const error = typeof response.response === 'string' ? response.response : 'Failed';
-                    console.log(`❌ ${error}`);
-                    results.push({ level: level.level, error });
-                }
-            }
-            catch (err) {
-                const error = err instanceof Error ? err.message : String(err);
-                console.log(`❌ ${error}`);
-                results.push({ level: level.level, error });
-            }
-            // Small delay between orders
-            await sleep(100);
-        }
-        // Summary
-        const successful = results.filter(r => r.oid).length;
-        const failed = results.filter(r => r.error).length;
-        console.log('\n========== Summary ==========');
-        console.log(`Orders Placed:  ${successful}/${numLevels}`);
-        if (failed > 0) {
-            console.log(`Failed:         ${failed}`);
-        }
-        if (successful > 0) {
-            console.log(`Order IDs:      ${results.filter(r => r.oid).map(r => r.oid).join(', ')}`);
-        }
     }
     catch (error) {
-        console.error('Error:', error);
+        console.error('Error:', error instanceof Error ? error.message : error);
         process.exit(1);
     }
 }
-main();
+// Only run when invoked as a script — not when imported as a module.
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+    main();
+}

package/dist/setup/install.js

@@ -5,19 +5,54 @@ import * as path from 'path';
 import { homedir } from 'os';
 import { fileURLToPath } from 'url';
 import { spawnSync } from 'child_process';
+import { INSTALLABLE_PACKAGES, packageSpec, resolveInstallablePackage, } from './package-catalog.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const packageRoot = path.resolve(__dirname, '../..');
-const args = new Set(process.argv.slice(2));
+const rawArgs = process.argv.slice(2);
+const args = new Set(rawArgs);
+function positionalArgs() {
+    const positionals = [];
+    for (let index = 0; index < rawArgs.length; index++) {
+        const arg = rawArgs[index];
+        if (arg === '--tag') {
+            index++;
+            continue;
+        }
+        if (!arg.startsWith('-'))
+            positionals.push(arg);
+    }
+    return positionals;
+}
+function optionValue(flag) {
+    const index = rawArgs.indexOf(flag);
+    if (index < 0)
+        return null;
+    const value = rawArgs[index + 1];
+    if (!value || value.startsWith('-'))
+        fail(`${flag} requires a value`);
+    return value;
+}
 function printUsage() {
     console.log(`
-OpenBroker Harness Installer
-============================
+OpenBroker Installer
+====================
 
 Usage:
+  openbroker install <package> [--tag <version>] [--dry]
+  openbroker install --list
   openbroker install --codex [options]
   npx openbroker@latest install --codex [options]
 
+Companion packages:
+  monitoring    Install the local automation dashboard
+  extended      Install the Extended Exchange CLI
+
+Package options:
+  --tag <tag>   Install a release tag or exact version (default: latest)
+  --dry         Print the npm command without installing
+  --list        List supported companion packages
+
 Harnesses:
   --codex       Install the OpenBroker skill for Codex
 
@@ -74,6 +109,55 @@ function installGlobalCli() {
         fail('global CLI installation failed. Fix the npm permission error, then rerun with --skip-cli.');
     }
 }
+function printInstallablePackages() {
+    console.log('Installable OpenBroker packages:\n');
+    for (const entry of INSTALLABLE_PACKAGES) {
+        console.log(`  ${entry.key.padEnd(12)} ${entry.packageName.padEnd(26)} ${entry.description}`);
+    }
+    console.log('\nInstall or upgrade with: openbroker install <package>');
+}
+function installCompanionPackage(target) {
+    const entry = resolveInstallablePackage(target);
+    if (!entry) {
+        printInstallablePackages();
+        fail(`unknown installable package: ${target}`);
+    }
+    const allowedFlags = new Set(['--tag', '--dry']);
+    const unsupported = rawArgs.filter((arg, index) => (arg.startsWith('-')
+        && !allowedFlags.has(arg)
+        && rawArgs[index - 1] !== '--tag'));
+    if (unsupported.length > 0)
+        fail(`unsupported package option: ${unsupported[0]}`);
+    const tag = optionValue('--tag') ?? 'latest';
+    let spec;
+    try {
+        spec = packageSpec(entry, tag);
+    }
+    catch (error) {
+        fail(error instanceof Error ? error.message : String(error));
+    }
+    const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    const npmArgs = ['install', '--global', spec];
+    console.log(`OpenBroker — Install ${entry.key}`);
+    console.log('================================\n');
+    console.log(`Package: ${spec}`);
+    console.log(`Command: ${npmCommand} ${npmArgs.join(' ')}`);
+    if (args.has('--dry')) {
+        console.log('\nDry run only; nothing was installed.');
+        return;
+    }
+    const result = spawnSync(npmCommand, npmArgs, { stdio: 'inherit' });
+    if (result.error)
+        fail(`could not start npm: ${result.error.message}`);
+    if (result.status !== 0) {
+        fail(`installation failed for ${entry.packageName}; resolve the npm error and retry`);
+    }
+    console.log(`\n✅ ${entry.packageName} installed successfully.`);
+    console.log(`Available command: ${entry.command}`);
+    console.log('\nNext steps:');
+    for (const step of entry.nextSteps)
+        console.log(`  ${step}`);
+}
 function runApiWalletSetup() {
     const onboardPath = path.join(packageRoot, 'scripts', 'setup', 'onboard.ts');
     console.log('\nStarting restricted API-wallet onboarding...\n');
@@ -94,6 +178,19 @@ function main() {
         printUsage();
         return;
     }
+    if (args.has('--list')) {
+        printInstallablePackages();
+        return;
+    }
+    const positionals = positionalArgs();
+    if (positionals.length > 0) {
+        if (positionals.length > 1)
+            fail(`expected one package name, received: ${positionals.join(' ')}`);
+        if (args.has('--codex'))
+            fail('choose either a companion package or the --codex harness installer');
+        installCompanionPackage(positionals[0]);
+        return;
+    }
     if (!args.has('--codex')) {
         printUsage();
         fail('choose a supported harness flag such as --codex');

package/dist/setup/package-catalog.d.ts

@@ -0,0 +1,12 @@
+export interface InstallablePackage {
+    key: string;
+    aliases: string[];
+    packageName: string;
+    command: string;
+    description: string;
+    nextSteps: string[];
+}
+export declare const INSTALLABLE_PACKAGES: InstallablePackage[];
+export declare function resolveInstallablePackage(input: string): InstallablePackage | null;
+export declare function packageSpec(entry: InstallablePackage, tag?: string): string;
+//# sourceMappingURL=package-catalog.d.ts.map

package/dist/setup/package-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-catalog.d.ts","sourceRoot":"","sources":["../../scripts/setup/package-catalog.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,eAAO,MAAM,oBAAoB,EAAE,kBAAkB,EAuBpD,CAAC;AAEF,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAOlF;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,kBAAkB,EAAE,GAAG,SAAW,GAAG,MAAM,CAK7E"}

package/dist/setup/package-catalog.js

@@ -0,0 +1,36 @@
+export const INSTALLABLE_PACKAGES = [
+    {
+        key: 'monitoring',
+        aliases: ['openbroker-monitoring'],
+        packageName: 'openbroker-monitoring',
+        command: 'openbroker-monitoring',
+        description: 'Local automation dashboard and optional audit observer',
+        nextSteps: [
+            'openbroker-monitoring serve --host 127.0.0.1 --port 3001',
+            'Open http://127.0.0.1:3001',
+        ],
+    },
+    {
+        key: 'extended',
+        aliases: ['openbroker-extended'],
+        packageName: 'openbroker-extended',
+        command: 'openbroker-ex',
+        description: 'Extended Exchange trading CLI and library',
+        nextSteps: [
+            'openbroker-ex --help',
+            'openbroker-ex setup',
+        ],
+    },
+];
+export function resolveInstallablePackage(input) {
+    const normalized = input.trim().toLowerCase();
+    return INSTALLABLE_PACKAGES.find((entry) => (entry.key === normalized
+        || entry.packageName === normalized
+        || entry.aliases.includes(normalized))) ?? null;
+}
+export function packageSpec(entry, tag = 'latest') {
+    if (!/^[a-z0-9][a-z0-9._-]*$/i.test(tag)) {
+        throw new Error(`invalid package tag or version: ${tag}`);
+    }
+    return `${entry.packageName}@${tag}`;
+}

package/dist/setup/package-catalog.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=package-catalog.test.d.ts.map

package/dist/setup/package-catalog.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-catalog.test.d.ts","sourceRoot":"","sources":["../../scripts/setup/package-catalog.test.ts"],"names":[],"mappings":""}

package/dist/setup/package-catalog.test.js

@@ -0,0 +1,31 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { INSTALLABLE_PACKAGES, packageSpec, resolveInstallablePackage, } from './package-catalog.js';
+const installScript = fileURLToPath(new URL('./install.ts', import.meta.url));
+test('resolves companion packages by short name and npm package name', () => {
+    assert.equal(resolveInstallablePackage('monitoring')?.packageName, 'openbroker-monitoring');
+    assert.equal(resolveInstallablePackage('openbroker-monitoring')?.key, 'monitoring');
+    assert.equal(resolveInstallablePackage('EXTENDED')?.command, 'openbroker-ex');
+    assert.equal(resolveInstallablePackage('unknown'), null);
+});
+test('builds pinned or latest npm package specs without accepting arbitrary specs', () => {
+    const monitoring = INSTALLABLE_PACKAGES.find((entry) => entry.key === 'monitoring');
+    assert.ok(monitoring);
+    assert.equal(packageSpec(monitoring), 'openbroker-monitoring@latest');
+    assert.equal(packageSpec(monitoring, '1.4.2'), 'openbroker-monitoring@1.4.2');
+    assert.throws(() => packageSpec(monitoring, 'npm:unrelated-package'));
+    assert.throws(() => packageSpec(monitoring, '../local-package'));
+});
+test('installer dry run prints the global npm operation without writing', () => {
+    const result = spawnSync(process.execPath, ['--import', 'tsx', installScript, 'monitoring', '--tag', '1.4.2', '--dry'], { encoding: 'utf8' });
+    assert.equal(result.status, 0, result.stderr);
+    assert.match(result.stdout, /npm install --global openbroker-monitoring@1\.4\.2/);
+    assert.match(result.stdout, /nothing was installed/i);
+});
+test('installer rejects packages outside the catalog', () => {
+    const result = spawnSync(process.execPath, ['--import', 'tsx', installScript, 'unrelated-package', '--dry'], { encoding: 'utf8' });
+    assert.equal(result.status, 1);
+    assert.match(result.stderr, /unknown installable package/i);
+});