@capyclaw/foundation 0.1.3 → 0.1.4

package/README.md

@@ -25,7 +25,10 @@ export const { name, inject, apply } = createPlugin({
 
 ## 状态
 
-- 已发布 `0.1.1`，并登记进 `capyclaw-registry.json`。
+- 已发布 `0.1.3`，并登记进 `capyclaw-registry.json`。
+- 分层：应用插件 → ABI → 内核 → **Host 适配器** → agent 运行时。内核不认识 dsh；
+  `lib/host/dsh.mjs` 是唯一知道 dsh 服务名的地方，`lib/host/memory.mjs` 是可移植性基线。
+  规范见 `docs/HOST-ADAPTER.md`。
 - ABI v1，六个接口适配器全部可用：`skill-provider` / `tool-provider` / `runtime-driver` /
   `http-router` / `ui-panel` / `lifecycle-hook`，另有逃生舱 `raw@1`。
 - 能力表按 `ctx` 实际服务探测（见 `lib/kernel.mjs` 的 `detectCapabilities`），不做空头承诺。

package/abi/loader.mjs

@@ -23,6 +23,8 @@ import { satisfies } from './version.mjs'
  * }} options
  */
 export function createLoader({ adapters = {}, capabilities = {}, log = null, abiMajor = ABI_MAJOR } = {}) {
+  /** 能力表可以是对象，也可以是函数（宿主服务晚到时可现查）。 */
+  const capabilityMap = () => (typeof capabilities === 'function' ? capabilities() : capabilities)
   /** @type {Map<string, { spec: object, entries: object[], handle: object }>} */
   const plugins = new Map()
   /** 唯一性占用：key -> 插件名 */
@@ -45,7 +47,7 @@ export function createLoader({ adapters = {}, capabilities = {}, log = null, abi
     const missing = []
     for (const requirement of spec.requires) {
       if (!requirement.name.startsWith('os.')) continue // 跨插件能力由 suite 组合期校验，运行时只报告
-      const version = capabilities[requirement.name]
+      const version = capabilityMap()[requirement.name]
       if (!version) {
         missing.push({ name: requirement.name, range: requirement.range, reason: '未提供' })
       } else if (!satisfies(version, requirement.range)) {
@@ -196,7 +198,7 @@ export function createLoader({ adapters = {}, capabilities = {}, log = null, abi
 
   /** 当前可用的能力版本：内核承诺优先，其次插件提供。 */
   function capability(name) {
-    return capabilities[name] || provided.get(name)?.version || null
+    return capabilityMap()[name] || provided.get(name)?.version || null
   }
 
   /** 未解析的跨插件能力（运行时只报告，组合期才是硬闸）。 */
@@ -205,7 +207,7 @@ export function createLoader({ adapters = {}, capabilities = {}, log = null, abi
     for (const { spec } of plugins.values()) {
       for (const requirement of spec.requires) {
         if (requirement.name.startsWith('os.')) continue
-        if (provided.has(requirement.name) || capabilities[requirement.name]) continue
+        if (provided.has(requirement.name) || capabilityMap()[requirement.name]) continue
         out.push({ plugin: spec.name, capability: requirement.name, range: requirement.range })
       }
     }
@@ -214,7 +216,7 @@ export function createLoader({ adapters = {}, capabilities = {}, log = null, abi
 
   /** 内核状态快照：给 os.report() 与健康检查用。 */
   function report() {
-    const capabilityView = { ...capabilities }
+    const capabilityView = { ...capabilityMap() }
     for (const [name, info] of provided) capabilityView[name] = info.version
     return {
       abiVersion: abiMajor,

package/lib/adapters/http-router.mjs

@@ -5,15 +5,14 @@
  * 应用侧不接触 server、不选端口。
  */
 import { AbiError, ERROR_CODES } from '../../abi/errors.mjs'
-import { getService } from '../ctx-service.mjs'
 
 export const kind = 'http-router@1'
 
-export function createHttpRouterAdapter({ ctx, net, log }) {
+export function createHttpRouterAdapter({ host, net, log }) {
   return {
     kind,
     compile(impl, { spec, config }) {
-      const serviceHost = getService(ctx, 'serviceHost')
+      const serviceHost = host.http()
       if (!serviceHost?.createApp) {
         throw new AbiError(ERROR_CODES.E_CAP_MISSING,
           'ctx.serviceHost 不可用：无法创建子 app', { plugin: spec.name, capability: 'os.net' })

package/lib/adapters/runtime-driver.mjs

@@ -7,17 +7,16 @@
 import { fileURLToPath } from 'node:url'
 
 import { AbiError, ERROR_CODES } from '../../abi/errors.mjs'
-import { getService } from '../ctx-service.mjs'
 
 export const kind = 'runtime-driver@1'
 
-export function createRuntimeDriverAdapter({ ctx, config, log }) {
+export function createRuntimeDriverAdapter({ host, config, log }) {
   const defaultPort = config.driverPort ?? 0
 
   return {
     kind,
     compile(impl, mountContext) {
-      const broker = getService(ctx, 'serviceBroker')
+      const broker = host.proc()
       if (!broker?.start || !broker?.stop) {
         throw new AbiError(ERROR_CODES.E_CAP_MISSING,
           'ctx.serviceBroker 不可用：无法拉起长驻进程',

package/lib/adapters/skill-provider.mjs

@@ -9,16 +9,15 @@ import { basename, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 import { AbiError, ERROR_CODES } from '../../abi/errors.mjs'
-import { getService } from '../ctx-service.mjs'
 import { createSkillProvider } from '../skill/scan.mjs'
 
 export const kind = 'skill-provider@1'
 
-export function createSkillAdapter({ ctx, log }) {
+export function createSkillAdapter({ host, log }) {
   return {
     kind,
     compile(impl, { spec, context }) {
-      const skills = getService(ctx, 'skills')
+      const skills = host.skills()
       if (!skills || typeof skills.registerProvider !== 'function') {
         throw new AbiError(ERROR_CODES.E_CAP_MISSING,
           'ctx.skills.registerProvider 不可用：skills 服务未加载', { plugin: spec.name })

package/lib/adapters/tool-provider.mjs

@@ -7,16 +7,15 @@
  * 工具实现不经过 foundation，foundation 只决定「什么时候挂上去、挂到哪个命名空间」。
  */
 import { AbiError, ERROR_CODES } from '../../abi/errors.mjs'
-import { getService } from '../ctx-service.mjs'
 
 export const kind = 'tool-provider@1'
 
-export function createToolProviderAdapter({ ctx, log }) {
+export function createToolProviderAdapter({ host, log }) {
   return {
     kind,
     compile(impl, { spec, config }) {
-      const toolHost = getService(ctx, 'toolHost')
-      if (!toolHost?.registerWithDsh) {
+      const tools = host.tools()
+      if (!tools?.register) {
         throw new AbiError(ERROR_CODES.E_CAP_MISSING,
           'ctx.toolHost 不可用：无法注册工具面', { plugin: spec.name, capability: 'os.tools' })
       }
@@ -33,7 +32,7 @@ export function createToolProviderAdapter({ ctx, log }) {
           'provide() 必须返回 { TOOLS, TOOL_IMPL } 形状的注册表', { plugin: spec.name })
       }
 
-      const dispose = toolHost.registerWithDsh(ctx, registry, { namespace: impl.namespace })
+      const dispose = tools.register(registry, { namespace: impl.namespace })
       log?.debug?.(`[foundation] ${spec.name} 注册 ${registry.TOOLS.length} 个工具（${impl.namespace}）`)
       return {
         registry,

package/lib/adapters/ui-panel.mjs

@@ -6,16 +6,15 @@
 import { fileURLToPath } from 'node:url'
 
 import { AbiError, ERROR_CODES } from '../../abi/errors.mjs'
-import { getService } from '../ctx-service.mjs'
 
 export const kind = 'ui-panel@1'
 
-export function createUiPanelAdapter({ ctx, net, log }) {
+export function createUiPanelAdapter({ host, net, log }) {
   return {
     kind,
     compile(impl, { spec, config, context }) {
-      const serviceHost = getService(ctx, 'serviceHost')
-      const editorHost = getService(ctx, 'editorHost')
+      const serviceHost = host.http()
+      const editorHost = host.ui()
       if (!serviceHost?.createApp || !editorHost?.createEditorHost) {
         throw new AbiError(ERROR_CODES.E_CAP_MISSING,
           'ctx.editorHost / ctx.serviceHost 不可用：无法挂静态面板',

package/lib/host/caps.mjs

@@ -0,0 +1,26 @@
+/**
+ * 宿主能力表：内核承诺给应用插件的 os.* 能力。
+ *
+ * BASE 是内核自身就能提供的；其余取决于宿主实际接入了哪些服务。
+ * 这里是唯一允许出现宿主服务名（skills / serviceHost / toolHost / serviceBroker /
+ * editorHost）的地方——它们属于 dsh 适配层，不属于 ABI。
+ */
+import { getService } from '../ctx-service.mjs'
+
+export const BASE_CAPABILITIES = Object.freeze({
+  'os.events': '1.0.0',
+  'os.log': '1.0.0',
+  'os.caps': '1.0.0',
+})
+
+/** dsh 宿主：按 ctx 里实际存在的服务生成能力表。 */
+export function detectDshCapabilities(ctx) {
+  const capabilities = { ...BASE_CAPABILITIES }
+  if (getService(ctx, 'skills')?.registerProvider) capabilities['os.skills'] = '1.0.0'
+  const serviceHost = getService(ctx, 'serviceHost')
+  if (serviceHost?.createSharedHost && serviceHost?.createApp) capabilities['os.net'] = '1.0.0'
+  if (getService(ctx, 'toolHost')?.registerWithDsh) capabilities['os.tools'] = '1.0.0'
+  if (getService(ctx, 'serviceBroker')?.start) capabilities['os.proc'] = '1.0.0'
+  if (getService(ctx, 'editorHost')?.createEditorHost) capabilities['os.ui'] = '1.0.0'
+  return capabilities
+}

package/lib/host/dsh.mjs

@@ -0,0 +1,41 @@
+/**
+ * dsh 宿主适配器：把 Cordis ctx 翻译成内核认识的 Host 接口。
+ *
+ * 这是整个 foundation 里**唯一**知道 dsh 服务名的地方。换一个 agent 运行时，
+ * 只需要照着 Host 接口写一个新的适配器（lib/host/<runtime>.mjs），
+ * 内核、ABI 与应用插件都不改。
+ *
+ * Host 接口（v1）：
+ *   kind           宿主标识
+ *   capabilities() 返回 { 'os.xxx': '1.0.0' }，用于 mount 前的能力校验
+ *   log()          返回 { debug/info/warn/error } 或 undefined
+ *   skills()       { registerProvider(factory) => dispose }
+ *   tools()        { registerWithDsh(ctx, registry, { namespace }) => dispose }
+ *   http()         { createApp({id}), createSharedHost({id}) }
+ *   proc()         { start(serviceSpec) => Promise<{errors?}>, stop(id) }
+ *   ui()           { createEditorHost({ id, dir, basePath, index }) }
+ */
+import { getService } from '../ctx-service.mjs'
+import { detectDshCapabilities } from './caps.mjs'
+
+export const HOST_VERSION = '1.0.0'
+
+export function createDshHost(ctx) {
+  return {
+    kind: 'dsh',
+    version: HOST_VERSION,
+    capabilities: () => detectDshCapabilities(ctx),
+    log: () => getService(ctx, 'logger'),
+    skills: () => getService(ctx, 'skills'),
+    tools: () => {
+      const toolHost = getService(ctx, 'toolHost')
+      if (!toolHost?.registerWithDsh) return null
+      return {
+        register: (registry, options) => toolHost.registerWithDsh(ctx, registry, options),
+      }
+    },
+    http: () => getService(ctx, 'serviceHost'),
+    proc: () => getService(ctx, 'serviceBroker'),
+    ui: () => getService(ctx, 'editorHost'),
+  }
+}

package/lib/host/memory.mjs

@@ -0,0 +1,116 @@
+/**
+ * 内存宿主：Host 接口的参考实现，不依赖任何 agent 运行时。
+ *
+ * 用途有两个：
+ *   1. 一致性测试的基线——应用插件在这里跑通，说明它没有偷偷依赖 dsh；
+ *   2. 新宿主（别的 agent 系统）的模板——照这个接口实现即可，应用插件零改动。
+ *
+ * 它不承担真实网络/进程语义，只保证 Host 契约的形状与生命周期。
+ */
+import { BASE_CAPABILITIES } from './caps.mjs'
+
+const NOOP_LOG = { debug() {}, info() {}, warn() {}, error() {} }
+
+export function createMemoryHost(options = {}) {
+  const state = {
+    providers: [],
+    tools: [],
+    apps: [],
+    mounts: new Map(),
+    services: new Map(),
+  }
+  const log = options.log ?? NOOP_LOG
+
+  function http() {
+    return {
+      createApp({ id, title } = {}) {
+        const routes = []
+        const app = {
+          id,
+          title: title || id,
+          routes,
+          use(handler) {
+            routes.push(handler)
+            return () => {
+              const index = routes.indexOf(handler)
+              if (index >= 0) routes.splice(index, 1)
+            }
+          },
+          async dispatch() {},
+        }
+        state.apps.push(app)
+        return app
+      },
+      createSharedHost({ id } = {}) {
+        return {
+          id,
+          mount(prefix, child) {
+            if (state.mounts.has(prefix)) throw new Error(`前缀已挂载: ${prefix}`)
+            state.mounts.set(prefix, child.id)
+            return () => state.mounts.delete(prefix)
+          },
+          listen: () => Promise.resolve({ port: 0, url: `memory://${id || 'shared'}` }),
+          close: async () => {},
+          children: () => [...state.mounts.keys()],
+        }
+      },
+    }
+  }
+
+  return {
+    kind: 'memory',
+    version: '1.0.0',
+    state,
+    capabilities: () => ({
+      ...BASE_CAPABILITIES,
+      'os.skills': '1.0.0',
+      'os.net': '1.0.0',
+      'os.tools': '1.0.0',
+      'os.proc': '1.0.0',
+      'os.ui': '1.0.0',
+    }),
+    log: () => log,
+    skills: () => ({
+      registerProvider(factory) {
+        const provider = factory()
+        state.providers.push(provider)
+        return () => {
+          const index = state.providers.indexOf(provider)
+          if (index >= 0) state.providers.splice(index, 1)
+        }
+      },
+    }),
+    tools: () => ({
+      register(registry, options2 = {}) {
+        const entry = { registry, namespace: options2.namespace || '' }
+        state.tools.push(entry)
+        return () => {
+          const index = state.tools.indexOf(entry)
+          if (index >= 0) state.tools.splice(index, 1)
+        }
+      },
+    }),
+    http,
+    proc: () => ({
+      async start(serviceSpec) {
+        state.services.set(serviceSpec.id, serviceSpec)
+        return { services: [{ id: serviceSpec.id }], errors: [] }
+      },
+      stop(id) {
+        state.services.delete(id)
+      },
+    }),
+    ui: () => ({
+      createEditorHost({ id, dir, basePath, index }) {
+        return {
+          id,
+          dir,
+          basePath,
+          index,
+          routes: () => [async () => false],
+          status: () => ({ connected: false, lease: null }),
+        }
+      },
+    }),
+  }
+}

package/lib/kernel.mjs

@@ -1,14 +1,17 @@
 /**
  * 内核装配：把 ABI 加载器、适配器与 os 子系统接到一起。
  *
- * 能力表是**探测出来**的，不是写死的：ctx 里没有 skills 服务，就不承诺 os.skills，
- * 依赖它的插件在 mount 阶段拿到 E_CAP_MISSING，而不是运行到一半才炸。
+ * 分层：应用插件 → ABI → 内核 → **Host 适配器** → agent 运行时（dsh）。
+ * 内核不认识 dsh：它只调用 Host 接口（skills/tools/http/proc/ui/log/capabilities）。
+ * 换宿主 = 写一个新的 lib/host/<runtime>.mjs，ABI 与应用插件零改动。
  *
- * 惰性：os.net 只在第一次挂路由时创建共享宿主并 listen；纯 skill 插件不占端口。
+ * 能力表是**每次 mount 时现查**的：宿主服务晚于 foundation 激活也能被看到。
+ * 惰性：os.net 只在第一次挂路由时创建共享宿主并 listen。
  */
 import { ABI_MAJOR } from '../abi/kinds.mjs'
 import { createLoader } from '../abi/loader.mjs'
-import { getService } from './ctx-service.mjs'
+import { BASE_CAPABILITIES, detectDshCapabilities } from './host/caps.mjs'
+import { createDshHost } from './host/dsh.mjs'
 import { createSkillAdapter } from './adapters/skill-provider.mjs'
 import { createToolProviderAdapter } from './adapters/tool-provider.mjs'
 import { createRuntimeDriverAdapter } from './adapters/runtime-driver.mjs'
@@ -19,55 +22,57 @@ import { createEvents } from './subsystems/events.mjs'
 import { createLogger } from './subsystems/log.mjs'
 import { createNet } from './subsystems/net.mjs'
 
-/** 内核自身就能提供的能力（不依赖任何 dsh 服务）。 */
-export const BASE_CAPABILITIES = Object.freeze({
-  'os.events': '1.0.0',
-  'os.log': '1.0.0',
-  'os.caps': '1.0.0',
-})
+export { BASE_CAPABILITIES }
 
-/** 按 ctx 里实际存在的服务生成能力表。 */
+/** 兼容导出：测试与旧调用方按 ctx 探测 dsh 能力。 */
 export function detectCapabilities(ctx) {
-  const capabilities = { ...BASE_CAPABILITIES }
-  if (getService(ctx, 'skills')?.registerProvider) capabilities['os.skills'] = '1.0.0'
-  const serviceHost = getService(ctx, 'serviceHost')
-  if (serviceHost?.createSharedHost && serviceHost?.createApp) capabilities['os.net'] = '1.0.0'
-  if (getService(ctx, 'toolHost')?.registerWithDsh) capabilities['os.tools'] = '1.0.0'
-  if (getService(ctx, 'serviceBroker')?.start) capabilities['os.proc'] = '1.0.0'
-  if (getService(ctx, 'editorHost')?.createEditorHost) capabilities['os.ui'] = '1.0.0'
-  return capabilities
+  return detectDshCapabilities(ctx)
 }
 
 export const KERNEL_VERSION = '0.1.0'
 export const ABI_VERSION = ABI_MAJOR
 
-export function createKernel(ctx, config = {}) {
-  const log = createLogger(ctx, config)
+/**
+ * @param {object} ctx dsh Cordis ctx（自定义宿主时可为 null）
+ * @param {object} config 内核配置
+ * @param {{ host?: object }} [options] 显式传入 Host 适配器（测试/其他运行时）
+ */
+export function createKernel(ctx, config = {}, options = {}) {
+  const host = options.host ?? createDshHost(ctx)
+  const log = createLogger(host, config)
   const events = createEvents({
     onError: (error, topic) => log.error(`事件订阅者抛错 (${topic}): ${error.message}`),
   })
   const hooks = createHookRegistry()
-  const net = createNet(ctx, config)
-  const capabilities = detectCapabilities(ctx)
+  const net = createNet(host, config)
 
   const adapters = {
-    'skill-provider@1': createSkillAdapter({ ctx, log }),
-    'tool-provider@1': createToolProviderAdapter({ ctx, log }),
-    'runtime-driver@1': createRuntimeDriverAdapter({ ctx, config, log }),
-    'http-router@1': createHttpRouterAdapter({ ctx, net, log }),
-    'ui-panel@1': createUiPanelAdapter({ ctx, net, log }),
+    'skill-provider@1': createSkillAdapter({ host, log }),
+    'tool-provider@1': createToolProviderAdapter({ host, log }),
+    'runtime-driver@1': createRuntimeDriverAdapter({ host, config, log }),
+    'http-router@1': createHttpRouterAdapter({ host, net, log }),
+    'ui-panel@1': createUiPanelAdapter({ host, net, log }),
     'lifecycle-hook@1': createLifecycleAdapter({ hooks, log }),
   }
 
-  const loader = createLoader({ adapters, capabilities, log })
+  /* 能力表按需现查：宿主服务可能晚于 foundation 激活。 */
+  const loader = createLoader({ adapters, capabilities: () => host.capabilities(), log })
   const startedAt = Date.now()
 
   const os = {
     version: KERNEL_VERSION,
     abi: ABI_VERSION,
+    host: host.kind,
+    hostVersion: host.version || '1.0.0',
     mount: (spec, mountConfig = {}, meta = {}) => loader.mount(spec, mountConfig, meta),
     report: () => ({
-      kernel: { version: KERNEL_VERSION, abi: ABI_VERSION, uptimeMs: Date.now() - startedAt },
+      kernel: {
+        version: KERNEL_VERSION,
+        abi: ABI_VERSION,
+        host: host.kind,
+        hostVersion: host.version || '1.0.0',
+        uptimeMs: Date.now() - startedAt,
+      },
       ...loader.report(),
     }),
     events,
@@ -77,7 +82,7 @@ export function createKernel(ctx, config = {}) {
 
     /** 能力检查与自报。 */
     caps: {
-      list: () => Object.keys(capabilities),
+      list: () => Object.keys(host.capabilities()),
       has: (name) => loader.capability(name) !== null,
       version: (name) => loader.capability(name),
       report: () => loader.report(),

package/lib/subsystems/log.mjs

@@ -7,7 +7,6 @@
 import { getService } from '../ctx-service.mjs'
 
 const LEVELS = ['debug', 'info', 'warn', 'error']
-
 function createScoped(underlying, scope) {
   const prefix = scope ? `[${scope}]` : ''
   const scoped = {}
@@ -24,7 +23,7 @@ function createScoped(underlying, scope) {
   return scoped
 }
 
-export function createLogger(ctx, config = {}) {
-  const underlying = getService(ctx, 'logger')
+export function createLogger(host, config = {}) {
+  const underlying = typeof host?.log === 'function' ? host.log() : getService(host, 'logger')
   return createScoped(underlying, config.scope || 'foundation')
 }

package/lib/subsystems/net.mjs

@@ -5,25 +5,24 @@
  * 只注册 skill 的插件不会因为装了 foundation 就占一个端口。
  */
 import { AbiError, ERROR_CODES } from '../../abi/errors.mjs'
-import { getService } from '../ctx-service.mjs'
 
-export function createNet(ctx, config = {}) {
+export function createNet(host, config = {}) {
   const http = config.http || {}
-  let host = null
+  let sharedHost = null
   let listening = null
   let closed = false
 
   function ensure() {
-    const serviceHost = getService(ctx, 'serviceHost')
+    const serviceHost = host.http()
     if (!serviceHost?.createSharedHost) {
       throw new AbiError(ERROR_CODES.E_CAP_MISSING,
         'ctx.serviceHost 不可用：无法挂载 HTTP 路由', { capability: 'os.net' })
     }
-    if (!host) {
-      host = serviceHost.createSharedHost({ id: http.hostId || 'foundation-shared' })
-      listening = Promise.resolve(host.listen({ port: http.port ?? 0 }))
+    if (!sharedHost) {
+      sharedHost = serviceHost.createSharedHost({ id: http.hostId || 'foundation-shared' })
+      listening = Promise.resolve(sharedHost.listen({ port: http.port ?? 0 }))
     }
-    return host
+    return sharedHost
   }
 
   return {
@@ -31,7 +30,7 @@ export function createNet(ctx, config = {}) {
     mount(prefix, child) {
       return ensure().mount(prefix, child)
     },
-    children: () => (host ? host.children() : []),
+    children: () => (sharedHost ? sharedHost.children() : []),
     ready() {
       ensure()
       return listening
@@ -39,12 +38,12 @@ export function createNet(ctx, config = {}) {
     async dispose() {
       if (closed) return
       closed = true
-      if (host) {
+      if (sharedHost) {
         try {
-          await host.close()
+          await sharedHost.close()
         } catch { /* 已关闭 */ }
       }
-      host = null
+      sharedHost = null
     },
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capyclaw/foundation",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "dsh 插件基石层：接口 ABI、插件加载器与内核服务 ctx.os。应用插件只声明接口，不写装配代码。",
   "type": "module",
   "main": "./lib/host.mjs",