@astrale-os/cli 0.4.0-alpha.13

package/src/kernel/errors.ts

@@ -0,0 +1,280 @@
+import chalk from 'chalk'
+
+import type { SelfExpansionMeta } from './expand'
+
+import { AstraleError } from '../errors'
+import { decodeJwtExpiration, readLocalStatus, type LocalStatus } from '../lib/local-status'
+import { log } from '../lib/log'
+
+type FieldError = { path: string[]; code: string; message: string }
+type InvariantError = { code: string; message: string; context?: unknown }
+
+/**
+ * Format and display a kernel client error.
+ *
+ * Handles AstraleError (CLI-local) and every error class exported by
+ * @astrale-os/kernel-client: ConnectionError, DisconnectedError,
+ * TimeoutError, AuthenticationError, PermissionDeniedError, NotFoundError,
+ * KernelError and its subclasses (ValidationError, InvariantViolationError).
+ *
+ * When `debug` is true, additional diagnostic information (class name, full
+ * error chain, attached url/details) is printed after the user-facing line.
+ */
+export async function formatKernelError(
+  error: unknown,
+  isRaw: boolean,
+  urlArg = '',
+  debug = false,
+  opts: { credential?: string } = {},
+): Promise<void> {
+  const url =
+    urlArg || (error instanceof Error ? ((error as Error & { url?: string }).url ?? '') : '')
+  const localContext = await contextForError(error)
+  const credentialExpiration = opts.credential ? decodeJwtExpiration(opts.credential) : null
+  // Handle AstraleError (AuthError, etc.) with structured hints
+  if (error instanceof AstraleError) {
+    if (isRaw) {
+      writeRaw({ error: error.code, message: error.message, hint: error.hint })
+    } else {
+      log.error(`${chalk.bold(error.code)}: ${error.message}`)
+      if (error.hint) log.dim(`  ${error.hint}`)
+    }
+    if (debug) printDebug(error, url)
+    return
+  }
+
+  if (!(error instanceof Error)) {
+    if (isRaw) writeRaw({ error: 'UNKNOWN', message: String(error) })
+    else log.error(String(error))
+    return
+  }
+
+  const name = error.name
+
+  switch (name) {
+    case 'ConnectionError':
+      if (isRaw)
+        writeRaw({ error: 'CONNECTION_ERROR', message: error.message, url, context: localContext })
+      else {
+        log.error(`Could not connect to ${chalk.bold(url || 'kernel')}`)
+        log.dim(`  ${error.message}`)
+        log.dim('  Is the kernel running? Try: astrale status')
+        printLocalContext(localContext)
+      }
+      break
+
+    case 'DisconnectedError':
+      if (isRaw) writeRaw({ error: 'DISCONNECTED', message: error.message })
+      else {
+        log.error('Connection closed while request was pending')
+        log.dim('  The kernel may have been stopped or restarted. Retry the command.')
+      }
+      break
+
+    case 'TimeoutError': {
+      const timeoutMs = (error as { timeoutMs?: number }).timeoutMs
+      if (isRaw) writeRaw({ error: 'TIMEOUT', message: error.message, timeoutMs })
+      else {
+        log.error(`Request timed out after ${timeoutMs ?? '?'}ms`)
+        log.dim('  Try increasing with --timeout')
+      }
+      break
+    }
+
+    case 'AuthenticationError': {
+      const reason = (error as { reason?: string }).reason ?? 'unknown'
+      if (isRaw)
+        writeRaw({
+          error: 'AUTH_ERROR',
+          reason,
+          message: error.message,
+          credential: credentialExpiration,
+          context: localContext,
+        })
+      else {
+        log.error(`Authentication failed: ${error.message}`)
+        if (reason === 'missing')
+          log.dim('  No credential was sent. Run: astrale identity create <name>')
+        else if (reason === 'invalid')
+          log.dim('  Credential is invalid — check issuer/keypair. Try: astrale identity whoami')
+        else if (reason === 'expired') log.dim('  Credential expired — sign a fresh one')
+        if (credentialExpiration) {
+          const state = credentialExpiration.expired ? 'expired' : 'expires'
+          log.dim(`  Credential ${state} at ${credentialExpiration.expiresAt}`)
+        }
+        printLocalContext(localContext)
+      }
+      break
+    }
+
+    case 'PermissionDeniedError':
+      if (isRaw) writeRaw({ error: 'PERMISSION_DENIED', message: error.message })
+      else {
+        log.error(`Permission denied: ${error.message}`)
+        log.dim('  Your identity does not have the required permissions for this operation')
+      }
+      break
+
+    case 'NotFoundError': {
+      const cleanMsg = stripMethodSuffix(error.message)
+      const selfMeta = (error as Error & { expandedFromSelf?: SelfExpansionMeta }).expandedFromSelf
+      // kernel-client maps both NOT_FOUND (the node doesn't exist) and
+      // METHOD_NOT_FOUND (the method doesn't exist on a real node) to
+      // `NotFoundError`. Firing the "refresh registration" hint for the
+      // method case is misleading. Gate on the message referencing the
+      // expanded id — node lookup errors mention `@<id>` whereas method
+      // errors mention the method path.
+      const selfHintApplies = selfMeta && error.message.includes(`@${selfMeta.selfId}`)
+      if (isRaw) {
+        const payload: Record<string, unknown> = { error: 'NOT_FOUND', message: cleanMsg }
+        if (selfHintApplies) payload.expandedFromSelf = selfMeta
+        writeRaw(payload)
+      } else {
+        log.error(`Not found: ${cleanMsg}`)
+        log.dim('  Check the path/ID and that the instance is booted')
+        if (selfHintApplies && selfMeta) {
+          const who = selfMeta.identity ?? 'your identity'
+          const where = selfMeta.slug ? ` on "${selfMeta.slug}"` : ''
+          log.dim(`  @self expanded to @${selfMeta.selfId} from ${who}'s registration${where}.`)
+          const fixCmd = `astrale identity register${
+            selfMeta.identity ? ` ${selfMeta.identity}` : ''
+          }${selfMeta.slug ? ` -i ${selfMeta.slug}` : ''}`
+          log.dim(`  If the node was deleted, refresh with: ${fixCmd}`)
+        }
+      }
+      break
+    }
+
+    case 'ValidationError': {
+      const errors = (error as { errors?: FieldError[] }).errors ?? []
+      if (isRaw) writeRaw({ error: 'VALIDATION_ERROR', message: error.message, details: errors })
+      else {
+        log.error('Validation Error')
+        if (errors.length > 0) {
+          for (const e of errors) {
+            console.log(chalk.red(`  ${e.path.join('.')}: ${e.message} (${chalk.dim(e.code)})`))
+          }
+        } else {
+          // Server often sends details in message but empty errors array
+          console.log(chalk.red(`  ${error.message}`))
+        }
+        log.dim('  Use `astrale call <path> --describe` to see the expected schema')
+      }
+      break
+    }
+
+    case 'InvariantViolationError': {
+      const errors = (error as { errors?: InvariantError[] }).errors ?? []
+      if (isRaw) writeRaw({ error: 'INVARIANT_VIOLATION', message: error.message, details: errors })
+      else {
+        log.error('Invariant Violation')
+        for (const e of errors) {
+          console.log(chalk.red(`  ${e.code}: ${e.message}`))
+          if (e.context) console.log(chalk.dim(`    ${JSON.stringify(e.context)}`))
+        }
+      }
+      break
+    }
+
+    case 'KernelError': {
+      const code = (error as { code?: number | string }).code ?? 'UNKNOWN'
+      const type = (error as { type?: string }).type ?? 'KERNEL_ERROR'
+      if (isRaw) writeRaw({ error: type, code, message: error.message })
+      else log.error(`${chalk.bold(`${type}(${code})`)}: ${error.message}`)
+      break
+    }
+
+    default:
+      // Catch-all: include class name so diagnosis is possible even without --debug
+      if (isRaw) writeRaw({ error: name || 'UNKNOWN', message: error.message })
+      else log.error(`${chalk.bold(name || 'Error')}: ${error.message}`)
+  }
+
+  if (debug) printDebug(error, url)
+}
+
+/** Strip internal `::methodName` suffixes from paths in error messages (e.g., "/path::listChildren" → "/path") */
+function stripMethodSuffix(msg: string): string {
+  return msg.replace(/(\/[^"\s:]+)::([a-zA-Z]\w*)/g, '$1')
+}
+
+function writeRaw(payload: Record<string, unknown>): void {
+  process.stderr.write(JSON.stringify(payload) + '\n')
+}
+
+async function contextForError(error: unknown): Promise<LocalStatus | undefined> {
+  if (!(error instanceof Error)) return undefined
+  if (error.name !== 'AuthenticationError' && error.name !== 'ConnectionError') return undefined
+  return readLocalStatus().catch(() => undefined)
+}
+
+function printLocalContext(context: LocalStatus | undefined): void {
+  if (!context) return
+  process.stderr.write(chalk.dim('\nContext:\n'))
+  if ('error' in context.admin) {
+    process.stderr.write(chalk.dim(`  admin: invalid (${context.admin.error})\n`))
+  } else {
+    process.stderr.write(chalk.dim(`  admin: ${context.admin.name} -> ${context.admin.url}\n`))
+  }
+  if (context.instance) {
+    process.stderr.write(
+      chalk.dim(`  instance: ${context.instance.active} -> ${context.instance.url}\n`),
+    )
+  } else {
+    process.stderr.write(chalk.dim('  instance: none\n'))
+  }
+  if (context.identity) {
+    const source =
+      context.identity.source === 'idp'
+        ? `idp:${context.identity.idp ?? 'unknown'}`
+        : context.identity.source
+    process.stderr.write(chalk.dim(`  identity: ${context.identity.name} [${source}]\n`))
+    if (context.identity.session?.cached) {
+      const state = context.identity.session.requiresLogin ? 'login required' : 'ready'
+      process.stderr.write(chalk.dim(`  session: ${state}\n`))
+    } else if (context.identity.source === 'idp') {
+      process.stderr.write(chalk.dim('  session: not cached\n'))
+    }
+  } else {
+    process.stderr.write(chalk.dim('  identity: none\n'))
+  }
+}
+
+function printDebug(error: unknown, url: string): void {
+  process.stderr.write('\n' + chalk.dim('── debug ─────────────────') + '\n')
+  if (url) process.stderr.write(chalk.dim(`url:   ${url}`) + '\n')
+  if (error instanceof Error) {
+    process.stderr.write(chalk.dim(`class: ${error.constructor.name}`) + '\n')
+    if (error.stack) process.stderr.write(chalk.dim(error.stack) + '\n')
+    // Walk cause chain
+    let cause = (error as Error & { cause?: unknown }).cause
+    while (cause instanceof Error) {
+      process.stderr.write(
+        chalk.dim(`caused by: ${cause.constructor.name}: ${cause.message}`) + '\n',
+      )
+      if (cause.stack) process.stderr.write(chalk.dim(cause.stack) + '\n')
+      cause = (cause as Error & { cause?: unknown }).cause
+    }
+    // Any attached fields (code, details, etc.)
+    const extras: Record<string, unknown> = {}
+    const bag = error as unknown as Record<string, unknown>
+    for (const key of [
+      'code',
+      'type',
+      'reason',
+      'details',
+      'errors',
+      'data',
+      'timeoutMs',
+      'requestId',
+    ]) {
+      const v = bag[key]
+      if (v !== undefined) extras[key] = v
+    }
+    if (Object.keys(extras).length > 0) {
+      process.stderr.write(chalk.dim(`extras: ${JSON.stringify(extras, null, 2)}`) + '\n')
+    }
+  } else {
+    process.stderr.write(chalk.dim(String(error)) + '\n')
+  }
+}

package/src/kernel/expand.ts

@@ -0,0 +1,217 @@
+import type { InstanceInfo } from '../lib/admin-instance'
+import type { KernelCommandOpts } from './types'
+
+import { ADMIN_INSTANCE } from '../lib/admin-instance'
+/**
+ * Bridges `lib/self.ts` to CLI command sites: builds a `SelfResolverContext`
+ * from CLI opts, resolves a nodeId via
+ * `resolveOrThrow` (throwing `SelfRefusalError` on refusal), and wraps async
+ * calls with `withSelfHint` so `NotFoundError`s carry expansion metadata for
+ * the stale-registration hint emitted by `formatKernelError`.
+ */
+import { readConfig } from '../lib/config'
+import { getDefault, getIdentity, setRegistration } from '../lib/identity'
+import { decodeTokenClaims, readIdpSession } from '../lib/idp'
+import { resolveInstanceTarget } from '../lib/instance-target'
+import { fileExists, keypairPaths } from '../lib/keys'
+import { KEYS_DIR } from '../lib/paths'
+import {
+  containsSelfRef,
+  expandSelfReferences,
+  resolveSelfNodeId,
+  selfRefusalError,
+  type SelfResolverContext,
+  type SelfResolution,
+} from '../lib/self'
+import { withAdminKernelClient, withKernelClient } from './client'
+
+/** Metadata attached to errors so the NotFoundError path can hint at stale `@self` expansions. */
+export type SelfExpansionMeta = {
+  original: string
+  expanded: string
+  selfId: string
+  identity?: string
+  slug?: string
+}
+
+/**
+ * Build a `SelfResolverContext` from CLI opts. Mirrors the target +
+ * signing-mode logic in `withKernelClient` / `resolveCredential`.
+ *
+ * Cheap enough to call eagerly; commands skip the call entirely when
+ * `containsSelfRef` returns false on every input.
+ */
+export async function buildSelfContext(opts: KernelCommandOpts): Promise<SelfResolverContext> {
+  const config = await readConfig()
+  // Mirror withKernelClient's slug logic: --url without -i ⇒ no slug.
+  let slug: string | undefined
+  let defaultIdentity: string | undefined
+  if (opts.url && !opts.instance) {
+    slug = undefined
+  } else {
+    const resolved = await resolveInstanceTarget(
+      opts.instance ? { source: 'name', name: opts.instance } : { source: 'active' },
+      {
+        config,
+        admin: adminLookupOpts(opts),
+        managed: (instanceSlug) => lookupManagedInstance(instanceSlug, opts),
+      },
+    )
+    slug = resolved.name
+    defaultIdentity = resolved.defaultIdentity
+  }
+
+  // Mirror resolveCredential's instance-signed branch: when targeting a
+  // child for which the CLI generated a dedicated keypair, the call signs
+  // as the instance itself, not as a user identity.
+  let instanceSigned = false
+  if (!opts.creds && !opts.as && !defaultIdentity && slug && slug !== 'manager') {
+    const { privatePath } = keypairPaths(slug, KEYS_DIR)
+    instanceSigned = await fileExists(privatePath)
+  }
+
+  // Identity that will sign (only relevant when not instance-signed and not --creds).
+  // Failures here (corrupt identities.json, missing --as identity) are
+  // re-thrown rather than swallowed — swallowing produces a useless
+  // refusal naming `identityName: '(unknown)'`. The fatal-error UX is
+  // honest about the actual problem.
+  let identity: SelfResolverContext['identity']
+  if (!opts.creds) {
+    const identityName = opts.as ?? defaultIdentity
+    if (identityName) {
+      const i = await getIdentity(identityName)
+      identity = { ...i, name: identityName }
+    } else {
+      identity = await getDefault()
+    }
+  }
+
+  let idpSubject: string | undefined
+  if (identity && (identity.source ?? 'key') === 'idp') {
+    instanceSigned = false
+    const session = await readIdpSession(identity.name)
+    const claims = decodeTokenClaims(session?.id_token ?? session?.access_token)
+    if (typeof claims?.sub === 'string' && claims.sub.trim().length > 0) {
+      idpSubject = claims.sub
+    }
+  }
+
+  return { identity, instanceSlug: slug, credsJwt: opts.creds, instanceSigned, idpSubject }
+}
+
+function adminLookupOpts(opts: KernelCommandOpts): KernelCommandOpts {
+  return {
+    as: opts.as,
+    creds: opts.creds,
+    timeout: opts.timeout,
+    debug: opts.debug,
+  }
+}
+
+async function lookupManagedInstance(slug: string, opts: KernelCommandOpts): Promise<InstanceInfo> {
+  return await withAdminKernelClient(
+    adminLookupOpts(opts),
+    async (ctx) => (await ctx.client.call(`${ADMIN_INSTANCE}/info`, { id: slug })) as InstanceInfo,
+  )
+}
+
+/**
+ * Run `fn`; if it throws a `NotFoundError`, stamp expansion metadata onto the
+ * error so `formatKernelError` can append the stale-registration hint. The
+ * error is re-thrown either way.
+ */
+export async function withSelfHint<T>(
+  fn: () => Promise<T>,
+  meta: SelfExpansionMeta | undefined,
+): Promise<T> {
+  if (!meta) return fn()
+  try {
+    return await fn()
+  } catch (err) {
+    if (err instanceof Error && err.name === 'NotFoundError') {
+      ;(err as Error & { expandedFromSelf?: SelfExpansionMeta }).expandedFromSelf = meta
+    }
+    throw err
+  }
+}
+
+/** Convenience: resolve the nodeId once, or throw the typed refusal. */
+export function resolveOrThrow(selfCtx: SelfResolverContext): string {
+  const r: SelfResolution = resolveSelfNodeId(selfCtx)
+  if ('reason' in r) throw selfRefusalError(r)
+  return r.id
+}
+
+// The kernel's whoami — returns the AUTHENTICATED principal's graph node.
+// Static interface method, so the colon form (slash form is rejected).
+const WHOAMI_PATH = '/:kernel.astrale.ai:interface.Identity:whoami'
+
+/**
+ * Resolve `@self`, falling back to ONE kernel `whoami` round-trip when an
+ * IdP identity merely lacks a cached registration on this instance (the
+ * normal `astrale auth login` flow — the IdP subject is never a node id).
+ * The resolved id is persisted as a registration so subsequent expansions
+ * are local again. Every other refusal (manager, instance-signed, …) and a
+ * failed whoami throw the typed refusal unchanged.
+ */
+export async function resolveSelfIdLazy(
+  selfCtx: SelfResolverContext,
+  opts: KernelCommandOpts,
+): Promise<string> {
+  const r: SelfResolution = resolveSelfNodeId(selfCtx)
+  if (!('reason' in r)) return r.id
+  if (r.reason !== 'idp-no-sub' || !selfCtx.instanceSlug || !selfCtx.identity) {
+    throw selfRefusalError(r)
+  }
+  let me: { id?: unknown } | null
+  let kernelUrl = ''
+  try {
+    me = (await withKernelClient(opts, (ctx) => {
+      kernelUrl = ctx.url
+      return ctx.client.call(WHOAMI_PATH as never, {} as never)
+    })) as { id?: unknown } | null
+  } catch {
+    // Network/auth failure — surface the original recipe, not a stack.
+    throw selfRefusalError(r)
+  }
+  const id = typeof me?.id === 'string' && me.id.trim().length > 0 ? me.id : undefined
+  if (!id) throw selfRefusalError(r)
+  await setRegistration(selfCtx.identity.name, selfCtx.instanceSlug, {
+    iss: kernelUrl,
+    sub: id,
+    registeredAt: new Date().toISOString(),
+  })
+  return id
+}
+
+/**
+ * Expand `@self` in a single path string for the common command shape
+ * (`get`, `ls`, `describe`). Returns the expanded path AND the metadata
+ * needed by `withSelfHint` to attach the stale-registration hint to a
+ * downstream `NotFoundError`.
+ *
+ * No-op (returns the input unchanged with `meta: undefined`) when the path
+ * contains no `@self` — avoids the I/O of `buildSelfContext`.
+ *
+ * Throws `SelfRefusalError` when `@self` is present but unresolvable.
+ */
+export async function expandSelfInPath(
+  path: string,
+  opts: KernelCommandOpts,
+): Promise<{ path: string; meta: SelfExpansionMeta | undefined }> {
+  if (!containsSelfRef(path)) return { path, meta: undefined }
+  const selfCtx = await buildSelfContext(opts)
+  const id = await resolveSelfIdLazy(selfCtx, opts)
+  const expanded = expandSelfReferences(path, id)
+  if (expanded === path) return { path, meta: undefined }
+  return {
+    path: expanded,
+    meta: {
+      original: path,
+      expanded,
+      selfId: id,
+      identity: selfCtx.identity?.name,
+      slug: selfCtx.instanceSlug,
+    },
+  }
+}

package/src/kernel/index.ts

@@ -0,0 +1,14 @@
+export { withKernelClient, withAdminKernelClient, type ClientContext } from './client'
+export { resolveCredential } from './auth'
+export { formatKernelError } from './errors'
+export {
+  buildSelfContext,
+  expandSelfInPath,
+  withSelfHint,
+  resolveOrThrow,
+  resolveSelfIdLazy,
+  type SelfExpansionMeta,
+} from './expand'
+export { mintRemoteCredential } from './remote-routing'
+export { runKernelCommand, extractItems } from './run'
+export type { KernelCommandOpts, CallCommandOpts } from './types'

package/src/kernel/options.ts

@@ -0,0 +1,22 @@
+import type { CommandOption } from '../command'
+
+/**
+ * Flags consumed by `withKernelClient` (and therefore valid on any command
+ * that talks to a kernel). Spread these into a command's `options` to expose
+ * the same `--url / --instance / --timeout / --as / --creds / --debug`
+ * surface as `astrale call`.
+ */
+export const KERNEL_PASSTHROUGH_OPTIONS: CommandOption[] = [
+  {
+    flags: '--url <url>',
+    description: 'Target a kernel URL directly (overrides instance resolution)',
+  },
+  {
+    flags: '-i, --instance <name>',
+    description: 'Target a specific instance (overrides active)',
+  },
+  { flags: '--timeout <ms>', description: 'Request timeout in ms', default: '30000' },
+  { flags: '--as <identity>', description: 'Call as a specific identity' },
+  { flags: '--creds <token>', description: 'Use a pre-signed credential (e.g. delegation token)' },
+  { flags: '--debug', description: 'Print full error diagnostics on failure' },
+]

package/src/kernel/remote-routing.ts

@@ -0,0 +1,88 @@
+import type { FnMap } from '@astrale-os/kernel-client'
+import type { ClientSession } from '@astrale-os/kernel-client/session'
+
+/**
+ * Credential-minting helpers for remote-bound kernel calls.
+ *
+ * The CLI no longer resolves remote bindings client-side: the kernel emits a
+ * redirect carrying the target worker's `iss`, and the `ClientSession` follows
+ * it, minting a worker-scoped delegation via `mintRemoteCredential` (wired as
+ * the session's delegation-cache mint in `client.ts`). These helpers (whoami →
+ * self-delegation) are the mint itself.
+ */
+
+/**
+ * Mint a delegation credential scoped to the remote worker's audience.
+ *
+ * The Function lives under the caller's self identity (`@__system__` in manager
+ * kernels), so the invariant on `mintDelegationCredential` passes without
+ * additional claims. A self-delegation is the least-privilege shape — the
+ * worker inherits whatever grants the caller already has.
+ *
+ * Internal calls pass `skipDelegation: true`: they target the default kernel
+ * (same origin), so the delegation cache would skip them anyway, but being
+ * explicit guarantees the mint can never recurse into itself.
+ */
+export async function mintRemoteCredential(
+  client: ClientSession<FnMap>,
+  audience: string,
+  callerCredential: string,
+): Promise<string> {
+  const mintPath = await mintDelegationPath(client, callerCredential)
+  const result = await client.call(
+    mintPath,
+    {
+      audience,
+      delegation: { kind: 'identity', self: true },
+      ttl: 3600,
+    },
+    { credential: callerCredential, skipDelegation: true },
+  )
+  if (typeof result !== 'string') {
+    throw new Error(
+      `mintDelegationCredential returned non-string: ${typeof result} — cannot use as credential`,
+    )
+  }
+  return result
+}
+
+/**
+ * Resolve the kernel path that mints a self-delegation credential for the
+ * CALLER: `@<nodeId>::mintDelegationCredential`.
+ */
+export async function mintDelegationPath(
+  client: ClientSession<FnMap>,
+  credential: string,
+): Promise<string> {
+  const sub = readJwtSub(credential)
+  // System / opaque credential: the graph node id is literally `__system__`,
+  // so we can skip the whoami round-trip.
+  if (!sub || sub === 'system') return '@__system__::mintDelegationCredential'
+  const self = (await client.call(
+    '/:kernel.astrale.ai:interface.Identity:whoami',
+    {},
+    { credential, skipDelegation: true },
+  )) as { id?: unknown } | null
+  const id = self && typeof self.id === 'string' ? self.id : undefined
+  if (!id) {
+    throw new Error(
+      'Could not resolve the caller identity (whoami returned no id) — cannot mint a delegation credential.',
+    )
+  }
+  return `@${id}::mintDelegationCredential`
+}
+
+function readJwtSub(credential: string): string | null {
+  const [, payload] = credential.split('.')
+  if (!payload) return null
+  try {
+    const normalized = payload.replace(/-/g, '+').replace(/_/g, '/')
+    const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, '=')
+    const decoded = JSON.parse(Buffer.from(padded, 'base64').toString('utf8')) as {
+      sub?: unknown
+    }
+    return typeof decoded.sub === 'string' && decoded.sub.length > 0 ? decoded.sub : null
+  } catch {
+    return null
+  }
+}

package/src/kernel/run.ts

@@ -0,0 +1,63 @@
+import chalk from 'chalk'
+
+import type { ClientContext } from './client'
+import type { KernelCommandOpts } from './types'
+
+import { formatElapsed } from '../lib/format'
+import { spinner } from '../lib/log'
+import { isMachine, present } from '../lib/output'
+import { withKernelClient } from './client'
+import { formatKernelError } from './errors'
+
+type RunOpts<T> = {
+  opts: KernelCommandOpts
+  label: string
+  fn: (ctx: ClientContext) => Promise<T>
+  format?: (result: T, opts: KernelCommandOpts, isRaw: boolean) => void | Promise<void>
+}
+
+/**
+ * Encapsulates the standard kernel command lifecycle:
+ * spinner → connect → call → timing → output → error handling.
+ *
+ * Commands provide a `fn` that does the actual work and an optional
+ * `format` callback for custom output. If `format` is omitted, the
+ * result is passed to the standard `output()` function.
+ */
+export async function runKernelCommand<T>(run: RunOpts<T>): Promise<void> {
+  const { opts, label, fn } = run
+  const isRaw = isMachine(opts)
+  const spin = !isRaw ? spinner(`${label}...`) : null
+  const startTime = performance.now()
+
+  try {
+    const result = await withKernelClient(opts, fn)
+    const elapsed = performance.now() - startTime
+
+    spin?.succeed(`${label} ${chalk.dim(formatElapsed(elapsed))}`)
+    if (!isRaw) console.log('')
+
+    if (run.format) {
+      await run.format(result, opts, isRaw)
+    } else {
+      present(result, opts)
+    }
+  } catch (error) {
+    if (!isRaw && spin) spin.fail(`${label} failed`)
+    await formatKernelError(error, isRaw, undefined, opts.debug, { credential: opts.creds })
+    process.exit(1)
+  }
+}
+
+/**
+ * Normalize a `listChildren` response into an array of items.
+ * The kernel may return a bare array or `{ items: [...] }`.
+ */
+export function extractItems<T = Record<string, unknown>>(result: unknown): T[] {
+  if (Array.isArray(result)) return result as T[]
+  if (result && typeof result === 'object') {
+    const items = (result as { items?: unknown }).items
+    if (Array.isArray(items)) return items as T[]
+  }
+  return []
+}