@jinn-network/client 0.1.1 → 0.1.2-canary.d6e72dfd

package/dist/restorer/engine/registry.d.ts

@@ -0,0 +1,62 @@
+/**
+ * RestorerImplRegistry — impl registration + operator-config-aware dispatch.
+ *
+ * §6.7 of spec/2026-04-17-portfolio-v0-design.md
+ *
+ * Dispatch priority:
+ *   1. byKind[spec.kind] — explicit operator mapping wins regardless of
+ *      registration order
+ *   2. config.default — named fallback impl
+ *   3. First-match — iterate registered impls, return first whose supports()
+ *      returns true
+ *
+ * Disabled impls (config.disabled[]) are filtered out before dispatch.
+ */
+import type { RestorerImpl } from '../types.js';
+import type { RestorerImplRegistry as IRestorerImplRegistry } from './engine.js';
+export interface RestorerDispatchConfig {
+    /**
+     * Explicit kind → impl name mapping.
+     * e.g. { "portfolio.v0": "claude-mcp-hyperliquid" }
+     */
+    byKind?: Record<string, string>;
+    /**
+     * Fallback impl name when no kind-specific match is found.
+     */
+    default?: string;
+    /**
+     * Impl names to exclude from dispatch entirely.
+     */
+    disabled?: string[];
+}
+export declare class RestorerImplRegistry implements IRestorerImplRegistry {
+    private readonly impls;
+    private readonly config;
+    constructor(config?: RestorerDispatchConfig);
+    /**
+     * Register an impl. Later registrations appear later in the list for
+     * first-match fallback dispatch.
+     */
+    register(impl: RestorerImpl): void;
+    /**
+     * Find the impl to use for the given spec kind, applying operator config
+     * dispatch rules.
+     *
+     * Returns undefined if no suitable impl is found (all disabled, none
+     * support the kind, or registry is empty).
+     */
+    findFor(ctx: {
+        kind: string;
+        type?: 'restoration' | 'evaluation';
+    }): RestorerImpl | undefined;
+    /** All registered impls (including disabled ones). */
+    list(): RestorerImpl[];
+    /**
+     * IRestorerImplRegistry compatibility: resolve an impl name for a given
+     * spec kind, or null if none registered.
+     */
+    resolveImplName(ctx: {
+        kind: string | null;
+        type?: 'restoration' | 'evaluation';
+    }): string | null;
+}

package/dist/restorer/engine/registry.js

@@ -0,0 +1,73 @@
+/**
+ * RestorerImplRegistry — impl registration + operator-config-aware dispatch.
+ *
+ * §6.7 of spec/2026-04-17-portfolio-v0-design.md
+ *
+ * Dispatch priority:
+ *   1. byKind[spec.kind] — explicit operator mapping wins regardless of
+ *      registration order
+ *   2. config.default — named fallback impl
+ *   3. First-match — iterate registered impls, return first whose supports()
+ *      returns true
+ *
+ * Disabled impls (config.disabled[]) are filtered out before dispatch.
+ */
+// ── RestorerImplRegistry ──────────────────────────────────────────────────────
+export class RestorerImplRegistry {
+    impls = [];
+    config;
+    constructor(config = {}) {
+        this.config = config;
+    }
+    /**
+     * Register an impl. Later registrations appear later in the list for
+     * first-match fallback dispatch.
+     */
+    register(impl) {
+        this.impls.push(impl);
+    }
+    /**
+     * Find the impl to use for the given spec kind, applying operator config
+     * dispatch rules.
+     *
+     * Returns undefined if no suitable impl is found (all disabled, none
+     * support the kind, or registry is empty).
+     */
+    findFor(ctx) {
+        const disabled = new Set(this.config.disabled ?? []);
+        const active = this.impls.filter((impl) => !disabled.has(impl.name));
+        // 1. byKind explicit mapping — but ONLY honor it if the named impl supports
+        //    the requested ctx. Otherwise fall through (e.g., byKind points at the
+        //    restorer impl, but ctx asks for an evaluation).
+        const kindName = this.config.byKind?.[ctx.kind];
+        if (kindName) {
+            const named = active.find((impl) => impl.name === kindName);
+            if (named && named.supports(ctx))
+                return named;
+        }
+        // 2. default fallback name
+        if (this.config.default) {
+            const defaultImpl = active.find((impl) => impl.name === this.config.default);
+            if (defaultImpl && defaultImpl.supports(ctx)) {
+                return defaultImpl;
+            }
+        }
+        // 3. First-match by supports()
+        return active.find((impl) => impl.supports(ctx));
+    }
+    /** All registered impls (including disabled ones). */
+    list() {
+        return [...this.impls];
+    }
+    /**
+     * IRestorerImplRegistry compatibility: resolve an impl name for a given
+     * spec kind, or null if none registered.
+     */
+    resolveImplName(ctx) {
+        if (ctx.kind === null)
+            return null;
+        const impl = this.findFor({ kind: ctx.kind, type: ctx.type });
+        return impl?.name ?? null;
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/restorer/engine/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/restorer/engine/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAuBH,iFAAiF;AAEjF,MAAM,OAAO,oBAAoB;IACd,KAAK,GAAmB,EAAE,CAAC;IAC3B,MAAM,CAAyB;IAEhD,YAAY,SAAiC,EAAE;QAC7C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;OAGG;IACH,QAAQ,CAAC,IAAkB;QACzB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;IAED;;;;;;OAMG;IACH,OAAO,CAAC,GAA0D;QAChE,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;QACrD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAErE,4EAA4E;QAC5E,2EAA2E;QAC3E,qDAAqD;QACrD,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAChD,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;YAC5D,IAAI,KAAK,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC;gBAAE,OAAO,KAAK,CAAC;QACjD,CAAC;QAED,2BAA2B;QAC3B,IAAI,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACxB,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAC7E,IAAI,WAAW,IAAI,WAAW,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC7C,OAAO,WAAW,CAAC;YACrB,CAAC;QACH,CAAC;QAED,+BAA+B;QAC/B,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;IACnD,CAAC;IAED,sDAAsD;IACtD,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;IACzB,CAAC;IAED;;;OAGG;IACH,eAAe,CAAC,GAAiE;QAC/E,IAAI,GAAG,CAAC,IAAI,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QACnC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;QAC9D,OAAO,IAAI,EAAE,IAAI,IAAI,IAAI,CAAC;IAC5B,CAAC;CACF"}

package/dist/restorer/engine/signing.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared canonical signing helper for the restorer engine.
+ *
+ * Extracted from manifest-assembly.ts and portfolio-v0-evaluator/index.ts to
+ * eliminate duplicated keccak256 → secp256k1 sign → assemble-recovery-byte logic.
+ *
+ * Signing method: raw secp256k1 ECDSA, no EIP-191 prefix.
+ * Uses viem `sign({ hash, privateKey })` from `viem/accounts`.
+ */
+export interface SignedCanonical {
+    /** Canonical JSON string of the object (sorted keys, no whitespace). */
+    canonicalJson: string;
+    /** keccak256 hash of the canonical JSON bytes. */
+    hash: `0x${string}`;
+    /** 65-byte secp256k1 signature: r ++ s ++ recoveryByte, hex-encoded. */
+    sig: `0x${string}`;
+    /** Address of the signing key (passed through from caller). */
+    signer: `0x${string}`;
+}
+/**
+ * Serialise `obj` to canonical JSON, hash it with keccak256, sign with
+ * `privateKey`, and return the hash + 65-byte signature.
+ *
+ * @param obj           Object to sign (must be JSON-serialisable).
+ * @param privateKey    Agent EOA private key.
+ * @param signerAddress Address corresponding to `privateKey` (caller-supplied
+ *                      to avoid a redundant `privateKeyToAccount` call when the
+ *                      caller already has it).
+ */
+export declare function signCanonical(obj: unknown, privateKey: `0x${string}`, signerAddress: `0x${string}`): Promise<SignedCanonical>;

package/dist/restorer/engine/signing.js

@@ -0,0 +1,39 @@
+/**
+ * Shared canonical signing helper for the restorer engine.
+ *
+ * Extracted from manifest-assembly.ts and portfolio-v0-evaluator/index.ts to
+ * eliminate duplicated keccak256 → secp256k1 sign → assemble-recovery-byte logic.
+ *
+ * Signing method: raw secp256k1 ECDSA, no EIP-191 prefix.
+ * Uses viem `sign({ hash, privateKey })` from `viem/accounts`.
+ */
+import { keccak256, toHex, hexToBytes } from 'viem';
+import { sign } from 'viem/accounts';
+import { canonicalJson } from './canonical-json.js';
+// ── signCanonical ─────────────────────────────────────────────────────────────
+/**
+ * Serialise `obj` to canonical JSON, hash it with keccak256, sign with
+ * `privateKey`, and return the hash + 65-byte signature.
+ *
+ * @param obj           Object to sign (must be JSON-serialisable).
+ * @param privateKey    Agent EOA private key.
+ * @param signerAddress Address corresponding to `privateKey` (caller-supplied
+ *                      to avoid a redundant `privateKeyToAccount` call when the
+ *                      caller already has it).
+ */
+export async function signCanonical(obj, privateKey, signerAddress) {
+    const canonical = canonicalJson(obj);
+    const canonicalBytes = new TextEncoder().encode(canonical);
+    const hash = keccak256(canonicalBytes);
+    const sigResult = await sign({ hash, privateKey });
+    // viem sign() returns { r, s, v, yParity } — use yParity (canonical) with
+    // fallback to v for older viem versions that may not populate yParity.
+    const recoveryByte = sigResult.yParity ?? (sigResult.v === 28n ? 1 : 0);
+    const sig = toHex(new Uint8Array([
+        ...hexToBytes(sigResult.r),
+        ...hexToBytes(sigResult.s),
+        recoveryByte,
+    ]));
+    return { canonicalJson: canonical, hash, sig, signer: signerAddress };
+}
+//# sourceMappingURL=signing.js.map

package/dist/restorer/engine/signing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signing.js","sourceRoot":"","sources":["../../../src/restorer/engine/signing.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,EAAY,MAAM,MAAM,CAAC;AAC9D,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAepD,iFAAiF;AAEjF;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,GAAY,EACZ,UAAyB,EACzB,aAA4B;IAE5B,MAAM,SAAS,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IACrC,MAAM,cAAc,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAC3D,MAAM,IAAI,GAAG,SAAS,CAAC,cAAc,CAAkB,CAAC;IAExD,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;IACnD,0EAA0E;IAC1E,uEAAuE;IACvE,MAAM,YAAY,GAAG,SAAS,CAAC,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxE,MAAM,GAAG,GAAG,KAAK,CACf,IAAI,UAAU,CAAC;QACb,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;QAC1B,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;QAC1B,YAAY;KACb,CAAC,CACc,CAAC;IAEnB,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;AACxE,CAAC"}

package/dist/restorer/engine/state.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Restorer engine — state machine definitions.
+ *
+ * §6.3 of spec/2026-04-17-portfolio-v0-design.md
+ *
+ * Pure logic; no I/O, no persistence.
+ */
+export declare const IntentState: {
+    readonly DISCOVERED: "DISCOVERED";
+    readonly CLAIMED: "CLAIMED";
+    readonly WAITING: "WAITING";
+    readonly PRE_SNAPSHOT: "PRE_SNAPSHOT";
+    readonly RUNNING: "RUNNING";
+    readonly POST_SNAPSHOT: "POST_SNAPSHOT";
+    readonly PACKAGING: "PACKAGING";
+    readonly DELIVERING: "DELIVERING";
+    readonly COMPLETE: "COMPLETE";
+    readonly FAILED: "FAILED";
+};
+export type IntentState = (typeof IntentState)[keyof typeof IntentState];
+export declare const TERMINAL_STATES: ReadonlySet<IntentState>;
+export declare const IN_FLIGHT_STATES: ReadonlySet<IntentState>;
+/**
+ * Returns true if the transition from → to is permitted by the state machine.
+ */
+export declare function isValidTransition(from: IntentState, to: IntentState): boolean;
+/**
+ * Asserts that a transition is valid; throws if not.
+ */
+export declare function assertValidTransition(from: IntentState, to: IntentState): void;
+/**
+ * All state values as an array, useful for exhaustive checks.
+ */
+export declare const ALL_STATES: readonly IntentState[];
+/**
+ * Thrown by deliver() when claimDeliveryVariant is 'v2' but evidenceHash is
+ * null/undefined. A zero fallback would silently submit bytes32(0) on-chain
+ * and brick staking rewards; we prefer a loud FAILED transition instead.
+ */
+export declare class MissingEvidenceHashError extends Error {
+    constructor(requestId: string);
+}

package/dist/restorer/engine/state.js

@@ -0,0 +1,87 @@
+/**
+ * Restorer engine — state machine definitions.
+ *
+ * §6.3 of spec/2026-04-17-portfolio-v0-design.md
+ *
+ * Pure logic; no I/O, no persistence.
+ */
+// ── State enum ────────────────────────────────────────────────────────────────
+export const IntentState = {
+    DISCOVERED: 'DISCOVERED',
+    CLAIMED: 'CLAIMED',
+    WAITING: 'WAITING',
+    PRE_SNAPSHOT: 'PRE_SNAPSHOT',
+    RUNNING: 'RUNNING',
+    POST_SNAPSHOT: 'POST_SNAPSHOT',
+    PACKAGING: 'PACKAGING',
+    DELIVERING: 'DELIVERING',
+    COMPLETE: 'COMPLETE',
+    FAILED: 'FAILED',
+};
+export const TERMINAL_STATES = new Set([
+    IntentState.COMPLETE,
+    IntentState.FAILED,
+]);
+export const IN_FLIGHT_STATES = new Set([
+    IntentState.DISCOVERED,
+    IntentState.CLAIMED,
+    IntentState.WAITING,
+    IntentState.PRE_SNAPSHOT,
+    IntentState.RUNNING,
+    IntentState.POST_SNAPSHOT,
+    IntentState.PACKAGING,
+    IntentState.DELIVERING,
+]);
+// ── Transition table ──────────────────────────────────────────────────────────
+/**
+ * Allowed transitions. Any state can transition to FAILED (terminal error path).
+ * The table below lists non-FAILED successors only.
+ */
+const TRANSITIONS = new Map([
+    [IntentState.DISCOVERED, new Set([IntentState.CLAIMED, IntentState.FAILED])],
+    [IntentState.CLAIMED, new Set([IntentState.WAITING, IntentState.FAILED])],
+    [IntentState.WAITING, new Set([IntentState.PRE_SNAPSHOT, IntentState.FAILED])],
+    [IntentState.PRE_SNAPSHOT, new Set([IntentState.RUNNING, IntentState.FAILED])],
+    [IntentState.RUNNING, new Set([IntentState.POST_SNAPSHOT, IntentState.FAILED])],
+    [IntentState.POST_SNAPSHOT, new Set([IntentState.PACKAGING, IntentState.FAILED])],
+    [IntentState.PACKAGING, new Set([IntentState.DELIVERING, IntentState.FAILED])],
+    [IntentState.DELIVERING, new Set([IntentState.COMPLETE, IntentState.FAILED])],
+    [IntentState.COMPLETE, new Set()],
+    [IntentState.FAILED, new Set()],
+]);
+/**
+ * Returns true if the transition from → to is permitted by the state machine.
+ */
+export function isValidTransition(from, to) {
+    const allowed = TRANSITIONS.get(from);
+    if (!allowed)
+        return false;
+    return allowed.has(to);
+}
+/**
+ * Asserts that a transition is valid; throws if not.
+ */
+export function assertValidTransition(from, to) {
+    if (!isValidTransition(from, to)) {
+        throw new Error(`Invalid state transition: ${from} → ${to}. ` +
+            `Allowed from ${from}: [${[...(TRANSITIONS.get(from) ?? [])].join(', ')}]`);
+    }
+}
+/**
+ * All state values as an array, useful for exhaustive checks.
+ */
+export const ALL_STATES = Object.values(IntentState);
+// ── Delivery errors ───────────────────────────────────────────────────────────
+/**
+ * Thrown by deliver() when claimDeliveryVariant is 'v2' but evidenceHash is
+ * null/undefined. A zero fallback would silently submit bytes32(0) on-chain
+ * and brick staking rewards; we prefer a loud FAILED transition instead.
+ */
+export class MissingEvidenceHashError extends Error {
+    constructor(requestId) {
+        super(`deliver: evidenceHash is required for v2 claimDelivery but is missing ` +
+            `(requestId=${requestId}). Ensure pack() completed successfully before deliver().`);
+        this.name = 'MissingEvidenceHashError';
+    }
+}
+//# sourceMappingURL=state.js.map

package/dist/restorer/engine/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../../src/restorer/engine/state.ts"],"names":[],"mappings":"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"}

package/dist/restorer/impls/claude-mcp-hyperliquid/api-wallet.d.ts

@@ -0,0 +1,64 @@
+/**
+ * API wallet management for claude-mcp-hyperliquid — §8.1.
+ *
+ * Architecture decision (v0):
+ *   Option (b): fresh keypair generated on first use, persisted in implStateDir.
+ *   This provides blast-radius isolation — a compromised API wallet does not
+ *   expose other keys held by the operator.
+ *
+ * HL "approve agent" flow (v0 operator prerequisite):
+ *   The approve-agent authorization (linking the API wallet to the master account)
+ *   is an OPERATOR PREREQUISITE for v0. The operator must manually approve the API
+ *   wallet via the Hyperliquid UI (Settings → API Wallets → Add) or via the HL
+ *   L2 action `approveAgent` BEFORE the impl can place trades.
+ *
+ *   Steps:
+ *     1. Run any `jinn` command or let the daemon boot once — the API wallet
+ *        keypair is generated and persisted to <implStateDir>/api-wallet.json.
+ *     2. Run `jinn portfolio api-wallet` (or inspect the file) to get the address.
+ *     3. Approve that address as an API wallet on your HL master account.
+ *     4. Set `approved: true` in <implStateDir>/api-wallet.json  OR  call
+ *        `markApiWalletApproved(implStateDir)` from the CLI.
+ *
+ *   This impl checks `state.approved` in `canAttempt()` and returns an
+ *   informative error including the wallet address if not approved.
+ *
+ *   Programmatic approval is a §8.5 future item.
+ *
+ * State file: <implStateDir>/api-wallet.json  (mode 0o600)
+ */
+export interface ApiWalletState {
+    /** 0x-prefixed hex private key */
+    privateKey: string;
+    /** Derived Ethereum address */
+    address: string;
+    /** Whether the operator has approved this wallet as an HL agent */
+    approved: boolean;
+    /** Epoch ms when the wallet was created */
+    createdAt: number;
+    /** Epoch ms when approved flag was last set */
+    approvedAt?: number;
+    /**
+     * The HL master that approved this agent, captured during the operator's
+     * approve-agent setup. When present, the impl cross-checks this against
+     * the intent's `spec.account.masterAddress` on every run — if they
+     * disagree, it aborts with `E_MASTER_MISMATCH` rather than silently
+     * routing trades to the wrong master.
+     */
+    masterAddress?: string;
+}
+export declare function walletStatePath(implStateDir: string): string;
+export declare function loadApiWalletState(implStateDir: string): ApiWalletState | null;
+export declare function saveApiWalletState(implStateDir: string, state: ApiWalletState): void;
+/**
+ * Ensure an API wallet exists in implStateDir. Creates one if absent.
+ * Returns the current state (approved or not).
+ *
+ * Synchronous — safe to call at impl startup.
+ */
+export declare function provisionApiWallet(implStateDir: string): ApiWalletState;
+/**
+ * Mark the API wallet as approved by the operator.
+ * Call this after the operator completes the HL approve-agent flow.
+ */
+export declare function markApiWalletApproved(implStateDir: string): ApiWalletState;

package/dist/restorer/impls/claude-mcp-hyperliquid/api-wallet.js

@@ -0,0 +1,96 @@
+/**
+ * API wallet management for claude-mcp-hyperliquid — §8.1.
+ *
+ * Architecture decision (v0):
+ *   Option (b): fresh keypair generated on first use, persisted in implStateDir.
+ *   This provides blast-radius isolation — a compromised API wallet does not
+ *   expose other keys held by the operator.
+ *
+ * HL "approve agent" flow (v0 operator prerequisite):
+ *   The approve-agent authorization (linking the API wallet to the master account)
+ *   is an OPERATOR PREREQUISITE for v0. The operator must manually approve the API
+ *   wallet via the Hyperliquid UI (Settings → API Wallets → Add) or via the HL
+ *   L2 action `approveAgent` BEFORE the impl can place trades.
+ *
+ *   Steps:
+ *     1. Run any `jinn` command or let the daemon boot once — the API wallet
+ *        keypair is generated and persisted to <implStateDir>/api-wallet.json.
+ *     2. Run `jinn portfolio api-wallet` (or inspect the file) to get the address.
+ *     3. Approve that address as an API wallet on your HL master account.
+ *     4. Set `approved: true` in <implStateDir>/api-wallet.json  OR  call
+ *        `markApiWalletApproved(implStateDir)` from the CLI.
+ *
+ *   This impl checks `state.approved` in `canAttempt()` and returns an
+ *   informative error including the wallet address if not approved.
+ *
+ *   Programmatic approval is a §8.5 future item.
+ *
+ * State file: <implStateDir>/api-wallet.json  (mode 0o600)
+ */
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { privateKeyToAccount } from 'viem/accounts';
+// ── File path ──────────────────────────────────────────────────────────────────
+export function walletStatePath(implStateDir) {
+    return join(implStateDir, 'api-wallet.json');
+}
+// ── Load / save ────────────────────────────────────────────────────────────────
+export function loadApiWalletState(implStateDir) {
+    const path = walletStatePath(implStateDir);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function saveApiWalletState(implStateDir, state) {
+    const path = walletStatePath(implStateDir);
+    writeFileSync(path, JSON.stringify(state, null, 2), { encoding: 'utf-8', mode: 0o600 });
+}
+// ── Provision ──────────────────────────────────────────────────────────────────
+/**
+ * Ensure an API wallet exists in implStateDir. Creates one if absent.
+ * Returns the current state (approved or not).
+ *
+ * Synchronous — safe to call at impl startup.
+ */
+export function provisionApiWallet(implStateDir) {
+    const existing = loadApiWalletState(implStateDir);
+    if (existing)
+        return existing;
+    // Generate a fresh 32-byte private key
+    const privateKeyBytes = randomBytes(32);
+    const privateKey = `0x${privateKeyBytes.toString('hex')}`;
+    const account = privateKeyToAccount(privateKey);
+    const state = {
+        privateKey,
+        address: account.address,
+        approved: false,
+        createdAt: Date.now(),
+    };
+    saveApiWalletState(implStateDir, state);
+    return state;
+}
+/**
+ * Mark the API wallet as approved by the operator.
+ * Call this after the operator completes the HL approve-agent flow.
+ */
+export function markApiWalletApproved(implStateDir) {
+    const existing = loadApiWalletState(implStateDir);
+    if (!existing) {
+        throw new Error('api-wallet: no wallet found in implStateDir — call provisionApiWallet first');
+    }
+    const updated = {
+        ...existing,
+        approved: true,
+        approvedAt: Date.now(),
+    };
+    saveApiWalletState(implStateDir, updated);
+    return updated;
+}
+//# sourceMappingURL=api-wallet.js.map

package/dist/restorer/impls/claude-mcp-hyperliquid/api-wallet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-wallet.js","sourceRoot":"","sources":["../../../../src/restorer/impls/claude-mcp-hyperliquid/api-wallet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAClE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAyBpD,kFAAkF;AAElF,MAAM,UAAU,eAAe,CAAC,YAAoB;IAClD,OAAO,IAAI,CAAC,YAAY,EAAE,iBAAiB,CAAC,CAAC;AAC/C,CAAC;AAED,kFAAkF;AAElF,MAAM,UAAU,kBAAkB,CAAC,YAAoB;IACrD,MAAM,IAAI,GAAG,eAAe,CAAC,YAAY,CAAC,CAAC;IAC3C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACxC,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAmB,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,YAAoB,EAAE,KAAqB;IAC5E,MAAM,IAAI,GAAG,eAAe,CAAC,YAAY,CAAC,CAAC;IAC3C,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AAC1F,CAAC;AAED,kFAAkF;AAElF;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,YAAoB;IACrD,MAAM,QAAQ,GAAG,kBAAkB,CAAC,YAAY,CAAC,CAAC;IAClD,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAE9B,uCAAuC;IACvC,MAAM,eAAe,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;IACxC,MAAM,UAAU,GAAG,KAAK,eAAe,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAmB,CAAC;IAE3E,MAAM,OAAO,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAC;IAEhD,MAAM,KAAK,GAAmB;QAC5B,UAAU;QACV,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,QAAQ,EAAE,KAAK;QACf,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;KACtB,CAAC;IAEF,kBAAkB,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;IACxC,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,YAAoB;IACxD,MAAM,QAAQ,GAAG,kBAAkB,CAAC,YAAY,CAAC,CAAC;IAClD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,6EAA6E,CAAC,CAAC;IACjG,CAAC;IAED,MAAM,OAAO,GAAmB;QAC9B,GAAG,QAAQ;QACX,QAAQ,EAAE,IAAI;QACd,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE;KACvB,CAAC;IAEF,kBAAkB,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IAC1C,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/restorer/impls/claude-mcp-hyperliquid/index.d.ts

@@ -0,0 +1,101 @@
+/**
+ * claude-mcp-hyperliquid — Reference RestorerImpl for portfolio.v0 — §8.
+ *
+ * Spawns Claude Code session(s) with HL-specific MCP tools (§8.2).
+ * Safety rails enforced at the tool boundary (§8.3).
+ * Sequential session cadence per §8.4.
+ * API wallet managed in implStateDir (§8.1).
+ *
+ * OPERATOR PREREQUISITE (v0):
+ *   Before this impl can place trades, the operator must:
+ *   1. Let the daemon boot once (or call canAttempt()) to generate the API wallet.
+ *   2. Approve the generated API wallet address on their HL master account
+ *      (Settings → API Wallets → Add in the HL UI).
+ *   3. Set approved:true in <implStateDir>/api-wallet.json
+ *
+ *   The impl will surface the wallet address and instructions in canAttempt()
+ *   if the wallet is not yet approved.
+ *
+ *   Programmatic approval is a §8.5 future item.
+ */
+import type { RestorerImpl, RestorationContext, RestorationOutput, ReadyStatus, EnableResult, IntentEnableMetadata } from '../../types.js';
+import type { DesiredState } from '../../../types/desired-state.js';
+import { HyperliquidClient } from '../../../venues/hyperliquid/client.js';
+import type { SafetyConfig } from './safety-rails.js';
+export interface ClaudeMcpHyperliquidConfig {
+    claudePath?: string;
+    claudeModel?: string;
+    /** Per-intent safety override (from intent context) */
+    safetyConfig?: Partial<SafetyConfig>;
+    /** Cadence between sessions in ms. Default: 30 min */
+    cadenceMs?: number;
+    /** Max session wall time in ms. Default: 8 min */
+    sessionMaxMs?: number;
+    /**
+     * Impl state directory root — used by `isReady` and `onEnable` to locate
+     * the api-wallet file outside of a running intent context. Defaults to
+     * `/tmp/jinn-engine-impl-state/claude-mcp-hyperliquid` to match the
+     * convention the engine uses in `main.ts`.
+     */
+    implStateDir?: string;
+    /** Injected deps for testing */
+    _testDeps?: TestDeps;
+}
+export interface TestDeps {
+    /** Mock runner — called instead of spawning Claude */
+    runSession?: (sessionId: string, prompt: string) => Promise<{
+        stdout: string;
+    }>;
+    hlClient?: HyperliquidClient;
+}
+export declare class ClaudeMcpHyperliquidImpl implements RestorerImpl {
+    readonly name = "claude-mcp-hyperliquid";
+    readonly version = "1.0.0";
+    private config;
+    constructor(config?: ClaudeMcpHyperliquidConfig);
+    supports(ctx: {
+        kind: string;
+        type?: 'restoration' | 'evaluation';
+    }): boolean;
+    canAttempt(intent: DesiredState): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    /** Resolve the impl state directory used by enable / readiness flows. */
+    private resolveImplStateDir;
+    isReady(): Promise<ReadyStatus>;
+    enableMetadata(): IntentEnableMetadata;
+    onEnable(args: Record<string, string | undefined>): Promise<EnableResult>;
+    onDisable(): Promise<void>;
+    run(ctx: RestorationContext): Promise<RestorationOutput>;
+}
+interface HlServerConfig {
+    hlBaseUrl: string;
+    apiWalletPrivateKey: string;
+    apiWalletAddress: string;
+    masterAddress: string;
+    safetyConfig?: Partial<SafetyConfig>;
+}
+/**
+ * Write a thin ESM wrapper script to disk that delegates to the compiled
+ * startMcpServer() from this package. This is spawned as a subprocess by
+ * Claude's --mcp-config.
+ *
+ * Security: the config (including apiWalletPrivateKey) is written to a
+ * SEPARATE file (hl-server-config.json) with mode 0o600. The script body
+ * receives only the config file path via process.argv[2] — no private key
+ * or secret data appears in the script source.
+ *
+ * The import path is resolved at write-time from __dirname (this module's
+ * location) so it always points to the compiled mcp-tools.js alongside this
+ * file. The daemon MUST run from a compiled build (dist/) — `yarn build`
+ * produces `dist/restorer/impls/claude-mcp-hyperliquid/mcp-tools.js`, which
+ * this wrapper imports by absolute path from plain Node. Running from tsx
+ * against src/ would leave mcp-tools.js non-existent and cause Claude to
+ * silently spawn with no HL tools loaded — hence the explicit existence
+ * check and `E_DAEMON_MUST_RUN_FROM_DIST` error below.
+ */
+export declare function _writeHlMcpServerScript(outPath: string, hlConfig: HlServerConfig): void;
+export default ClaudeMcpHyperliquidImpl;