@astrale-os/cli 1.0.0-beta.3 → 1.0.0-beta.31

package/src/commands/view.ts

@@ -19,6 +19,7 @@ import { fatal, log } from '../lib/log'
 import { isMachine, output, type RawOutputOpts } from '../lib/output'
 import { findFreePort } from '../lib/port'
 import { run, spawnHandle } from '../lib/proc'
+import { admitExternalOpenOrigins } from '../lib/view/external-open-origins'
 import { withViewPortAllocationLock } from '../lib/view/port-allocation'
 import {
   candidateSlug,
@@ -42,7 +43,7 @@ import {
 import { snapshotText, waitForSettledSnapshot } from '../lib/view/snapshot'
 
 /**
- * `astrale view` — open ONE view in an emulated host shell, authenticated as
+ * `astrale view` — open ONE view in a local browser shell, authenticated as
  * the CLI identity, driveable by agent-browser (default) or a real browser.
  * Design + protocol details: VIEW_CLI_SPEC.md at the workspace root.
  */
@@ -62,6 +63,7 @@ type ViewOpts = KernelCommandOpts &
     sessions?: boolean
     close?: string | boolean
     all?: boolean
+    allowExternalOrigin?: string[]
   }
 
 const VIEW_PORT_BASE = 4419
@@ -89,9 +91,10 @@ export async function resolveSession(
   }
   const targetInput =
     parsed.kind === 'target' ? parsed.path : (opts.target ?? viewOwnerTarget(parsed.path))
-  const { path: target } = await expandSelfInPath(targetInput, opts)
-
-  const candidates = await withClientSession(opts, (ctx) => resolveViewCandidates(ctx, target))
+  const { target, candidates } = await withClientSession(opts, async (context) => {
+    const { path: target } = await expandSelfInPath(targetInput, context)
+    return { target, candidates: await resolveViewCandidates(context, target) }
+  })
 
   if (opts.list) {
     return { candidates }
@@ -150,16 +153,47 @@ async function chooseCandidate(
  * die once the CLI exits. The published CLI entry is node-runnable; a dev
  * checkout builds `dist/astrale.js` on demand (Bun is present there).
  */
-async function resolveServeRuntime(): Promise<{ file: string; args: string[] }> {
-  const entry = process.argv[1]
-  const node = await findOnPath('node')
-  if (node && entry?.endsWith('.js') && existsSync(entry)) return { file: node, args: [entry] }
+interface ServeRuntimeEnvironment {
+  readonly entry: string | undefined
+  readonly executable: string
+  readonly exists: typeof existsSync
+  readonly find: typeof findOnPath
+}
+
+export async function resolveServeRuntime(
+  environment: Partial<ServeRuntimeEnvironment> = {},
+): Promise<{ file: string; args: string[] }> {
+  const entry = environment.entry ?? process.argv[1]
+  const executable = environment.executable ?? process.execPath
+  const exists = environment.exists ?? existsSync
+  const find = environment.find ?? findOnPath
+  const node = await find('node')
+  if (node && entry?.endsWith('.js') && exists(entry)) return { file: node, args: [entry] }
   if (node && entry?.endsWith('.ts')) {
     const dist = join(dirname(entry), '..', 'dist', 'astrale.js')
     await ensureDevDist(entry, dist)
-    if (existsSync(dist)) return { file: node, args: [dist] }
+    if (exists(dist)) return { file: node, args: [dist] }
+  }
+  return directServeRuntime(executable, entry, entry !== undefined && exists(entry))
+}
+
+/** Reinvoke a compiled executable without its virtual Bun filesystem entry. */
+export function directServeRuntime(
+  executable: string,
+  entry: string | undefined,
+  entryExists = entry !== undefined && existsSync(entry),
+): { file: string; args: string[] } {
+  return {
+    file: executable,
+    args: entry && !entry.startsWith('/$bunfs/') && entryExists ? [entry] : [],
   }
-  return { file: process.execPath, args: entry && existsSync(entry) ? [entry] : [] }
+}
+
+export function viewServeInvocation(
+  runtime: { file: string; args: string[] },
+  config: string,
+): { file: string; args: string[] } {
+  return { file: runtime.file, args: [...runtime.args, '__view-serve', '--config', config] }
 }
 
 async function findOnPath(name: string): Promise<string | null> {
@@ -228,6 +262,31 @@ async function startSession(view: ResolvedView, opts: ViewOpts): Promise<ViewSes
   )
 }
 
+export function createViewServeConfig(
+  record: ViewSessionRecord,
+  opts: Pick<ViewOpts, 'allowExternalOrigin' | 'as' | 'creds' | 'instance' | 'timeout' | 'url'>,
+  kernelTarget: { url: string; kernelIssuer: string; caFile?: string },
+): ViewServeConfig {
+  return {
+    session: record,
+    kernel: {
+      url: opts.url,
+      instance: opts.instance,
+      as: opts.as,
+      creds: opts.creds,
+      timeout: opts.timeout,
+    },
+    proxy: {
+      kernelUrl: kernelTarget.url,
+      issuer: kernelTarget.kernelIssuer,
+      caFile: kernelTarget.caFile,
+      direct: isPublicHttps(kernelTarget.url) && !kernelTarget.caFile,
+    },
+    externalOrigins: admitExternalOpenOrigins(opts.allowExternalOrigin),
+    idleMs: IDLE_MS,
+  }
+}
+
 /**
  * Called under the cross-process port-allocation lock. Keep the lock until the
  * detached child answers its readiness probe: only then is the selected port
@@ -261,34 +320,15 @@ async function startSessionLocked(
     identity: opts.creds ? '(pre-signed creds)' : (opts.as ?? defaultIdentity),
     createdAt: new Date().toISOString(),
   }
-  const serveConfig: ViewServeConfig = {
-    session: record,
-    kernel: {
-      url: opts.url,
-      instance: opts.instance,
-      as: opts.as,
-      creds: opts.creds,
-      timeout: opts.timeout,
-    },
-    proxy: {
-      kernelUrl: kernelTarget.url,
-      issuer: kernelTarget.kernelIssuer,
-      caFile: kernelTarget.caFile,
-      direct: isPublicHttps(kernelTarget.url) && !kernelTarget.caFile,
-    },
-    idleMs: IDLE_MS,
-  }
+  const serveConfig = createViewServeConfig(record, opts, kernelTarget)
 
   await saveServeConfig(serveConfig)
   const logFd = await openSessionLog(id)
-  const child = spawnHandle(
-    runtime.file,
-    [...runtime.args, '__view-serve', '--config', configPath(id)],
-    {
-      detached: true,
-      stdio: ['ignore', logFd, logFd],
-    },
-  )
+  const invocation = viewServeInvocation(runtime, configPath(id))
+  const child = spawnHandle(invocation.file, invocation.args, {
+    detached: true,
+    stdio: ['ignore', logFd, logFd],
+  })
   child.unref()
   closeSync(logFd)
   if (!child.pid) throw new Error('Failed to spawn the view session server')
@@ -484,7 +524,7 @@ async function sessionsCommand(opts: ViewOpts): Promise<void> {
 
 export default {
   name: 'view',
-  description: 'Open one view in an emulated host shell your agent can drive',
+  description: 'Open one view in a local browser shell your agent can drive',
   arguments: [
     {
       name: 'spec',
@@ -520,11 +560,15 @@ export default {
       description: 'Close a view session (bare: the only open one; with --all: every session)',
     },
     { flags: '--all', description: 'With --close: close every session' },
+    {
+      flags: '--allow-external-origin <origin...>',
+      description: 'Grant this View exact HTTPS origins it may open in a new browser context',
+    },
   ],
   afterHelpText: `
 What it does:
   Renders ONE view — no GUI, no cookies, no WorkOS. It resolves the view on the
-  kernel, starts a loopback session server that emulates the shell host (real
+  kernel, starts a loopback session server that supplies the shell handshake (real
   handshake via @astrale-os/shell, token minted from YOUR CLI identity, kernel
   calls proxied), and opens the page headless in agent-browser. Driving stays
   agent-browser's job; auth follows --as/--creds/-i like any kernel command.
@@ -538,6 +582,7 @@ Examples:
   $ astrale view /:crm.example.dev:view.dashboard
   $ astrale view /:agents.astrale.ai:view.agent --target @f00d1234 --as alice
   $ astrale view @customer --snapshot
+  $ astrale view /:integrations.astrale.ai:view.application --allow-external-origin https://connect.nango.dev https://connect.composio.dev
   $ astrale view --list
   $ astrale view --sessions ; astrale view --close --all
 `,

package/src/connection/.spec/api.d.ts

@@ -1,8 +1,7 @@
-import type { Call } from '@astrale-os/kernel-client'
-import type { AuthApi } from '@astrale-os/kernel-client/auth'
-import type { GraphApi } from '@astrale-os/kernel-client/graph'
-import type { ClientSession } from '@astrale-os/kernel-client/session'
 import type { IssuerId } from '@astrale-os/sdk/auth'
+import type { AuthApi } from '@astrale-os/sdk/auth'
+import type { Call, GraphApi } from '@astrale-os/sdk/client'
+import type { ClientSession } from '@astrale-os/sdk/client/session'
 
 /** Existing CLI connection flags accepted by Kernel-touching commands. */
 export interface ConnectionOptions {
@@ -78,17 +77,17 @@ export function withAdminClientSession<Value>(
 /** Expand @self through the effective principal returned by authenticated Identity.whoami. */
 export function expandSelfInPath(
   path: string,
-  options: KernelCommandOpts,
+  context: ConnectionContext,
 ): Promise<{ readonly path: string; readonly meta?: SelfExpansionMeta }>
 
 /** Expand @self once across one Call path and its CLI-authored string parameters. */
 export function expandSelfInCall(
   path: string,
-  parameters: readonly string[],
-  options: KernelCommandOpts,
+  parameters: Readonly<Record<string, unknown>>,
+  context: ConnectionContext,
 ): Promise<{
   readonly path: string
-  readonly parameters: readonly string[]
+  readonly parameters: Readonly<Record<string, unknown>>
   readonly meta?: SelfExpansionMeta
 }>
 

package/src/connection/.spec/architecture.md

@@ -28,7 +28,15 @@ selection, and the single safe stale-route recovery. The CLI does not reproduce
 discover destination identity. `SessionAuth.resolve(call, signal)` returns source-Kernel authority and
 ClientSession supplies an audience-free Delegate with omitted attenuation, preserving the exact
 current Grant for routing. Connection itself persists no credential or route; the separate state
-owner persists only exchanged source credentials.
+owner persists exchanged source credentials and the separate Kernel Client route artifact. A valid exchanged credential is selected by the
+authenticated source issuer and subject before any live `whoami`; cache misses alone resolve the
+registered Kernel User and perform delegation plus Domain exchange.
+Exchange authority is bounded to five minutes and never outlives the current source credential,
+matching the CLI route-age ceiling without forcing an unrelated two-minute refresh cycle.
+
+Every ClientSession receives the CLI-owned `state/session-routes` representation capability. Kernel
+Client still owns route keying, admission, expiry, and one safe stale/miss recovery; Connection does
+not reproduce routing or add an Admin-only bypass.
 
 `--anonymous` deliberately suppresses ambient and bookmark-default identities by omitting the
 `SessionAuth` capability. It cannot be combined with `--as` or `--creds`; contradictory selections fail
@@ -40,7 +48,8 @@ customizes only the Fetch capability passed to Client. `withClientSession` and
 `withAdminClientSession` are terminal lifecycle boundaries: success, failure, and cancellation all
 close both the Client Session and its direct source-Auth client.
 
-The command boundary maps typed Client transport phase and delivery evidence without inspecting a
-private cause message. It preserves every admitted Kernel reason in machine output; human repair
-details are rendered only after the connection owner admits bounded public Function issues or one
-exact Query reason variant.
+The command boundary projects typed Client failure identity, transport context, phase, and
+invocation-only delivery evidence without inspecting a private cause message. Unknown native
+failures become one honest unexpected diagnostic; their bounded cause graph is visible only under
+explicit debug output. Every admitted Kernel reason remains available in machine output, while
+human repair details require a bounded public Function issue or exact Query reason variant.

package/src/connection/.spec/flows/session.ts

@@ -1,5 +1,5 @@
-import type { SessionAuth } from '@astrale-os/kernel-client/session'
-import type { Call } from '@astrale-os/kernel-protocol/invocation'
+import type { Call } from '@astrale-os/sdk/client'
+import type { SessionAuth } from '@astrale-os/sdk/client/session'
 
 import type { ConnectionContext, ConnectionOptions, ConnectionTarget } from '../api.js'
 

package/src/connection/.spec/laws/connection.ts

@@ -111,7 +111,7 @@ export const CLI_AUTH_REGISTRATION_TARGET = defineLaw({
 export const CLI_SELF_AUTHENTICATED_PRINCIPAL = defineLaw({
   id: 'CLI-SELF-AUTHENTICATED-PRINCIPAL',
   statement:
-    '@self resolves only from authenticated Identity.whoami on the selected target, so delegated carriers use their effective principal and never an unverified JWT subject or stale local registration.',
+    '@self resolves inside the command-owned Client Session from authenticated Identity.whoami on the selected target, so resolution and dispatch share one lifecycle and delegated carriers never use an unverified JWT subject or stale local registration.',
   tests: [
     {
       file: '__tests__/self.test.ts',
@@ -183,7 +183,7 @@ export const CLI_CONNECTION_PUBLIC_SEMANTIC_REASON = defineLaw({
 export const CLI_CONNECTION_TYPED_ERROR_PRESENTATION = defineLaw({
   id: 'CLI-CONNECTION-TYPED-ERROR-PRESENTATION',
   statement:
-    'The command boundary maps typed Client transport phase and delivery evidence without parsing a private cause, preserves the admitted Kernel reason in machine output, and renders only bounded public Function issues or one exact Query repair variant for humans.',
+    'The command boundary maps typed Client failure identity, transport context, phase, and invocation-only delivery evidence without parsing a private cause; acquisition never receives retry advice, unknown native failures have one non-blank unexpected diagnostic, and raw causes appear only under explicit debug output.',
   tests: [
     {
       file: '__tests__/errors.test.ts',
@@ -197,5 +197,9 @@ export const CLI_CONNECTION_TYPED_ERROR_PRESENTATION = defineLaw({
       file: '__tests__/reasons.test.ts',
       id: 'TEST-CLI-CONNECTION-ADMITS-BOUNDED-REASONS',
     },
+    {
+      file: '__tests__/failure-safety.test.ts',
+      id: 'TEST-CLI-CONNECTION-FAILURE-SAFETY',
+    },
   ],
 })

package/src/connection/.spec/layout.ts

@@ -8,6 +8,7 @@ export default defineLayout({
     'command.ts',
     'credential.ts',
     'errors.ts',
+    'failure/',
     'exchange.ts',
     'index.ts',
     'reasons.ts',

package/src/connection/__tests__/auth.test.ts

@@ -15,6 +15,7 @@ const config: AstraleConfig = {
     kernelIssuer: 'https://admin.eu.astrale.ai/api',
   },
   telemetry: { enabled: true },
+  browser: {},
 }
 
 describe('resolveKeyIdentityAuthOptions', () => {

package/src/connection/__tests__/credential.test.ts

@@ -1,4 +1,4 @@
-import type { SessionAuth } from '@astrale-os/kernel-client/session'
+import type { SessionAuth } from '@astrale-os/sdk/client/session'
 
 import { issuer, type IssuerId } from '@astrale-os/sdk/auth'
 import { Path } from '@astrale-os/sdk/graph/path'
@@ -6,6 +6,7 @@ import { describe, expect, test } from 'bun:test'
 
 import type { AstraleConfig } from '../../lib/config'
 
+import { bindCredentialIdentity } from '../auth'
 import { createCliCredential, createConnectionCredential } from '../credential'
 
 const SOURCE = issuer.accept('https://kernel.example')
@@ -17,9 +18,28 @@ const config: AstraleConfig = {
   issuer: 'https://cli.example',
   admin: { name: 'admin', url: SOURCE, kernelIssuer: SOURCE },
   telemetry: { enabled: false },
+  browser: {},
 }
 
 describe('connection credential', () => {
+  test('pins the bookmark identity while leaving explicit credentials unnamed', async () => {
+    const target = {
+      url: `${SOURCE}/invoke`,
+      kernelIssuer: SOURCE,
+      defaultIdentity: 'bookmark-owner',
+    }
+
+    await expect(bindCredentialIdentity({}, target)).resolves.toMatchObject({
+      as: 'bookmark-owner',
+    })
+    await expect(bindCredentialIdentity({ as: 'explicit-owner' }, target)).resolves.toEqual({
+      as: 'explicit-owner',
+    })
+    await expect(bindCredentialIdentity({ creds: 'opaque' }, target)).resolves.toEqual({
+      creds: 'opaque',
+    })
+  })
+
   /** @evidence TEST-CLI-CONNECTION-RESOLVES-SOURCE-AUTH-BEFORE-ROUTING */
   test('resolves source authority without destination knowledge', async () => {
     const audiences: IssuerId[] = []

package/src/connection/__tests__/errors.test.ts

@@ -1,7 +1,9 @@
-import { ResponseError, TransportError } from '@astrale-os/kernel-client'
+import { ResponseError } from '@astrale-os/sdk/client'
+import { Path } from '@astrale-os/sdk/graph/path'
 import { describe, expect, test } from 'bun:test'
 
 import { formatKernelError, functionInputIssues, schemaUpgradeHint } from '../errors'
+import { transportFailure } from './failure-fixtures'
 
 const CONFLICT = 4001
 const VALIDATION = 1003
@@ -19,24 +21,28 @@ describe('formatKernelError', () => {
       writes.push(typeof chunk === 'string' ? chunk : new TextDecoder().decode(chunk))
       return true
     }) as typeof process.stderr.write
-    const error = new TransportError('Publication discovery request failed.', {
-      cause: Object.assign(new Error('connect ECONNREFUSED'), { code: 'ECONNREFUSED' }),
-      phase: 'connect',
-      delivery: 'unknown',
-    }) as TransportError & { url?: string }
-    error.url = 'https://localhost:8443/kernel/host'
+    const error = Object.assign(
+      transportFailure('Publication discovery request failed.', 'unknown', {
+        kind: 'acquisition',
+        resource: 'publication',
+      }),
+      {
+        url: 'https://localhost:8443/kernel/host',
+        cause: Object.assign(new Error('connect ECONNREFUSED'), { code: 'ECONNREFUSED' }),
+      },
+    )
     try {
-      await formatKernelError(error, true)
+      await formatKernelError(error, true, 'https://localhost:8443/kernel/host')
     } finally {
       process.stderr.write = original
     }
 
     expect(JSON.parse(writes[0]!)).toMatchObject({
-      error: 'CONNECTION_ERROR',
+      error: 'TRANSPORT_ERROR',
       message: 'Publication discovery request failed.',
       url: 'https://localhost:8443/kernel/host',
-      phase: 'connect',
-      delivery: 'unknown',
+      phase: 'unknown',
+      transport: { kind: 'acquisition', resource: 'publication' },
     })
     expect(writes[0]).not.toContain('ECONNREFUSED')
   })
@@ -50,9 +56,8 @@ describe('formatKernelError', () => {
     }) as typeof process.stderr.write
     try {
       await formatKernelError(
-        new TransportError('Request timed out.', {
-          cause: new Error('timeout'),
-          phase: 'timeout',
+        transportFailure('Request timed out.', 'timeout', {
+          kind: 'invocation',
           delivery: 'unknown',
         }),
         true,
@@ -74,7 +79,7 @@ describe('formatKernelError', () => {
     expect(JSON.parse(writes[0]!)).toMatchObject({
       error: 'TIMEOUT',
       phase: 'timeout',
-      delivery: 'unknown',
+      transport: { kind: 'invocation', delivery: 'unknown' },
       operation: '4a4c9a18-50f6-4d84-a7b7-2d83e3e45dc8',
       retry:
         'astrale domain install https://crm.test --direct --operation 4a4c9a18-50f6-4d84-a7b7-2d83e3e45dc8',
@@ -229,7 +234,7 @@ describe('formatKernelError', () => {
     )
   })
 
-  test('maps SDK class names to stable CLI error codes', async () => {
+  test('maps SDK error identities to stable CLI error codes', async () => {
     const writes: string[] = []
     const original = process.stderr.write
     process.stderr.write = ((chunk: string | Uint8Array) => {
@@ -237,15 +242,17 @@ describe('formatKernelError', () => {
       return true
     }) as typeof process.stderr.write
     try {
-      const pathError = new Error('Path must have an Id or Domain anchor.')
-      pathError.name = 'PathError'
-      await formatKernelError(pathError, true)
+      try {
+        Path.parse('not-a-path')
+      } catch (error) {
+        await formatKernelError(error, true)
+      }
     } finally {
       process.stderr.write = original
     }
     expect(JSON.parse(writes[0]!)).toEqual({
       error: 'PATH_INVALID',
-      message: 'Path must have an Id or Domain anchor.',
+      message: expect.any(String),
     })
   })
 

package/src/connection/__tests__/exchange.test.ts

@@ -1,4 +1,4 @@
-import type { Fetch } from '@astrale-os/kernel-client'
+import type { Fetch } from '@astrale-os/sdk/client'
 
 import { issuer } from '@astrale-os/sdk/auth'
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
@@ -14,13 +14,8 @@ const DOMAIN = issuer.accept('https://admin.example')
 const TARGET = { url: `${KERNEL}/api`, kernelIssuer: KERNEL, domainIssuer: DOMAIN }
 const INVOCATION = `${KERNEL}/invoke`
 const EXPIRES_AT = Math.floor(Date.now() / 1_000) + 500
-const SOURCE_EXPIRES_AT = Math.floor(Date.now() / 1_000) + 120
-const SOURCE_TOKEN = token(
-  issuer.accept('https://workos.example'),
-  KERNEL,
-  'user-1',
-  SOURCE_EXPIRES_AT,
-)
+const SOURCE_EXPIRES_AT = Math.floor(Date.now() / 1_000) + 600
+const SOURCE_TOKEN = sourceToken('user-1')
 let directory: string
 
 beforeEach(async () => {
@@ -33,7 +28,7 @@ afterEach(async () => {
 
 describe('Domain token exchange', () => {
   /** @evidence TEST-CLI-EXCHANGE-WHOAMI-DELEGATE-EXCHANGE-CACHE */
-  test('runs the exact User to Kernel to Domain journey and reuses the bound token', async () => {
+  test('runs the exact User to Kernel to Domain journey once and reuses it before whoami', async () => {
     const observed: Array<{
       url: string
       init: RequestInit | undefined
@@ -91,7 +86,7 @@ describe('Domain token exchange', () => {
     await expect(resolver.resolve(KERNEL, new AbortController().signal)).resolves.toBe(exchanged)
 
     const kernelRequests = observed.filter((entry) => entry.url === INVOCATION)
-    expect(kernelRequests).toHaveLength(3)
+    expect(kernelRequests).toHaveLength(2)
     expect(kernelRequests[0]!.body).toMatchObject({
       credential: SOURCE_TOKEN,
       call: { input: {} },
@@ -107,13 +102,32 @@ describe('Domain token exchange', () => {
     })
     const delegatedTtl = kernelRequests[1]!.body!.call.input.ttlSeconds
     expect(delegatedTtl).toBeGreaterThan(0)
-    expect(delegatedTtl).toBeLessThan(120)
+    expect(delegatedTtl).toBeGreaterThanOrEqual(295)
+    expect(delegatedTtl).toBeLessThanOrEqual(300)
     expect(sourceAudiences).toEqual([KERNEL, KERNEL])
     expect(
       observed.filter((entry) => entry.url.endsWith('/.well-known/astrale/token')),
     ).toHaveLength(1)
   })
 
+  test('rejects a source credential without a stable cache identity before network I/O', async () => {
+    let fetches = 0
+    const resolver = createExchangeCredentialResolver(
+      TARGET,
+      { resolve: async () => sourceToken(undefined) },
+      async () => {
+        fetches += 1
+        throw new Error('network must remain untouched')
+      },
+      5_000,
+      new ExchangeCredentialCache(join(directory, 'credentials.json')),
+    )
+    await expect(resolver.resolve(KERNEL, new AbortController().signal)).rejects.toMatchObject({
+      code: 'TOKEN_EXCHANGE_SOURCE_INVALID',
+    })
+    expect(fetches).toBe(0)
+  })
+
   /** @evidence TEST-CLI-EXCHANGE-NO-LEGACY-FALLBACK */
   test('fails closed when issuer discovery does not advertise exchange', async () => {
     const fetch: Fetch = async (input, init) => {
@@ -190,6 +204,35 @@ describe('Domain token exchange', () => {
       message: 'Token exchange returned an invalid success response.',
     })
   })
+
+  test('normalizes native issuer Fetch failures without exposing their message', async () => {
+    const native = new AggregateError([new Error('private DNS state')], '')
+    const resolver = createExchangeCredentialResolver(
+      TARGET,
+      { resolve: async () => SOURCE_TOKEN },
+      async (input, init) => {
+        if (String(input) === INVOCATION) {
+          const body = JSON.parse(await new Response(init?.body).text()) as Record<string, any>
+          return invocationResponse(
+            body.requestId,
+            body.call.input && Object.keys(body.call.input).length === 0
+              ? { id: 'user-1' }
+              : 'kernel-destination-envelope',
+            new Headers(init?.headers).get('accept')!,
+          )
+        }
+        throw native
+      },
+      5_000,
+      new ExchangeCredentialCache(join(directory, 'native-failure.json')),
+    )
+
+    await expect(resolver.resolve(KERNEL, new AbortController().signal)).rejects.toMatchObject({
+      code: 'TOKEN_EXCHANGE_UNAVAILABLE',
+      message: 'Domain issuer discovery could not be reached.',
+      cause: native,
+    })
+  })
 })
 
 function exchangeFetch(
@@ -264,3 +307,13 @@ function token(iss: string, aud: string, user: string, exp: number): string {
     grant: { v: 1, expr: { kind: 'identity', credential: proof } },
   })}.signature`
 }
+
+function sourceToken(subject: string | undefined): string {
+  const encode = (value: unknown) => Buffer.from(JSON.stringify(value)).toString('base64url')
+  return `${encode({ alg: 'EdDSA', typ: 'JWT' })}.${encode({
+    iss: 'https://workos.example',
+    ...(subject === undefined ? {} : { sub: subject }),
+    aud: KERNEL,
+    exp: SOURCE_EXPIRES_AT,
+  })}.signature`
+}

package/src/connection/__tests__/failure-fixtures.ts

@@ -0,0 +1,39 @@
+import { ClientError, TransportError } from '@astrale-os/sdk/client'
+
+import type { TransportDiagnosticContext } from '../failure/model'
+
+type CompatibleTransportPhase = TransportError['phase'] | 'unknown'
+
+export function transportFailure(
+  message: string,
+  phase: CompatibleTransportPhase,
+  context: TransportDiagnosticContext,
+): TransportError {
+  const error = new Error(message) as TransportError & {
+    context: TransportDiagnosticContext
+  }
+  Object.setPrototypeOf(error, TransportError.prototype)
+  Object.assign(error, { name: 'TransportError', phase, context })
+  return error
+}
+
+export function legacyTransportFailure(
+  message: string,
+  phase: CompatibleTransportPhase,
+  delivery: 'not-sent' | 'unknown',
+): TransportError {
+  const error = new Error(message) as TransportError & { delivery: typeof delivery }
+  Object.setPrototypeOf(error, TransportError.prototype)
+  Object.assign(error, { name: 'TransportError', phase, delivery })
+  return error
+}
+
+export function sessionFailure(
+  message: string,
+  failure: 'cancelled' | 'closed' | 'timeout',
+): ClientError {
+  const error = new Error(message) as ClientError & { failure: typeof failure }
+  Object.setPrototypeOf(error, ClientError.prototype)
+  Object.assign(error, { name: 'SessionError', failure })
+  return error
+}