@zerox1/sdk 0.1.28 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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,7 +1,8 @@
 {
   "name": "@zerox1/sdk",
-  "version": "0.1.28",
+  "version": "0.2.1",
   "description": "0x01 mesh agent SDK — zero-config, binary bundled, works on every platform",
+  "license": "MIT",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
@@ -12,10 +13,10 @@
     "ws": "^8.18.0"
   },
   "optionalDependencies": {
-    "@zerox1/sdk-darwin-arm64": "0.1.28",
-    "@zerox1/sdk-darwin-x64": "0.1.28",
-    "@zerox1/sdk-linux-x64": "0.1.28",
-    "@zerox1/sdk-win32-x64": "0.1.28"
+    "@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.1.28",
+  "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.1.28",
+  "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.1.28",
+  "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.1.28",
+  "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 */ }
+    }
+  }
+}