lightnode-sdk 0.4.9 → 0.5.0

package/dist/bridge.d.ts

@@ -0,0 +1,233 @@
+/**
+ * Bridge SDK: typed wrapper around the LightChain bridge (Hyperlane Warp
+ * Route). Bridging LCAI between Ethereum mainnet and LightChain mainnet
+ * (chain 9200) is the main flow today; the addresses below were extracted
+ * from `lightchain-protocol/bridge-ui/src/consts/warpRoutes.ts`.
+ *
+ * The protocol:
+ *
+ *   Ethereum (chain 1) ─┐                                        ┌─ LightChain (chain 9200)
+ *      LCAI ERC-20      │                                        │     native LCAI
+ *      0x9cA8...8927    │                                        │
+ *                       │                                        │
+ *      user.approve()   │   transferRemote(9200, recipient, amt) │
+ *      ───────────► HypERC20Collateral 0x01f80b...e353 ──────────┼───► HypNative 0xEc7096...A6f1
+ *                       │   (locks LCAI in collateral vault)     │     (mints / releases native LCAI)
+ *                       └────────────────────────────────────────┘
+ *
+ *   Reverse: user calls transferRemote on HypNative (with native value =
+ *   amount + quoteGasPayment) to send LCAI back to Ethereum.
+ *
+ * Both sides expose:
+ *   - transferRemote(uint32 destination, bytes32 recipient, uint256 amount)
+ *     payable returns (bytes32 messageId)
+ *   - quoteGasPayment(uint32 destination) view returns (uint256)
+ *
+ * For the Ethereum -> LightChain direction the user must first call
+ * `approve(0x01f80b...e353, amount)` on the LCAI ERC-20.
+ */
+export type BridgeChain = "ethereum" | "lightchain-mainnet";
+export interface BridgeEndpoints {
+    /** Numeric chain id (mainnet ETH = 1, LightChain mainnet = 9200). */
+    chainId: number;
+    /** Hyperlane domain id (matches chainId for these two routes). */
+    hyperlaneDomain: number;
+    /** The user-facing router (HypERC20Collateral on Ethereum, HypNative on LightChain). */
+    router: `0x${string}`;
+    /**
+     * Underlying ERC-20 the router collateralizes. Null on the synthetic
+     * side (LightChain mainnet uses native LCAI). On Ethereum this is the
+     * LCAI ERC-20 the user must `approve` before calling `transferRemote`.
+     */
+    underlying: `0x${string}` | null;
+    /** Hyperlane mailbox (the message dispatch contract; useful for tracking). */
+    mailbox: `0x${string}`;
+    /** Block explorer for this side. */
+    explorer: string;
+    /** RPC endpoint we know about. */
+    rpc: string;
+    /** Human label for logs. */
+    label: string;
+}
+/** Live LCAI mainnet bridge route. From bridge-ui/src/consts/warpRoutes.ts. */
+export declare const BRIDGE_ROUTE: Record<BridgeChain, BridgeEndpoints>;
+/** Hyperlane TokenRouter ABI (subset we use). */
+export declare const HYPERLANE_ROUTER_ABI: readonly [{
+    readonly name: "transferRemote";
+    readonly type: "function";
+    readonly stateMutability: "payable";
+    readonly inputs: readonly [{
+        readonly type: "uint32";
+        readonly name: "destination";
+    }, {
+        readonly type: "bytes32";
+        readonly name: "recipient";
+    }, {
+        readonly type: "uint256";
+        readonly name: "amount";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bytes32";
+        readonly name: "messageId";
+    }];
+}, {
+    readonly name: "quoteGasPayment";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "uint32";
+        readonly name: "destination";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "balanceOf";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "account";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}];
+/** Minimal ERC-20 ABI for the LCAI approval step on the Ethereum side. */
+export declare const ERC20_ABI: readonly [{
+    readonly name: "approve";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "spender";
+    }, {
+        readonly type: "uint256";
+        readonly name: "amount";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}, {
+    readonly name: "allowance";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "owner";
+    }, {
+        readonly type: "address";
+        readonly name: "spender";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "balanceOf";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "account";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "decimals";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint8";
+    }];
+}];
+/** Pad a 20-byte EVM address to a 32-byte (bytes32) Hyperlane recipient. */
+export declare function addressToBytes32(addr: `0x${string}`): `0x${string}`;
+interface MinimalPublicClient {
+    readContract: (args: {
+        address: `0x${string}`;
+        abi: readonly unknown[];
+        functionName: string;
+        args?: readonly unknown[];
+    }) => Promise<unknown>;
+}
+/**
+ * Get the Hyperlane gas-payment quote for delivering ONE bridge message
+ * from `from` to `to`. Returned in wei of the FROM chain's gas token
+ * (ETH on Ethereum, LCAI on LightChain). Add this to the `value` of the
+ * `transferRemote` call.
+ */
+export declare function quoteBridgeFee(client: MinimalPublicClient, from: BridgeChain, to: BridgeChain): Promise<bigint>;
+/**
+ * Read the underlying token balance of `account` on the FROM side. Returned
+ * in raw wei (18 decimals for LCAI on both sides). For Ethereum -> LightChain
+ * use `from: "ethereum"` (returns ERC-20 balance). For the reverse use
+ * `from: "lightchain-mainnet"` and pass the chain's native-balance reader
+ * separately - HypNative does not expose `balanceOf`.
+ */
+export declare function bridgeableBalance(client: MinimalPublicClient, from: BridgeChain, account: `0x${string}`): Promise<bigint>;
+/** Read the LCAI ERC-20 allowance the user has approved for the bridge router. */
+export declare function bridgeAllowance(client: MinimalPublicClient, account: `0x${string}`): Promise<bigint>;
+interface MinimalWalletClient {
+    writeContract: (args: {
+        address: `0x${string}`;
+        abi: readonly unknown[];
+        functionName: string;
+        args: readonly unknown[];
+        value?: bigint;
+        gas?: bigint;
+    }) => Promise<`0x${string}`>;
+}
+/**
+ * Approve the Ethereum bridge router to spend LCAI on the user's behalf.
+ * Required ONCE before the first Ethereum -> LightChain transfer. The
+ * standard pattern is to approve `MaxUint256` so subsequent transfers do
+ * not need a second approve. Returns the tx hash.
+ */
+export declare function approveBridge(wallet: MinimalWalletClient, amount?: bigint): Promise<`0x${string}`>;
+export interface BridgeTransferArgs {
+    /** Source chain. */
+    from: BridgeChain;
+    /** Destination chain. */
+    to: BridgeChain;
+    /** Amount to bridge in raw wei (18 decimals for LCAI on both sides). */
+    amount: bigint;
+    /** Recipient EVM address on the destination chain. Defaults to the signer's address. */
+    recipient: `0x${string}`;
+    /**
+     * Bridge fee in wei to attach as `msg.value`. Get from `quoteBridgeFee()`.
+     * On the LightChain side (HypNative) the SDK adds the `amount` to this so
+     * the total `value` passed to transferRemote equals `amount + fee`.
+     */
+    fee: bigint;
+}
+/**
+ * Build and send the bridge transferRemote call. For Ethereum -> LightChain,
+ * `approveBridge()` must have run first. For LightChain -> Ethereum, no
+ * approval is needed (native LCAI is attached as value).
+ */
+export declare function bridgeTransfer(wallet: MinimalWalletClient, args: BridgeTransferArgs): Promise<`0x${string}`>;
+/**
+ * Convenience wrapper that bundles read + write helpers and exposes the
+ * mainnet route addresses as fields. Pass a viem PublicClient for reads
+ * and (optionally) a WalletClient for writes.
+ */
+export declare class Bridge {
+    private readonly publicClient;
+    private readonly walletClient?;
+    /** Confirmed mainnet route. Currently the only live bridge. */
+    readonly route: Record<BridgeChain, BridgeEndpoints>;
+    constructor(publicClient: MinimalPublicClient, walletClient?: MinimalWalletClient | undefined);
+    /** See `quoteBridgeFee` standalone. */
+    quoteFee(from: BridgeChain, to: BridgeChain): Promise<bigint>;
+    /** See `bridgeableBalance` standalone. */
+    balance(from: BridgeChain, account: `0x${string}`): Promise<bigint>;
+    /** See `bridgeAllowance` standalone (Ethereum side only). */
+    allowance(account: `0x${string}`): Promise<bigint>;
+    /** Approve the Ethereum bridge router. Requires a wallet. */
+    approve(amount?: bigint): Promise<`0x${string}`>;
+    /** Send a bridge transfer. Requires a wallet. */
+    transfer(args: BridgeTransferArgs): Promise<`0x${string}`>;
+}
+export {};

package/dist/bridge.js

@@ -0,0 +1,201 @@
+/**
+ * Bridge SDK: typed wrapper around the LightChain bridge (Hyperlane Warp
+ * Route). Bridging LCAI between Ethereum mainnet and LightChain mainnet
+ * (chain 9200) is the main flow today; the addresses below were extracted
+ * from `lightchain-protocol/bridge-ui/src/consts/warpRoutes.ts`.
+ *
+ * The protocol:
+ *
+ *   Ethereum (chain 1) ─┐                                        ┌─ LightChain (chain 9200)
+ *      LCAI ERC-20      │                                        │     native LCAI
+ *      0x9cA8...8927    │                                        │
+ *                       │                                        │
+ *      user.approve()   │   transferRemote(9200, recipient, amt) │
+ *      ───────────► HypERC20Collateral 0x01f80b...e353 ──────────┼───► HypNative 0xEc7096...A6f1
+ *                       │   (locks LCAI in collateral vault)     │     (mints / releases native LCAI)
+ *                       └────────────────────────────────────────┘
+ *
+ *   Reverse: user calls transferRemote on HypNative (with native value =
+ *   amount + quoteGasPayment) to send LCAI back to Ethereum.
+ *
+ * Both sides expose:
+ *   - transferRemote(uint32 destination, bytes32 recipient, uint256 amount)
+ *     payable returns (bytes32 messageId)
+ *   - quoteGasPayment(uint32 destination) view returns (uint256)
+ *
+ * For the Ethereum -> LightChain direction the user must first call
+ * `approve(0x01f80b...e353, amount)` on the LCAI ERC-20.
+ */
+import { parseAbi } from "viem";
+/** Live LCAI mainnet bridge route. From bridge-ui/src/consts/warpRoutes.ts. */
+export const BRIDGE_ROUTE = {
+    ethereum: {
+        chainId: 1,
+        hyperlaneDomain: 1,
+        router: "0x01f80bb8e78e79881E8Ec7832fB6C2c59f64e353",
+        underlying: "0x9cA8530CA349c966Fe9ef903Df17a75B8A778927", // LCAI ERC-20
+        mailbox: "0x287cf56E5b1435Ae59BF9Ce6443F055A0321a063",
+        explorer: "https://etherscan.io",
+        rpc: "https://eth.llamarpc.com",
+        label: "Ethereum",
+    },
+    "lightchain-mainnet": {
+        chainId: 9200,
+        hyperlaneDomain: 9200,
+        router: "0xEc7096A3116EE769457C939617375Ec1785AA6f1",
+        underlying: null, // HypNative: amount IS the native LCAI value
+        mailbox: "0x142a9CEf00ACcAddB76283c49A1Bf37f20c1F00e",
+        explorer: "https://mainnet.lightscan.app",
+        rpc: "https://rpc.mainnet.lightchain.ai",
+        label: "LightChain mainnet",
+    },
+};
+/** Hyperlane TokenRouter ABI (subset we use). */
+export const HYPERLANE_ROUTER_ABI = parseAbi([
+    "function transferRemote(uint32 destination, bytes32 recipient, uint256 amount) external payable returns (bytes32 messageId)",
+    "function quoteGasPayment(uint32 destination) external view returns (uint256)",
+    "function balanceOf(address account) external view returns (uint256)",
+]);
+/** Minimal ERC-20 ABI for the LCAI approval step on the Ethereum side. */
+export const ERC20_ABI = parseAbi([
+    "function approve(address spender, uint256 amount) external returns (bool)",
+    "function allowance(address owner, address spender) external view returns (uint256)",
+    "function balanceOf(address account) external view returns (uint256)",
+    "function decimals() external view returns (uint8)",
+]);
+/** Pad a 20-byte EVM address to a 32-byte (bytes32) Hyperlane recipient. */
+export function addressToBytes32(addr) {
+    const hex = addr.toLowerCase().replace(/^0x/, "");
+    if (hex.length !== 40)
+        throw new Error("bridge: recipient must be a 20-byte EVM address");
+    return (`0x${"0".repeat(24)}${hex}`);
+}
+/**
+ * Get the Hyperlane gas-payment quote for delivering ONE bridge message
+ * from `from` to `to`. Returned in wei of the FROM chain's gas token
+ * (ETH on Ethereum, LCAI on LightChain). Add this to the `value` of the
+ * `transferRemote` call.
+ */
+export async function quoteBridgeFee(client, from, to) {
+    if (from === to)
+        throw new Error("bridge: source and destination must differ");
+    const src = BRIDGE_ROUTE[from];
+    const dst = BRIDGE_ROUTE[to];
+    const result = (await client.readContract({
+        address: src.router,
+        abi: HYPERLANE_ROUTER_ABI,
+        functionName: "quoteGasPayment",
+        args: [dst.hyperlaneDomain],
+    }));
+    return result;
+}
+/**
+ * Read the underlying token balance of `account` on the FROM side. Returned
+ * in raw wei (18 decimals for LCAI on both sides). For Ethereum -> LightChain
+ * use `from: "ethereum"` (returns ERC-20 balance). For the reverse use
+ * `from: "lightchain-mainnet"` and pass the chain's native-balance reader
+ * separately - HypNative does not expose `balanceOf`.
+ */
+export async function bridgeableBalance(client, from, account) {
+    const side = BRIDGE_ROUTE[from];
+    if (!side.underlying) {
+        throw new Error(`bridge: ${from} bridges native LCAI; query getBalance(account) on the RPC directly`);
+    }
+    return (await client.readContract({
+        address: side.underlying,
+        abi: ERC20_ABI,
+        functionName: "balanceOf",
+        args: [account],
+    }));
+}
+/** Read the LCAI ERC-20 allowance the user has approved for the bridge router. */
+export async function bridgeAllowance(client, account) {
+    const eth = BRIDGE_ROUTE.ethereum;
+    if (!eth.underlying)
+        throw new Error("bridge: unreachable - Ethereum side has no underlying");
+    return (await client.readContract({
+        address: eth.underlying,
+        abi: ERC20_ABI,
+        functionName: "allowance",
+        args: [account, eth.router],
+    }));
+}
+/**
+ * Approve the Ethereum bridge router to spend LCAI on the user's behalf.
+ * Required ONCE before the first Ethereum -> LightChain transfer. The
+ * standard pattern is to approve `MaxUint256` so subsequent transfers do
+ * not need a second approve. Returns the tx hash.
+ */
+export async function approveBridge(wallet, amount = (1n << 256n) - 1n) {
+    const eth = BRIDGE_ROUTE.ethereum;
+    if (!eth.underlying)
+        throw new Error("bridge: unreachable");
+    return wallet.writeContract({
+        address: eth.underlying,
+        abi: ERC20_ABI,
+        functionName: "approve",
+        args: [eth.router, amount],
+    });
+}
+/**
+ * Build and send the bridge transferRemote call. For Ethereum -> LightChain,
+ * `approveBridge()` must have run first. For LightChain -> Ethereum, no
+ * approval is needed (native LCAI is attached as value).
+ */
+export async function bridgeTransfer(wallet, args) {
+    if (args.from === args.to)
+        throw new Error("bridge: source and destination must differ");
+    const src = BRIDGE_ROUTE[args.from];
+    const dst = BRIDGE_ROUTE[args.to];
+    // HypNative requires `value = amount + fee`. HypERC20Collateral takes the
+    // ERC-20 from the user's allowance and only requires the fee as `value`.
+    const value = src.underlying ? args.fee : args.amount + args.fee;
+    return wallet.writeContract({
+        address: src.router,
+        abi: HYPERLANE_ROUTER_ABI,
+        functionName: "transferRemote",
+        args: [dst.hyperlaneDomain, addressToBytes32(args.recipient), args.amount],
+        value,
+        gas: 500000n,
+    });
+}
+// =============================================================================
+// LightNode-style facade so consumers can do `new Bridge()` and read fields.
+// =============================================================================
+/**
+ * Convenience wrapper that bundles read + write helpers and exposes the
+ * mainnet route addresses as fields. Pass a viem PublicClient for reads
+ * and (optionally) a WalletClient for writes.
+ */
+export class Bridge {
+    constructor(publicClient, walletClient) {
+        this.publicClient = publicClient;
+        this.walletClient = walletClient;
+        /** Confirmed mainnet route. Currently the only live bridge. */
+        this.route = BRIDGE_ROUTE;
+    }
+    /** See `quoteBridgeFee` standalone. */
+    quoteFee(from, to) {
+        return quoteBridgeFee(this.publicClient, from, to);
+    }
+    /** See `bridgeableBalance` standalone. */
+    balance(from, account) {
+        return bridgeableBalance(this.publicClient, from, account);
+    }
+    /** See `bridgeAllowance` standalone (Ethereum side only). */
+    allowance(account) {
+        return bridgeAllowance(this.publicClient, account);
+    }
+    /** Approve the Ethereum bridge router. Requires a wallet. */
+    approve(amount) {
+        if (!this.walletClient)
+            throw new Error("bridge: no wallet client; pass one to the Bridge constructor for writes");
+        return approveBridge(this.walletClient, amount);
+    }
+    /** Send a bridge transfer. Requires a wallet. */
+    transfer(args) {
+        if (!this.walletClient)
+            throw new Error("bridge: no wallet client; pass one to the Bridge constructor for writes");
+        return bridgeTransfer(this.walletClient, args);
+    }
+}

package/dist/chat.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Multi-turn conversation helper. The LightChain inference protocol is
+ * single-turn at the session level (one createSession + one submitJob =
+ * one answer), but stateful chat is the most common builder need. So this
+ * keeps the conversation HISTORY client-side, serializes it into a single
+ * prompt per turn, and runs one full encrypted inference per turn under
+ * the hood. To the protocol it looks like N independent jobs; to the
+ * caller it reads as a coherent chat.
+ *
+ * Usage:
+ *
+ *   const chat = new Conversation({ network: "testnet", privateKey: "0x..." });
+ *   const a = await chat.send("Who wrote 'The Great Gatsby'?");
+ *   const b = await chat.send("In what year?");      // 'b' sees the prior turn
+ *   console.log(chat.messages());                    // full transcript
+ */
+import { type RunInferenceWithKeyArgs, type RunInferenceResult } from "./inference.js";
+export type ChatRole = "system" | "user" | "assistant";
+export interface ChatMessage {
+    role: ChatRole;
+    content: string;
+}
+export interface ConversationOptions extends Omit<RunInferenceWithKeyArgs, "prompt"> {
+    /**
+     * Initial system message (optional). Prepended to the serialized prompt on
+     * every turn. Use for persona, response constraints, or guardrails.
+     */
+    system?: string;
+    /**
+     * Cap how many prior turns are serialized into each new prompt. Older
+     * turns drop off in FIFO order. Default 20. Models tolerate longer
+     * histories but per-call fees scale with prompt length on token-priced
+     * networks.
+     */
+    maxHistoryTurns?: number;
+}
+export interface ConversationSendResult extends RunInferenceResult {
+    /** Updated transcript after this turn (includes the latest user + assistant pair). */
+    messages: ChatMessage[];
+}
+/**
+ * One round of `send` returns the assistant's reply plus all the
+ * on-chain receipts. `messages()` exposes the running transcript so a UI
+ * can render it; `reset()` clears history.
+ */
+export declare class Conversation {
+    private readonly opts;
+    private readonly history;
+    constructor(opts: ConversationOptions);
+    /** Read-only snapshot of the conversation so far. */
+    messages(): ChatMessage[];
+    /** Drop the running history (the next send becomes a fresh first turn). */
+    reset(): void;
+    /**
+     * Push a single user message and run one full inference. Returns the
+     * assistant's reply plus the standard runInference result (txs, worker,
+     * jobId). The assistant's reply is automatically appended to history so
+     * the next send sees it.
+     */
+    send(message: string): Promise<ConversationSendResult>;
+    /**
+     * Format the current history as a single text prompt the model can read.
+     * Chat-style turn markers ("User:" / "Assistant:") since the protocol's
+     * llama3-8b serving stack treats prompts as raw text and any reasonable
+     * formatting works. Uses the configured max-history-turns cap.
+     */
+    private serialize;
+}
+/** Functional shortcut for `new Conversation(opts)` so it reads inline. */
+export declare function chat(opts: ConversationOptions): Conversation;

package/dist/chat.js

@@ -0,0 +1,88 @@
+/**
+ * Multi-turn conversation helper. The LightChain inference protocol is
+ * single-turn at the session level (one createSession + one submitJob =
+ * one answer), but stateful chat is the most common builder need. So this
+ * keeps the conversation HISTORY client-side, serializes it into a single
+ * prompt per turn, and runs one full encrypted inference per turn under
+ * the hood. To the protocol it looks like N independent jobs; to the
+ * caller it reads as a coherent chat.
+ *
+ * Usage:
+ *
+ *   const chat = new Conversation({ network: "testnet", privateKey: "0x..." });
+ *   const a = await chat.send("Who wrote 'The Great Gatsby'?");
+ *   const b = await chat.send("In what year?");      // 'b' sees the prior turn
+ *   console.log(chat.messages());                    // full transcript
+ */
+import { runInferenceWithKey } from "./inference.js";
+/**
+ * One round of `send` returns the assistant's reply plus all the
+ * on-chain receipts. `messages()` exposes the running transcript so a UI
+ * can render it; `reset()` clears history.
+ */
+export class Conversation {
+    constructor(opts) {
+        this.history = [];
+        if (!opts.network)
+            throw new Error("Conversation: network is required");
+        if (!opts.privateKey)
+            throw new Error("Conversation: privateKey is required");
+        this.opts = opts;
+    }
+    /** Read-only snapshot of the conversation so far. */
+    messages() {
+        return [...this.history];
+    }
+    /** Drop the running history (the next send becomes a fresh first turn). */
+    reset() {
+        this.history.length = 0;
+    }
+    /**
+     * Push a single user message and run one full inference. Returns the
+     * assistant's reply plus the standard runInference result (txs, worker,
+     * jobId). The assistant's reply is automatically appended to history so
+     * the next send sees it.
+     */
+    async send(message) {
+        if (!message?.trim())
+            throw new Error("Conversation.send: message is empty");
+        // 1. Add the new user turn BEFORE serializing so the model sees it.
+        this.history.push({ role: "user", content: message });
+        // 2. Build the serialized prompt: system (if any) + last N turns.
+        const prompt = this.serialize();
+        // 3. Run one full encrypted inference with the conversation as prompt.
+        const result = await runInferenceWithKey({
+            ...this.opts,
+            prompt,
+        });
+        // 4. Append the assistant's reply and return.
+        this.history.push({ role: "assistant", content: result.answer });
+        return { ...result, messages: this.messages() };
+    }
+    /**
+     * Format the current history as a single text prompt the model can read.
+     * Chat-style turn markers ("User:" / "Assistant:") since the protocol's
+     * llama3-8b serving stack treats prompts as raw text and any reasonable
+     * formatting works. Uses the configured max-history-turns cap.
+     */
+    serialize() {
+        const cap = this.opts.maxHistoryTurns ?? 20;
+        // A "turn" here is one message; cap*2 messages = cap user+assistant pairs.
+        const recent = this.history.slice(Math.max(0, this.history.length - cap * 2));
+        const sys = this.opts.system?.trim();
+        const lines = [];
+        if (sys)
+            lines.push(`System: ${sys}`);
+        for (const m of recent) {
+            const tag = m.role === "user" ? "User" : m.role === "assistant" ? "Assistant" : "System";
+            lines.push(`${tag}: ${m.content}`);
+        }
+        // Trailing prompt for the model to continue from.
+        lines.push("Assistant:");
+        return lines.join("\n");
+    }
+}
+/** Functional shortcut for `new Conversation(opts)` so it reads inline. */
+export function chat(opts) {
+    return new Conversation(opts);
+}