@aithos/sdk 0.1.0-alpha.19 → 0.1.0-alpha.20

package/dist/src/compute.d.ts

@@ -19,8 +19,13 @@ export interface InvokeBedrockArgs {
     readonly mandateId?: string;
     /**
      * Model id. Today the proxy accepts the canonical Aithos identifiers:
-     *   `claude-sonnet-4-6`, `claude-haiku-4-5`, `claude-opus-4-7`.
+     *   `claude-sonnet-4-6`, `claude-haiku-4-5`, `claude-opus-4-6`.
      * The proxy maps these to Bedrock cross-region inference profiles.
+     *
+     * NOTE: `claude-opus-4-7` is also provisioned on the Bedrock account
+     * but commercial access is gated behind an AWS Sales unlock (as of
+     * May 2026) — InvokeModel returns AccessDeniedException pointing to
+     * AWS Sales. Stick with `claude-opus-4-6` until the unlock lands.
      */
     readonly model: string;
     /** Conversation messages (user / assistant turns). */
@@ -187,6 +192,119 @@ export interface InvokeSegmentationResult {
     readonly walletBalance: number;
     readonly auditId: string;
 }
+/**
+ * Models accepted by `invokeUrlFetch`. These are the Anthropic-API-direct
+ * model aliases — the proxy resolves them to the canonical API model id
+ * (`claude-haiku-4-5-20251001`, etc.) at dispatch time.
+ *
+ * Bedrock's compute_invoke supports the same names but routes through
+ * Bedrock; url_fetch routes through `api.anthropic.com` directly because
+ * the `web_fetch` server-side tool isn't exposed via Bedrock.
+ */
+export type UrlFetchModelId = "claude-haiku-4-5" | "claude-sonnet-4-6" | "claude-opus-4-6";
+export interface InvokeUrlFetchArgs {
+    /**
+     * Mandate ID under which this call should be attributed.
+     *
+     * - **Owner sessions**: optional. The owner's own DID is used as a
+     *   sentinel "self" mandate id; the proxy skips all mandate checks
+     *   for owner-signed envelopes.
+     * - **Delegate sessions**: required. Must reference an imported
+     *   mandate bundle that carries the `compute.url_fetch` scope (NOT
+     *   the same scope as `compute.invoke` — see the protocol spec).
+     */
+    readonly mandateId?: string;
+    /**
+     * Anthropic model alias. Default `"claude-haiku-4-5"` — fastest and
+     * cheapest model that supports `web_fetch`. Bump to Sonnet 4.6 for
+     * deeper reasoning over the fetched content; Opus 4.6 for the
+     * heaviest analyses (priced accordingly via reconcile). Opus 4.7 is
+     * provisioned but commercially gated — see the docstring on
+     * InvokeBedrockArgs.model for the unlock path.
+     */
+    readonly model?: UrlFetchModelId;
+    /**
+     * User prompt — should normally contain the URL(s) the caller wants
+     * the model to fetch and analyze. Example:
+     *   "Voici l'URL https://tata.com — résume le service, identifie
+     *    le style du site et la couleur primaire. Renvoie en JSON."
+     */
+    readonly prompt: string;
+    /** Optional system prompt (Anthropic-style separate field). */
+    readonly system?: string;
+    /** Cap on output tokens. Default 2048. */
+    readonly maxTokens?: number;
+    /** Sampling temperature. Default model-dependent. */
+    readonly temperature?: number;
+    /**
+     * Maximum number of `web_fetch` invocations the model is allowed to
+     * make in this call. Default 5; range [1, 10].
+     */
+    readonly maxFetches?: number;
+    /**
+     * Maximum tokens of fetched content Anthropic will inject per fetch.
+     * Default 100_000; range [1000, 200_000]. Pages larger than this
+     * are truncated server-side.
+     */
+    readonly maxContentTokens?: number;
+    /**
+     * When `true` (default), the response carries citation spans tying
+     * generated text back to fetched documents — useful for displaying
+     * "selon X, …" footnotes in the UI without post-processing.
+     */
+    readonly citations?: boolean;
+    /**
+     * Optional domain allowlist — if set, the model can only fetch from
+     * these domains. Mutually exclusive with `blockedDomains`.
+     */
+    readonly allowedDomains?: readonly string[];
+    /**
+     * Optional domain blocklist. Mutually exclusive with `allowedDomains`.
+     */
+    readonly blockedDomains?: readonly string[];
+    /** Idempotency key for retries (generated if omitted). */
+    readonly idempotencyKey?: string;
+    /** Abort signal to cancel the request. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Single citation projection — flattened from Anthropic's wire shape so
+ * consumers can render `{cited_text}` next to `{url}` without parsing
+ * vendor-specific block types.
+ */
+export interface UrlFetchCitation {
+    readonly url: string;
+    readonly citedText: string;
+    readonly documentTitle?: string;
+    readonly startCharIndex?: number;
+    readonly endCharIndex?: number;
+}
+/** Per-fetch metadata in the order the model performed the fetches. */
+export interface UrlFetchMetadata {
+    readonly url: string;
+    readonly retrievedAt?: string;
+    readonly title?: string;
+}
+export interface InvokeUrlFetchResult {
+    /** Final assistant text — typically a JSON string when the prompt asked for structure. */
+    readonly content: string;
+    /** Citation spans (empty when `citations: false` or no fetches succeeded). */
+    readonly citations: readonly UrlFetchCitation[];
+    /** Per-URL fetch metadata. */
+    readonly urlsFetched: readonly UrlFetchMetadata[];
+    readonly stopReason: "end_turn" | "max_tokens" | "tool_use" | "stop_sequence" | "pause_turn" | "refusal";
+    readonly usage: {
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+        readonly webFetchInvocations: number;
+    };
+    /** Microcredits charged after reconcile (already net of any refund). */
+    readonly creditsCharged: number;
+    /** Wallet balance after the debit + reconcile. */
+    readonly walletBalance: number;
+    /** Audit log id for traceability. */
+    readonly auditId: string;
+}
 export interface ComputeNamespaceDeps {
     readonly auth: AithosAuth;
     readonly appDid: string;
@@ -274,5 +392,41 @@ export declare class ComputeNamespace {
      * Pricing: flat 5 000 mc per call (~$0.005 — Florence-2 is cheap).
      */
     invokeSegmentation(args: InvokeSegmentationArgs): Promise<InvokeSegmentationResult>;
+    /**
+     * Fetch one or more URLs and have Claude analyze the content. Routes
+     * through `api.anthropic.com` with the `web_fetch` server-side tool —
+     * NOT through Bedrock — because Bedrock does not expose Anthropic's
+     * server-side tools (web_fetch, web_search, etc.). The proxy hides
+     * this multi-backend detail from the SDK consumer; the wallet,
+     * envelope, and mandate-scope contracts are unchanged.
+     *
+     * Typical use:
+     * ```ts
+     * const r = await sdk.compute.invokeUrlFetch({
+     *   prompt: "Voici l'URL https://tata.com — résume le service, " +
+     *           "identifie le style et la couleur primaire. JSON.",
+     * });
+     * console.log(r.content);
+     * for (const c of r.citations) console.log(c.url, "→", c.citedText);
+     * ```
+     *
+     * Mandate scope: requires `compute.url_fetch` (distinct from
+     * `compute.invoke` — see {@link InvokeUrlFetchArgs.mandateId}).
+     *
+     * Pricing: same Claude 4.x rates as Bedrock (Anthropic's direct API
+     * and Bedrock list prices are identical). Default Haiku 4.5 ≈
+     * $0.001/1k input + $0.005/1k output. The proxy pre-debits a
+     * conservative upper bound (`maxFetches × maxContentTokens × input
+     * rate + maxTokens × output rate`) and reconciles down to the actual
+     * usage Anthropic reports — so the wallet is always charged the
+     * exact post-call cost.
+     *
+     * @throws {AithosSDKError} on protocol errors. Notable codes:
+     *   `sdk_no_signer`, `sdk_no_delegate_for_mandate`, `network`,
+     *   `http`, `empty`, plus proxy codes `-32042` (mandate scope
+     *   missing), `-32070`/`-32071` (wallet), `-32074` (fetch blocked
+     *   by robots.txt / domain filter), `-32050` (rate limit).
+     */
+    invokeUrlFetch(args: InvokeUrlFetchArgs): Promise<InvokeUrlFetchResult>;
 }
 //# sourceMappingURL=compute.d.ts.map

package/dist/src/compute.js

@@ -234,6 +234,82 @@ export class ComputeNamespace {
             signal: args.signal,
         });
     }
+    /**
+     * Fetch one or more URLs and have Claude analyze the content. Routes
+     * through `api.anthropic.com` with the `web_fetch` server-side tool —
+     * NOT through Bedrock — because Bedrock does not expose Anthropic's
+     * server-side tools (web_fetch, web_search, etc.). The proxy hides
+     * this multi-backend detail from the SDK consumer; the wallet,
+     * envelope, and mandate-scope contracts are unchanged.
+     *
+     * Typical use:
+     * ```ts
+     * const r = await sdk.compute.invokeUrlFetch({
+     *   prompt: "Voici l'URL https://tata.com — résume le service, " +
+     *           "identifie le style et la couleur primaire. JSON.",
+     * });
+     * console.log(r.content);
+     * for (const c of r.citations) console.log(c.url, "→", c.citedText);
+     * ```
+     *
+     * Mandate scope: requires `compute.url_fetch` (distinct from
+     * `compute.invoke` — see {@link InvokeUrlFetchArgs.mandateId}).
+     *
+     * Pricing: same Claude 4.x rates as Bedrock (Anthropic's direct API
+     * and Bedrock list prices are identical). Default Haiku 4.5 ≈
+     * $0.001/1k input + $0.005/1k output. The proxy pre-debits a
+     * conservative upper bound (`maxFetches × maxContentTokens × input
+     * rate + maxTokens × output rate`) and reconciles down to the actual
+     * usage Anthropic reports — so the wallet is always charged the
+     * exact post-call cost.
+     *
+     * @throws {AithosSDKError} on protocol errors. Notable codes:
+     *   `sdk_no_signer`, `sdk_no_delegate_for_mandate`, `network`,
+     *   `http`, `empty`, plus proxy codes `-32042` (mandate scope
+     *   missing), `-32070`/`-32071` (wallet), `-32074` (fetch blocked
+     *   by robots.txt / domain filter), `-32050` (rate limit).
+     */
+    async invokeUrlFetch(args) {
+        const { endpoints, fetch: fetchImpl } = this.#deps;
+        const choice = this.#resolveSigner(args.mandateId);
+        const url = computeInvokeUrl(endpoints);
+        const idempotencyKey = args.idempotencyKey ?? generateIdempotencyKey();
+        const model = args.model ?? "claude-haiku-4-5";
+        const params = {
+            app_did: this.#deps.appDid,
+            mandate_id: this.#resolveMandateIdForWire(args.mandateId, choice),
+            model,
+            prompt: args.prompt,
+            idempotency_key: idempotencyKey,
+        };
+        if (args.system !== undefined)
+            params.system = args.system;
+        if (args.maxTokens !== undefined)
+            params.max_tokens = args.maxTokens;
+        if (args.temperature !== undefined)
+            params.temperature = args.temperature;
+        if (args.maxFetches !== undefined)
+            params.max_fetches = args.maxFetches;
+        if (args.maxContentTokens !== undefined) {
+            params.max_content_tokens = args.maxContentTokens;
+        }
+        if (args.citations !== undefined)
+            params.citations = args.citations;
+        if (args.allowedDomains !== undefined && args.allowedDomains.length > 0) {
+            params.allowed_domains = args.allowedDomains;
+        }
+        if (args.blockedDomains !== undefined && args.blockedDomains.length > 0) {
+            params.blocked_domains = args.blockedDomains;
+        }
+        return await this.#signAndPost({
+            url,
+            method: "aithos.compute_invoke_url_fetch",
+            params,
+            choice,
+            fetchImpl,
+            signal: args.signal,
+        });
+    }
     /**
      * Resolve the active signer (owner takes precedence over delegate).
      *

package/dist/src/index.d.ts

@@ -5,7 +5,7 @@ export { AithosSDKError } from "./types.js";
 export { AithosRpcError } from "@aithos/protocol-client";
 export type { AithosSdkEndpoints } from "./endpoints.js";
 export { DEFAULT_SDK_ENDPOINTS } from "./endpoints.js";
-export type { ComputeMessage, ImageAspectRatio, ImageModelId, InvokeBedrockArgs, InvokeBedrockResult, InvokeBedrockVisionArgs, InvokeBedrockVisionResult, InvokeImageArgs, InvokeImageImage, InvokeImageResult, InvokeSegmentationArgs, InvokeSegmentationResult, SegmentPolygon, StopReason, } from "./compute.js";
+export type { ComputeMessage, ImageAspectRatio, ImageModelId, InvokeBedrockArgs, InvokeBedrockResult, InvokeBedrockVisionArgs, InvokeBedrockVisionResult, InvokeImageArgs, InvokeImageImage, InvokeImageResult, InvokeSegmentationArgs, InvokeSegmentationResult, InvokeUrlFetchArgs, InvokeUrlFetchResult, SegmentPolygon, StopReason, UrlFetchCitation, UrlFetchMetadata, UrlFetchModelId, } from "./compute.js";
 export { ComputeNamespace } from "./compute.js";
 export type { CreditPackId, CreateTopupSessionArgs, CreateTopupSessionResult, GetBalanceArgs, GetBalanceResult, } from "./wallet.js";
 export { WalletNamespace } from "./wallet.js";

package/dist/test/compute.test.js

@@ -187,4 +187,166 @@ describe("compute.invokeBedrock — abort", () => {
         assert.equal(receivedSignal, ac.signal);
     });
 });
+/* -------------------------------------------------------------------------- */
+/*  invokeUrlFetch                                                            */
+/* -------------------------------------------------------------------------- */
+const URL_FETCH_HAPPY_RESULT = {
+    content: "Tata.com propose un service Y avec une couleur primaire bleu (#1E40AF).",
+    citations: [
+        {
+            url: "https://tata.com",
+            citedText: "Notre service révolutionne...",
+            documentTitle: "Tata — Home",
+            startCharIndex: 0,
+            endCharIndex: 28,
+        },
+    ],
+    urlsFetched: [
+        {
+            url: "https://tata.com",
+            retrievedAt: "2026-05-12T10:00:00Z",
+            title: "Tata — Home",
+        },
+    ],
+    stopReason: "end_turn",
+    usage: { inputTokens: 28_500, outputTokens: 420, webFetchInvocations: 1 },
+    creditsCharged: 35,
+    walletBalance: 99_965,
+    auditId: "audit-url-1",
+};
+describe("compute.invokeUrlFetch — happy path", () => {
+    it("posts to ${compute}/v1/invoke with method=aithos.compute_invoke_url_fetch", async () => {
+        let capturedUrl;
+        let capturedInit;
+        const fakeFetch = async (input, init) => {
+            capturedUrl = typeof input === "string" ? input : input.toString();
+            capturedInit = init;
+            return new Response(JSON.stringify({ result: URL_FETCH_HAPPY_RESULT }), {
+                status: 200,
+                headers: { "content-type": "application/json" },
+            });
+        };
+        const sdk = await makeSdk(fakeFetch);
+        const out = await sdk.compute.invokeUrlFetch({
+            mandateId: "mandate:abc",
+            prompt: "Voici l'URL https://tata.com — résume.",
+        });
+        assert.deepEqual(out, URL_FETCH_HAPPY_RESULT);
+        assert.equal(capturedUrl, "https://compute.example.test/v1/invoke");
+        const body = JSON.parse(capturedInit?.body);
+        assert.equal(body.jsonrpc, "2.0");
+        assert.equal(body.method, "aithos.compute_invoke_url_fetch");
+        assert.equal(body.params.app_did, APP_DID);
+        assert.equal(body.params.mandate_id, "mandate:abc");
+        // Default model is Haiku 4.5 (cheapest model that supports web_fetch).
+        assert.equal(body.params.model, "claude-haiku-4-5");
+        assert.equal(body.params.prompt, "Voici l'URL https://tata.com — résume.");
+        // Auto-generated idempotency key.
+        assert.match(body.params.idempotency_key, /^[0-9a-f]{32}$/);
+        // Envelope is present on the wire.
+        assert.ok(body.params._envelope, "request must carry a signed envelope");
+        // Optional params NOT forwarded when not provided.
+        assert.equal(body.params.system, undefined);
+        assert.equal(body.params.max_fetches, undefined);
+        assert.equal(body.params.max_content_tokens, undefined);
+        assert.equal(body.params.citations, undefined);
+        assert.equal(body.params.allowed_domains, undefined);
+        assert.equal(body.params.blocked_domains, undefined);
+    });
+    it("forwards all optional knobs: system / maxTokens / maxFetches / maxContentTokens / citations / allowedDomains / idempotencyKey / model", async () => {
+        let capturedBody;
+        const fakeFetch = async (_input, init) => {
+            capturedBody = JSON.parse(init?.body).params;
+            return new Response(JSON.stringify({ result: URL_FETCH_HAPPY_RESULT }), {
+                status: 200,
+                headers: { "content-type": "application/json" },
+            });
+        };
+        const sdk = await makeSdk(fakeFetch);
+        await sdk.compute.invokeUrlFetch({
+            mandateId: "mandate:abc",
+            model: "claude-sonnet-4-6",
+            prompt: "Analyse https://tata.com",
+            system: "You are a brand analyst.",
+            maxTokens: 1024,
+            temperature: 0.1,
+            maxFetches: 3,
+            maxContentTokens: 50_000,
+            citations: false,
+            allowedDomains: ["tata.com", "*.tata.com"],
+            idempotencyKey: "idem-url-1",
+        });
+        assert.equal(capturedBody?.model, "claude-sonnet-4-6");
+        assert.equal(capturedBody?.system, "You are a brand analyst.");
+        assert.equal(capturedBody?.max_tokens, 1024);
+        assert.equal(capturedBody?.temperature, 0.1);
+        assert.equal(capturedBody?.max_fetches, 3);
+        assert.equal(capturedBody?.max_content_tokens, 50_000);
+        assert.equal(capturedBody?.citations, false);
+        assert.deepEqual(capturedBody?.allowed_domains, ["tata.com", "*.tata.com"]);
+        assert.equal(capturedBody?.idempotency_key, "idem-url-1");
+        // Empty / undefined arrays must NOT bleed through as `[]` on the wire.
+        assert.equal(capturedBody?.blocked_domains, undefined);
+    });
+    it("omits empty allowedDomains / blockedDomains arrays from the wire payload", async () => {
+        let capturedBody;
+        const fakeFetch = async (_input, init) => {
+            capturedBody = JSON.parse(init?.body).params;
+            return new Response(JSON.stringify({ result: URL_FETCH_HAPPY_RESULT }), {
+                status: 200,
+                headers: { "content-type": "application/json" },
+            });
+        };
+        const sdk = await makeSdk(fakeFetch);
+        await sdk.compute.invokeUrlFetch({
+            mandateId: "mandate:abc",
+            prompt: "Analyse https://tata.com",
+            allowedDomains: [],
+            blockedDomains: [],
+        });
+        assert.equal(capturedBody?.allowed_domains, undefined);
+        assert.equal(capturedBody?.blocked_domains, undefined);
+    });
+});
+describe("compute.invokeUrlFetch — errors", () => {
+    it("wraps a JSON-RPC error from the proxy as AithosSDKError with the proxy code", async () => {
+        const fakeFetch = async () => new Response(JSON.stringify({
+            error: {
+                code: -32074,
+                message: "web_fetch failed: robots.txt disallows /api/* — fetch refused",
+                data: { detail: "robots_blocked" },
+            },
+        }), { status: 200, headers: { "content-type": "application/json" } });
+        const sdk = await makeSdk(fakeFetch);
+        await assert.rejects(sdk.compute.invokeUrlFetch({
+            mandateId: "mandate:abc",
+            prompt: "Analyse https://tata.com/api/secret",
+        }), (err) => {
+            assert.ok(err instanceof AithosSDKError);
+            assert.equal(err.code, "-32074");
+            assert.match(err.message, /robots\.txt/);
+            return true;
+        });
+    });
+});
+describe("compute.invokeUrlFetch — abort", () => {
+    it("propagates an AbortSignal to fetch", async () => {
+        let receivedSignal;
+        const fakeFetch = async (_input, init) => {
+            receivedSignal = init?.signal;
+            return new Response(JSON.stringify({ result: URL_FETCH_HAPPY_RESULT }), {
+                status: 200,
+                headers: { "content-type": "application/json" },
+            });
+        };
+        const sdk = await makeSdk(fakeFetch);
+        const ac = new AbortController();
+        await sdk.compute.invokeUrlFetch({
+            mandateId: "mandate:abc",
+            prompt: "Analyse https://tata.com",
+            signal: ac.signal,
+        });
+        assert.equal(receivedSignal, ac.signal);
+    });
+});
 //# sourceMappingURL=compute.test.js.map

package/dist/test/signup-bootstrap.test.d.ts

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

package/dist/test/signup-bootstrap.test.js

@@ -0,0 +1,222 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+// Tests for the Ethos bootstrap step inside AithosAuth.signUp().
+//
+// The contract:
+//   1. POST /auth/register → creates the auth user (auth.aithos.be).
+//   2. POST /mcp/primitives/write with method=aithos.publish_identity →
+//      provisions the user's Ethos on api.aithos.be.
+//   3. Hydrate local state ONLY after both steps succeed.
+//
+// Failure modes:
+//   - register fails  → throw, no publish_identity attempted, no hydrate.
+//   - publish_identity rejected (JSON-RPC error) → throw immediately,
+//     no retry, no hydrate.
+//   - publish_identity 5xx / network error → 2 retries with backoff,
+//     then throw `ethos_bootstrap_failed` if all fail.
+//
+// We mock fetch end-to-end so the tests run offline. The protocol-client
+// crypto runs for real — we want to assert that the envelope shape coming
+// out of the SDK matches what api.aithos.be will accept.
+import { strict as assert } from "node:assert";
+import { describe, it } from "node:test";
+import { AithosAuth, AithosSDKError, memoryKeyStore, noopStore, } from "../src/index.js";
+function makeMockFetch(handlers) {
+    const calls = [];
+    const fetchImpl = (async (input, init) => {
+        const url = String(input);
+        const method = init?.method ?? "GET";
+        const bodyText = typeof init?.body === "string"
+            ? init.body
+            : init?.body == null
+                ? null
+                : String(init.body);
+        const body = bodyText ? JSON.parse(bodyText) : null;
+        const call = { url, method, body };
+        calls.push(call);
+        for (const h of handlers) {
+            if (!url.includes(h.url))
+                continue;
+            if (h.method && h.method !== method)
+                continue;
+            if (h.remaining !== undefined && h.remaining <= 0)
+                continue;
+            if (h.remaining !== undefined)
+                h.remaining--;
+            const out = await h.respond(call);
+            const status = out.status ?? 200;
+            return new Response(JSON.stringify(out.json), {
+                status,
+                headers: { "content-type": "application/json" },
+            });
+        }
+        throw new Error(`unhandled fetch: ${method} ${url}`);
+    });
+    return { fetch: fetchImpl, calls };
+}
+function fakeRegisterOk() {
+    return {
+        json: {
+            session: "jwt-token-here",
+            exp: Math.floor(Date.now() / 1000) + 3600,
+        },
+    };
+}
+function fakePublishIdentityOk() {
+    return {
+        json: {
+            jsonrpc: "2.0",
+            id: "publish_identity",
+            result: { ok: true, did_document_url: "https://cdn.aithos.be/ethos/zABC/did.json" },
+        },
+    };
+}
+function makeAuth(fetchImpl) {
+    return new AithosAuth({
+        authBaseUrl: "https://auth.test",
+        apiBaseUrl: "https://api.test",
+        fetch: fetchImpl,
+        sessionStore: noopStore(),
+        keyStore: memoryKeyStore(),
+    });
+}
+const validInput = {
+    email: "alice@test.example",
+    password: "correct horse battery staple",
+    handle: "alice",
+};
+/* -------------------------------------------------------------------------- */
+/*  Happy path                                                                */
+/* -------------------------------------------------------------------------- */
+describe("AithosAuth.signUp — Ethos bootstrap", () => {
+    it("calls /auth/register THEN /mcp/primitives/write with publish_identity", async () => {
+        const { fetch: f, calls } = makeMockFetch([
+            { url: "/auth/register", method: "POST", respond: fakeRegisterOk },
+            {
+                url: "/mcp/primitives/write",
+                method: "POST",
+                respond: fakePublishIdentityOk,
+            },
+        ]);
+        const auth = makeAuth(f);
+        const r = await auth.signUp(validInput);
+        assert.equal(calls.length, 2, "should make exactly 2 calls");
+        assert.match(calls[0].url, /\/auth\/register$/);
+        assert.match(calls[1].url, /\/mcp\/primitives\/write$/);
+        assert.ok(r.session.session === "jwt-token-here");
+        assert.ok(auth.canSignAsOwner(), "must be hydrated as owner");
+    });
+    it("envelope is JSON-RPC publish_identity, signed by #root, with valid params", async () => {
+        let publishBody = null;
+        const { fetch: f } = makeMockFetch([
+            { url: "/auth/register", method: "POST", respond: fakeRegisterOk },
+            {
+                url: "/mcp/primitives/write",
+                method: "POST",
+                respond: (call) => {
+                    publishBody = call.body;
+                    return fakePublishIdentityOk();
+                },
+            },
+        ]);
+        await makeAuth(f).signUp(validInput);
+        // JSON-RPC envelope shape
+        assert.equal(publishBody.jsonrpc, "2.0");
+        assert.equal(publishBody.method, "aithos.publish_identity");
+        // params include the inline _envelope and the publish_identity payload
+        const params = publishBody.params;
+        assert.equal(typeof params.handle, "string");
+        assert.equal(params.handle, "alice");
+        assert.equal(typeof params.display_name, "string");
+        assert.ok(params.did_document, "did_document must be present");
+        assert.ok(params._envelope, "_envelope must be present");
+        // envelope is signed by #root
+        const env = params._envelope;
+        assert.equal(env["aithos-envelope"], "0.1.0");
+        assert.match(env.iss, /^did:aithos:/);
+        assert.equal(env.method, "aithos.publish_identity");
+        assert.equal(env.aud, "https://api.test/mcp/primitives/write");
+        assert.equal(env.proof.type, "Ed25519Signature2020");
+        assert.match(env.proof.verificationMethod, /#root$/);
+        assert.equal(typeof env.proof.proofValue, "string");
+        assert.ok(env.proof.proofValue.length > 0);
+    });
+    it("does NOT hydrate state when /auth/register fails", async () => {
+        const { fetch: f, calls } = makeMockFetch([
+            {
+                url: "/auth/register",
+                method: "POST",
+                respond: () => ({
+                    status: 409,
+                    json: { error: "email_taken" },
+                }),
+            },
+        ]);
+        const auth = makeAuth(f);
+        await assert.rejects(() => auth.signUp(validInput), AithosSDKError);
+        assert.equal(calls.length, 1, "publish_identity must NOT be called");
+        assert.equal(auth.canSignAsOwner(), false);
+    });
+    it("does NOT hydrate state when publish_identity returns a JSON-RPC error", async () => {
+        const { fetch: f, calls } = makeMockFetch([
+            { url: "/auth/register", method: "POST", respond: fakeRegisterOk },
+            {
+                url: "/mcp/primitives/write",
+                method: "POST",
+                respond: () => ({
+                    json: {
+                        jsonrpc: "2.0",
+                        id: "publish_identity",
+                        error: { code: -32600, message: "invalid envelope signature" },
+                    },
+                }),
+            },
+        ]);
+        const auth = makeAuth(f);
+        await assert.rejects(() => auth.signUp(validInput), (e) => e instanceof AithosSDKError && e.code === "ethos_bootstrap_failed");
+        // No retry on JSON-RPC error: 1 register + 1 publish.
+        assert.equal(calls.length, 2);
+        assert.equal(auth.canSignAsOwner(), false);
+    });
+    it("retries publish_identity on 5xx, then succeeds", async () => {
+        let publishCalls = 0;
+        const { fetch: f } = makeMockFetch([
+            { url: "/auth/register", method: "POST", respond: fakeRegisterOk },
+            {
+                url: "/mcp/primitives/write",
+                method: "POST",
+                respond: () => {
+                    publishCalls++;
+                    if (publishCalls < 2) {
+                        return { status: 503, json: { error: "transient" } };
+                    }
+                    return fakePublishIdentityOk();
+                },
+            },
+        ]);
+        const auth = makeAuth(f);
+        await auth.signUp(validInput);
+        assert.equal(publishCalls, 2);
+        assert.ok(auth.canSignAsOwner());
+    });
+    it("throws ethos_bootstrap_failed after all retries fail with 5xx", async () => {
+        let publishCalls = 0;
+        const { fetch: f } = makeMockFetch([
+            { url: "/auth/register", method: "POST", respond: fakeRegisterOk },
+            {
+                url: "/mcp/primitives/write",
+                method: "POST",
+                respond: () => {
+                    publishCalls++;
+                    return { status: 503, json: { error: "transient" } };
+                },
+            },
+        ]);
+        const auth = makeAuth(f);
+        await assert.rejects(() => auth.signUp(validInput), (e) => e instanceof AithosSDKError && e.code === "ethos_bootstrap_failed");
+        // 3 attempts total (initial + 2 retries).
+        assert.equal(publishCalls, 3);
+        assert.equal(auth.canSignAsOwner(), false);
+    });
+});
+//# sourceMappingURL=signup-bootstrap.test.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aithos/sdk",
-  "version": "0.1.0-alpha.19",
+  "version": "0.1.0-alpha.20",
   "description": "Aithos SDK — high-level TypeScript developer kit for building agentic apps on the Aithos protocol. Wraps @aithos/protocol-client and exposes the Aithos compute proxy and wallet (Stripe top-up) endpoints.",
   "keywords": [
     "aithos",
@@ -39,6 +39,15 @@
     "README.md",
     "LICENSE"
   ],
+  "scripts": {
+    "build": "tsc",
+    "build:test": "tsc -p tsconfig.test.json",
+    "check-types": "tsc --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "test": "npm run clean && npm run build && npm run build:test && cd dist && node --test",
+    "test:watch": "cd dist && node --test --watch",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build && npm test"
+  },
   "engines": {
     "node": ">=20"
   },
@@ -54,13 +63,5 @@
   "publishConfig": {
     "access": "public",
     "tag": "alpha"
-  },
-  "scripts": {
-    "build": "tsc",
-    "build:test": "tsc -p tsconfig.test.json",
-    "check-types": "tsc --noEmit && tsc -p tsconfig.test.json --noEmit",
-    "test": "npm run clean && npm run build && npm run build:test && cd dist && node --test",
-    "test:watch": "cd dist && node --test --watch",
-    "clean": "rm -rf dist"
   }
-}
+}