@caltra/backend-sdk 0.1.0 → 0.2.0

package/README.md

@@ -58,6 +58,11 @@ The URL must use `wss://`; `ws://` is allowed only for loopback development. Cre
 
 `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.js

@@ -49,7 +49,7 @@ export class CaltraBackendClient {
         peer.method("tools/call", params => this.invoke(params));
         try {
             this.registration = RegistrationSchema.parse(await peer.request("instances/register", {
-                protocolVersion: 1, manifestHash: BackendProtocol.hash(this.manifest), label: this.options.label, maxConcurrency: this.options.maxConcurrency ?? 1,
+                protocolVersion: 2, manifestHash: BackendProtocol.hash(this.manifest), label: this.options.label, maxConcurrency: this.options.maxConcurrency ?? 1,
             }));
             this.scheduleHeartbeat(peer);
             return this.registration;

package/dist/protocol.d.ts

@@ -17,7 +17,7 @@ export declare const ManifestVersionSchema: z.ZodObject<{
     hash: z.ZodString;
 }, z.core.$strip>;
 export declare const RegisterSchema: z.ZodObject<{
-    protocolVersion: z.ZodLiteral<1>;
+    protocolVersion: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>]>;
     manifestHash: z.ZodString;
     label: z.ZodString;
     maxConcurrency: z.ZodNumber;
@@ -31,6 +31,32 @@ export declare const RegistrationSchema: z.ZodObject<{
     }, 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;
@@ -39,6 +65,8 @@ export declare const CallContextSchema: z.ZodUnion<readonly [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;
@@ -56,6 +84,8 @@ export declare const CallContextSchema: z.ZodUnion<readonly [z.ZodObject<{
     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;
@@ -70,6 +100,8 @@ export declare const CallSchema: 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;
@@ -87,6 +119,8 @@ export declare const CallSchema: z.ZodObject<{
         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>;
@@ -94,12 +128,17 @@ 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 the version-one wire contract and a stable digest independent of JSON object key order. */
+/** 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;

package/dist/protocol.js

@@ -11,24 +11,48 @@ export const ManifestSchema = z.array(ToolManifestSchema).max(100).superRefine((
         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.literal(1), 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 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(),
 });
-export const CallContextSchema = z.union([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(), 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()]);
+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 the version-one wire contract and a stable digest independent of JSON object key order. */
+/** 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;

package/examples/quickstart.ts

@@ -15,8 +15,8 @@ class BackendQuickstart {
         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(), handledBy: z.string() }).strict(),
-        handler: async (context, inputs) => ({ message: inputs.message, workspaceId: context.workspaceId, handledBy: config.label }),
+        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") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caltra/backend-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "exports": {
     ".": {