@dxos/client-services 0.8.4-main.9be5663bfe → 0.8.4-main.abd8ff62ef

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/client-services",
-  "version": "0.8.4-main.9be5663bfe",
+  "version": "0.8.4-main.abd8ff62ef",
   "description": "DXOS client services implementation",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -47,13 +47,6 @@
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {
-      "testing": [
-        "dist/types/src/testing/index.d.ts"
-      ]
-    }
-  },
   "files": [
     "dist",
     "src"
@@ -68,49 +61,49 @@
     "cbor-x": "^1.5.4",
     "effect": "3.20.0",
     "platform": "^1.3.6",
-    "@dxos/async": "0.8.4-main.9be5663bfe",
-    "@dxos/client-protocol": "0.8.4-main.9be5663bfe",
-    "@dxos/codec-protobuf": "0.8.4-main.9be5663bfe",
-    "@dxos/credentials": "0.8.4-main.9be5663bfe",
-    "@dxos/context": "0.8.4-main.9be5663bfe",
-    "@dxos/config": "0.8.4-main.9be5663bfe",
-    "@dxos/crypto": "0.8.4-main.9be5663bfe",
-    "@dxos/debug": "0.8.4-main.9be5663bfe",
-    "@dxos/echo": "0.8.4-main.9be5663bfe",
-    "@dxos/echo-db": "0.8.4-main.9be5663bfe",
-    "@dxos/edge-client": "0.8.4-main.9be5663bfe",
-    "@dxos/effect": "0.8.4-main.9be5663bfe",
-    "@dxos/echo-protocol": "0.8.4-main.9be5663bfe",
-    "@dxos/feed": "0.8.4-main.9be5663bfe",
-    "@dxos/echo-pipeline": "0.8.4-main.9be5663bfe",
-    "@dxos/feed-store": "0.8.4-main.9be5663bfe",
-    "@dxos/keyring": "0.8.4-main.9be5663bfe",
-    "@dxos/invariant": "0.8.4-main.9be5663bfe",
-    "@dxos/keys": "0.8.4-main.9be5663bfe",
-    "@dxos/kv-store": "0.8.4-main.9be5663bfe",
-    "@dxos/lock-file": "0.8.4-main.9be5663bfe",
-    "@dxos/log": "0.8.4-main.9be5663bfe",
-    "@dxos/messaging": "0.8.4-main.9be5663bfe",
-    "@dxos/node-std": "0.8.4-main.9be5663bfe",
-    "@dxos/network-manager": "0.8.4-main.9be5663bfe",
-    "@dxos/protocols": "0.8.4-main.9be5663bfe",
-    "@dxos/random-access-storage": "0.8.4-main.9be5663bfe",
-    "@dxos/rpc": "0.8.4-main.9be5663bfe",
-    "@dxos/sql-sqlite": "0.8.4-main.9be5663bfe",
-    "@dxos/teleport-extension-gossip": "0.8.4-main.9be5663bfe",
-    "@dxos/teleport": "0.8.4-main.9be5663bfe",
-    "@dxos/timeframe": "0.8.4-main.9be5663bfe",
-    "@dxos/tracing": "0.8.4-main.9be5663bfe",
-    "@dxos/util": "0.8.4-main.9be5663bfe",
-    "@dxos/websocket-rpc": "0.8.4-main.9be5663bfe",
-    "@dxos/teleport-extension-object-sync": "0.8.4-main.9be5663bfe"
+    "@dxos/async": "0.8.4-main.abd8ff62ef",
+    "@dxos/client-protocol": "0.8.4-main.abd8ff62ef",
+    "@dxos/codec-protobuf": "0.8.4-main.abd8ff62ef",
+    "@dxos/credentials": "0.8.4-main.abd8ff62ef",
+    "@dxos/context": "0.8.4-main.abd8ff62ef",
+    "@dxos/crypto": "0.8.4-main.abd8ff62ef",
+    "@dxos/debug": "0.8.4-main.abd8ff62ef",
+    "@dxos/echo": "0.8.4-main.abd8ff62ef",
+    "@dxos/echo-db": "0.8.4-main.abd8ff62ef",
+    "@dxos/echo-pipeline": "0.8.4-main.abd8ff62ef",
+    "@dxos/config": "0.8.4-main.abd8ff62ef",
+    "@dxos/effect": "0.8.4-main.abd8ff62ef",
+    "@dxos/edge-client": "0.8.4-main.abd8ff62ef",
+    "@dxos/feed": "0.8.4-main.abd8ff62ef",
+    "@dxos/feed-store": "0.8.4-main.abd8ff62ef",
+    "@dxos/invariant": "0.8.4-main.abd8ff62ef",
+    "@dxos/keyring": "0.8.4-main.abd8ff62ef",
+    "@dxos/keys": "0.8.4-main.abd8ff62ef",
+    "@dxos/kv-store": "0.8.4-main.abd8ff62ef",
+    "@dxos/lock-file": "0.8.4-main.abd8ff62ef",
+    "@dxos/log": "0.8.4-main.abd8ff62ef",
+    "@dxos/messaging": "0.8.4-main.abd8ff62ef",
+    "@dxos/node-std": "0.8.4-main.abd8ff62ef",
+    "@dxos/protocols": "0.8.4-main.abd8ff62ef",
+    "@dxos/random-access-storage": "0.8.4-main.abd8ff62ef",
+    "@dxos/echo-protocol": "0.8.4-main.abd8ff62ef",
+    "@dxos/rpc": "0.8.4-main.abd8ff62ef",
+    "@dxos/sql-sqlite": "0.8.4-main.abd8ff62ef",
+    "@dxos/teleport": "0.8.4-main.abd8ff62ef",
+    "@dxos/teleport-extension-gossip": "0.8.4-main.abd8ff62ef",
+    "@dxos/teleport-extension-object-sync": "0.8.4-main.abd8ff62ef",
+    "@dxos/tracing": "0.8.4-main.abd8ff62ef",
+    "@dxos/timeframe": "0.8.4-main.abd8ff62ef",
+    "@dxos/network-manager": "0.8.4-main.abd8ff62ef",
+    "@dxos/util": "0.8.4-main.abd8ff62ef",
+    "@dxos/websocket-rpc": "0.8.4-main.abd8ff62ef"
   },
   "devDependencies": {
     "@types/platform": "^1.3.4",
     "@types/readable-stream": "^2.3.9",
     "get-port-please": "^3.1.1",
-    "@dxos/test-utils": "0.8.4-main.9be5663bfe",
-    "@dxos/signal": "0.8.4-main.9be5663bfe"
+    "@dxos/signal": "0.8.4-main.abd8ff62ef",
+    "@dxos/test-utils": "0.8.4-main.abd8ff62ef"
   },
   "publishConfig": {
     "access": "public"

package/src/packlets/agents/edge-agent-service.ts

@@ -2,6 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
+import { type RequestOptions } from '@dxos/codec-protobuf';
 import { Stream } from '@dxos/codec-protobuf/stream';
 import { Context } from '@dxos/context';
 import { type EdgeConnection } from '@dxos/edge-client';
@@ -44,8 +45,8 @@ export class EdgeAgentServiceImpl implements EdgeAgentService {
     });
   }
 
-  async createAgent(): Promise<void> {
-    return (await this._agentManagerProvider()).createAgent(Context.default());
+  async createAgent(_request: void, options?: RequestOptions): Promise<void> {
+    return (await this._agentManagerProvider()).createAgent(options?.ctx ?? Context.default());
   }
 
   queryAgentStatus(): Stream<QueryAgentStatusResponse> {

package/src/packlets/diagnostics/diagnostics.ts

@@ -23,7 +23,7 @@ import {
 import { type SubscribeToFeedsResponse } from '@dxos/protocols/proto/dxos/devtools/host';
 import { type SwarmInfo } from '@dxos/protocols/proto/dxos/devtools/swarm';
 import { type Epoch } from '@dxos/protocols/proto/dxos/halo/credentials';
-import { type Resource, type Span } from '@dxos/protocols/proto/dxos/tracing';
+import { type Resource } from '@dxos/protocols/proto/dxos/tracing';
 import { TRACE_PROCESSOR } from '@dxos/tracing';
 
 import { DXOS_VERSION } from '../../version';
@@ -62,7 +62,6 @@ export type Diagnostics = {
 
 export type TraceDiagnostic = {
   resources: Record<string, Resource>;
-  spans: Span[];
   logs: LogEntry[];
 };
 

package/src/packlets/identity/identity-manager.ts

@@ -13,7 +13,6 @@ import { invariant } from '@dxos/invariant';
 import { type Keyring } from '@dxos/keyring';
 import { PublicKey } from '@dxos/keys';
 import { log } from '@dxos/log';
-import { trace } from '@dxos/protocols';
 import { Device, DeviceKind } from '@dxos/protocols/proto/dxos/client/services';
 import { type Runtime } from '@dxos/protocols/proto/dxos/config';
 import { type FeedMessage } from '@dxos/protocols/proto/dxos/echo/feed';
@@ -112,8 +111,7 @@ export class IdentityManager {
 
   @Trace.span({ showInBrowserTimeline: true })
   async open(ctx: Context): Promise<void> {
-    const traceId = PublicKey.random().toHex();
-    log.trace('dxos.halo.identity-manager.open', trace.begin({ id: traceId }));
+    log('opening identity manager');
 
     const identityRecord = this._metadataStore.getIdentityRecord();
     log('identity record', { identityRecord });
@@ -128,7 +126,7 @@ export class IdentityManager {
 
       this.stateUpdate.emit();
     }
-    log.trace('dxos.halo.identity-manager.open', trace.end({ id: traceId }));
+    log('opened identity manager');
   }
 
   async close(ctx: Context): Promise<void> {

package/src/packlets/identity/identity-service.ts

@@ -2,6 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
+import { type RequestOptions } from '@dxos/codec-protobuf';
 import { Stream } from '@dxos/codec-protobuf/stream';
 import { Context, Resource } from '@dxos/context';
 import { createCredential, signPresentation } from '@dxos/credentials';
@@ -27,14 +28,15 @@ export class IdentityServiceImpl extends Resource implements IdentityService {
     private readonly _identityManager: IdentityManager,
     private readonly _recoveryManager: EdgeIdentityRecoveryManager,
     private readonly _keyring: Keyring,
-    private readonly _createIdentity: (params: CreateIdentityOptions) => Promise<Identity>,
+    private readonly _createIdentity: (params: CreateIdentityOptions, ctx?: Context) => Promise<Identity>,
     private readonly _onProfileUpdate?: (profile: ProfileDocument | undefined) => Promise<void>,
   ) {
     super();
   }
 
-  async createIdentity(request: CreateIdentityRequest): Promise<IdentityProto> {
-    await this._createIdentity({ profile: request.profile, deviceProfile: request.deviceProfile });
+  async createIdentity(request: CreateIdentityRequest, options?: RequestOptions): Promise<IdentityProto> {
+    const ctx = options?.ctx ?? Context.default();
+    await this._createIdentity({ profile: request.profile, deviceProfile: request.deviceProfile }, ctx);
     return this._getIdentity()!;
   }
 
@@ -71,17 +73,18 @@ export class IdentityServiceImpl extends Resource implements IdentityService {
     return this._recoveryManager.createRecoveryCredential(request);
   }
 
-  async requestRecoveryChallenge() {
-    return this._recoveryManager.requestRecoveryChallenge(Context.default());
+  async requestRecoveryChallenge(_request: void, options?: RequestOptions) {
+    return this._recoveryManager.requestRecoveryChallenge(options?.ctx ?? Context.default());
   }
 
-  async recoverIdentity(request: RecoverIdentityRequest): Promise<IdentityProto> {
+  async recoverIdentity(request: RecoverIdentityRequest, options?: RequestOptions): Promise<IdentityProto> {
+    const ctx = options?.ctx ?? Context.default();
     if (request.recoveryCode) {
-      await this._recoveryManager.recoverIdentity(Context.default(), { recoveryCode: request.recoveryCode });
+      await this._recoveryManager.recoverIdentity(ctx, { recoveryCode: request.recoveryCode });
     } else if (request.external) {
-      await this._recoveryManager.recoverIdentityWithExternalSignature(Context.default(), request.external);
+      await this._recoveryManager.recoverIdentityWithExternalSignature(ctx, request.external);
     } else if (request.token) {
-      await this._recoveryManager.recoverIdentityWithToken(Context.default(), { token: request.token });
+      await this._recoveryManager.recoverIdentityWithToken(ctx, { token: request.token });
     } else {
       throw new Error('Invalid request.');
     }

package/src/packlets/identity/identity.ts

@@ -104,7 +104,7 @@ export class Identity {
     return this._deviceStateMachine.authorizedDeviceKeys;
   }
 
-  @trace.span()
+  @trace.span({ op: 'lifecycle' })
   async open(ctx: DxosContext): Promise<void> {
     await this._presence?.open();
     await this.space.spaceState.addCredentialProcessor(this._deviceStateMachine);
@@ -120,7 +120,7 @@ export class Identity {
     await this._edgeFeedReplicator?.open();
   }
 
-  @trace.span()
+  @trace.span({ op: 'lifecycle' })
   async close(ctx: DxosContext): Promise<void> {
     await this._presence?.close();
     await this.authVerifier.close();

package/src/packlets/invitations/device-invitation-protocol.ts

@@ -2,6 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
+import { type Context } from '@dxos/context';
 import { getCredentialAssertion } from '@dxos/credentials';
 import { invariant } from '@dxos/invariant';
 import { type Keyring } from '@dxos/keyring';
@@ -96,7 +97,7 @@ export class DeviceInvitationProtocol implements InvitationProtocol {
     };
   }
 
-  async accept(response: AdmissionResponse, request: AdmissionRequest): Promise<Partial<Invitation>> {
+  async accept(_ctx: Context, response: AdmissionResponse, request: AdmissionRequest): Promise<Partial<Invitation>> {
     invariant(response.device);
     const { identityKey, haloSpaceKey, genesisFeedKey, controlTimeframe } = response.device;
 
@@ -104,6 +105,7 @@ export class DeviceInvitationProtocol implements InvitationProtocol {
     const { deviceKey, controlFeedKey, dataFeedKey, profile } = request.device;
 
     // TODO(wittjosiah): When multiple identities are supported, verify identity doesn't already exist before accepting.
+    // ctx is unused here because _acceptIdentity uses ServiceContext's lifecycle ctx internally.
 
     await this._acceptIdentity({
       identityKey,

package/src/packlets/invitations/edge-invitation-handler.ts

@@ -23,13 +23,14 @@ import {
   type AdmissionResponse,
   type SpaceAdmissionRequest,
 } from '@dxos/protocols/proto/dxos/halo/invitations';
+import { trace } from '@dxos/tracing';
 
 import { type InvitationProtocol } from './invitation-protocol';
 import { type FlowLockHolder, type GuardedInvitationState } from './invitation-state';
 import { tryAcquireBeforeContextDisposed } from './utils';
 
 export interface EdgeInvitationHandlerCallbacks {
-  onInvitationSuccess(response: AdmissionResponse, request: AdmissionRequest): Promise<void>;
+  onInvitationSuccess(ctx: Context, response: AdmissionResponse, request: AdmissionRequest): Promise<void>;
 }
 
 export const MAX_RETRIES_PER_INVITATION = 5;
@@ -41,6 +42,7 @@ export type EdgeInvitationConfig = {
   retryJitter?: number;
 };
 
+@trace.resource()
 export class EdgeInvitationHandler implements FlowLockHolder {
   private _flowLock: MutexGuard | undefined;
 
@@ -113,6 +115,7 @@ export class EdgeInvitationHandler implements FlowLockHolder {
     scheduleMicroTask(ctx, tryHandleInvitation);
   }
 
+  @trace.span({ op: 'invitation.edge' })
   private async _handleSpaceInvitationFlow(
     ctx: Context,
     guardedState: GuardedInvitationState,
@@ -132,7 +135,7 @@ export class EdgeInvitationHandler implements FlowLockHolder {
       });
 
       const admissionResponse = await this._mapToAdmissionResponse(response);
-      await this._callbacks.onInvitationSuccess(admissionResponse, { space: admissionRequest });
+      await this._callbacks.onInvitationSuccess(ctx, admissionResponse, { space: admissionRequest });
     } catch (error) {
       guardedState.set(this, Invitation.State.ERROR);
       throw error;

package/src/packlets/invitations/invitation-host-extension.ts

@@ -8,7 +8,7 @@ import { randomBytes, verify } from '@dxos/crypto';
 import { InvariantViolation, invariant } from '@dxos/invariant';
 import { PublicKey } from '@dxos/keys';
 import { log } from '@dxos/log';
-import { InvalidInvitationExtensionRoleError, trace } from '@dxos/protocols';
+import { InvalidInvitationExtensionRoleError } from '@dxos/protocols';
 import { schema } from '@dxos/protocols/proto';
 import { Invitation } from '@dxos/protocols/proto/dxos/client/services';
 import { type ProfileDocument } from '@dxos/protocols/proto/dxos/halo/credentials';
@@ -110,8 +110,7 @@ export class InvitationHostExtension
 
         introduce: async (request) => {
           const { profile, invitationId } = request;
-          const traceId = PublicKey.random().toHex();
-          log.trace('dxos.sdk.invitation-handler.host.introduce', trace.begin({ id: traceId }));
+          log('introducing host invitation');
 
           const invitation = this._requireActiveInvitation();
           this._assertInvitationState(Invitation.State.CONNECTED);
@@ -131,7 +130,7 @@ export class InvitationHostExtension
           this._challenge =
             invitation.authMethod === Invitation.AuthMethod.KNOWN_PUBLIC_KEY ? randomBytes(32) : undefined;
 
-          log.trace('dxos.sdk.invitation-handler.host.introduce', trace.end({ id: traceId }));
+          log('introduced host invitation');
           return {
             authMethod: invitation.authMethod,
             challenge: this._challenge,
@@ -139,8 +138,7 @@ export class InvitationHostExtension
         },
 
         authenticate: async ({ authCode: code, signedChallenge }) => {
-          const traceId = PublicKey.random().toHex();
-          log.trace('dxos.sdk.invitation-handler.host.authenticate', trace.begin({ id: traceId }));
+          log('authenticating host invitation');
 
           const invitation = this._requireActiveInvitation();
           log.verbose('received authentication request', { authCode: code });
@@ -201,13 +199,12 @@ export class InvitationHostExtension
             return { status };
           }
 
-          log.trace('dxos.sdk.invitation-handler.host.authenticate', trace.end({ id: traceId, data: { status } }));
+          log('authenticated host invitation', { status });
           return { status };
         },
 
         admit: async (request) => {
-          const traceId = PublicKey.random().toHex();
-          log.trace('dxos.sdk.invitation-handler.host.admit', trace.begin({ id: traceId }));
+          log('admitting guest');
           const invitation = this._requireActiveInvitation();
 
           try {
@@ -221,7 +218,7 @@ export class InvitationHostExtension
 
             const response = await this._callbacks.admit(request);
 
-            log.trace('dxos.sdk.invitation-handler.host.admit', trace.end({ id: traceId }));
+            log('admitted guest');
             return response;
           } catch (err: any) {
             this._callbacks.onError(err);

package/src/packlets/invitations/invitation-protocol.ts

@@ -2,6 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
+import { type Context } from '@dxos/context';
 import { type PublicKey } from '@dxos/keys';
 import type { Invitation } from '@dxos/protocols/proto/dxos/client/services';
 import type { DeviceProfileDocument, ProfileDocument } from '@dxos/protocols/proto/dxos/halo/credentials';
@@ -71,6 +72,9 @@ export interface InvitationProtocol {
 
   /**
    * Redeem the admission credential.
+   * @param ctx - Caller context used for tracing and cancellation. Forwarded to downstream
+   *   internal methods (e.g. `DataSpaceManager.acceptSpace`) so their spans become children of
+   *   the invitation flow span.
    */
-  accept(response: AdmissionResponse, request: AdmissionRequest): Promise<Partial<Invitation>>;
+  accept(ctx: Context, response: AdmissionResponse, request: AdmissionRequest): Promise<Partial<Invitation>>;
 }

package/src/packlets/invitations/invitation-state.ts

@@ -31,12 +31,6 @@ export const createGuardedInvitationState = (
   invitation: Invitation,
   stream: PushStream<Invitation>,
 ): GuardedInvitationState => {
-  // the mutex guards invitation flow on host and guest side, making sure only one flow is currently active
-  // deadlocks seem very unlikely because hosts don't initiate multiple connections
-  // even if this somehow happens that there are 2 guests (A, B) and 2 hosts (1, 2) and:
-  //  A has lock for flow with 1, B has lock for flow with 2
-  //  1 has lock for flow with B, 2 has lock for flow with A
-  // there'll be a 10-second introduction timeout after which connection will be closed and deadlock broken
   const mutex = new Mutex();
   let lastActiveLockHolder: FlowLockHolder | null = null;
   let currentInvitation = { ...invitation };
@@ -44,9 +38,6 @@ export const createGuardedInvitationState = (
     if (ctx.disposed || (lockHolder !== null && mutex.isLocked() && !lockHolder.hasFlowLock())) {
       return false;
     }
-    // don't allow transitions from a terminal state unless a new extension acquired mutex
-    // handles a case when error occurs (e.g. connection is closed) after we completed the flow
-    // successfully or already reported another error
     return lockHolder == null || lastActiveLockHolder !== lockHolder || isNonTerminalState(currentInvitation.state);
   };
   return {
@@ -54,7 +45,6 @@ export const createGuardedInvitationState = (
     get current() {
       return currentInvitation;
     },
-    // disposing context prevents any further state updates
     complete: (newState: Partial<Invitation>) => {
       logStateUpdate(currentInvitation, undefined, invitation.state);
       currentInvitation = { ...currentInvitation, ...newState };
@@ -94,11 +84,7 @@ const logStateUpdate = (invitation: Invitation, actor: any, newState: Invitation
     error: error?.message,
     errorStack: error?.stack,
   };
-  if (isNonTerminalState(newState)) {
-    log.verbose('dxos.sdk.invitations-handler.state.update', logContext);
-  } else {
-    log.info('dxos.sdk.invitations-handler.state.update', logContext);
-  }
+  log.verbose('dxos.sdk.invitations-handler.state.update', logContext);
 };
 
 const isNonTerminalState = (currentState: Invitation.State): boolean => {

package/src/packlets/invitations/invitations-handler.ts

@@ -11,7 +11,7 @@ import { invariant } from '@dxos/invariant';
 import { PublicKey } from '@dxos/keys';
 import { log } from '@dxos/log';
 import { type SwarmConnection, type SwarmNetworkManager, createTeleportProtocolFactory } from '@dxos/network-manager';
-import { InvalidInvitationError, InvalidInvitationExtensionRoleError, trace } from '@dxos/protocols';
+import { InvalidInvitationError, InvalidInvitationExtensionRoleError } from '@dxos/protocols';
 import { type AdmissionKeypair, Invitation } from '@dxos/protocols/proto/dxos/client/services';
 import { type DeviceProfileDocument } from '@dxos/protocols/proto/dxos/halo/credentials';
 import { AuthenticationResponse, type IntroductionResponse } from '@dxos/protocols/proto/dxos/halo/invitations';
@@ -64,6 +64,7 @@ export type InvitationConnectionProps = {
  *  TODO: the flow logic should either be contained in invitations-handler or in extensions, not be split across
  *  TODO: potentially re-evaluate host-side API to allow multiple concurrent connection, so that mutex can be removed
  */
+@_trace.resource()
 export class InvitationsHandler {
   /**
    * @internal
@@ -87,6 +88,33 @@ export class InvitationsHandler {
       type: invitation.type,
     });
     metrics.increment('dxos.invitation.host');
+
+    const hostSpanId = `invitation-host-${invitation.invitationId}`;
+    // Reassign ctx to the child context so downstream `@trace.span` calls stay in the same trace.
+    // Link child -> parent disposal so `ctx.dispose()` inside this flow still completes the
+    // invitation stream (the caller's ctx owns `stream.complete()` via onDispose).
+    // Do NOT await `invitationCtx.dispose()` here: `derive()` registers a parent -> child
+    // dispose hook, so awaiting the parent dispose would re-enter the still-pending child
+    // dispose promise and deadlock.
+    const invitationCtx = ctx;
+    ctx =
+      _trace.spanStart({
+        id: hostSpanId,
+        instance: this,
+        methodName: 'handleInvitationFlow',
+        parentCtx: ctx,
+        op: 'invitation.host',
+        attributes: {
+          'ctx.dxos.invitation.id': invitation.invitationId,
+          'ctx.dxos.invitation.kind': Invitation.Kind[invitation.kind],
+        },
+      }) ?? ctx;
+    if (ctx !== invitationCtx) {
+      ctx.onDispose(() => {
+        void invitationCtx.dispose();
+      });
+    }
+    ctx.onDispose(() => _trace.spanEnd(hostSpanId));
     const guardedState = createGuardedInvitationState(ctx, invitation, stream);
     // Called for every connecting peer.
     const createExtension = (): InvitationHostExtension => {
@@ -132,15 +160,14 @@ export class InvitationsHandler {
           });
 
           scheduleTask(connectionCtx, async () => {
-            const traceId = PublicKey.random().toHex();
             try {
-              log.trace('dxos.sdk.invitations-handler.host.onOpen', trace.begin({ id: traceId }));
+              log('opening host invitation handler');
               log.verbose('connected', { ...protocol.toJSON() });
               const deviceKey = await extension.completedTrigger.wait({ timeout: invitation.timeout });
               log.verbose('admitted guest', { guest: deviceKey, ...protocol.toJSON() });
               guardedState.set(extension, Invitation.State.SUCCESS);
               metrics.increment('dxos.invitation.success');
-              log.trace('dxos.sdk.invitations-handler.host.onOpen', trace.end({ id: traceId }));
+              log('host invitation handler opened');
               admitted = true;
 
               if (!invitation.multiUse) {
@@ -159,7 +186,6 @@ export class InvitationsHandler {
                   log.error('failed', err);
                 }
               }
-              log.trace('dxos.sdk.invitations-handler.host.onOpen', trace.error({ id: traceId, error: err }));
               // Close connection
               extensionsCtx.close(err);
             }
@@ -232,6 +258,34 @@ export class InvitationsHandler {
     });
     const { timeout = INVITATION_TIMEOUT } = invitation;
 
+    const guestSpanId = `invitation-guest-${invitation.invitationId}`;
+    // Reassign ctx to the child context returned by spanStart so downstream calls
+    // (`edgeInvitationHandler.handle`, `_joinSwarm`, etc.) inherit this span as their
+    // parent rather than starting a new root trace.
+    // Link child -> parent disposal so `ctx.dispose()` inside this flow still completes the
+    // invitation stream. See note in `handleInvitationFlow`: must not await the parent
+    // dispose here (`derive()` registers a parent -> child dispose hook, so awaiting would
+    // re-enter the still-pending child dispose promise and deadlock).
+    const invitationCtx = ctx;
+    ctx =
+      _trace.spanStart({
+        id: guestSpanId,
+        instance: this,
+        methodName: 'acceptInvitation',
+        parentCtx: ctx,
+        op: 'invitation.guest',
+        attributes: {
+          'ctx.dxos.invitation.id': invitation.invitationId,
+          'ctx.dxos.invitation.kind': Invitation.Kind[invitation.kind],
+        },
+      }) ?? ctx;
+    if (ctx !== invitationCtx) {
+      ctx.onDispose(() => {
+        void invitationCtx.dispose();
+      });
+    }
+    ctx.onDispose(() => _trace.spanEnd(guestSpanId));
+
     if (deviceProfile) {
       invariant(invitation.kind === Invitation.Kind.DEVICE, 'deviceProfile provided for non-device invitation');
     }
@@ -279,9 +333,8 @@ export class InvitationsHandler {
           });
 
           scheduleTask(connectionCtx, async () => {
-            const traceId = PublicKey.random().toHex();
             try {
-              log.trace('dxos.sdk.invitations-handler.guest.onOpen', trace.begin({ id: traceId }));
+              log('opening guest invitation handler');
 
               scheduleTask(
                 connectionCtx,
@@ -345,7 +398,7 @@ export class InvitationsHandler {
               admitted = true;
 
               // 4. Record credential in our HALO.
-              const result = await protocol.accept(admissionResponse, admissionRequest);
+              const result = await protocol.accept(ctx, admissionResponse, admissionRequest);
 
               // 5. Success.
               log.verbose('dxos.sdk.invitations-handler.guest.admitted-by-host', {
@@ -357,7 +410,7 @@ export class InvitationsHandler {
                 ...result,
                 state: Invitation.State.SUCCESS,
               });
-              log.trace('dxos.sdk.invitations-handler.guest.onOpen', trace.end({ id: traceId }));
+              log('guest invitation handler opened');
             } catch (err: any) {
               if (err instanceof TimeoutError) {
                 log.verbose('timeout', { ...protocol.toJSON() });
@@ -367,7 +420,6 @@ export class InvitationsHandler {
                 guardedState.error(extension, err);
               }
               extensionCtx.close(err);
-              log.trace('dxos.sdk.invitations-handler.guest.onOpen', trace.error({ id: traceId, error: err }));
             }
           });
         },
@@ -389,8 +441,8 @@ export class InvitationsHandler {
     };
 
     const edgeInvitationHandler = new EdgeInvitationHandler(this._connectionProps?.edgeInvitations, this._edgeClient, {
-      onInvitationSuccess: async (admissionResponse, admissionRequest) => {
-        const result = await protocol.accept(admissionResponse, admissionRequest);
+      onInvitationSuccess: async (edgeCtx, admissionResponse, admissionRequest) => {
+        const result = await protocol.accept(edgeCtx, admissionResponse, admissionRequest);
         log.info('admitted by edge', { ...protocol.toJSON() });
         guardedState.complete({ ...guardedState.current, ...result, state: Invitation.State.SUCCESS });
       },

package/src/packlets/invitations/invitations-manager.ts

@@ -50,7 +50,7 @@ export class InvitationsManager {
     private readonly _metadataStore: MetadataStore,
   ) {}
 
-  @trace.span({ showInBrowserTimeline: true })
+  @trace.span({ showInBrowserTimeline: true, op: 'lifecycle' })
   async createInvitation(
     ctx: Context,
     options: Partial<Invitation> & Pick<Invitation, 'kind'>,
@@ -125,7 +125,7 @@ export class InvitationsManager {
     }
   }
 
-  acceptInvitation(_ctx: Context, request: AcceptInvitationRequest): AuthenticatingInvitation {
+  acceptInvitation(ctx: Context, request: AcceptInvitationRequest): AuthenticatingInvitation {
     const options = request.invitation;
     const existingInvitation = this._acceptInvitations.get(options.invitationId);
     if (existingInvitation) {
@@ -138,7 +138,7 @@ export class InvitationsManager {
       invitation,
       stream,
       otpEnteredTrigger,
-    } = this._createObservableAcceptingInvitation(handler, options);
+    } = this._createObservableAcceptingInvitation(ctx, handler, options);
     this._invitationsHandler.acceptInvitation(
       invitationCtx,
       stream,
@@ -281,6 +281,7 @@ export class InvitationsManager {
   }
 
   private _createObservableAcceptingInvitation(
+    parentCtx: Context,
     handler: InvitationProtocol,
     initialState: Invitation,
   ): {
@@ -291,7 +292,8 @@ export class InvitationsManager {
   } {
     const otpEnteredTrigger = new Trigger<string>();
     const stream = new PushStream<Invitation>();
-    const ctx = new Context({
+    // Derive from caller ctx so `TRACE_SPAN_ATTRIBUTE` propagates via the parent chain.
+    const ctx = parentCtx.derive({
       onError: (err) => {
         if (err instanceof TimeoutError) {
           log('timeout', { ...handler.toJSON() });