@zerox1/sdk 0.2.0 → 0.2.1

package/LICENSE

@@ -1,32 +1,6 @@
-hidden: false
-
-description: A short and simple permissive license with conditions only requiring preservation of copyright and license notices. Licensed works, modifications, and larger works may be distributed under different terms and without source code.
-
-how: Create a text file (typically named LICENSE or LICENSE.txt) in the root of your source code and copy the text of the license into the file. Replace 2026 with the current year and 0x01-a2a with the name (or names) of the copyright holders.
-
-using:
-  Babel: https://github.com/babel/babel/blob/master/LICENSE
-  .NET: https://github.com/dotnet/runtime/blob/main/LICENSE.TXT
-  Rails: https://github.com/rails/rails/blob/master/MIT-LICENSE
-
-permissions:
-  - commercial-use
-  - modifications
-  - distribution
-  - private-use
-
-conditions:
-  - include-copyright
-
-limitations:
-  - liability
-  - warranty
-
----
-
 MIT License
 
-Copyright (c) 2026 0x01-a2a
+Copyright (c) 2026 0x01 Labs
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/index.d.ts

@@ -64,6 +64,41 @@ export interface SendFeedbackParams {
     outcome: 'negative' | 'neutral' | 'positive';
     role: 'participant' | 'notary';
 }
+export interface HostingNode {
+    node_id: string;
+    name: string;
+    fee_bps: number;
+    api_url: string;
+    hosted_count: number;
+    first_seen: number;
+    last_seen: number;
+}
+export interface HostedRegistration {
+    agent_id: string;
+    token: string;
+}
+export interface HostedAgentConfig {
+    /** Base URL of the host node, e.g. "https://host.example.com". */
+    hostApiUrl: string;
+    /** Bearer token returned by registerHosted(). */
+    token: string;
+}
+export interface OwnerProposal {
+    status: 'pending';
+    agent_id: string;
+    proposed_owner: string;
+    proposed_at: number;
+}
+export interface OwnerRecord {
+    status: 'claimed';
+    agent_id: string;
+    owner: string;
+    claimed_at: number;
+}
+export interface OwnerUnclaimed {
+    status: 'unclaimed';
+}
+export type OwnerStatus = OwnerUnclaimed | OwnerProposal | OwnerRecord;
 type Handler = (env: InboundEnvelope) => void | Promise<void>;
 export declare class Zerox1Agent {
     private proc;
@@ -79,6 +114,59 @@ export declare class Zerox1Agent {
      * the mesh. The node binary is bundled — no separate install required.
      */
     static create(config: Zerox1AgentConfig): Zerox1Agent;
+    /**
+     * Fetch active hosting nodes from the 0x01 aggregator.
+     * These are nodes that offer to relay envelopes for
+     * lightweight/serverless agents that cannot run a full node.
+     */
+    static listHostingNodes(aggregatorUrl?: string): Promise<HostingNode[]>;
+    /**
+     * Register a new hosted-agent session on a hosting node.
+     * The host generates a fresh Ed25519 sub-keypair; your
+     * agent_id is its public key. Keep the token secret.
+     *
+     * @param hostApiUrl - Base URL of the selected hosting node.
+     * @returns { agent_id, token } — persist both for reconnection.
+     */
+    static registerHosted(hostApiUrl: string): Promise<HostedRegistration>;
+    /**
+     * Create a hosted agent that delegates to an existing host node.
+     * No binary is spawned — the SDK connects to the host's WebSocket inbox
+     * and routes outbound sends through the host.
+     *
+     * @param config - { hostApiUrl, token } returned from registerHosted().
+     */
+    static createHosted(config: HostedAgentConfig): HostedAgent;
+    /**
+     * Propose a human wallet as the owner of this agent.
+     *
+     * Called by the agent or its operator. The human wallet is notified
+     * and can accept via `accept_claim()` in the agent-ownership Solana program,
+     * then call `claimOwner()` (or POST /agents/:id/claim-owner) to confirm.
+     *
+     * Optional — agents without an owner are fully functional on the mesh.
+     *
+     * @param agentId        - Hex-encoded 64-char agent ID.
+     * @param proposedOwner  - Base58 Solana wallet address of the intended human.
+     * @param aggregatorUrl  - Aggregator base URL (defaults to mainnet).
+     */
+    static proposeOwner(agentId: string, proposedOwner: string, aggregatorUrl?: string): Promise<{
+        status: string;
+        agent_id: string;
+        proposed_owner: string;
+    }>;
+    /**
+     * Read the current ownership status of an agent.
+     *
+     * Possible responses:
+     *   - `{ status: "unclaimed" }`
+     *   - `{ status: "pending",  proposed_owner: "7XsB...", proposed_at: 123 }`
+     *   - `{ status: "claimed",  owner: "7XsB...", claimed_at: 123 }`
+     *
+     * @param agentId       - Hex-encoded 64-char agent ID.
+     * @param aggregatorUrl - Aggregator base URL.
+     */
+    static getOwner(agentId: string, aggregatorUrl?: string): Promise<OwnerStatus>;
     private _config;
     /**
      * Start the node, wait for it to be ready, connect the inbox stream.
@@ -118,4 +206,46 @@ export declare class Zerox1Agent {
     encodeBidValue(value: bigint, rest?: Buffer): Buffer;
     private _connectInbox;
 }
+/**
+ * A hosted agent that delegates signing and routing to a host node.
+ * No binary is spawned. Inbound envelopes are streamed via WebSocket;
+ * outbound sends go through `POST /hosted/send` on the host.
+ *
+ * Obtain via `Zerox1Agent.createHosted({ hostApiUrl, token })`.
+ */
+export declare class HostedAgent {
+    private ws;
+    private handlers;
+    private _reconnectDelay;
+    private _running;
+    private readonly baseUrl;
+    private readonly token;
+    constructor(config: HostedAgentConfig);
+    /**
+     * Connect to the host node's inbox WebSocket.
+     * Resolves once the connection is open.
+     */
+    start(): Promise<void>;
+    /** Disconnect from the host node. */
+    disconnect(): void;
+    /**
+     * Register a handler for a message type.
+     * Use `'*'` to catch all inbound message types.
+     */
+    on(msgType: MsgType | '*', handler: Handler): this;
+    /**
+     * Send an envelope through the host node.
+     * The host signs it with this agent's sub-keypair and broadcasts via libp2p.
+     */
+    send(params: SendParams): Promise<void>;
+    /**
+     * Send a FEEDBACK envelope with CBOR-encoded payload.
+     * Mirrors `Zerox1Agent.sendFeedback()`.
+     */
+    sendFeedback(params: SendFeedbackParams): Promise<void>;
+    /** Generate a random 16-byte conversation ID as hex. */
+    newConversationId(): string;
+    private _connect;
+    private _dispatch;
+}
 export {};

package/dist/index.js

@@ -36,7 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Zerox1Agent = void 0;
+exports.HostedAgent = exports.Zerox1Agent = void 0;
 const fs = __importStar(require("fs"));
 const net = __importStar(require("net"));
 const os = __importStar(require("os"));
@@ -164,6 +164,87 @@ class Zerox1Agent {
         agent._config = config;
         return agent;
     }
+    /**
+     * Fetch active hosting nodes from the 0x01 aggregator.
+     * These are nodes that offer to relay envelopes for
+     * lightweight/serverless agents that cannot run a full node.
+     */
+    static async listHostingNodes(aggregatorUrl = 'https://api.0x01.world') {
+        const res = await fetch(`${aggregatorUrl}/hosting/nodes`);
+        if (!res.ok)
+            throw new Error(`Failed to fetch hosting nodes: HTTP ${res.status}`);
+        return res.json();
+    }
+    /**
+     * Register a new hosted-agent session on a hosting node.
+     * The host generates a fresh Ed25519 sub-keypair; your
+     * agent_id is its public key. Keep the token secret.
+     *
+     * @param hostApiUrl - Base URL of the selected hosting node.
+     * @returns { agent_id, token } — persist both for reconnection.
+     */
+    static async registerHosted(hostApiUrl) {
+        const url = hostApiUrl.replace(/\/$/, '');
+        const res = await fetch(`${url}/hosted/register`, { method: 'POST' });
+        if (!res.ok) {
+            const body = await res.text();
+            throw new Error(`registerHosted failed (${res.status}): ${body}`);
+        }
+        return res.json();
+    }
+    /**
+     * Create a hosted agent that delegates to an existing host node.
+     * No binary is spawned — the SDK connects to the host's WebSocket inbox
+     * and routes outbound sends through the host.
+     *
+     * @param config - { hostApiUrl, token } returned from registerHosted().
+     */
+    static createHosted(config) {
+        return new HostedAgent(config);
+    }
+    // ── Ownership claims ───────────────────────────────────────────────────────
+    /**
+     * Propose a human wallet as the owner of this agent.
+     *
+     * Called by the agent or its operator. The human wallet is notified
+     * and can accept via `accept_claim()` in the agent-ownership Solana program,
+     * then call `claimOwner()` (or POST /agents/:id/claim-owner) to confirm.
+     *
+     * Optional — agents without an owner are fully functional on the mesh.
+     *
+     * @param agentId        - Hex-encoded 64-char agent ID.
+     * @param proposedOwner  - Base58 Solana wallet address of the intended human.
+     * @param aggregatorUrl  - Aggregator base URL (defaults to mainnet).
+     */
+    static async proposeOwner(agentId, proposedOwner, aggregatorUrl = 'https://api.0x01.world') {
+        const res = await fetch(`${aggregatorUrl}/agents/${agentId}/propose-owner`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ proposed_owner: proposedOwner }),
+        });
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({ error: `HTTP ${res.status}` }));
+            throw new Error(`proposeOwner failed: ${err.error ?? res.status}`);
+        }
+        return res.json();
+    }
+    /**
+     * Read the current ownership status of an agent.
+     *
+     * Possible responses:
+     *   - `{ status: "unclaimed" }`
+     *   - `{ status: "pending",  proposed_owner: "7XsB...", proposed_at: 123 }`
+     *   - `{ status: "claimed",  owner: "7XsB...", claimed_at: 123 }`
+     *
+     * @param agentId       - Hex-encoded 64-char agent ID.
+     * @param aggregatorUrl - Aggregator base URL.
+     */
+    static async getOwner(agentId, aggregatorUrl = 'https://api.0x01.world') {
+        const res = await fetch(`${aggregatorUrl}/agents/${agentId}/owner`);
+        if (!res.ok)
+            throw new Error(`getOwner failed: HTTP ${res.status}`);
+        return res.json();
+    }
     // ── Lifecycle ─────────────────────────────────────────────────────────────
     /**
      * Start the node, wait for it to be ready, connect the inbox stream.
@@ -379,3 +460,153 @@ class Zerox1Agent {
     }
 }
 exports.Zerox1Agent = Zerox1Agent;
+// ============================================================================
+// HostedAgent — lightweight hosted-mode client
+// ============================================================================
+/**
+ * A hosted agent that delegates signing and routing to a host node.
+ * No binary is spawned. Inbound envelopes are streamed via WebSocket;
+ * outbound sends go through `POST /hosted/send` on the host.
+ *
+ * Obtain via `Zerox1Agent.createHosted({ hostApiUrl, token })`.
+ */
+class HostedAgent {
+    constructor(config) {
+        this.ws = null;
+        this.handlers = new Map();
+        this._reconnectDelay = 1000;
+        this._running = false;
+        this.baseUrl = config.hostApiUrl.replace(/\/$/, '');
+        this.token = config.token;
+    }
+    /**
+     * Connect to the host node's inbox WebSocket.
+     * Resolves once the connection is open.
+     */
+    async start() {
+        this._running = true;
+        await this._connect();
+    }
+    /** Disconnect from the host node. */
+    disconnect() {
+        this._running = false;
+        this.ws?.close();
+        this.ws = null;
+    }
+    /**
+     * Register a handler for a message type.
+     * Use `'*'` to catch all inbound message types.
+     */
+    on(msgType, handler) {
+        const key = msgType === '*' ? '__all__' : msgType;
+        const list = this.handlers.get(key) ?? [];
+        list.push(handler);
+        this.handlers.set(key, list);
+        return this;
+    }
+    /**
+     * Send an envelope through the host node.
+     * The host signs it with this agent's sub-keypair and broadcasts via libp2p.
+     */
+    async send(params) {
+        const res = await fetch(`${this.baseUrl}/hosted/send`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${this.token}`,
+            },
+            body: JSON.stringify({
+                msg_type: params.msgType,
+                recipient: params.recipient ?? null,
+                conversation_id: params.conversationId,
+                payload_hex: Buffer.from(params.payload).toString('hex'),
+            }),
+        });
+        if (!res.ok && res.status !== 204) {
+            const body = await res.text();
+            throw new Error(`hosted send failed (${res.status}): ${body}`);
+        }
+    }
+    /**
+     * Send a FEEDBACK envelope with CBOR-encoded payload.
+     * Mirrors `Zerox1Agent.sendFeedback()`.
+     */
+    async sendFeedback(params) {
+        if (params.score < -100 || params.score > 100)
+            throw new RangeError(`score must be in [-100, 100], got ${params.score}`);
+        const outcomeMap = { negative: 0, neutral: 1, positive: 2 };
+        const roleMap = { participant: 0, notary: 1 };
+        const payload = encodeFeedbackCbor(params.conversationId, params.targetAgent, params.score, outcomeMap[params.outcome], false, roleMap[params.role]);
+        return this.send({ msgType: 'FEEDBACK', conversationId: params.conversationId, payload });
+    }
+    /** Generate a random 16-byte conversation ID as hex. */
+    newConversationId() {
+        const bytes = new Uint8Array(16);
+        crypto.getRandomValues(bytes);
+        return Buffer.from(bytes).toString('hex');
+    }
+    // ── Internal ──────────────────────────────────────────────────────────────
+    async _connect() {
+        const wsUrl = `${this.baseUrl.replace(/^http/, 'ws')}/ws/hosted/inbox`;
+        return new Promise((resolve, reject) => {
+            const ws = new ws_1.default(wsUrl, {
+                headers: { Authorization: `Bearer ${this.token}` },
+            });
+            this.ws = ws;
+            ws.once('open', () => {
+                this._reconnectDelay = 1000;
+                resolve();
+            });
+            ws.once('error', reject);
+            ws.on('message', (data) => {
+                try {
+                    const raw = JSON.parse(data.toString());
+                    const env = {
+                        msgType: raw.msg_type,
+                        sender: raw.sender,
+                        recipient: raw.recipient,
+                        conversationId: raw.conversation_id,
+                        slot: raw.slot,
+                        nonce: raw.nonce,
+                        payloadB64: raw.payload_b64,
+                        feedback: raw.feedback ? {
+                            conversationId: raw.feedback.conversation_id,
+                            targetAgent: raw.feedback.target_agent,
+                            score: raw.feedback.score,
+                            outcome: raw.feedback.outcome,
+                            isDispute: raw.feedback.is_dispute,
+                            role: raw.feedback.role,
+                        } : undefined,
+                        notarizeBid: raw.notarize_bid ? {
+                            bidType: raw.notarize_bid.bid_type,
+                            conversationId: raw.notarize_bid.conversation_id,
+                            opaqueB64: raw.notarize_bid.opaque_b64,
+                        } : undefined,
+                    };
+                    this._dispatch(env);
+                }
+                catch { /* malformed — ignore */ }
+            });
+            ws.on('close', () => {
+                if (this._running) {
+                    setTimeout(() => {
+                        this._reconnectDelay = 1000;
+                        this._connect().catch(() => { });
+                    }, this._reconnectDelay);
+                    this._reconnectDelay = Math.min(this._reconnectDelay * 2, 30000);
+                }
+            });
+        });
+    }
+    _dispatch(env) {
+        const specific = this.handlers.get(env.msgType) ?? [];
+        const wildcard = this.handlers.get('__all__') ?? [];
+        for (const h of [...specific, ...wildcard]) {
+            try {
+                void h(env);
+            }
+            catch { /* handler errors are isolated */ }
+        }
+    }
+}
+exports.HostedAgent = HostedAgent;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerox1/sdk",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "0x01 mesh agent SDK — zero-config, binary bundled, works on every platform",
   "license": "MIT",
   "main": "dist/index.js",
@@ -13,10 +13,10 @@
     "ws": "^8.18.0"
   },
   "optionalDependencies": {
-    "@zerox1/sdk-darwin-arm64": "0.2.0",
-    "@zerox1/sdk-darwin-x64": "0.2.0",
-    "@zerox1/sdk-linux-x64": "0.2.0",
-    "@zerox1/sdk-win32-x64": "0.2.0"
+    "@zerox1/sdk-darwin-arm64": "0.2.1",
+    "@zerox1/sdk-darwin-x64": "0.2.1",
+    "@zerox1/sdk-linux-x64": "0.2.1",
+    "@zerox1/sdk-win32-x64": "0.2.1"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/packages/darwin-arm64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerox1/sdk-darwin-arm64",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "zerox1-node binary for macOS ARM64 (Apple Silicon)",
   "os": [
     "darwin"
@@ -8,6 +8,7 @@
   "cpu": [
     "arm64"
   ],
+  "license": "MIT",
   "files": [
     "bin/"
   ]

package/packages/darwin-x64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerox1/sdk-darwin-x64",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "zerox1-node binary for macOS x64 (Intel)",
   "os": [
     "darwin"
@@ -8,6 +8,7 @@
   "cpu": [
     "x64"
   ],
+  "license": "MIT",
   "files": [
     "bin/"
   ]

package/packages/linux-x64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerox1/sdk-linux-x64",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "zerox1-node binary for Linux x64",
   "os": [
     "linux"
@@ -8,6 +8,7 @@
   "cpu": [
     "x64"
   ],
+  "license": "MIT",
   "files": [
     "bin/"
   ]

package/packages/win32-x64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerox1/sdk-win32-x64",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "zerox1-node binary for Windows x64",
   "os": [
     "win32"
@@ -8,6 +8,7 @@
   "cpu": [
     "x64"
   ],
+  "license": "MIT",
   "files": [
     "bin/"
   ]

package/src/index.ts

@@ -90,6 +90,56 @@ export interface SendFeedbackParams {
   role: 'participant' | 'notary'
 }
 
+// ============================================================================
+// Hosting types
+// ============================================================================
+
+export interface HostingNode {
+  node_id: string
+  name: string
+  fee_bps: number
+  api_url: string
+  hosted_count: number
+  first_seen: number
+  last_seen: number
+}
+
+export interface HostedRegistration {
+  agent_id: string
+  token: string
+}
+
+export interface HostedAgentConfig {
+  /** Base URL of the host node, e.g. "https://host.example.com". */
+  hostApiUrl: string
+  /** Bearer token returned by registerHosted(). */
+  token: string
+}
+
+// ============================================================================
+// Ownership types
+// ============================================================================
+
+export interface OwnerProposal {
+  status: 'pending'
+  agent_id: string
+  proposed_owner: string
+  proposed_at: number
+}
+
+export interface OwnerRecord {
+  status: 'claimed'
+  agent_id: string
+  owner: string
+  claimed_at: number
+}
+
+export interface OwnerUnclaimed {
+  status: 'unclaimed'
+}
+
+export type OwnerStatus = OwnerUnclaimed | OwnerProposal | OwnerRecord
+
 // ============================================================================
 // CBOR encoding for FEEDBACK payload
 //
@@ -230,6 +280,100 @@ export class Zerox1Agent {
     return agent
   }
 
+  /**
+   * Fetch active hosting nodes from the 0x01 aggregator.
+   * These are nodes that offer to relay envelopes for
+   * lightweight/serverless agents that cannot run a full node.
+   */
+  static async listHostingNodes(
+    aggregatorUrl = 'https://api.0x01.world'
+  ): Promise<HostingNode[]> {
+    const res = await fetch(`${aggregatorUrl}/hosting/nodes`)
+    if (!res.ok) throw new Error(`Failed to fetch hosting nodes: HTTP ${res.status}`)
+    return res.json() as Promise<HostingNode[]>
+  }
+
+  /**
+   * Register a new hosted-agent session on a hosting node.
+   * The host generates a fresh Ed25519 sub-keypair; your
+   * agent_id is its public key. Keep the token secret.
+   *
+   * @param hostApiUrl - Base URL of the selected hosting node.
+   * @returns { agent_id, token } — persist both for reconnection.
+   */
+  static async registerHosted(hostApiUrl: string): Promise<HostedRegistration> {
+    const url = hostApiUrl.replace(/\/$/, '')
+    const res = await fetch(`${url}/hosted/register`, { method: 'POST' })
+    if (!res.ok) {
+      const body = await res.text()
+      throw new Error(`registerHosted failed (${res.status}): ${body}`)
+    }
+    return res.json() as Promise<HostedRegistration>
+  }
+
+  /**
+   * Create a hosted agent that delegates to an existing host node.
+   * No binary is spawned — the SDK connects to the host's WebSocket inbox
+   * and routes outbound sends through the host.
+   *
+   * @param config - { hostApiUrl, token } returned from registerHosted().
+   */
+  static createHosted(config: HostedAgentConfig): HostedAgent {
+    return new HostedAgent(config)
+  }
+
+  // ── Ownership claims ───────────────────────────────────────────────────────
+
+  /**
+   * Propose a human wallet as the owner of this agent.
+   *
+   * Called by the agent or its operator. The human wallet is notified
+   * and can accept via `accept_claim()` in the agent-ownership Solana program,
+   * then call `claimOwner()` (or POST /agents/:id/claim-owner) to confirm.
+   *
+   * Optional — agents without an owner are fully functional on the mesh.
+   *
+   * @param agentId        - Hex-encoded 64-char agent ID.
+   * @param proposedOwner  - Base58 Solana wallet address of the intended human.
+   * @param aggregatorUrl  - Aggregator base URL (defaults to mainnet).
+   */
+  static async proposeOwner(
+    agentId: string,
+    proposedOwner: string,
+    aggregatorUrl = 'https://api.0x01.world',
+  ): Promise<{ status: string; agent_id: string; proposed_owner: string }> {
+    const res = await fetch(`${aggregatorUrl}/agents/${agentId}/propose-owner`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ proposed_owner: proposedOwner }),
+    })
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({ error: `HTTP ${res.status}` }))
+      throw new Error(`proposeOwner failed: ${(err as { error?: string }).error ?? res.status}`)
+    }
+    return res.json() as Promise<{ status: string; agent_id: string; proposed_owner: string }>
+  }
+
+  /**
+   * Read the current ownership status of an agent.
+   *
+   * Possible responses:
+   *   - `{ status: "unclaimed" }`
+   *   - `{ status: "pending",  proposed_owner: "7XsB...", proposed_at: 123 }`
+   *   - `{ status: "claimed",  owner: "7XsB...", claimed_at: 123 }`
+   *
+   * @param agentId       - Hex-encoded 64-char agent ID.
+   * @param aggregatorUrl - Aggregator base URL.
+   */
+  static async getOwner(
+    agentId: string,
+    aggregatorUrl = 'https://api.0x01.world',
+  ): Promise<OwnerStatus> {
+    const res = await fetch(`${aggregatorUrl}/agents/${agentId}/owner`)
+    if (!res.ok) throw new Error(`getOwner failed: HTTP ${res.status}`)
+    return res.json() as Promise<OwnerStatus>
+  }
+
   private _config!: Zerox1AgentConfig
 
   // ── Lifecycle ─────────────────────────────────────────────────────────────
@@ -480,3 +624,175 @@ export class Zerox1Agent {
     ws.on('error', () => { /* close event handles reconnect */ })
   }
 }
+
+// ============================================================================
+// HostedAgent — lightweight hosted-mode client
+// ============================================================================
+
+/**
+ * A hosted agent that delegates signing and routing to a host node.
+ * No binary is spawned. Inbound envelopes are streamed via WebSocket;
+ * outbound sends go through `POST /hosted/send` on the host.
+ *
+ * Obtain via `Zerox1Agent.createHosted({ hostApiUrl, token })`.
+ */
+export class HostedAgent {
+  private ws: WebSocket | null = null
+  private handlers: Map<string, Handler[]> = new Map()
+  private _reconnectDelay: number = 1000
+  private _running = false
+  private readonly baseUrl: string
+  private readonly token: string
+
+  constructor(config: HostedAgentConfig) {
+    this.baseUrl = config.hostApiUrl.replace(/\/$/, '')
+    this.token = config.token
+  }
+
+  /**
+   * Connect to the host node's inbox WebSocket.
+   * Resolves once the connection is open.
+   */
+  async start(): Promise<void> {
+    this._running = true
+    await this._connect()
+  }
+
+  /** Disconnect from the host node. */
+  disconnect(): void {
+    this._running = false
+    this.ws?.close()
+    this.ws = null
+  }
+
+  /**
+   * Register a handler for a message type.
+   * Use `'*'` to catch all inbound message types.
+   */
+  on(msgType: MsgType | '*', handler: Handler): this {
+    const key = msgType === '*' ? '__all__' : msgType
+    const list = this.handlers.get(key) ?? []
+    list.push(handler)
+    this.handlers.set(key, list)
+    return this
+  }
+
+  /**
+   * Send an envelope through the host node.
+   * The host signs it with this agent's sub-keypair and broadcasts via libp2p.
+   */
+  async send(params: SendParams): Promise<void> {
+    const res = await fetch(`${this.baseUrl}/hosted/send`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.token}`,
+      },
+      body: JSON.stringify({
+        msg_type: params.msgType,
+        recipient: params.recipient ?? null,
+        conversation_id: params.conversationId,
+        payload_hex: Buffer.from(params.payload).toString('hex'),
+      }),
+    })
+    if (!res.ok && res.status !== 204) {
+      const body = await res.text()
+      throw new Error(`hosted send failed (${res.status}): ${body}`)
+    }
+  }
+
+  /**
+   * Send a FEEDBACK envelope with CBOR-encoded payload.
+   * Mirrors `Zerox1Agent.sendFeedback()`.
+   */
+  async sendFeedback(params: SendFeedbackParams): Promise<void> {
+    if (params.score < -100 || params.score > 100)
+      throw new RangeError(`score must be in [-100, 100], got ${params.score}`)
+
+    const outcomeMap = { negative: 0, neutral: 1, positive: 2 } as const
+    const roleMap = { participant: 0, notary: 1 } as const
+
+    const payload = encodeFeedbackCbor(
+      params.conversationId,
+      params.targetAgent,
+      params.score,
+      outcomeMap[params.outcome],
+      false,
+      roleMap[params.role],
+    )
+
+    return this.send({ msgType: 'FEEDBACK', conversationId: params.conversationId, payload })
+  }
+
+  /** Generate a random 16-byte conversation ID as hex. */
+  newConversationId(): string {
+    const bytes = new Uint8Array(16)
+    crypto.getRandomValues(bytes)
+    return Buffer.from(bytes).toString('hex')
+  }
+
+  // ── Internal ──────────────────────────────────────────────────────────────
+
+  private async _connect(): Promise<void> {
+    const wsUrl = `${this.baseUrl.replace(/^http/, 'ws')}/ws/hosted/inbox`
+    return new Promise((resolve, reject) => {
+      const ws = new WebSocket(wsUrl, {
+        headers: { Authorization: `Bearer ${this.token}` },
+      })
+      this.ws = ws
+
+      ws.once('open', () => {
+        this._reconnectDelay = 1000
+        resolve()
+      })
+      ws.once('error', reject)
+
+      ws.on('message', (data) => {
+        try {
+          const raw = JSON.parse(data.toString())
+          const env: InboundEnvelope = {
+            msgType: raw.msg_type,
+            sender: raw.sender,
+            recipient: raw.recipient,
+            conversationId: raw.conversation_id,
+            slot: raw.slot,
+            nonce: raw.nonce,
+            payloadB64: raw.payload_b64,
+            feedback: raw.feedback ? {
+              conversationId: raw.feedback.conversation_id,
+              targetAgent: raw.feedback.target_agent,
+              score: raw.feedback.score,
+              outcome: raw.feedback.outcome,
+              isDispute: raw.feedback.is_dispute,
+              role: raw.feedback.role,
+            } : undefined,
+            notarizeBid: raw.notarize_bid ? {
+              bidType: raw.notarize_bid.bid_type,
+              conversationId: raw.notarize_bid.conversation_id,
+              opaqueB64: raw.notarize_bid.opaque_b64,
+            } : undefined,
+          }
+          this._dispatch(env)
+        } catch { /* malformed — ignore */ }
+      })
+
+      ws.on('close', () => {
+        if (this._running) {
+          setTimeout(() => {
+            this._reconnectDelay = 1000
+            this._connect().catch(() => { })
+          }, this._reconnectDelay)
+          this._reconnectDelay = Math.min(this._reconnectDelay * 2, 30_000)
+        }
+      })
+    })
+  }
+
+  private _dispatch(env: InboundEnvelope): void {
+    const specific = this.handlers.get(env.msgType) ?? []
+    const wildcard = this.handlers.get('__all__') ?? []
+    for (const h of [...specific, ...wildcard]) {
+      try { void h(env) } catch { /* handler errors are isolated */ }
+    }
+  }
+}