@caltra/backend-sdk 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,68 @@
-# Temporary Holding Version
+# Caltra backend SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Define tools in your TypeScript backend and serve them to Caltra through an outbound authenticated WebSocket. Handler code and application data remain on your backend. The public client is `CaltraBackendClient`.
+
+## Install
+
+Requires Node.js 24 or newer. This package is ESM.
+
+```sh
+mkdir caltra-backend && cd caltra-backend
+npm init -y
+npm pkg set type=module
+npm install @caltra/backend-sdk zod
+npm install --save-dev typescript tsx @types/node
+cp node_modules/@caltra/backend-sdk/examples/quickstart.ts quickstart.ts
+```
+
+In Caltra, open **Backends → Add backend**. Restrict its workspace availability, then save the backend ID and one-time credential. All replicas share those credentials.
+
+Create `backend.config.json` using your backend ID and credential:
+
+```json
+{
+  "url": "wss://api.caltra.dev/backends/v1/connect",
+  "backendId": "REPLACE_WITH_BACKEND_UUID",
+  "credential": "REPLACE_WITH_BACKEND_CREDENTIAL",
+  "label": "example-replica-1"
+}
+```
+
+Keep the credential in your secret manager, restrict permissions on the configuration file, and exclude it from source control. The executable [quickstart](examples/quickstart.ts) validates this configuration before connecting. It defines a harmless `diagnostics.echo` tool returning a message, trusted workspace ID, and replica label.
+
+```sh
+chmod 600 backend.config.json
+npx tsc --noEmit --strict --target ES2022 --module NodeNext --moduleResolution NodeNext quickstart.ts
+# Publish once when deploying new definitions.
+npx tsx quickstart.ts publish backend.config.json
+# Start each replica separately; Ctrl-C closes its connection.
+npx tsx quickstart.ts serve backend.config.json
+```
+
+In **Backends → Tools**, call `diagnostics.echo` with `{"message":"hello"}` in an allowed workspace. Expect the same message, that workspace's ID, and `example-replica-1`. For a hosted agent, grant the tool to its execution principal under **Access**, then ask the agent to discover and call it. Revoke the grant to deny subsequent calls, including an already discovered action ID.
+
+## API
+
+```ts
+import { BackendTool, CaltraBackendClient, type ToolContext } from "@caltra/backend-sdk";
+```
+
+- `BackendTool` takes a name, description, Zod input/output schemas, and `handler(context, inputs)`. Use JSON-Schema-compatible Zod schemas. Input and output validation happens locally and on Caltra.
+- `new CaltraBackendClient({ url, backendId, credential, label, tools, maxConcurrency? })` creates a client. Default concurrency is 1; supported values are 1–100.
+- `publish()` explicitly publishes definitions and returns `{ id, version, hash }`. It opens and closes its own connection. Identical current definitions reuse the version.
+- `connect()` registers one replica against matching, already-published definitions. It returns `{ instanceId, manifest, heartbeatMs }` and starts transport heartbeats.
+- `waitForDisconnect()` waits for that serving connection to close. The SDK does not reconnect automatically.
+- `close()` closes the serving connection and waits for disconnect.
+
+The URL must use `wss://`; `ws://` is allowed only for loopback development. Credentials belong in authentication headers, never the URL. A proxy must support WebSocket upgrades and long-lived connections.
+
+`ToolContext` carries trusted organization, workspace, environment, principal, invocation ID and deadline. Hosted calls also include principal, session, turn and agent IDs. Tool inputs cannot replace these fields. Enforce your application's business permissions using the trusted context.
+
+
+Protocol 2 always supplies `workspaceExternalId: string | null` from the authorized workspace row and `tenantUserExternalId: string | null` from the execution principal's tenant-user row. Values are exact stored IDs, including any workspace namespace prefix; Caltra does not strip or guess them. A null means that the row has no external ID, or, for the user field, that the execution is not a tenant user. Agent-identity, system and platform-user playground calls always receive a null user external ID, even when the session has a user owner or initiator. Hosted `principalId` and `principal.id` remain the Caltra tenant-principal UUID, not the tenant-user UUID or external ID. Use the environment and workspace context together with external IDs when selecting application data.
+
+Upgrade all Caltra API nodes before starting clients from this SDK revision. The client explicitly registers `protocolVersion: 2` on the existing `/backends/v1/connect` URL; older servers reject registration and there is no silent fallback. Updated servers still accept SDK 0.1.0 / protocol 1 replicas and omit both external-ID fields entirely for them, including calls routed across API nodes. Redis forwarding preserves the legacy call shape and carries the new identity fields separately, so older API socket owners continue serving legacy clients during the server rollout. Protocol 2 requires both fields, so incomplete context from an older API node fails before handler execution during a mixed-server rollout. Protocol versions are independent of manifest versions. Publication of this SDK revision and deployment of Caltra are separate release steps.
+
+Caltra routes each call to one available matching-manifest replica and rechecks current access at dispatch. There is no cancellation API or automatic execution retry. A timeout/disconnect can leave the outcome unknown; your handler may continue. Deduplicate business writes using your own operation key before retrying. A newer manifest can temporarily make older replicas unavailable; publish deliberately and start matching replicas.
+
+See the [backend tools documentation](https://caltra.dev/docs/backend-tools) for grants, version rollout, context, limits and wire protocol. The `/protocol` and `/peer` exports support protocol integrations; ordinary applications need only the package root.

package/dist/client.d.ts

@@ -0,0 +1,28 @@
+import { type ManifestVersion, type Registration } from "./protocol.js";
+import type { ToolRegistration } from "./tool.js";
+/** Publishes definitions explicitly and serves one replica on an outbound, authenticated socket. */
+export declare class CaltraBackendClient {
+    private readonly options;
+    private peer?;
+    private registration?;
+    private heartbeat?;
+    private readonly calls;
+    private readonly seen;
+    private closed;
+    private readonly manifest;
+    constructor(options: {
+        url: string;
+        backendId: string;
+        credential: string;
+        tools: ToolRegistration[];
+        label: string;
+        maxConcurrency?: number;
+    });
+    publish(): Promise<ManifestVersion>;
+    connect(): Promise<Registration>;
+    waitForDisconnect(): Promise<void>;
+    close(): Promise<void>;
+    private open;
+    private scheduleHeartbeat;
+    private invoke;
+}

package/dist/client.js

@@ -0,0 +1,105 @@
+import { WebSocket } from "ws";
+import { JSONRPCErrorException } from "json-rpc-2.0";
+import { z } from "zod";
+import { BackendProtocol, CallSchema, ManifestVersionSchema, RegistrationSchema } from "./protocol.js";
+import { BackendRpcPeer } from "./peer.js";
+/** Publishes definitions explicitly and serves one replica on an outbound, authenticated socket. */
+export class CaltraBackendClient {
+    options;
+    peer;
+    registration;
+    heartbeat;
+    calls = new Set();
+    seen = new Set();
+    closed = Promise.resolve();
+    manifest;
+    constructor(options) {
+        this.options = options;
+        const url = new URL(options.url);
+        if (url.protocol !== "wss:" && !(url.protocol === "ws:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)))
+            throw new Error("Use wss:// (ws:// is allowed only on loopback).");
+        if (url.username || url.password || url.search || url.hash)
+            throw new Error("Connection URL must not contain credentials, query parameters or fragments.");
+        z.string().uuid().parse(options.backendId);
+        this.manifest = options.tools.map(tool => tool.manifest);
+        BackendProtocol.hash(this.manifest);
+    }
+    async publish() {
+        const peer = await this.open();
+        try {
+            return ManifestVersionSchema.parse(await peer.request("manifests/publish", { tools: this.manifest }));
+        }
+        finally {
+            peer.close();
+        }
+    }
+    async connect() {
+        if (this.peer)
+            throw new Error("This client is already connected.");
+        const peer = await this.open();
+        this.peer = peer;
+        this.closed = new Promise(resolve => peer.socket.once("close", () => {
+            if (this.peer === peer) {
+                this.peer = undefined;
+                this.registration = undefined;
+            }
+            clearTimeout(this.heartbeat);
+            resolve();
+        }));
+        peer.method("tools/call", params => this.invoke(params));
+        try {
+            this.registration = RegistrationSchema.parse(await peer.request("instances/register", {
+                protocolVersion: 2, manifestHash: BackendProtocol.hash(this.manifest), label: this.options.label, maxConcurrency: this.options.maxConcurrency ?? 1,
+            }));
+            this.scheduleHeartbeat(peer);
+            return this.registration;
+        }
+        catch (error) {
+            peer.close();
+            throw error;
+        }
+    }
+    waitForDisconnect() { return this.closed; }
+    async close() { clearTimeout(this.heartbeat); this.peer?.close(); await this.closed; }
+    async open() {
+        const socket = new WebSocket(this.options.url, { headers: { authorization: `Bearer ${this.options.credential}`, "x-caltra-backend-id": this.options.backendId }, maxPayload: BackendProtocol.maxBytes, handshakeTimeout: 10000, followRedirects: false });
+        const peer = new BackendRpcPeer(socket);
+        await new Promise((resolve, reject) => { socket.once("open", resolve); socket.once("error", () => reject(new Error("Backend connection failed; check URL and credential."))); });
+        return peer;
+    }
+    scheduleHeartbeat(peer) {
+        // This timer observes a live transport; PostgreSQL lease expiry remains authoritative after a crash.
+        this.heartbeat = setTimeout(() => {
+            void peer.request("instances/heartbeat", {}, 5000).then(() => {
+                if (this.peer === peer && peer.socket.readyState === WebSocket.OPEN)
+                    this.scheduleHeartbeat(peer);
+            }).catch(() => peer.close());
+        }, this.registration.heartbeatMs);
+    }
+    async invoke(params) {
+        const call = CallSchema.parse(params);
+        if (!this.registration || call.manifestVersion !== this.registration.manifest.version)
+            throw new JSONRPCErrorException("Manifest mismatch.", -32001);
+        const tool = this.options.tools.find(tool => tool.manifest.name === call.name);
+        if (!tool)
+            throw new JSONRPCErrorException("Tool not found.", -32601);
+        if (this.seen.has(call.invocationId))
+            throw new JSONRPCErrorException("Duplicate invocation.", -32002);
+        if (this.calls.size >= (this.options.maxConcurrency ?? 1))
+            throw new JSONRPCErrorException("Instance is busy.", -32003);
+        const remaining = Date.parse(call.deadline) - Date.now();
+        if (remaining <= 0)
+            throw new JSONRPCErrorException("Deadline expired.", -32004);
+        this.seen.add(call.invocationId);
+        if (this.seen.size > 10000)
+            this.seen.delete(this.seen.values().next().value);
+        this.calls.add(call.invocationId);
+        // A disconnected or timed-out call can still be running; retain its capacity until the handler finishes.
+        try {
+            return await tool.invoke({ ...call.context, invocationId: call.invocationId, deadline: new Date(call.deadline) }, call.inputs);
+        }
+        finally {
+            this.calls.delete(call.invocationId);
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { CaltraBackendClient } from "./client.js";
+export { BackendTool } from "./tool.js";
+export type { ToolRegistration } from "./tool.js";
+export type { ToolContext, ManifestVersion, Registration } from "./protocol.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { CaltraBackendClient } from "./client.js";
+export { BackendTool } from "./tool.js";

package/dist/peer.d.ts

@@ -0,0 +1,14 @@
+import { WebSocket } from "ws";
+/** Binds the JSON-RPC library to bounded text frames and rejects pending requests on disconnect. */
+export declare class BackendRpcPeer {
+    readonly socket: WebSocket;
+    private readonly server;
+    private readonly client;
+    private readonly peer;
+    private inFlight;
+    constructor(socket: WebSocket);
+    method(name: string, handler: (params: unknown) => Promise<unknown>): void;
+    request(method: string, params: unknown, timeoutMs?: number): Promise<unknown>;
+    close(): void;
+    private send;
+}

package/dist/peer.js

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { randomUUID } from "node:crypto";
+import { JSONRPCClient, JSONRPCServer, JSONRPCServerAndClient, JSONRPCErrorException, createJSONRPCErrorResponse } from "json-rpc-2.0";
+import { WebSocket } from "ws";
+import { BackendProtocol } from "./protocol.js";
+/** Binds the JSON-RPC library to bounded text frames and rejects pending requests on disconnect. */
+export class BackendRpcPeer {
+    socket;
+    server = new JSONRPCServer({ errorListener: () => undefined });
+    client;
+    peer;
+    inFlight = 0;
+    constructor(socket) {
+        this.socket = socket;
+        this.client = new JSONRPCClient(async (request) => this.send(request), () => randomUUID());
+        this.peer = new JSONRPCServerAndClient(this.server, this.client, { errorListener: () => undefined });
+        socket.on("message", (data, binary) => {
+            if (binary || Buffer.byteLength(data.toString()) > BackendProtocol.maxBytes || this.inFlight >= 128) {
+                socket.close(1008, "Invalid frame or too many requests");
+                return;
+            }
+            let payload;
+            try {
+                payload = JSON.parse(data.toString());
+            }
+            catch {
+                void this.send(createJSONRPCErrorResponse(null, -32700, "Parse error")).catch(() => socket.terminate());
+                return;
+            }
+            if (Array.isArray(payload)) {
+                void this.send(createJSONRPCErrorResponse(null, -32600, "Batch requests are not supported.")).catch(() => socket.terminate());
+                return;
+            }
+            this.inFlight++;
+            void this.peer.receiveAndSend(payload).catch(() => socket.close(1008, "Invalid RPC message")).finally(() => this.inFlight--);
+        });
+        socket.on("error", () => this.client.rejectAllPendingRequests("Backend disconnected; invocation outcome may be unknown."));
+        socket.on("close", () => this.client.rejectAllPendingRequests("Backend disconnected; invocation outcome may be unknown."));
+    }
+    method(name, handler) {
+        this.server.addMethod(name, async (params) => {
+            try {
+                return await handler(params);
+            }
+            catch (error) {
+                if (error instanceof JSONRPCErrorException)
+                    throw error;
+                if (error instanceof z.ZodError)
+                    throw new JSONRPCErrorException("Invalid parameters or tool data.", -32602);
+                throw new JSONRPCErrorException("Request could not be completed.", -32000);
+            }
+        });
+    }
+    async request(method, params, timeoutMs = BackendProtocol.callTimeoutMs) {
+        return this.client.timeout(timeoutMs, id => createJSONRPCErrorResponse(id, -32015, "Backend RPC timed out; invocation outcome may be unknown. Do not automatically retry.")).request(method, params);
+    }
+    close() { this.socket.close(1000, "Closed"); }
+    async send(value) {
+        const data = JSON.stringify(value);
+        if (this.socket.readyState !== WebSocket.OPEN)
+            throw new Error("Backend connection is closed.");
+        if (Buffer.byteLength(data) > BackendProtocol.maxBytes || this.socket.bufferedAmount > BackendProtocol.maxBytes)
+            throw new Error("RPC payload or buffered data exceeds limit.");
+        await new Promise((resolve, reject) => this.socket.send(data, error => error ? reject(error) : resolve()));
+    }
+}

package/dist/protocol.d.ts

@@ -0,0 +1,149 @@
+import { z } from "zod";
+export declare const ToolManifestSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    inputSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    outputSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strict>;
+export declare const ManifestSchema: z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    inputSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    outputSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strict>>;
+export declare const ManifestVersionSchema: z.ZodObject<{
+    id: z.ZodString;
+    version: z.ZodNumber;
+    hash: z.ZodString;
+}, z.core.$strip>;
+export declare const RegisterSchema: z.ZodObject<{
+    protocolVersion: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>]>;
+    manifestHash: z.ZodString;
+    label: z.ZodString;
+    maxConcurrency: z.ZodNumber;
+}, z.core.$strict>;
+export declare const RegistrationSchema: z.ZodObject<{
+    instanceId: z.ZodString;
+    manifest: z.ZodObject<{
+        id: z.ZodString;
+        version: z.ZodNumber;
+        hash: z.ZodString;
+    }, z.core.$strip>;
+    heartbeatMs: z.ZodNumber;
+}, z.core.$strip>;
+export declare const LegacyCallContextSchema: z.ZodUnion<readonly [z.ZodObject<{
+    organizationId: z.ZodString;
+    workspaceId: z.ZodString;
+    environmentId: z.ZodString;
+    principal: z.ZodObject<{
+        kind: z.ZodLiteral<"platform_user">;
+        id: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    organizationId: z.ZodString;
+    workspaceId: z.ZodString;
+    environmentId: z.ZodString;
+    principalId: z.ZodString;
+    principal: z.ZodObject<{
+        kind: z.ZodEnum<{
+            tenant_user: "tenant_user";
+            agent_identity: "agent_identity";
+            system: "system";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strict>;
+    sessionId: z.ZodString;
+    turnId: z.ZodString;
+    agentIdentityId: z.ZodNullable<z.ZodString>;
+    agentId: z.ZodString;
+}, z.core.$strict>]>;
+export declare const CallContextSchema: z.ZodUnion<readonly [z.ZodObject<{
+    organizationId: z.ZodString;
+    workspaceId: z.ZodString;
+    environmentId: z.ZodString;
+    principal: z.ZodObject<{
+        kind: z.ZodLiteral<"platform_user">;
+        id: z.ZodString;
+    }, z.core.$strict>;
+    tenantUserExternalId: z.ZodNull;
+    workspaceExternalId: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    organizationId: z.ZodString;
+    workspaceId: z.ZodString;
+    environmentId: z.ZodString;
+    principalId: z.ZodString;
+    principal: z.ZodObject<{
+        kind: z.ZodEnum<{
+            tenant_user: "tenant_user";
+            agent_identity: "agent_identity";
+            system: "system";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strict>;
+    sessionId: z.ZodString;
+    turnId: z.ZodString;
+    agentIdentityId: z.ZodNullable<z.ZodString>;
+    agentId: z.ZodString;
+    workspaceExternalId: z.ZodNullable<z.ZodString>;
+    tenantUserExternalId: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>]>;
+export declare const CallSchema: z.ZodObject<{
+    invocationId: z.ZodString;
+    manifestVersion: z.ZodNumber;
+    name: z.ZodString;
+    inputs: z.ZodUnknown;
+    context: z.ZodUnion<readonly [z.ZodObject<{
+        organizationId: z.ZodString;
+        workspaceId: z.ZodString;
+        environmentId: z.ZodString;
+        principal: z.ZodObject<{
+            kind: z.ZodLiteral<"platform_user">;
+            id: z.ZodString;
+        }, z.core.$strict>;
+        tenantUserExternalId: z.ZodNull;
+        workspaceExternalId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        organizationId: z.ZodString;
+        workspaceId: z.ZodString;
+        environmentId: z.ZodString;
+        principalId: z.ZodString;
+        principal: z.ZodObject<{
+            kind: z.ZodEnum<{
+                tenant_user: "tenant_user";
+                agent_identity: "agent_identity";
+                system: "system";
+            }>;
+            id: z.ZodString;
+        }, z.core.$strict>;
+        sessionId: z.ZodString;
+        turnId: z.ZodString;
+        agentIdentityId: z.ZodNullable<z.ZodString>;
+        agentId: z.ZodString;
+        workspaceExternalId: z.ZodNullable<z.ZodString>;
+        tenantUserExternalId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>]>;
+    deadline: z.ZodString;
+}, z.core.$strict>;
+export type ToolManifest = z.infer<typeof ToolManifestSchema>;
+export type ManifestVersion = z.infer<typeof ManifestVersionSchema>;
+export type Registration = z.infer<typeof RegistrationSchema>;
+export type ToolCall = z.infer<typeof CallSchema>;
+export type LegacyToolCall = Omit<ToolCall, "context"> & {
+    context: z.infer<typeof LegacyCallContextSchema>;
+};
+export type ToolContext = z.infer<typeof CallContextSchema> & {
+    invocationId: string;
+    deadline: Date;
+};
+/** Defines negotiated wire contracts and a stable digest independent of JSON object key order. */
+export declare class BackendProtocol {
+    /** Projects at the socket owner so legacy replicas never see protocol-two fields. */
+    static forVersion(call: ToolCall | LegacyToolCall, version: 1 | 2): ToolCall | LegacyToolCall;
+    static readonly path = "/backends/v1/connect";
+    static readonly maxBytes: number;
+    static readonly heartbeatMs = 10000;
+    static readonly leaseMs = 35000;
+    static readonly callTimeoutMs = 15000;
+    static hash(tools: ToolManifest[]): string;
+    private static canonical;
+}

package/dist/protocol.js

@@ -0,0 +1,71 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+export const ToolManifestSchema = z.object({
+    name: z.string().min(1).max(128).regex(/^[A-Za-z0-9_.-]+$/u),
+    description: z.string().max(10000),
+    inputSchema: z.record(z.string(), z.unknown()),
+    outputSchema: z.record(z.string(), z.unknown()),
+}).strict();
+export const ManifestSchema = z.array(ToolManifestSchema).max(100).superRefine((tools, context) => {
+    if (new Set(tools.map(tool => tool.name)).size !== tools.length)
+        context.addIssue({ code: "custom", message: "Duplicate tool names." });
+});
+export const ManifestVersionSchema = z.object({ id: z.string().uuid(), version: z.number().int().positive(), hash: z.string().length(64) });
+export const RegisterSchema = z.object({ protocolVersion: z.union([z.literal(1), z.literal(2)]), manifestHash: z.string().length(64), label: z.string().min(1).max(100).regex(/\S/u), maxConcurrency: z.number().int().min(1).max(100) }).strict();
+export const RegistrationSchema = z.object({ instanceId: z.string().uuid(), manifest: ManifestVersionSchema, heartbeatMs: z.number().int().positive() });
+const ContextScope = z.object({
+    organizationId: z.string().uuid(), workspaceId: z.string().uuid(), environmentId: z.string().uuid(),
+});
+const PlatformContextSchema = z.object({
+    organizationId: z.string().uuid(), workspaceId: z.string().uuid(), environmentId: z.string().uuid(),
+    principal: z.object({ kind: z.literal("platform_user"), id: z.string().uuid() }).strict(),
+}).strict();
+const HostedContextSchema = ContextScope.extend({
+    principalId: z.string().uuid(), principal: z.object({ kind: z.enum(["tenant_user", "agent_identity", "system"]), id: z.string().uuid() }).strict(),
+    sessionId: z.string().uuid(), turnId: z.string().uuid(), agentIdentityId: z.string().uuid().nullable(), agentId: z.string().uuid(),
+}).strict();
+// Version one remains frozen: deployed 0.1.0 clients reject unknown context keys.
+export const LegacyCallContextSchema = z.union([PlatformContextSchema, HostedContextSchema]);
+const ExternalContext = {
+    workspaceExternalId: z.string().nullable(),
+    tenantUserExternalId: z.string().nullable(),
+};
+export const CallContextSchema = z.union([
+    PlatformContextSchema.extend({ ...ExternalContext, tenantUserExternalId: z.null() }),
+    HostedContextSchema.extend(ExternalContext).superRefine((context, issue) => {
+        if (context.principal.kind !== "tenant_user" && context.tenantUserExternalId !== null) {
+            issue.addIssue({ code: "custom", message: "Only tenant-user execution may carry a user external ID." });
+        }
+    }),
+]);
+export const CallSchema = z.object({
+    invocationId: z.string().uuid(), manifestVersion: z.number().int().positive(), name: z.string(),
+    inputs: z.unknown(), context: CallContextSchema, deadline: z.string().datetime(),
+}).strict();
+/** Defines negotiated wire contracts and a stable digest independent of JSON object key order. */
+export class BackendProtocol {
+    /** Projects at the socket owner so legacy replicas never see protocol-two fields. */
+    static forVersion(call, version) {
+        if (version === 2)
+            return CallSchema.parse(call);
+        const context = { ...call.context };
+        delete context.workspaceExternalId;
+        delete context.tenantUserExternalId;
+        return { ...call, context: LegacyCallContextSchema.parse(context) };
+    }
+    static path = "/backends/v1/connect";
+    static maxBytes = 1024 * 1024;
+    static heartbeatMs = 10000;
+    static leaseMs = 35000;
+    static callTimeoutMs = 15000;
+    static hash(tools) {
+        return createHash("sha256").update(JSON.stringify(this.canonical([...ManifestSchema.parse(tools)].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)))).digest("hex");
+    }
+    static canonical(value) {
+        if (Array.isArray(value))
+            return value.map(item => this.canonical(item));
+        if (value && typeof value === "object")
+            return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, item]) => [key, this.canonical(item)]));
+        return value;
+    }
+}

package/dist/tool.d.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import type { ToolContext, ToolManifest } from "./protocol.js";
+export type ToolRegistration = {
+    manifest: ToolManifest;
+    invoke(context: ToolContext, inputs: unknown): Promise<unknown>;
+};
+/** Keeps executable code local while exporting the same schemas used to validate each invocation. */
+export declare class BackendTool<I extends z.ZodType, O extends z.ZodType> implements ToolRegistration {
+    private readonly definition;
+    readonly manifest: ToolManifest;
+    constructor(definition: {
+        name: string;
+        description: string;
+        input: I;
+        output: O;
+        handler(context: ToolContext, inputs: z.output<I>): Promise<z.input<O>>;
+    });
+    invoke(context: ToolContext, inputs: unknown): Promise<unknown>;
+}

package/dist/tool.js

@@ -0,0 +1,15 @@
+import { z } from "zod";
+/** Keeps executable code local while exporting the same schemas used to validate each invocation. */
+export class BackendTool {
+    definition;
+    manifest;
+    constructor(definition) {
+        this.definition = definition;
+        this.manifest = { name: definition.name, description: definition.description,
+            inputSchema: z.toJSONSchema(definition.input, { io: "input" }), outputSchema: z.toJSONSchema(definition.output, { io: "output" }) };
+    }
+    async invoke(context, inputs) {
+        const parsed = this.definition.input.parse(inputs);
+        return this.definition.output.parse(await this.definition.handler(context, parsed));
+    }
+}

package/examples/quickstart.ts

@@ -0,0 +1,35 @@
+import { readFileSync } from "node:fs";
+import { BackendTool, CaltraBackendClient } from "@caltra/backend-sdk";
+import { z } from "zod";
+
+/** Loads validated deployment configuration and serves a harmless tool without accessing application data. */
+class BackendQuickstart {
+  async run(command: string, configPath: string): Promise<void> {
+    if (command !== "publish" && command !== "serve") throw new Error("Use publish or serve, followed by a config file path.");
+    const config = z.object({
+      url: z.url(), backendId: z.uuid(), credential: z.string().min(1), label: z.string().min(1),
+    }).strict().parse(JSON.parse(readFileSync(configPath, "utf8")));
+    const backend = new CaltraBackendClient({
+      ...config,
+      tools: [new BackendTool({
+        name: "diagnostics.echo",
+        description: "Echo a test message with the trusted workspace and serving replica.",
+        input: z.object({ message: z.string().min(1) }).strict(),
+        output: z.object({ message: z.string(), workspaceId: z.uuid(), workspaceExternalId: z.string().nullable(), tenantUserExternalId: z.string().nullable(), handledBy: z.string() }).strict(),
+        handler: async (context, inputs) => ({ message: inputs.message, workspaceId: context.workspaceId, workspaceExternalId: context.workspaceExternalId, tenantUserExternalId: context.tenantUserExternalId, handledBy: config.label }),
+      })],
+    });
+    if (command === "publish") {
+      process.stdout.write(`${JSON.stringify(await backend.publish())}\n`);
+      return;
+    }
+    process.once("SIGINT", () => { void backend.close(); });
+    process.once("SIGTERM", () => { void backend.close(); });
+    try {
+      process.stdout.write(`${JSON.stringify(await backend.connect())}\n`);
+      await backend.waitForDisconnect();
+    } finally { await backend.close(); }
+  }
+}
+
+await new BackendQuickstart().run(process.argv[2] ?? "", process.argv[3] ?? "backend.config.json");

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@caltra/backend-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol.d.ts",
+      "import": "./dist/protocol.js"
+    },
+    "./peer": {
+      "types": "./dist/peer.d.ts",
+      "import": "./dist/peer.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint src --ext .ts",
+    "test": "vitest run",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "json-rpc-2.0": "1.8.1",
+    "ws": "8.22.0",
+    "zod": "^4.4.3",
+    "@types/ws": "8.18.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.7"
+  },
+  "description": "TypeScript backend tools for Caltra over outbound authenticated WebSockets",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "examples/quickstart.ts",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/caltra-dev/caltra.git",
+    "directory": "packages/backend-sdk"
+  },
+  "homepage": "https://caltra.dev/docs/backend-tools",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}