@astrale-os/cli 0.8.0-alpha.0 → 0.8.1-alpha.2

package/src/commands/view.ts

@@ -1,18 +1,19 @@
+import type { ResolvedView } from '@astrale-os/shell'
+
 import chalk from 'chalk'
 import { randomBytes } from 'node:crypto'
-import { closeSync, existsSync, openSync, statSync } from 'node:fs'
-import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises'
+import { closeSync, existsSync, statSync } from 'node:fs'
+import { readdir, readFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 
-import type { CommandDefinition } from '../command'
-import type { KernelCommandOpts } from '../kernel'
+import type { KernelCommandOpts } from '../connection'
 import type { ViewServeConfig, ViewSessionRecord } from '../lib/view/session'
+import type { CommandDefinition } from '../program/index'
 
+import { expandSelfInPath, withClientSession } from '../connection'
 import { AstraleError } from '../errors'
-import { bindGraph, expandSelfInPath, resolveKernelTarget, withKernelClient } from '../kernel'
+import { readIdentities } from '../identity/index'
 import { ab, AGENT_BROWSER_REPO, BROWSER_DIR, findAgentBrowser } from '../lib/browser'
-import { readConfig } from '../lib/config'
-import { readIdentities } from '../lib/identity'
 import { readInstances } from '../lib/instance'
 import { fatal, log } from '../lib/log'
 import { isMachine, output, type RawOutputOpts } from '../lib/output'
@@ -20,13 +21,13 @@ import { findFreePort } from '../lib/port'
 import { run, spawnHandle } from '../lib/proc'
 import { withViewPortAllocationLock } from '../lib/view/port-allocation'
 import {
-  applyViewUrlOverride,
   candidateSlug,
   parseViewSpec,
   pickCandidate,
   resolveViewCandidates,
-  rewriteLocalViewUrl,
+  selectedView,
   type ViewCandidate,
+  viewOwnerTarget,
 } from '../lib/view/resolve'
 import { ensureViewerAssets } from '../lib/view/server'
 import {
@@ -34,8 +35,9 @@ import {
   configPath,
   listSessions,
   logPath,
+  openSessionLog,
   saveRecord,
-  VIEW_DIR,
+  saveServeConfig,
 } from '../lib/view/session'
 import { snapshotText, waitForSettledSnapshot } from '../lib/view/snapshot'
 
@@ -73,84 +75,57 @@ const VIEW_PROFILE = `${BROWSER_DIR}/_view`
 
 const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
 
-type ResolvedTarget = { id: string; path: string }
-type ResolvedView = {
-  url: string
-  functionId: string
-  handshake: 'shell' | 'none'
-  path?: string
-  name?: string
-}
-
 export async function resolveSession(
-  spec: string | undefined,
+  spec: string,
   opts: ViewOpts,
-): Promise<{ view?: ResolvedView; target?: ResolvedTarget; candidates: ViewCandidate[] }> {
-  const parsed = spec ? parseViewSpec(spec) : undefined
-  if (parsed?.kind === 'target' && opts.target) {
+): Promise<{ view?: ResolvedView; candidates: ViewCandidate[] }> {
+  rejectUnrepresentableOverrides(opts)
+  const parsed = parseViewSpec(spec)
+  if (parsed.kind === 'target' && opts.target) {
     fatal(new Error('Pass the target either as the positional or as --target, not both'))
   }
-  const targetInput = parsed?.kind === 'target' ? parsed.path : opts.target
-
-  const resolved = await withKernelClient(opts, async (ctx) => {
-    let target: ResolvedTarget | undefined
-    if (targetInput) {
-      const { path } = await expandSelfInPath(targetInput, opts)
-      const node = (await bindGraph(ctx).get(path)) as { id?: string } | null
-      if (!node?.id) {
-        throw new AstraleError('NOT_FOUND', `target ${path} not found or not visible`)
-      }
-      target = { id: node.id, path }
-    }
-    // A bare --view-url already identifies the frontend. Its target is only
-    // shell context, so asking View:resolve for installed candidates is both
-    // unnecessary and incorrect for classes without a class-owned self view.
-    const anchor = parsed ? (parsed.kind === 'view' ? parsed.path : target?.path) : undefined
-    const candidates = anchor ? await resolveViewCandidates(ctx, anchor) : []
-    return { target, candidates }
-  })
-
-  // Bare --view-url: mount an arbitrary URL as a view (nothing installed yet).
-  if (!parsed) {
-    return {
-      view: {
-        url: rewriteLocalViewUrl(opts.viewUrl!),
-        functionId: 'dev-view',
-        handshake: opts.handshake ?? 'shell',
-        name: 'dev',
-      },
-      target: resolved.target,
-      candidates: [],
-    }
+  if (parsed.kind === 'view' && opts.view) {
+    fatal(new Error('An explicit ViewPath cannot be combined with --view <slug>'))
   }
+  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 anchor = parsed.kind === 'view' ? parsed.path : resolved.target!.path
   if (opts.list) {
-    return { target: resolved.target, candidates: resolved.candidates }
+    return { candidates }
   }
-  const picked = await chooseCandidate(resolved.candidates, anchor, opts)
-  let url = picked.url
-  if (opts.viewUrl) url = applyViewUrlOverride(url, opts.viewUrl)
-  url = rewriteLocalViewUrl(url)
+  const selector = parsed.kind === 'view' ? parsed.path : opts.view
+  const picked = await chooseCandidate(candidates, target, selector, opts)
   return {
-    view: {
-      url,
-      functionId: picked.id,
-      handshake: opts.handshake ?? picked.handshake ?? 'shell',
-      path: picked.path,
-      name: candidateSlug(picked),
-    },
-    target: resolved.target,
-    candidates: resolved.candidates,
+    view: selectedView(picked),
+    candidates,
   }
 }
 
+/**
+ * Retain the frozen command flags while failing closed: neither legacy flag
+ * has a truthful representation in V2's verified View placement contract.
+ */
+export function rejectUnrepresentableOverrides(
+  opts: Pick<ViewOpts, 'handshake' | 'viewUrl'>,
+): void {
+  if (opts.viewUrl === undefined && opts.handshake === undefined) return
+  throw new AstraleError(
+    'UNSUPPORTED_VIEW_OVERRIDE',
+    '--view-url and --handshake cannot override a V2 View: the Shell mounts one verified View placement with complete provenance.',
+    'Pass a ViewPath or target and use the placement published by its Domain.',
+  )
+}
+
 async function chooseCandidate(
   candidates: ViewCandidate[],
   anchor: string,
+  selector: string | undefined,
   opts: ViewOpts,
 ): Promise<ViewCandidate> {
-  const picked = pickCandidate(candidates, anchor, opts.view)
+  const picked = pickCandidate(candidates, anchor, selector)
   if (picked !== 'ambiguous') return picked
   if (process.stdin.isTTY && !isMachine(opts)) {
     const { select } = await import('@inquirer/prompts')
@@ -225,29 +200,19 @@ async function newerThan(dir: string, mtimeMs: number): Promise<boolean> {
 }
 
 /** Spawn the detached session server (the CLI re-invoking itself) and wait for it. */
-async function startSession(
-  view: ResolvedView,
-  target: ResolvedTarget | undefined,
-  opts: ViewOpts,
-): Promise<ViewSessionRecord> {
+async function startSession(view: ResolvedView, opts: ViewOpts): Promise<ViewSessionRecord> {
   await ensureViewerAssets()
-  const config = await readConfig()
-  const kernelTarget = await resolveKernelTarget(opts, config)
+  const kernelTarget = await withClientSession(
+    opts,
+    async ({ target: connectionTarget }) => connectionTarget,
+  )
   const [instances, identities, runtime] = await Promise.all([
     readInstances(),
     readIdentities(),
     resolveServeRuntime(),
   ])
   return withViewPortAllocationLock(() =>
-    startSessionLocked(
-      view,
-      target,
-      opts,
-      kernelTarget,
-      instances.active,
-      identities.default,
-      runtime,
-    ),
+    startSessionLocked(view, opts, kernelTarget, instances.active, identities.default, runtime),
   )
 }
 
@@ -258,9 +223,8 @@ async function startSession(
  */
 async function startSessionLocked(
   view: ResolvedView,
-  target: ResolvedTarget | undefined,
   opts: ViewOpts,
-  kernelTarget: { url: string; caFile?: string },
+  kernelTarget: { url: string; kernelIssuer: string; caFile?: string },
   activeInstance: string | undefined,
   defaultIdentity: string | undefined,
   runtime: { file: string; args: string[] },
@@ -281,7 +245,6 @@ async function startSessionLocked(
     nonce,
     pageUrl: `http://127.0.0.1:${port}/s/${nonce}/`,
     view,
-    target,
     instance: opts.instance ?? (opts.url ? opts.url : activeInstance),
     identity: opts.creds ? '(pre-signed creds)' : (opts.as ?? defaultIdentity),
     createdAt: new Date().toISOString(),
@@ -297,15 +260,15 @@ async function startSessionLocked(
     },
     proxy: {
       kernelUrl: kernelTarget.url,
+      issuer: kernelTarget.kernelIssuer,
       caFile: kernelTarget.caFile,
       direct: isPublicHttps(kernelTarget.url) && !kernelTarget.caFile,
     },
     idleMs: IDLE_MS,
   }
 
-  await mkdir(VIEW_DIR, { recursive: true })
-  await writeFile(configPath(id), JSON.stringify(serveConfig, null, 2))
-  const logFd = openSync(logPath(id), 'a')
+  await saveServeConfig(serveConfig)
+  const logFd = await openSessionLog(id)
   const child = spawnHandle(
     runtime.file,
     [...runtime.args, '__view-serve', '--config', configPath(id)],
@@ -422,9 +385,9 @@ async function reportOpened(
     )
     return
   }
-  const label = record.view.path ?? record.view.url
+  const label = `/:${record.view.route.key}`
   log.success(`View session ${chalk.bold(record.id)} — ${chalk.bold(label)}`)
-  if (record.target) log.dim(`  target    ${record.target.path} (${record.target.id})`)
+  log.dim(`  target    ${record.view.target}`)
   log.dim(
     `  identity  ${record.identity ?? '(default)'}  instance  ${record.instance ?? '(active)'}`,
   )
@@ -479,7 +442,7 @@ async function closeCommand(opts: ViewOpts): Promise<void> {
     return fatal(
       new Error(
         `${sessions.length} sessions open — pass --close <id> or --close --all:\n${sessions
-          .map((s) => `  ${s.id}  ${s.view.path ?? s.view.url}`)
+          .map((s) => `  ${s.id}  /:${s.view.route.key}`)
           .join('\n')}`,
       ),
     )
@@ -502,7 +465,7 @@ async function sessionsCommand(opts: ViewOpts): Promise<void> {
   }
   for (const s of sessions) {
     console.log(
-      `${chalk.bold(s.id)}  ${s.view.path ?? s.view.url}${s.target ? `  target ${s.target.path}` : ''}  ${chalk.dim(s.pageUrl)}`,
+      `${chalk.bold(s.id)}  /:${s.view.route.key}  target ${s.view.target}  ${chalk.dim(s.pageUrl)}`,
     )
   }
 }
@@ -555,27 +518,22 @@ What it does:
   agent-browser's job; auth follows --as/--creds/-i like any kernel command.
 
   A session stays up ~30 min idle (heartbeat while the page is open). The view
-  gets exactly what the GUI would hand it: a delegation token, a kernel URL,
-  and your target node id.
+  gets exactly what the GUI would hand it: one target-bound resolved placement,
+  an audience-bound credential for shell mounts, and the kernel endpoint.
 
 Examples:
   $ astrale view /crm/customers/ada                      # views on a node
   $ astrale view /:crm.acme.dev:view.dashboard           # explicit ViewPath
   $ astrale view /:agents.astrale.ai:view.agent --target @f00d1234 --as alice
   $ astrale view /crm/customers/ada --snapshot           # open + show it
-  $ astrale view /:d:view.x --view-url http://localhost:8787   # local frontend, live data
-  $ astrale view --view-url http://localhost:8787/ui/x --handshake shell --target /a/b
   $ astrale view --sessions ; astrale view --close --all
 `,
   action: async (spec: string | undefined, opts: ViewOpts) => {
     if (opts.close !== undefined) return closeCommand(opts)
     if (opts.sessions) return sessionsCommand(opts)
 
-    if (!spec && !opts.viewUrl) {
-      return fatal(
-        new Error('Nothing to open — pass a ViewPath or target node, or --view-url <url>.'),
-      )
-    }
+    rejectUnrepresentableOverrides(opts)
+    if (!spec) return fatal(new Error('Nothing to open — pass a ViewPath or target node.'))
     const wantsAgentBrowser = !opts.browser && opts.open !== false
     if ((opts.snapshot || opts.screenshot) && !wantsAgentBrowser) {
       return fatal(
@@ -590,14 +548,14 @@ Examples:
       process.exit(1)
     }
 
-    const { view, target, candidates } = await resolveSession(spec, opts)
+    const { view, candidates } = await resolveSession(spec, opts)
     if (opts.list) {
       if (isMachine(opts)) output(candidates, opts)
       else if (candidates.length === 0) log.dim('No views resolve here.')
       else {
         for (const c of candidates) {
           console.log(
-            `${chalk.bold(candidateSlug(c))}  ${c.handshake ?? 'shell'}  ${c.origin}  ${chalk.dim(c.url)}  ${c.path}`,
+            `${chalk.bold(candidateSlug(c))}  ${c.handshake}  ${c.origin}  ${chalk.dim(c.url)}  ${c.path}`,
           )
         }
       }
@@ -605,7 +563,7 @@ Examples:
     }
     if (!view) throw new Error('View resolution completed without a selected view')
 
-    const record = await startSession(view, target, opts)
+    const record = await startSession(view, opts)
 
     let mode: 'agent' | 'system' | 'none' = 'none'
     if (wantsAgentBrowser) {

package/src/connect-core.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from 'bun:test'
+
+import * as compatibility from './connect-core'
+
+describe('connect-core compatibility barrel', () => {
+  test('retains the functions borrowed by connect-host', () => {
+    for (const value of [
+      compatibility.readIdentities,
+      compatibility.getDefault,
+      compatibility.getIdentity,
+      compatibility.signAs,
+      compatibility.listIdentityKeys,
+      compatibility.readInstances,
+      compatibility.resetInstancesMemo,
+      compatibility.resolveInstance,
+      compatibility.normalizeInstanceKernelUrl,
+      compatibility.orgIdForAudience,
+      compatibility.resolveInstanceTarget,
+      compatibility.readConfig,
+      compatibility.resolveCredential,
+      compatibility.fetchWithCaFile,
+      compatibility.createPaths,
+      compatibility.loginViaIdp,
+      compatibility.resolveIdpName,
+      compatibility.readIdpSession,
+      compatibility.isSessionExpired,
+    ]) {
+      expect(value).toBeTypeOf('function')
+    }
+  })
+
+  test('retains typed errors and the captured paths singleton', () => {
+    expect(compatibility.AuthError).toBeTypeOf('function')
+    expect(compatibility.IdpRefreshTransientError).toBeTypeOf('function')
+    expect(compatibility.IdpOrgMembershipError).toBeTypeOf('function')
+    expect(compatibility.paths.home).toBeTypeOf('string')
+  })
+})

package/src/connect-core.ts

@@ -0,0 +1,42 @@
+/**
+ * Temporary compatibility surface for the observed `@astrale-os/connect-host`
+ * consumer. Keep this file as re-exports only: CLI state and connection owners
+ * remain authoritative, and no Kernel Client implementation type is exposed.
+ */
+
+export { getDefault, getIdentity, readIdentities } from './identity/registry'
+export type { Identity, IdentityStore } from './identity/registry'
+
+export { listIdentityKeys, signAs } from './keys/index'
+
+export {
+  normalizeInstanceKernelUrl,
+  orgIdForAudience,
+  readInstances,
+  resetInstancesMemo,
+  resolveInstance,
+} from './lib/instance'
+export type { InstanceEntry, InstanceStore, ResolvedInstance } from './lib/instance'
+
+export { resolveInstanceTarget } from './lib/instance-target'
+export type { ResolvedInstanceTarget } from './lib/instance-target'
+
+export { readConfig } from './lib/config'
+export type { AstraleConfig } from './lib/config'
+
+export {
+  IdpOrgMembershipError,
+  IdpRefreshTransientError,
+  resolveCredential,
+} from './connection/auth'
+
+export { loginViaIdp, resolveIdpName } from './lib/login-flow'
+export type { DeviceVerification, LoginFlowOpts, LoginResult } from './lib/login-flow'
+
+export { isSessionExpired, readIdpSession } from './lib/idp'
+export type { IdpSession } from './lib/idp'
+
+export { AuthError } from './errors'
+export { fetchWithCaFile } from './lib/ca-fetch'
+
+export { createPaths, paths } from './state/index'

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

@@ -0,0 +1,111 @@
+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'
+
+/** Existing CLI connection flags accepted by Kernel-touching commands. */
+export interface ConnectionOptions {
+  readonly url?: string
+  readonly instance?: string
+  readonly timeout?: string
+  readonly as?: string
+  readonly creds?: string
+  /** Omit caller credentials even when local or bookmark defaults exist. */
+  readonly anonymous?: boolean
+}
+
+/** Existing Admin-target overrides accepted only by Admin Domain operations. */
+export interface AdminConnectionOptions extends ConnectionOptions {
+  readonly admin?: string
+  readonly adminUrl?: string
+  readonly domainIssuer?: string
+}
+
+/** Exact source Kernel selected from flags and local CLI state. */
+export interface ConnectionTarget {
+  readonly url: string
+  readonly issuer: IssuerId
+  /** Installed Domain issuer; presence activates standard token exchange. */
+  readonly domainIssuer?: IssuerId
+  readonly slug?: string
+  readonly defaultIdentity?: string
+  readonly caFile?: string
+}
+
+/** Stable local identity-registration key for the exact selected source Kernel. */
+export function registrationKeyForTarget(target: ConnectionTarget): string
+
+/** Narrow capabilities available during one scoped CLI connection. */
+export interface ConnectionContext {
+  readonly session: ClientSession
+  readonly graph: GraphApi
+  readonly auth: AuthApi
+  readonly target: ConnectionTarget
+}
+
+/** Existing output and diagnostic flags shared by commands that open a Kernel connection. */
+export interface KernelCommandOpts extends ConnectionOptions {
+  readonly raw?: boolean
+  readonly json?: boolean
+  readonly format?: 'yaml' | 'json'
+  readonly debug?: boolean
+}
+
+/** Detached metadata used only to improve an error after a caller-authored @self expansion. */
+export interface SelfExpansionMeta {
+  readonly original: string
+  readonly expanded: string
+  readonly selfId: string
+  readonly slug?: string
+}
+
+/** Parse caller-authored path text and retain one portable input in the public Call shape. */
+export function createPathCall(path: string, input: unknown): Call
+
+/** Resolve one ordinary CLI target, run an action, and close every owned Client resource. */
+export function withClientSession<Value>(
+  options: ConnectionOptions,
+  action: (context: ConnectionContext) => Promise<Value>,
+): Promise<Value>
+
+/** Resolve the configured Admin Domain target under the same scoped lifecycle. */
+export function withAdminClientSession<Value>(
+  options: AdminConnectionOptions,
+  action: (context: ConnectionContext) => Promise<Value>,
+): Promise<Value>
+
+/** Expand @self through the effective principal returned by authenticated Identity.whoami. */
+export function expandSelfInPath(
+  path: string,
+  options: KernelCommandOpts,
+): 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,
+): Promise<{
+  readonly path: string
+  readonly parameters: readonly string[]
+  readonly meta?: SelfExpansionMeta
+}>
+
+/** Preserve stale-registration evidence while an expanded request is executed. */
+export function withSelfHint<Value>(
+  action: () => Promise<Value>,
+  meta: SelfExpansionMeta | undefined,
+): Promise<Value>
+
+/** Run one command through the canonical progress, connection, presentation, and error boundary. */
+export function runKernelCommand<Value>(input: {
+  readonly opts: KernelCommandOpts
+  readonly label: string
+  readonly fn: (context: ConnectionContext) => Promise<Value>
+  readonly format?: (
+    result: Value,
+    options: KernelCommandOpts,
+    machine: boolean,
+  ) => void | Promise<void>
+}): Promise<void>

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

@@ -0,0 +1,41 @@
+# CLI connection architecture
+
+The private `connection` module owns one scoped bridge from existing CLI flags and local identity
+state to the public Kernel Client. It selects the exact source Kernel URL and issuer, either omits
+credentials for an explicit anonymous selection or resolves fresh source-Kernel authority for each
+Call, binds Graph and Auth helpers, and closes every owned Client resource when the command action
+terminates.
+
+When a target also names an exact Domain issuer, the connection owner performs the client-mediated
+`whoami -> delegate(attenuation) -> issuer exchange` journey. The resulting Domain token crosses
+into ClientSession as an opaque credential; connection does not authorize Domain operations.
+
+```mermaid
+flowchart LR
+  F[CLI flags and local state] --> T[Connection target]
+  T --> H[ClientSession]
+  C[CLI credential sources] --> R[SessionAuth]
+  R --> H
+  H --> G[GraphApi]
+  H --> A[AuthApi]
+  H --> X[Command action]
+  G --> X
+  A --> X
+```
+
+ClientSession owns source admission, Publication discovery, redirect witnessing, route caching, transport
+selection, and the single safe stale-route recovery. The CLI does not reproduce those rules or
+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.
+
+`--anonymous` deliberately suppresses ambient and bookmark-default identities by omitting the
+`SessionAuth` capability. It cannot be combined with `--as` or `--creds`; contradictory selections fail
+before local identity state or a connection is opened. Public and optional callables can then
+observe a genuinely anonymous caller, while required callables reject the request at the Kernel.
+
+The target, timeout, and optional CA file are resolved before constructing the session. The CA file
+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.

package/src/connection/.spec/capabilities/connection.ts

@@ -0,0 +1,13 @@
+import { defineCapability } from '@astrale-os/spec/authoring'
+
+export const CLI_CONNECTION = defineCapability({
+  id: 'CLI-CONNECTION',
+  statement:
+    'Selects one exact source Kernel and exposes scoped public Host, Graph, and Auth capabilities with terminal cleanup.',
+})
+
+export const CLI_AUTH = defineCapability({
+  id: 'CLI-AUTH',
+  statement:
+    'Pins the selected source issuer, explicitly admits either credential-less or target-bound authenticated sessions, and delegates remote destinations without forwarding a prior bearer.',
+})

package/src/connection/.spec/examples/call.ts

@@ -0,0 +1,7 @@
+import { createPathCall, withClientSession } from '../api.js'
+
+const result = await withClientSession({ instance: 'staging', as: 'alice' }, ({ session }) =>
+  session.call(createPathCall('/:notes.example.dev:function.search', { text: 'astrale' })),
+)
+
+console.log(result)

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

@@ -0,0 +1,20 @@
+import type { ConnectionContext, KernelCommandOpts } from '../api.js'
+
+declare const open: <Value>(
+  options: KernelCommandOpts,
+  action: (context: ConnectionContext) => Promise<Value>,
+) => Promise<Value>
+declare const present: <Value>(value: Value) => void | Promise<void>
+declare const mapExpectedFailure: (error: unknown) => Promise<void>
+
+/** One command owns progress and error presentation around one terminal ClientSession lifecycle. */
+export async function runKernelCommand<Value>(
+  options: KernelCommandOpts,
+  action: (context: ConnectionContext) => Promise<Value>,
+): Promise<void> {
+  try {
+    await present(await open(options, action))
+  } catch (error) {
+    await mapExpectedFailure(error)
+  }
+}

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

@@ -0,0 +1,61 @@
+import type { SessionAuth } from '@astrale-os/kernel-client/session'
+import type { Call } from '@astrale-os/kernel-protocol/invocation'
+
+import type { ConnectionContext, ConnectionOptions, ConnectionTarget } from '../api.js'
+
+interface OwnedConnection {
+  readonly context: ConnectionContext
+  close(): void
+}
+
+declare const resolveTarget: (options: ConnectionOptions) => Promise<ConnectionTarget>
+declare const resolveTimeoutMs: (input: string | undefined) => number
+declare const createClientConnection: (
+  target: ConnectionTarget,
+  timeoutMs: number,
+  auth: SessionAuth | undefined,
+) => OwnedConnection
+declare const validateCredentialSelection: (options: ConnectionOptions) => void
+declare const resolveSourceCredential: (
+  target: ConnectionTarget,
+  options: ConnectionOptions,
+  audience: string,
+  signal: AbortSignal,
+) => Promise<string>
+/** Bind source authority without learning or minting destination credentials. */
+function createConnectionAuth(target: ConnectionTarget, options: ConnectionOptions): SessionAuth {
+  return {
+    ttlSeconds: 3_600,
+    async resolve(_call: Call, signal: AbortSignal) {
+      return {
+        credential: await resolveSourceCredential(target, options, target.issuer, signal),
+      }
+    },
+  }
+}
+
+/** Open one Client Session with a call-scoped source-authority resolver bound once. */
+function openConnection(
+  target: ConnectionTarget,
+  timeoutMs: number,
+  options: ConnectionOptions,
+): OwnedConnection {
+  const auth = options.anonymous === true ? undefined : createConnectionAuth(target, options)
+  return createClientConnection(target, timeoutMs, auth)
+}
+
+/** One terminal command-scoped connection lifecycle. */
+export async function withClientSession<Value>(
+  options: ConnectionOptions,
+  action: (context: ConnectionContext) => Promise<Value>,
+): Promise<Value> {
+  validateCredentialSelection(options)
+  const timeoutMs = resolveTimeoutMs(options.timeout)
+  const target = await resolveTarget(options)
+  const connection = openConnection(target, timeoutMs, options)
+  try {
+    return await action(connection.context)
+  } finally {
+    connection.close()
+  }
+}