@astrale-os/cli 0.4.0-alpha.13 → 0.6.0-alpha.0

package/src/connect-core.ts

@@ -0,0 +1,53 @@
+/**
+ * connect-core — the frozen, curated re-export surface the connect-host adapter
+ * borrows from the CLI. It is the ONE public seam between `@astrale-os/cli` and
+ * `@astrale-os/connect-host`; nothing else in cli/src is contract.
+ *
+ * Consumed by `@astrale-os/connect-host`; temps-2 seed of a future
+ * `@astrale-os/client-core`. Re-export ONLY — no logic lives here.
+ */
+
+// ── identity registry (~/.astrale/identities.json) ──────────────────────────
+export { readIdentities, getDefault, getIdentity } from './lib/identity'
+export type { Identity, IdentityStore } from './lib/identity'
+
+// ── keypairs on disk + self-grant mint ──────────────────────────────────────
+export { signAs, listIdentityKeys } from './lib/keys'
+
+// ── instance bookmarks (~/.astrale/instances.json) ──────────────────────────
+export {
+  readInstances,
+  resetInstancesMemo,
+  resolveInstance,
+  normalizeInstanceKernelUrl,
+  orgIdForAudience,
+} from './lib/instance'
+export type { InstanceEntry, InstanceStore, ResolvedInstance } from './lib/instance'
+
+// ── instance-target resolution (bookmark | managed | admin | free url) ──────
+export { resolveInstanceTarget } from './lib/instance-target'
+export type { ResolvedInstanceTarget } from './lib/instance-target'
+
+// ── global config (~/.astrale/config.json) ──────────────────────────────────
+export { readConfig } from './lib/config'
+export type { AstraleConfig } from './lib/config'
+
+// ── credential resolution (self-grant + IdP) ────────────────────────────────
+export { resolveCredential, IdpRefreshTransientError, IdpOrgMembershipError } from './kernel/auth'
+
+// ── IdP login (device flow) — driven by connect-host's `auth.login` op ───────
+export { loginViaIdp, resolveIdpName } from './lib/login-flow'
+export type { LoginFlowOpts, LoginResult, DeviceVerification } from './lib/login-flow'
+
+// ── IdP session state (so connect-host can flag "login required" rows) ───────
+export { readIdpSession, isSessionExpired } from './lib/idp'
+export type { IdpSession } from './lib/idp'
+
+// ── typed errors ────────────────────────────────────────────────────────────
+export { AuthError } from './errors'
+
+// ── custom-CA fetch (private-CA local stacks) ───────────────────────────────
+export { fetchWithCaFile } from './kernel/ca-fetch'
+
+// ── path resolution (~/.astrale layout) ─────────────────────────────────────
+export { paths, createPaths } from './lib/env'

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

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

package/src/kernel/__tests__/expand.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, test } from 'bun:test'
+
+import type { SelfResolverContext } from '../../lib/self'
+
+import { resolveSelfIdLazy } from '../expand'
+
+describe('resolveSelfIdLazy', () => {
+  test('refreshes a cached IdP @self registration via whoami', async () => {
+    const writes: unknown[][] = []
+    const ctx: SelfResolverContext = {
+      identity: {
+        name: 'bryan',
+        subject: 'user_01KC9MW1M6S5J6V9ERSRJ8RDYF',
+        createdAt: '2026-06-25T08:00:00.000Z',
+        source: 'idp',
+        registrations: {
+          bryan: {
+            iss: 'https://old.example',
+            sub: '4ad8e4ce-5cf7-4c2e-ab29-5549023dc8bf',
+            registeredAt: '2026-06-25T08:00:00.000Z',
+          },
+        },
+      },
+      instanceSlug: 'bryan',
+      instanceSigned: false,
+    }
+
+    const id = await resolveSelfIdLazy(
+      ctx,
+      {},
+      {
+        whoami: async () => ({
+          id: 'f011538e-9edc-4c29-92ce-9b81b6c1b6c7',
+          kernelUrl: 'https://bryan.example',
+        }),
+        setRegistration: async (...args) => {
+          writes.push(args)
+        },
+        now: () => new Date('2026-06-25T08:15:00.000Z'),
+      },
+    )
+
+    expect(id).toBe('f011538e-9edc-4c29-92ce-9b81b6c1b6c7')
+    expect(writes).toEqual([
+      [
+        'bryan',
+        'bryan',
+        {
+          iss: 'https://bryan.example',
+          sub: 'f011538e-9edc-4c29-92ce-9b81b6c1b6c7',
+          registeredAt: '2026-06-25T08:15:00.000Z',
+        },
+      ],
+    ])
+  })
+
+  test('keeps the cached IdP id when whoami is temporarily unavailable', async () => {
+    const ctx: SelfResolverContext = {
+      identity: {
+        name: 'bryan',
+        subject: 'user_01KC9MW1M6S5J6V9ERSRJ8RDYF',
+        createdAt: '2026-06-25T08:00:00.000Z',
+        source: 'idp',
+        registrations: {
+          bryan: {
+            iss: 'https://bryan.example',
+            sub: 'cached-id',
+            registeredAt: '2026-06-25T08:00:00.000Z',
+          },
+        },
+      },
+      instanceSlug: 'bryan',
+      instanceSigned: false,
+    }
+
+    await expect(
+      resolveSelfIdLazy(
+        ctx,
+        {},
+        {
+          whoami: async () => {
+            throw new Error('network down')
+          },
+        },
+      ),
+    ).resolves.toBe('cached-id')
+  })
+
+  test('does not run whoami for key-backed registrations', async () => {
+    const ctx: SelfResolverContext = {
+      identity: {
+        name: 'alice',
+        subject: 'alice',
+        createdAt: '2026-06-25T08:00:00.000Z',
+        source: 'key',
+        registrations: {
+          bryan: {
+            iss: 'https://bryan.example',
+            sub: 'key-node-id',
+            registeredAt: '2026-06-25T08:00:00.000Z',
+          },
+        },
+      },
+      instanceSlug: 'bryan',
+      instanceSigned: false,
+    }
+    let called = false
+
+    const id = await resolveSelfIdLazy(
+      ctx,
+      {},
+      {
+        whoami: async () => {
+          called = true
+          return { id: 'should-not-be-used', kernelUrl: 'https://bryan.example' }
+        },
+      },
+    )
+
+    expect(id).toBe('key-node-id')
+    expect(called).toBe(false)
+  })
+})

package/src/kernel/client.ts

@@ -1,16 +1,15 @@
 import { KernelClient, type FnMap } from '@astrale-os/kernel-client'
-import { ClientSession } from '@astrale-os/kernel-client/session'
+import { ClientSession, delegationMintVia } from '@astrale-os/kernel-client/session'
 
 import type { AdminTargetCommandOpts } from '../lib/admin-target'
 import type { KernelCommandOpts } from './types'
 
 import { AstraleError } from '../errors'
-import { ADMIN_INSTANCE, type InstanceInfo } from '../lib/admin-instance'
+import { adminInstanceMethod, type InstanceInfo } from '../lib/admin-instance'
 import { readConfig } from '../lib/config'
 import { resolveInstanceTarget, type ResolvedInstanceTarget } from '../lib/instance-target'
 import { resolveCredential } from './auth'
 import { fetchWithCaFile } from './ca-fetch'
-import { mintRemoteCredential } from './remote-routing'
 
 const DEFAULT_TIMEOUT_MS = 30_000
 
@@ -22,7 +21,7 @@ export type ClientContext = {
   config: Awaited<ReturnType<typeof readConfig>>
 }
 
-type ResolvedKernelTarget = {
+export type ResolvedKernelTarget = {
   url: string
   audience: string
   slug?: string
@@ -30,44 +29,50 @@ type ResolvedKernelTarget = {
   caFile?: string
 }
 
-/**
- * Connect to a kernel instance, run `fn`, then disconnect.
- * The new client is lazy: construction does no I/O. We only need to
- * release sockets on the way out.
- */
-export async function withKernelClient<T>(
+/** Resolve the kernel a command targets (`--url` / `-i` / active instance). */
+export async function resolveKernelTarget(
   opts: KernelCommandOpts,
-  fn: (ctx: ClientContext) => Promise<T>,
-): Promise<T> {
-  const config = await readConfig()
+  config: Awaited<ReturnType<typeof readConfig>>,
+): Promise<ResolvedKernelTarget> {
   // Ad-hoc `--url` — unknown kernel. Stamp the URL itself as audience,
   // no slug for per-instance signing.
-  let target: ResolvedKernelTarget
   if (opts.url && !opts.instance) {
     const resolved = await resolveInstanceTarget(
       { source: 'url', url: opts.url },
       { config, admin: adminLookupOpts(opts) },
     )
-    target = resolvedToKernelTarget(resolved)
-  } else {
-    const resolved = await resolveInstanceTarget(
-      opts.instance ? { source: 'name', name: opts.instance } : { source: 'active' },
-      {
-        config,
-        admin: adminLookupOpts(opts),
-        managed: (slug) => lookupManagedInstance(slug, opts),
-      },
-    )
-    target = resolvedToKernelTarget(resolved, opts.url)
+    return resolvedToKernelTarget(resolved)
   }
+  const resolved = await resolveInstanceTarget(
+    opts.instance ? { source: 'name', name: opts.instance } : { source: 'active' },
+    {
+      config,
+      admin: adminLookupOpts(opts),
+      managed: (slug) => lookupManagedInstance(slug, opts),
+    },
+  )
+  return resolvedToKernelTarget(resolved, opts.url)
+}
 
+/**
+ * Connect to a kernel instance, run `fn`, then disconnect.
+ * The new client is lazy: construction does no I/O. We only need to
+ * release sockets on the way out.
+ */
+export async function withKernelClient<T>(
+  opts: KernelCommandOpts,
+  fn: (ctx: ClientContext) => Promise<T>,
+): Promise<T> {
+  const config = await readConfig()
+  const target = await resolveKernelTarget(opts, config)
   return withResolvedKernelClient(opts, config, target, fn)
 }
 
 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,
+    async (ctx) =>
+      (await ctx.client.call(adminInstanceMethod('info'), { id: slug })) as InstanceInfo,
   )
 }
 
@@ -131,21 +136,12 @@ async function withResolvedKernelClient<T>(
   // exponential backoff on ECONNREFUSED / 5xx). The user can re-run.
   const requestTimeout = resolveTimeoutMs(opts.timeout)
   const fetchImpl = target.caFile ? fetchWithCaFile(target.caFile) : undefined
-  // The delegation mint references `client` lazily — it only fires on a cache
-  // miss during an actual remote call, long after this binding is initialised,
-  // so the self-reference inside the closure is safe.
   const client: ClientSession<FnMap> = new ClientSession<FnMap>({
     default: target.url,
     identity: credential,
-    // Remote-bound functions redirect to a worker that verifies `aud` against
-    // its own identity. The session follows the redirect and mints a worker-
-    // scoped delegation here, for the audience the kernel carries on the
-    // redirect (`redirection.iss`, surfaced by the default iss-aware policy).
     delegation: {
-      mint: async (audience) => ({
-        credential: await mintRemoteCredential(client, audience, credential),
-        ttl: 3600,
-      }),
+      // Resolve lazily: the session must exist before the cache mints.
+      mint: delegationMintVia(() => client, credential),
       ttl: 3600,
     },
     pool: {

package/src/kernel/expand.ts

@@ -1,14 +1,8 @@
 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 { adminInstanceMethod } from '../lib/admin-instance'
+/** CLI bridge for @self resolution and stale-registration error hints. */
 import { readConfig } from '../lib/config'
 import { getDefault, getIdentity, setRegistration } from '../lib/identity'
 import { decodeTokenClaims, readIdpSession } from '../lib/idp'
@@ -34,13 +28,7 @@ export type SelfExpansionMeta = {
   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.
- */
+/** Build the same target/signing context `withKernelClient` will use. */
 export async function buildSelfContext(opts: KernelCommandOpts): Promise<SelfResolverContext> {
   const config = await readConfig()
   // Mirror withKernelClient's slug logic: --url without -i ⇒ no slug.
@@ -70,11 +58,7 @@ export async function buildSelfContext(opts: KernelCommandOpts): Promise<SelfRes
     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.
+  // Identity lookup failures should surface as real CLI errors, not @self refusals.
   let identity: SelfResolverContext['identity']
   if (!opts.creds) {
     const identityName = opts.as ?? defaultIdentity
@@ -111,7 +95,8 @@ function adminLookupOpts(opts: KernelCommandOpts): KernelCommandOpts {
 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,
+    async (ctx) =>
+      (await ctx.client.call(adminInstanceMethod('info'), { id: slug })) as InstanceInfo,
   )
 }
 
@@ -142,59 +127,68 @@ export function resolveOrThrow(selfCtx: SelfResolverContext): string {
   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'
+export type ResolveSelfIdLazyDeps = {
+  whoami?: (opts: KernelCommandOpts) => Promise<{ id?: unknown; kernelUrl: string }>
+  setRegistration?: typeof setRegistration
+  now?: () => Date
+}
 
 /**
- * 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.
+ * Resolve @self for IdP identities through one whoami refresh, then cache the
+ * current node id. Non-IdP refusals stay typed and local.
  */
 export async function resolveSelfIdLazy(
   selfCtx: SelfResolverContext,
   opts: KernelCommandOpts,
+  deps: ResolveSelfIdLazyDeps = {},
 ): 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)
+  const cachedId = 'reason' in r ? undefined : r.id
+  const isIdp = (selfCtx.identity?.source ?? 'key') === 'idp'
+
+  if (isIdp && selfCtx.instanceSlug && selfCtx.identity) {
+    let lookup: { id?: unknown; kernelUrl: string }
+    try {
+      lookup = await (deps.whoami ?? whoamiSelfId)(opts)
+    } catch {
+      if (cachedId) return cachedId
+      if ('reason' in r) throw selfRefusalError(r)
+      throw selfRefusalError({ reason: 'idp-no-sub', identityName: selfCtx.identity.name })
+    }
+
+    const resolvedId =
+      typeof lookup.id === 'string' && lookup.id.trim().length > 0 ? lookup.id : undefined
+    if (!resolvedId) {
+      if (cachedId) return cachedId
+      if ('reason' in r) throw selfRefusalError(r)
+      throw selfRefusalError({ reason: 'idp-no-sub', identityName: selfCtx.identity.name })
+    }
+
+    const cached = selfCtx.identity.registrations?.[selfCtx.instanceSlug]
+    if (cached?.sub !== resolvedId || cached?.iss !== lookup.kernelUrl) {
+      await (deps.setRegistration ?? setRegistration)(selfCtx.identity.name, selfCtx.instanceSlug, {
+        iss: lookup.kernelUrl,
+        sub: resolvedId,
+        registeredAt: (deps.now ?? (() => new Date()))().toISOString(),
+      })
+    }
+    return resolvedId
   }
-  let me: { id?: unknown } | null
+
+  if (!('reason' in r)) return r.id
+  throw selfRefusalError(r)
+}
+
+async function whoamiSelfId(opts: KernelCommandOpts): Promise<{ id?: unknown; kernelUrl: string }> {
   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(),
+  const me = await withKernelClient(opts, (ctx) => {
+    kernelUrl = ctx.url
+    return ctx.client.as(ctx.credential).auth.whoami()
   })
-  return id
+  return { id: me.id, kernelUrl }
 }
 
-/**
- * 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.
- */
+/** Expand @self in path-like commands and return metadata for NotFound hints. */
 export async function expandSelfInPath(
   path: string,
   opts: KernelCommandOpts,

package/src/kernel/graph.ts

@@ -0,0 +1,96 @@
+import type {
+  GetResultWire,
+  GraphApi,
+  GraphNodeWire,
+  MutationResultWire,
+  PatchInput,
+  QueryASTInput,
+} from '@astrale-os/kernel-client/graph'
+
+import { createGraph, rawOf } from '@astrale-os/kernel-client/graph'
+
+import type { ClientContext } from './client'
+
+export type {
+  GetResultWire,
+  GraphApi,
+  GraphNodeWire,
+  MutationResultWire,
+  PatchInput,
+  QueryASTInput,
+}
+
+/** A node row as it crosses the graph doors — the shared item shape for `get`/`ls`/`describe`. */
+export type GraphNode = GraphNodeWire
+
+/**
+ * Bind the graph sugar (`function.get` / `function.mutate` + the read/write
+ * helpers) over a CLI client session. The sugar is pure over a call capability;
+ * we hand it `ClientSession.call` — the same surface every command already uses.
+ */
+export function bindGraph(ctx: ClientContext): GraphApi {
+  return createGraph((method, params) => ctx.client.call(method, params))
+}
+
+/**
+ * Split a `function.get` page into addressed root and descendants. Root matches
+ * path/id first, then falls back to the shallowest node in the page.
+ */
+export function splitRoot(
+  nodes: readonly GraphNode[],
+  rootPath: string,
+): { root: GraphNode | undefined; children: GraphNode[] } {
+  const raw = rawOf(rootPath)
+  const idForm = rootPath.startsWith('@') ? rootPath.slice(1) : undefined
+
+  let idx = nodes.findIndex(
+    (n) => rawOf(n.path) === raw || (idForm !== undefined && n.id === idForm),
+  )
+  if (idx < 0 && nodes.length > 0) {
+    let min = Number.POSITIVE_INFINITY
+    nodes.forEach((n, i) => {
+      const depth = rawOf(n.path).split('/').length
+      if (depth < min) {
+        min = depth
+        idx = i
+      }
+    })
+  }
+
+  const root = idx >= 0 ? nodes[idx] : undefined
+  const children = idx >= 0 ? nodes.filter((_, i) => i !== idx) : [...nodes]
+  return { root, children }
+}
+
+/** The children cursor of a single-root `function.get` result, if the page overflowed. */
+export function childrenCursor(result: GetResultWire): string | undefined {
+  const next = result.next
+  if (!next) return undefined
+  return Object.values(next)[0]?.children
+}
+
+/**
+ * Strip a fully-qualified prop key to its leaf name. Node props travel under
+ * qualified keys (`<domain>:class.X.property.name` / `<domain>:interface.I.property.name`);
+ * this recovers `name`.
+ */
+export function unqualifyKey(key: string): string {
+  const dot = key.lastIndexOf('.property.')
+  if (dot >= 0) return key.slice(dot + '.property.'.length)
+  const slash = key.lastIndexOf('/')
+  return slash >= 0 ? key.slice(slash + 1) : key
+}
+
+/** Read a node prop by its unqualified leaf name (exact key wins, else a qualified match). */
+export function nodeProp(
+  node: { props: Record<string, unknown> } | null | undefined,
+  name: string,
+): unknown {
+  const props = node?.props
+  if (!props) return undefined
+  if (name in props) return props[name]
+  for (const [k, v] of Object.entries(props)) {
+    if (unqualifyKey(k) === name) return v
+  }
+  return undefined
+}

package/src/kernel/index.ts

@@ -1,4 +1,10 @@
-export { withKernelClient, withAdminKernelClient, type ClientContext } from './client'
+export {
+  withKernelClient,
+  withAdminKernelClient,
+  resolveKernelTarget,
+  type ClientContext,
+  type ResolvedKernelTarget,
+} from './client'
 export { resolveCredential } from './auth'
 export { formatKernelError } from './errors'
 export {
@@ -9,6 +15,15 @@ export {
   resolveSelfIdLazy,
   type SelfExpansionMeta,
 } from './expand'
-export { mintRemoteCredential } from './remote-routing'
-export { runKernelCommand, extractItems } from './run'
+export { runKernelCommand } from './run'
+export { bindGraph, splitRoot, childrenCursor, nodeProp, unqualifyKey } from './graph'
+export type {
+  GetResultWire,
+  GraphApi,
+  GraphNode,
+  GraphNodeWire,
+  MutationResultWire,
+  PatchInput,
+  QueryASTInput,
+} from './graph'
 export type { KernelCommandOpts, CallCommandOpts } from './types'

package/src/kernel/options.ts

@@ -15,7 +15,7 @@ export const KERNEL_PASSTHROUGH_OPTIONS: CommandOption[] = [
     flags: '-i, --instance <name>',
     description: 'Target a specific instance (overrides active)',
   },
-  { flags: '--timeout <ms>', description: 'Request timeout in ms', default: '30000' },
+  { 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/run.ts

@@ -48,16 +48,3 @@ export async function runKernelCommand<T>(run: RunOpts<T>): Promise<void> {
     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 []
-}

package/src/lib/__tests__/instance-target.test.ts

@@ -3,6 +3,7 @@ import { describe, expect, test } from 'bun:test'
 import type { AstraleConfig } from '../config'
 import type { InstanceStore } from '../instance'
 
+import { AstraleError } from '../../errors'
 import { DEFAULT_CONFIG } from '../config'
 import {
   couldBeConfiguredAdminInstance,
@@ -181,3 +182,36 @@ describe('instance target helpers', () => {
     expect(isManagedInstanceNotFound(auth)).toBe(false)
   })
 })
+
+describe('isManagedInstanceNotFound: kernel InternalKernelError wrap', () => {
+  test('NOT_FOUND-prefixed InternalKernelError is an instance miss', () => {
+    const e = new Error('NOT_FOUND: no instance node for "knowledge"')
+    e.name = 'InternalKernelError'
+    expect(isManagedInstanceNotFound(e)).toBe(true)
+  })
+  test('other InternalKernelError messages are not swallowed', () => {
+    const e = new Error('DISPATCH_FAILED: handler crashed')
+    e.name = 'InternalKernelError'
+    expect(isManagedInstanceNotFound(e)).toBe(false)
+  })
+  test('resolveNamedInstanceTarget maps the wrap to typed INSTANCE_NOT_FOUND', async () => {
+    const managed = async () => {
+      const e = new Error('NOT_FOUND: no instance node for "ghost"')
+      e.name = 'InternalKernelError'
+      throw e
+    }
+    const opts = {
+      config: DEFAULT_CONFIG,
+      instances: { instances: {} },
+      managed,
+    } as unknown as Parameters<typeof resolveInstanceTarget>[1]
+    let caught: unknown
+    try {
+      await resolveInstanceTarget({ source: 'name', name: 'ghost' }, opts)
+    } catch (e) {
+      caught = e
+    }
+    expect(caught).toBeInstanceOf(AstraleError)
+    expect((caught as AstraleError).code).toBe('INSTANCE_NOT_FOUND')
+  })
+})