agent-embassy 1.0.0 → 1.3.0

package/dist/src/gateway/provenance-envelope.js

@@ -0,0 +1,80 @@
+import { createHash } from "node:crypto";
+import { BridgeError } from "../errors.js";
+export const PROVENANCE_RAW_BODY_MAX_BYTES = 16 * 1024;
+export const PROVENANCE_ENVELOPE_MAX_BYTES = 64 * 1024;
+const ALIAS_PATTERN = /^[a-z][a-z0-9_-]{0,31}@[a-z0-9](?:[a-z0-9.-]{0,61}[a-z0-9])?$/;
+const CONVERSATION_ID_PATTERN = /^conv_[A-Za-z0-9_-]{16,64}$/;
+const RESERVED_TAG_PATTERN = /<(?=\/?(?:cross-session-message|embassy-reply-hint)(?:[>\s/]|$))/giu;
+const CLAUDE_FROM_NAME_MAX_CODEPOINTS = 64;
+const LONG_ALIAS_PREFIX_CODEPOINTS = 47;
+const LONG_ALIAS_HASH_HEX_LENGTH = 16;
+function invalidEnvelope() {
+    throw new BridgeError("PROVENANCE_ENVELOPE_INVALID", "The provenance envelope metadata is invalid.");
+}
+function envelopeTooLarge() {
+    throw new BridgeError("PROVENANCE_ENVELOPE_TOO_LARGE", "The provenance envelope exceeds its byte limit.");
+}
+function validateInput(input) {
+    if (typeof input !== "object" ||
+        input === null ||
+        (input.direction !== "codex" && input.direction !== "claude") ||
+        typeof input.sourceAlias !== "string" ||
+        !ALIAS_PATTERN.test(input.sourceAlias) ||
+        typeof input.targetAlias !== "string" ||
+        !ALIAS_PATTERN.test(input.targetAlias) ||
+        typeof input.conversationId !== "string" ||
+        !CONVERSATION_ID_PATTERN.test(input.conversationId) ||
+        typeof input.body !== "string") {
+        invalidEnvelope();
+    }
+    if (Buffer.byteLength(input.body, "utf8") > PROVENANCE_RAW_BODY_MAX_BYTES) {
+        envelopeTooLarge();
+    }
+}
+function claudeDisplayAlias(alias) {
+    const codepoints = [...alias];
+    if (codepoints.length <= CLAUDE_FROM_NAME_MAX_CODEPOINTS) {
+        return { displayAlias: alias, shortened: false };
+    }
+    const digest = createHash("sha256")
+        .update(alias, "utf8")
+        .digest("hex")
+        .slice(0, LONG_ALIAS_HASH_HEX_LENGTH);
+    return {
+        displayAlias: `${codepoints.slice(0, LONG_ALIAS_PREFIX_CODEPOINTS).join("")}~${digest}`,
+        shortened: true,
+    };
+}
+function neutralizeReservedTags(body) {
+    return body.replace(RESERVED_TAG_PATTERN, "<\\");
+}
+/**
+ * Adds broker-owned, Claude-compatible textual framing at the provider write
+ * boundary. The result is not general XML and does not provide a cryptographic
+ * signature; the wrapper is a structural provenance marker for the recipient.
+ */
+export function composeProvenanceEnvelope(input) {
+    validateInput(input);
+    const display = claudeDisplayAlias(input.sourceAlias);
+    const fromName = input.direction === "codex" ? input.sourceAlias : display.displayAlias;
+    const conversationAttribute = input.direction === "codex"
+        ? ` conversation="${input.conversationId}"`
+        : "";
+    const exactSourceAttribute = input.direction === "claude" && display.shortened
+        ? ` from-alias="${input.sourceAlias}"`
+        : "";
+    const replyCommand = `embassy reply --conversation ${input.conversationId}` +
+        ` --alias ${input.targetAlias}`;
+    const hint = `<embassy-reply-hint conversation="${input.conversationId}"` +
+        ` reply-as="${input.targetAlias}"${exactSourceAttribute}>` +
+        `Reply by running \`${replyCommand}\` with the reply body on stdin. ` +
+        "Caller, conversation, and route policy are rechecked.</embassy-reply-hint>";
+    const body = neutralizeReservedTags(input.body);
+    const envelope = `<cross-session-message from-name="${fromName}"${conversationAttribute}>\n` +
+        `${hint}\n${body}\n</cross-session-message>`;
+    if (Buffer.byteLength(envelope, "utf8") > PROVENANCE_ENVELOPE_MAX_BYTES) {
+        envelopeTooLarge();
+    }
+    return envelope;
+}
+//# sourceMappingURL=provenance-envelope.js.map

package/dist/src/gateway/provenance-envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenance-envelope.js","sourceRoot":"","sources":["../../../src/gateway/provenance-envelope.ts"],"names":[],"mappings":"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"}

package/dist/src/gateway/providers.d.ts

@@ -1,13 +1,12 @@
 import { ClaudePeerAdapter, type ClaudePeerInboundProgress, type ClaudePeerRegistryPublicationOutcome } from "./claude-peer.js";
 import type { AttestedClaudePeerRuntime } from "./claude-runtime.js";
-import { type ClaudeCompatibilityScratchFactory } from "./claude-compatibility-scratch.js";
-import { type CompatibilityAttestation, type CompatibilityCertification, type CompatibilityProbeResult, type CompatibilitySurfaceObservation } from "./compatibility.js";
+import { type CompatibilityAttestation, type CompatibilityProbeResult, type CompatibilitySurfaceObservation } from "./compatibility.js";
 import { type CodexConnectorObservation } from "./codex-app-server.js";
 import type { LocalCodexTransportFactory } from "./codex-local-transport.js";
 import type { GatewayDeliveryNoticeMode } from "./config.js";
 import type { ClaudeNativeHelperFactory } from "./claude-helper-client.js";
 import { type DashboardLocale } from "./locale.js";
-import type { GatewayAdapterCallbacks, GatewayAdapterDiscoverySnapshot, GatewayAdapterDispatchResult, GatewayAdapterRouteState, GatewayAdapterStart, GatewayProviderAdapter } from "./service.js";
+import type { GatewayAdapterCallbacks, GatewayAdapterDiscoverySnapshot, GatewayAdapterDispatchResult, GatewayAdapterEndpointRefresh, GatewayAdapterDispatchInput, GatewayAdapterRouteState, GatewayAdapterStart, GatewayProviderAdapter } from "./service.js";
 import type { PrivateEndpointIdentity, PrivateRouteBinding } from "./types.js";
 type ClaudePeerFactory = (runtime: AttestedClaudePeerRuntime, locale: DashboardLocale, deliveryNotices: GatewayDeliveryNoticeMode) => ClaudePeerAdapter;
 export type LocalClaudeGatewayProviderOptions = {
@@ -28,8 +27,6 @@ export type LocalClaudeGatewayProviderOptions = {
     }>;
     /** Deterministic test seam. Production callers must omit this. */
     peerFactory?: ClaudePeerFactory;
-    /** Deterministic test seam. Production starts one bounded local scratch. */
-    compatibilityScratchFactory?: ClaudeCompatibilityScratchFactory;
 };
 export type ClaudeNativeCodexSuccessionBarrier = Readonly<{
     generation: string;
@@ -66,7 +63,6 @@ export declare class LocalClaudeGatewayProvider implements GatewayProviderAdapte
     private readonly now;
     private readonly selectedStateRoots;
     private readonly nativeHelpers;
-    private readonly compatibilityScratchFactory;
     private readonly discovered;
     private readonly selected;
     /** Exact live same-UID sessions observed through native inbound frames. */
@@ -99,17 +95,11 @@ export declare class LocalClaudeGatewayProvider implements GatewayProviderAdapte
     private retiredNativeCodexListener;
     /** Fences discovery callbacks and monitor restarts across listener rotation. */
     private nativeCodexSuccessionFreeze;
-    private compatibilityCertificationInFlight;
     private initialized;
     private closed;
     constructor(options: LocalClaudeGatewayProviderOptions);
     compatibilitySurface(): CompatibilitySurfaceObservation;
     runCompatibilityProbes(): Promise<readonly CompatibilityProbeResult[]>;
-    runCompatibilityCertification(input: Readonly<{
-        controllerStateRoot: string;
-        routeHandle?: string;
-        withTurn: boolean;
-    }>): Promise<CompatibilityCertification>;
     initialize(callbacks: GatewayAdapterCallbacks): Promise<GatewayAdapterStart>;
     discoverClaudePeers(): Promise<GatewayAdapterDiscoverySnapshot>;
     assertWorkspaceDisjoint(routeHandle: string, stateRoot: string): Promise<void>;
@@ -161,7 +151,9 @@ export declare class LocalClaudeGatewayProvider implements GatewayProviderAdapte
     releaseNativeInboundReceipt(receiptHandle: string): Promise<boolean>;
     quiesceNativeInbound(): Promise<void>;
     dispatch(input: {
-        sourceAlias?: string;
+        sourceAlias: string;
+        targetAlias: string;
+        conversationId: string;
         binding: PrivateRouteBinding;
         authorization: "selected_route" | "native_reply";
         messageId: string;
@@ -199,6 +191,8 @@ export declare class LocalClaudeGatewayProvider implements GatewayProviderAdapte
 export declare function createLocalClaudeGatewayProvider(options: LocalClaudeGatewayProviderOptions): LocalClaudeGatewayProvider;
 export type LocalCodexGatewayProviderOptions = {
     factory: LocalCodexTransportFactory;
+    /** Re-resolves the exact pinned managed install after its generation moves. */
+    refreshFactory?: () => Promise<LocalCodexTransportFactory>;
     cleanupPollMs?: number;
     cleanupTimeoutMs?: number;
     recoveryInitialMs?: number;
@@ -209,10 +203,8 @@ export type LocalCodexGatewayProviderOptions = {
     now?: () => Date;
 };
 export declare class LocalCodexGatewayProvider implements GatewayProviderAdapter {
-    readonly identity: PrivateEndpointIdentity;
-    readonly protocol: string;
-    readonly protocolVersion: string;
-    private readonly factory;
+    private factory;
+    private readonly refreshFactory;
     private readonly maxCallbacks;
     private readonly maxRoutes;
     private readonly maxReplyBytes;
@@ -222,31 +214,40 @@ export declare class LocalCodexGatewayProvider implements GatewayProviderAdapter
     private readonly recoveryMaxMs;
     private readonly now;
     private readonly routes;
+    /** Exact public alias authority retained across internal route recovery. */
+    private readonly routeAliases;
     private readonly routeCreations;
     private readonly routeReleases;
     private readonly routeRecoveryAttempts;
     private readonly routeRecoveryTimers;
     private readonly routeRecoveries;
     private readonly routesRequiringRecovery;
+    private readonly trackedRoutes;
+    private retiredEndpointGeneration;
     private readonly expectsReply;
-    private readonly compatibilityCertifyingRoutes;
-    private readonly compatibilityTurns;
     private readonly callbackQueue;
     private callbackScheduled;
     private callbacks;
+    private endpointRefresh;
+    private endpointRefreshDelivery;
+    private endpointActivationRetry;
+    private endpointActivationRetryTimer;
+    private callbackDrainFrozen;
     private compatibilityAttested;
+    private endpointUnavailable;
+    private pendingEndpointAttestation;
+    private pendingEndpointRefreshEvent;
     private initialized;
     private closing;
     private closed;
     constructor(options: LocalCodexGatewayProviderOptions);
+    get identity(): PrivateEndpointIdentity;
+    get protocol(): string;
+    get protocolVersion(): string;
     compatibilitySurface(): CompatibilitySurfaceObservation;
     acceptCompatibilityAttestation(attestation: CompatibilityAttestation): void;
     runCompatibilityProbes(): Promise<readonly CompatibilityProbeResult[]>;
-    runCompatibilityCertification(input: Readonly<{
-        controllerStateRoot: string;
-        routeHandle?: string;
-        withTurn: boolean;
-    }>): Promise<CompatibilityCertification>;
+    private runCompatibilityProbesFor;
     initialize(callbacks: GatewayAdapterCallbacks): Promise<GatewayAdapterStart>;
     selectRoute(input: {
         alias: string;
@@ -254,17 +255,10 @@ export declare class LocalCodexGatewayProvider implements GatewayProviderAdapter
     }): Promise<{
         routeHandle: string;
         state: GatewayAdapterRouteState;
+        endpointRefresh?: GatewayAdapterEndpointRefresh;
     }>;
     observeRouteSuccessionBarrier(routeHandle: string): CodexRouteSuccessionBarrier;
-    dispatch(input: {
-        binding: PrivateRouteBinding;
-        authorization: "selected_route" | "native_reply";
-        messageId: string;
-        text: string;
-        expectsReply: boolean;
-        deadlineAt: string;
-        steer?: true;
-    }): Promise<GatewayAdapterDispatchResult>;
+    dispatch(input: GatewayAdapterDispatchInput): Promise<GatewayAdapterDispatchResult>;
     releaseRoute(routeHandle: string): Promise<void>;
     private releaseRouteInternal;
     close(): Promise<void>;
@@ -275,6 +269,19 @@ export declare class LocalCodexGatewayProvider implements GatewayProviderAdapter
     private scheduleRouteRecovery;
     private recoverRoute;
     private cancelRouteRecovery;
+    private isEndpointGenerationChanged;
+    private pendingEndpointActivationClaims;
+    private refreshEndpoint;
+    private performEndpointRefresh;
+    private resolveEndpointRefreshCandidate;
+    private retireEndpointGeneration;
+    private reserveSelectorRefresh;
+    private emitSelectorRefreshFallback;
+    private publishEndpointRefresh;
+    private armEndpointActivationRetry;
+    private scheduleEndpointActivationRetry;
+    private clearEndpointActivationRetry;
+    private emitEndpointRefresh;
     private onTurnResult;
     private queueRouteObservation;
     private enqueueCodexCallback;