refactor(devframe)!: keep utils/hash; move hub-only internals to devframe/internal

antfubot · opencode · antfubot · commit b44ac51a67ee · 2026-08-11T04:50:06.000Z
- Restore `devframe/utils/hash` — kept as a public utility (maintainer request).
- Add a new `devframe/internal` entry point for the low-level primitives shared
  only between `devframe` and `@devframes/hub`, and relocate `createContextRpcServer`,
  `DevframeAgentHost`, and `coerceAgentPositionalArgs` there from `devframe/node`.
  `devframe/internal` is an explicitly-unstable cross-package surface; the hub
  imports these three from it. This keeps the public `devframe/node` barrel to
  the genuinely-public server-assembly API.

Updates the migration guide, SKILL/utilities docs, knip entry list, plan, and
regenerates the tsnapi snapshots.

Co-authored-by: opencode &lt;noreply@opencode.ai&gt;
diff --git a/alias.ts b/alias.ts
@@ -18,11 +18,13 @@ export const alias = {
   'devframe/node/auth': r('devframe/src/node/auth/index.ts'),
   'devframe/node/hub-internals': r('devframe/src/node/hub-internals/index.ts'),
   'devframe/node': r('devframe/src/node/index.ts'),
+  'devframe/internal': r('devframe/src/internal/index.ts'),
   'devframe/constants': r('devframe/src/constants.ts'),
   'devframe/utils/agent-tool-name': r('devframe/src/utils/agent-tool-name.ts'),
   'devframe/utils/colors': r('devframe/src/utils/colors.ts'),
   'devframe/utils/crypto-token': r('devframe/src/utils/crypto-token.ts'),
   'devframe/utils/events': r('devframe/src/utils/events.ts'),
+  'devframe/utils/hash': r('devframe/src/utils/hash.ts'),
   'devframe/utils/launch-editor': r('devframe/src/utils/launch-editor.ts'),
   'devframe/utils/nanoid': r('devframe/src/utils/nanoid.ts'),
   'devframe/utils/open': r('devframe/src/utils/open.ts'),
diff --git a/docs/guide/migration-0.9.md b/docs/guide/migration-0.9.md
@@ -114,21 +114,20 @@ import { defineDevframe, defineRpcFunction } from 'devframe'
 
 `devframe/types` still resolves as the type-only subpath — useful for `declare module 'devframe/types'` augmentations — but `devframe` is the canonical import for both values and types.
 
-## `devframe/utils/{hash,promise,scope}` are removed
+## `devframe/utils/{promise,scope}` are removed
 
-Three utility subpaths with no integration consumers are removed:
+Two utility subpaths with no integration consumers are removed:
 
 | Removed | Replacement |
 |---------|-------------|
 | `import { promiseWithResolver } from 'devframe/utils/promise'` | `Promise.withResolvers()` (native) |
-| `import { hash } from 'devframe/utils/hash'` | Any structural-hash library (e.g. `ohash`) |
 | `import { isQualifiedName, qualifyName } from 'devframe/utils/scope'` | Inline the check (`name.includes(':')`) |
 
-The other `devframe/utils/*` helpers — `colors`, `open`, `launch-editor`, `nanoid`, `crypto-token`, `structured-clone`, `events`, `shared-state`, `streaming-channel`, `when`, `simple-schema`, `serve-static`, `agent-tool-name` — are unchanged.
+The other `devframe/utils/*` helpers — `colors`, `open`, `launch-editor`, `hash`, `nanoid`, `crypto-token`, `structured-clone`, `events`, `shared-state`, `streaming-channel`, `when`, `simple-schema`, `serve-static`, `agent-tool-name` — are unchanged.
 
 ## `devframe/node` is slimmed to the server-assembly surface
 
-`devframe/node` keeps the API that hosts wiring up their own runtime actually use — `createHostContext`, `createH3DevframeHost`, `startHttpAndWs`, `createContextRpcServer`, `createStorage`, `registerDevframeInstance` / `listLiveDevframeInstances`, `DevframeAgentHost`, `coerceAgentPositionalArgs`, `isObject`, `normalizeHttpServerUrl`, and the `RpcFunctionsHost` / instance-record types.
+`devframe/node` keeps the API that hosts wiring up their own runtime actually use — `createHostContext`, `createH3DevframeHost`, `startHttpAndWs`, `createStorage`, `registerDevframeInstance` / `listLiveDevframeInstances`, `isObject`, `normalizeHttpServerUrl`, and the `RpcFunctionsHost` / instance-record types.
 
 The internal host implementations and low-level factories are no longer exported:
 
@@ -139,7 +138,17 @@ The internal host implementations and low-level factories are no longer exported
 | `createScopedNodeContext`, `createNodeSettings` | Internal to context assembly. |
 | `toDialableHost`, `formatHostForUrl` | Internal host-URL helpers. |
 
-A host that binds its own transport composes from `createContextRpcServer` (`devframe/node`) plus `devframe/rpc/server`, `devframe/rpc/transports/*`, and `devframe/node/hub-internals` — the path `@devframes/hub`'s `initHub` and `@vitejs/devtools` both take.
+## Cross-package internals move to `devframe/internal`
+
+The low-level primitives that only exist for the `devframe` ↔ `@devframes/hub` boundary now live at the new `devframe/internal` entry point, which is explicitly **unstable** (it can change in any minor release). They were previously on `devframe/node`:
+
+| Moved | From | To |
+|---|---|---|
+| `createContextRpcServer` (+ `ContextRpcServer`, `CreateContextRpcServerOptions`) | `devframe/node` | `devframe/internal` |
+| `DevframeAgentHost` (class) | `devframe/node` | `devframe/internal` |
+| `coerceAgentPositionalArgs` (+ `AgentArgsFallback`) | `devframe/node` | `devframe/internal` |
+
+A host that binds its own transport composes from `createContextRpcServer` (`devframe/internal`) plus `devframe/rpc/server`, `devframe/rpc/transports/*`, and `devframe/node/hub-internals` — the path `@devframes/hub`'s `initHub` takes. Application code should prefer the adapters and `devframe/node`.
 
 ## `@devframes/hub` category order lives only on `/constants`
 
diff --git a/docs/helpers/utilities.md b/docs/helpers/utilities.md
@@ -4,7 +4,7 @@ outline: deep
 
 # Utilities
 
-Devframe ships a set of small, stable helpers under the `devframe/utils/*` subpaths. They cover the most common ancillary tasks a devtool needs — colorising terminal output, opening files in an editor, generating IDs and tokens — without forcing every author to pick (and install) their own library.
+Devframe ships a set of small, stable helpers under the `devframe/utils/*` subpaths. They cover the most common ancillary tasks a devtool needs — colorising terminal output, hashing arbitrary values, opening files in an editor — without forcing every author to pick (and install) their own library.
 
 Each helper is bundled inside devframe. Importing from `devframe/utils/*` is enough — there's no separate `npm install` for these dependencies.
 
@@ -48,6 +48,16 @@ launchEditor('src/main.ts:42:7', 'code')
 
 The auto-detection reads the `LAUNCH_EDITOR` environment variable and falls back to common defaults. Most devframes consume this through the prebuilt `openInEditor` recipe — see [Common RPC Functions](./common-rpc-functions).
 
+### `devframe/utils/hash`
+
+Stable, deterministic hash of any structured-cloneable value. Useful for cache keys and dedup.
+
+```ts
+import { hash } from 'devframe/utils/hash'
+
+const key = hash({ functionName, args })
+```
+
 ### `devframe/utils/structured-clone`
 
 JSON-safe serialization for the structured-clone algorithm — round-trips `Map`, `Set`, `Date`, `BigInt`, cycles, and class instances. Used internally by the RPC wire format; exposed for tools that need the same encoding.
@@ -127,6 +137,6 @@ Statically-validated when-clause expressions for conditional UI visibility. The
 The utilities are exposed as **stable wrappers over their underlying libraries** rather than bare re-exports. Two consequences:
 
 - **One install.** Consumers do not list these libraries in their own `package.json`. Bundling them inside devframe means version drift across devtools is impossible.
-- **Swappable internals.** The wrapper signatures are deliberately narrower than upstream. Devframe can change the implementation (`ansis` → `picocolors`, …) without a breaking change to dependent devtools.
+- **Swappable internals.** The wrapper signatures are deliberately narrower than upstream. Devframe can change the implementation (`ansis` → `picocolors`, `ohash` → `crypto.subtle.digest`, …) without a breaking change to dependent devtools.
 
 When you need a feature outside the wrapper's minimal surface, prefer extending the wrapper inside devframe over bypassing it.
diff --git a/knip.jsonc b/knip.jsonc
@@ -76,6 +76,7 @@
         "src/adapters/{build,cac,dev,embedded,initiate}.ts",
         "src/adapters/mcp/index.ts",
         "src/client/index.ts",
+        "src/internal/index.ts",
         "src/node/index.ts",
         "src/node/{auth,hub-internals}/index.ts",
         "src/recipes/{common-rpc-functions,interactive-auth}.ts",
diff --git a/packages/devframe/package.json b/packages/devframe/package.json
@@ -29,6 +29,7 @@
     "./constants": "./dist/constants.mjs",
     "./helpers/vite": "./dist/helpers/vite.mjs",
     "./initiate": "./dist/adapters/initiate.mjs",
+    "./internal": "./dist/internal/index.mjs",
     "./node": "./dist/node/index.mjs",
     "./node/auth": "./dist/node/auth.mjs",
     "./node/hub-internals": "./dist/node/hub-internals.mjs",
@@ -46,6 +47,7 @@
     "./utils/colors": "./dist/utils/colors.mjs",
     "./utils/crypto-token": "./dist/utils/crypto-token.mjs",
     "./utils/events": "./dist/utils/events.mjs",
+    "./utils/hash": "./dist/utils/hash.mjs",
     "./utils/launch-editor": "./dist/utils/launch-editor.mjs",
     "./utils/nanoid": "./dist/utils/nanoid.mjs",
     "./utils/open": "./dist/utils/open.mjs",
diff --git a/packages/devframe/src/client/static-rpc.test.ts b/packages/devframe/src/client/static-rpc.test.ts
@@ -1,7 +1,7 @@
 import { DEVFRAME_RPC_DUMP_DIRNAME } from 'devframe/constants'
+import { hash } from 'devframe/utils/hash'
 import { structuredCloneStringify } from 'devframe/utils/structured-clone'
 import { describe, expect, it } from 'vitest'
-import { hash } from '../utils/hash'
 import { createStaticRpcCaller } from './static-rpc'
 
 const DEMO_STATIC_VERSION_PATH = `${DEVFRAME_RPC_DUMP_DIRNAME}/demo~version.static.json`
diff --git a/packages/devframe/src/client/static-rpc.ts b/packages/devframe/src/client/static-rpc.ts
@@ -1,7 +1,7 @@
 import type { RpcDumpRecordError } from '../rpc/types'
+import { hash } from 'devframe/utils/hash'
 import { structuredCloneDeserialize } from 'devframe/utils/structured-clone'
 import { reviveDumpError } from '../rpc/dump/error'
-import { hash } from '../utils/hash'
 
 export type StaticRpcSerialization = 'json' | 'structured-clone'
 
diff --git a/packages/devframe/src/internal/index.ts b/packages/devframe/src/internal/index.ts
@@ -0,0 +1,18 @@
+// Internal cross-package surface: low-level host primitives shared between
+// `devframe` and `@devframes/hub` (and any first-party host built on the same
+// wiring). These are NOT part of the stable public API — they can change in any
+// minor release. Application code should use `devframe/node` and the adapters
+// instead.
+//
+// - `createContextRpcServer` — the transport-agnostic RPC core; a host that
+//   binds its own transport (e.g. the hub's `initHub`) reuses the exact
+//   session/auth wiring `startHttpAndWs` uses.
+// - `DevframeAgentHost` — the agent host implementation the hub composes into
+//   its own commands host.
+// - `coerceAgentPositionalArgs` — positional-arg coercion the hub applies when
+//   invoking agent tools as commands.
+export { coerceAgentPositionalArgs } from '../node/agent-args'
+export type { AgentArgsFallback } from '../node/agent-args'
+export { DevframeAgentHost } from '../node/host-agent'
+export { createContextRpcServer } from '../node/rpc-core'
+export type { ContextRpcServer, CreateContextRpcServerOptions } from '../node/rpc-core'
diff --git a/packages/devframe/src/node/index.ts b/packages/devframe/src/node/index.ts
@@ -1,20 +1,17 @@
 // Node-side public API for hosts that wire up their own runtime — the
 // server-assembly surface (`createHostContext` → `startHttpAndWs`), the
-// transport-agnostic RPC core (`createContextRpcServer`), the instance
-// registry, storage, and the two URL/host helpers consumers use.
+// instance registry, storage, and the two URL/host helpers consumers use.
 //
 // The diagnostics/services/views hosts, the streaming/shared-state/scope/
 // settings factories, and the internal host helpers (`toDialableHost`,
 // `formatHostForUrl`) stay internal. `toAgentToolName` lives at
 // `devframe/utils/agent-tool-name` (a client-safe string transform).
 //
-// `coerceAgentPositionalArgs`, the `DevframeAgentHost` class, and
-// `createContextRpcServer` stay public because `@devframes/hub` composes its
-// own commands/agent host and hand-rolled server on top of them — the exact
-// custom-transport path `createContextRpcServer` exists for.
-export { coerceAgentPositionalArgs } from './agent-args'
+// The low-level primitives shared only between `devframe` and `@devframes/hub`
+// — `createContextRpcServer`, `DevframeAgentHost`, `coerceAgentPositionalArgs`
+// — live at `devframe/internal` (an explicitly-unstable cross-package surface),
+// not here.
 export * from './context'
-export { DevframeAgentHost } from './host-agent'
 // `RpcFunctionsHostImpl` stays internal; expose only the structural
 // `RpcFunctionsHost` type so consumers can type/cast `ctx.rpc` without
 // pulling in the implementation's `@internal` members.
@@ -26,10 +23,6 @@ export * from './host-h3'
 // lower-level read/probe/prune helpers stay internal to the connector.
 export { listLiveDevframeInstances, registerDevframeInstance } from './instance-registry'
 export type { DevframeInstanceRecord, DevframeInstanceRegistration } from './instance-registry'
-// The transport-agnostic RPC core is public so hosts that bind their own
-// transports (a Bun fetch-upgrade route, a custom relay — e.g. `initHub`)
-// reuse the exact session/auth wiring `startHttpAndWs` uses.
-export * from './rpc-core'
 export * from './server'
 export * from './storage'
 export { isObject, normalizeHttpServerUrl } from './utils'
diff --git a/packages/devframe/src/rpc/cache.ts b/packages/devframe/src/rpc/cache.ts
@@ -1,4 +1,4 @@
-import { hash } from '../utils/hash'
+import { hash } from 'devframe/utils/hash'
 
 export interface RpcCacheOptions {
   functions: string[]
diff --git a/packages/devframe/src/rpc/dump/collect.ts b/packages/devframe/src/rpc/dump/collect.ts
@@ -7,8 +7,8 @@ import type {
   RpcDumpStore,
   RpcFunctionDefinitionAny,
 } from '../types'
+import { hash } from 'devframe/utils/hash'
 import pLimit from 'p-limit'
-import { hash } from '../../utils/hash'
 import { diagnostics } from '../diagnostics'
 import { validateDefinitions } from '../validation'
 import { reviveDumpError, serializeDumpError } from './error'
diff --git a/packages/devframe/test/runtime-agnostic.test.ts b/packages/devframe/test/runtime-agnostic.test.ts
@@ -12,6 +12,7 @@ const AGNOSTIC_ENTRIES = [
   'utils/colors.mjs',
   'utils/crypto-token.mjs',
   'utils/events.mjs',
+  'utils/hash.mjs',
   'utils/nanoid.mjs',
   'utils/shared-state.mjs',
   'utils/streaming-channel.mjs',
diff --git a/packages/devframe/tsdown.config.ts b/packages/devframe/tsdown.config.ts
@@ -73,6 +73,7 @@ const clientEntries = {
   'utils/colors': 'src/utils/colors.ts',
   'utils/crypto-token': 'src/utils/crypto-token.ts',
   'utils/events': 'src/utils/events.ts',
+  'utils/hash': 'src/utils/hash.ts',
   'utils/nanoid': 'src/utils/nanoid.ts',
   'utils/simple-schema': 'src/utils/simple-schema.ts',
   'utils/shared-state': 'src/utils/shared-state.ts',
@@ -96,6 +97,7 @@ const serverEntries = {
   'node/index': 'src/node/index.ts',
   'node/auth': 'src/node/auth/index.ts',
   'node/hub-internals': 'src/node/hub-internals/index.ts',
+  'internal/index': 'src/internal/index.ts',
   'utils/launch-editor': 'src/utils/launch-editor.ts',
   'utils/open': 'src/utils/open.ts',
   'utils/serve-static': 'src/utils/serve-static.ts',
@@ -146,6 +148,7 @@ export default defineConfig([
             resolve(distDir, 'utils/colors.mjs'),
             resolve(distDir, 'utils/crypto-token.mjs'),
             resolve(distDir, 'utils/events.mjs'),
+            resolve(distDir, 'utils/hash.mjs'),
             resolve(distDir, 'utils/nanoid.mjs'),
             resolve(distDir, 'utils/simple-schema.mjs'),
             resolve(distDir, 'utils/shared-state.mjs'),
diff --git a/packages/hub/src/node/__tests__/host-commands.test.ts b/packages/hub/src/node/__tests__/host-commands.test.ts
@@ -1,6 +1,6 @@
 import type { DevframeNodeContext } from 'devframe/types'
 import type { DevframeHubContext } from '../context'
-import { DevframeAgentHost } from 'devframe/node'
+import { DevframeAgentHost } from 'devframe/internal'
 import * as v from 'valibot'
 import { describe, expect, it } from 'vitest'
 import { DevframeCommandsHost } from '../host-commands'
diff --git a/packages/hub/src/node/host-commands.ts b/packages/hub/src/node/host-commands.ts
@@ -6,7 +6,7 @@ import type {
   DevframeServerCommandInput,
 } from '../types/commands'
 import type { DevframeHubContext } from './context'
-import { coerceAgentPositionalArgs } from 'devframe/node'
+import { coerceAgentPositionalArgs } from 'devframe/internal'
 import { createEventEmitter } from 'devframe/utils/events'
 import { diagnostics } from './diagnostics'
 
diff --git a/packages/hub/src/node/initiate.ts b/packages/hub/src/node/initiate.ts
@@ -506,7 +506,7 @@ function instantiateHub(options: InitHubOptions): HubInstance {
     }
     else {
       const { attachBunWsTransport } = await import('devframe/rpc/transports/ws-bun')
-      const { createContextRpcServer } = await import('devframe/node')
+      const { createContextRpcServer } = await import('devframe/internal')
       const core = createContextRpcServer({ context: ctx, auth: resolvedAuth })
       bunTier = await attachBunWsTransport(core, { allowedOrigins: options.allowedOrigins })
       bunUpgradePath = joinURL(base, route)
diff --git a/plans/032-0.9-public-api-surface-reduction.md b/plans/032-0.9-public-api-surface-reduction.md
@@ -90,10 +90,17 @@ consumer):
   hand-rolled-server host the ⚠️ note below anticipated. **Kept** (resolves the
   open question: keep it).
 
-Net effect: dead-subpath removals are `utils/hash`, `utils/promise`, and
-`utils/scope` (not `ws-bun`); the `devframe/node` trim drops **9** internal
-exports, not 12. `devframe/adapters/embedded` was initially removed but restored
-on maintainer request — it stays as a named, discoverable adapter.
+Net effect (after maintainer follow-ups):
+
+- Dead-subpath removals are `utils/promise` and `utils/scope` only. `ws-bun` is
+  kept (hub uses it); `utils/hash` is kept (maintainer request); `embedded` is
+  kept (maintainer request — a named, discoverable adapter).
+- The `devframe/node` trim drops **12** exports again — but the three
+  hub-only low-level APIs (`createContextRpcServer`, `DevframeAgentHost`,
+  `coerceAgentPositionalArgs`) are **relocated** to a new **`devframe/internal`**
+  entry (an explicitly-unstable cross-package surface) rather than kept on the
+  public `devframe/node`, and the hub imports them from there. The other 9 stay
+  fully internal (relative imports only).
 
 ### ⚠️ One item to confirm during review
 
diff --git a/skills/devframe/SKILL.md b/skills/devframe/SKILL.md
@@ -550,6 +550,7 @@ Devframe re-exports a curated set of helpers under `devframe/utils/*`. They are
 | `colors` from `devframe/utils/colors` | `ansis` | Terminal ANSI colors (`c.red`, `c.green`, tagged templates) |
 | `open` from `devframe/utils/open` | `open` | Open URLs / files in the OS default handler |
 | `launchEditor` from `devframe/utils/launch-editor` | `launch-editor` | Open `file:line:column` in the user's editor (optional `editor` arg) |
+| `hash` from `devframe/utils/hash` | `ohash` | Stable structural hash — cache keys, dedup |
 | `structuredClone{Serialize,Deserialize,Stringify,Parse}` from `devframe/utils/structured-clone` | `structured-clone-es` | JSON-safe round-trip of `Map` / `Set` / `Date` / `BigInt` / cycles |
 | `nanoid` from `devframe/utils/nanoid` | (vendored) | URL-safe random IDs |
 | `randomToken` / `randomDigits` / `timingSafeEqual` from `devframe/utils/crypto-token` | (native WebCrypto) | CSPRNG bearer tokens, one-time codes, constant-time compare |
diff --git a/tests/__snapshots__/tsnapi/devframe/internal.snapshot.d.ts b/tests/__snapshots__/tsnapi/devframe/internal.snapshot.d.ts
@@ -0,0 +1,44 @@
+/**
+ * Generated by tsnapi — public API snapshot of `devframe/internal`
+ */
+// #region Types
+export type AgentArgsFallback = 'wrap' | 'drop';
+// #endregion
+
+// #region Classes
+export declare class DevframeAgentHost implements DevframeAgentHost$1 {
+  readonly context: DevframeNodeContext;
+  readonly events: EventEmitter<DevframeAgentHostEvents>;
+  private readonly tools;
+  private readonly resources;
+  private readonly providers;
+  private _rpcUnsubscribe;
+  constructor(_: DevframeNodeContext);
+  registerTool(_: AgentToolInput): AgentHandle;
+  unregisterTool(_: string): boolean;
+  registerToolProvider(_: AgentToolProvider): AgentToolProviderHandle;
+  registerResource(_: AgentResourceInput): AgentHandle;
+  unregisterResource(_: string): boolean;
+  list(): AgentManifest;
+  getTool(_: string): AgentTool | undefined;
+  getResource(_: string): AgentResource | undefined;
+  invoke(_: string, _: unknown): Promise<unknown>;
+  read(_: string): Promise<AgentResourceContent>;
+  _dispose(): void;
+  private _validateToolId;
+  private _projectTool;
+  private _collectProviderTools;
+  private _collectRpcTools;
+  private _findRpcDefinition;
+}
+// #endregion
+
+// #region Functions
+export declare function coerceAgentPositionalArgs(_: unknown, _: readonly unknown[] | undefined, _?: AgentArgsFallback): unknown[];
+// #endregion
+
+// #region Other
+export { ContextRpcServer }
+export { createContextRpcServer }
+export { CreateContextRpcServerOptions }
+// #endregion
diff --git a/tests/__snapshots__/tsnapi/devframe/internal.snapshot.js b/tests/__snapshots__/tsnapi/devframe/internal.snapshot.js
@@ -0,0 +1,8 @@
+/**
+ * Generated by tsnapi — public API snapshot of `devframe/internal`
+ */
+// #region Other
+export { coerceAgentPositionalArgs }
+export { createContextRpcServer }
+export { DevframeAgentHost }
+// #endregion
diff --git a/tests/__snapshots__/tsnapi/devframe/node.snapshot.d.ts b/tests/__snapshots__/tsnapi/devframe/node.snapshot.d.ts
diff --git a/tests/__snapshots__/tsnapi/devframe/node.snapshot.js b/tests/__snapshots__/tsnapi/devframe/node.snapshot.js
diff --git a/tests/__snapshots__/tsnapi/devframe/utils/hash.snapshot.d.ts b/tests/__snapshots__/tsnapi/devframe/utils/hash.snapshot.d.ts
diff --git a/tests/__snapshots__/tsnapi/devframe/utils/hash.snapshot.js b/tests/__snapshots__/tsnapi/devframe/utils/hash.snapshot.js
diff --git a/tsconfig.base.json b/tsconfig.base.json

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-import { hash } from '../utils/hash'`
	`1`	`+import { hash } from 'devframe/utils/hash'`
`2`	`2`
`3`	`3`	`export interface RpcCacheOptions {`
`4`	`4`	`functions: string[]`