devframe 0.8.2 → 0.9.0-beta.10

package/dist/instance-shell-CljiKq1c.d.mts

@@ -0,0 +1,255 @@
+import { K as DevframeRpcClientFunctions, R as DevframeNodeRpcSession, c as DevframeWsOptions, d as ConnectionMeta, g as DevframeNodeContext, q as DevframeRpcServerFunctions, s as DevframeSseOptions, u as DevframeAuthHandler } from "./devframe-DJMg0WLe.mjs";
+import { d as DevframeRpcConnection, n as WsOriginRegistry, u as DevframeNodeRpcSessionMeta } from "./ws-server-D1d3QM9f.mjs";
+import "./index-CB-fSUyn.mjs";
+import { BirpcGroup } from "birpc";
+import { NodeAdapter } from "crossws/adapters/node";
+import { Buffer } from "node:buffer";
+import { IncomingMessage, Server, ServerResponse } from "node:http";
+import { Duplex } from "node:stream";
+import { H3 } from "h3";
+//#region src/node/instance-registry.d.ts
+/**
+ * One running devframe instance, as recorded in the instance registry.
+ * Records are self-describing JSON — additive fields are safe.
+ */
+interface DevframeInstanceRecord {
+  /** Process id of the dev server. */
+  pid: number;
+  /** Listening port. */
+  port: number;
+  /** Dialable HTTP origin, e.g. `http://127.0.0.1:9876`. */
+  origin: string;
+  /** Base path the devframe is mounted at (trailing slash). */
+  basePath: string;
+  /** Definition id. */
+  id: string;
+  /** Definition display name. */
+  name?: string;
+  /** Working directory the instance was started from. */
+  rootDir: string;
+  /**
+   * Absolute URL path of the MCP Streamable-HTTP endpoint on `origin`, or
+   * `null` when the instance runs without an MCP route.
+   */
+  mcp: {
+    path: string;
+  } | null;
+  /** Epoch-ms timestamp of registration. */
+  startedAt: number;
+}
+/**
+ * Handle returned by {@link registerDevframeInstance}.
+ */
+interface DevframeInstanceRegistration {
+  /** The registry file backing this registration. */
+  readonly file: string;
+  /** Remove the record (idempotent). Call on server close. */
+  unregister: () => void;
+}
+/**
+ * Record a running devframe instance in the global instance registry so
+ * discovery tooling (`devframe connect`, editor integrations) can find it
+ * without port guessing.
+ *
+ * `createDevServer` registers automatically; custom hosts that serve a
+ * devframe in-process (e.g. `@devframes/next`'s host inside a Next dev
+ * server) call this explicitly with the origin they are reachable at.
+ *
+ * The record is written atomically to `<dir>/<pid>-<port>.json` and removed
+ * by {@link DevframeInstanceRegistration.unregister}. Records surviving a
+ * crash are pruned by readers whose liveness probe fails. Registration never
+ * throws — a write failure degrades to a coded warning (`DF0045`), since a
+ * dev server must not die over discovery metadata.
+ */
+declare function registerDevframeInstance(record: DevframeInstanceRecord, options?: {
+  instancesDir?: string;
+}): DevframeInstanceRegistration;
+/**
+ * Read the registry and split records into live and dead by probing each
+ * one's `__connection.json`, deleting dead records (prune-on-read). Live
+ * records carry the dialable origin the probe confirmed (a `localhost`
+ * record may come back as `127.0.0.1` / `[::1]`).
+ *
+ * A liveness probe only proves *something* answers on the record's port, so
+ * records left behind by killed processes shadow the server currently bound
+ * there: per `(port, basePath)` only the newest record survives, older
+ * ghosts are pruned with the dead.
+ */
+declare function listLiveDevframeInstances(options?: {
+  instancesDir?: string;
+  timeoutMs?: number;
+}): Promise<{
+  live: DevframeInstanceRecord[];
+  pruned: DevframeInstanceRecord[];
+}>;
+//#endregion
+//#region src/node/instance-shell.d.ts
+/**
+ * The live handle for a bound HTTP + WebSocket RPC server — what the
+ * side-car / shared-server tiers produce and what {@link createDevServer}
+ * re-exposes through its own return contract.
+ */
+interface StartedServer {
+  /** Listening origin, e.g. `http://localhost:9999`. */
+  origin: string;
+  port: number;
+  app: H3;
+  /**
+   * The crossws node adapter driving the RPC socket (connected peers,
+   * pub/sub). Absent when the WebSocket transport is disabled (`ws: false`).
+   */
+  ws?: NodeAdapter;
+  rpcGroup: BirpcGroup<DevframeRpcClientFunctions, DevframeRpcServerFunctions, false>;
+  /**
+   * The {@link ConnectionMeta} descriptor for this server — the same shape a
+   * `__connection.json` route should serve so a devframe client's
+   * `resolveWsUrl` can dial back in.
+   */
+  connectionMeta: () => ConnectionMeta;
+  close: () => Promise<void>;
+}
+/**
+ * How the instance's RPC socket is bound:
+ *
+ * - `sidecar` — its own HTTP+WS server on a dedicated port (`ws.port` /
+ *   `ws.sidecar`), advertised with that port.
+ * - `server` — a shared upgrade route on the host's `node:http` server.
+ * - `external` — no local transport: `ws.url` alone names a server that owns
+ *   both the socket and its auth.
+ * - `unbound` — the transport exists but nothing is bound to it yet; the host
+ *   drives it through {@link InstanceShell.handleUpgrade} /
+ *   {@link InstanceShell.attach}.
+ * - `disabled` — `ws: false`: no WebSocket at all; clients connect over the
+ *   SSE endpoint instead (`backend: 'sse'`).
+ */
+type InstanceWsTier = 'sidecar' | 'server' | 'external' | 'unbound' | 'disabled';
+/** The live shell surface an `init` / `mount` callback can reach. */
+interface InstanceShellApi {
+  /** The normalized mount base, with leading and trailing slash. */
+  base: string;
+  /** The h3 app every route is mounted on. */
+  app: H3;
+  /** The public origin, once known (pinned, or derived from the first request). */
+  origin: () => string | undefined;
+  /** The connection meta, once the transport has resolved. */
+  connectionMeta: () => ConnectionMeta | undefined;
+}
+/** What an instance's own initialization contributes to the shell. */
+interface InstanceShellInit<TContext extends DevframeNodeContext> {
+  /** The context every mounted surface shares. */
+  context: TContext;
+  /** The `mcp` entry to advertise, when an MCP route was mounted. */
+  mcp?: ConnectionMeta['mcp'];
+  /** Torn down before the transport on `close()` (e.g. MCP sessions). */
+  dispose?: () => Promise<void>;
+}
+interface CreateInstanceShellOptions<TContext extends DevframeNodeContext> {
+  /** Normalized mount base (leading and trailing slash). */
+  base: string;
+  /** h3 app to mount on. A fresh one is created when omitted. */
+  app?: H3;
+  /** Public origin, or a getter. Derived from the first request when omitted. */
+  origin?: string | (() => string);
+  /** Resolved auth intent: `undefined`/`true` gates, `false` opts out, a handler installs a scheme. */
+  auth?: boolean | DevframeAuthHandler;
+  /** Host `node:http` server to share the WS upgrade with. */
+  server?: Server;
+  /** Explicit WebSocket control — see {@link DevframeWsOptions}. `false` disables the socket (SSE-only). */
+  ws?: DevframeWsOptions | false;
+  /** SSE endpoint control — enabled by default; `false` disables, an object renames the route. */
+  sse?: boolean | DevframeSseOptions;
+  /** Bind host for a side-car WebSocket server. Default: `localhost`. */
+  host?: string;
+  /** Extra WS-upgrade origins beyond the loopback default; `false` disables the gate. */
+  allowedOrigins?: readonly string[] | WsOriginRegistry | false;
+  /** Destroy off-route upgrades on a shared `server`. */
+  destroyUnmatchedUpgrades?: boolean;
+  onPeerConnect?: (connection: DevframeRpcConnection, session: DevframeNodeRpcSession) => void;
+  onPeerDisconnect?: (connection: DevframeRpcConnection, meta: DevframeNodeRpcSessionMeta) => void;
+  /**
+   * Advertise the WS and SSE routes as base-absolute paths (`<base>__ws` /
+   * `<base>__sse`) instead of the base-relative default. A hub serves one
+   * meta document from several bases, so its clients need the absolute form
+   * to resolve the same endpoints.
+   */
+  absoluteWsPath?: boolean;
+  /** Pick the first port a `ws.sidecar` server tries. Default: a random free port. */
+  resolveSidecarPort?: (host: string) => Promise<number>;
+  /**
+   * Publish this instance in the global registry (`~/.devframe/instances/`)
+   * once its public origin is known — a dynamic import so the registry code
+   * stays out of instances that opt out. Omit to skip registration.
+   */
+  register?: InstanceRegisterConfig;
+  /** Create the context and mount everything that must precede the transport. */
+  init: (api: InstanceShellApi) => Promise<InstanceShellInit<TContext>>;
+  /** Mount the routes that describe the resolved transport (discovery, SPA). */
+  mount?: (context: TContext, meta: ConnectionMeta, api: InstanceShellApi) => void | Promise<void>;
+  /** Throw the instance's own diagnostic for `connectionMeta()` before readiness. */
+  onMetaUnavailable: () => never;
+}
+/**
+ * The identity a shell needs to publish itself in the global instance
+ * registry — the parts it can't derive on its own. The shell fills in
+ * `pid` / `origin` / `port` / `basePath` / `mcp` / `startedAt` once the
+ * origin resolves, then merges {@link InstanceRegisterConfig.overrides} last.
+ */
+interface InstanceRegisterConfig {
+  /** Definition id (or a synthetic one for a hub). */
+  id: string;
+  /** Display name. */
+  name?: string;
+  /** Working directory the instance runs from. Default: `process.cwd()`. */
+  rootDir?: string;
+  /** Fields overriding the shell-derived record (from the public option's object form). */
+  overrides?: Partial<DevframeInstanceRecord>;
+}
+/**
+ * Translate the public `register?: boolean | Partial<DevframeInstanceRecord>`
+ * option into a shell {@link InstanceRegisterConfig}, or `undefined` when
+ * registration is opted out. The object form supplies record overrides on top
+ * of the caller-provided identity defaults.
+ */
+declare function resolveInstanceRegister(option: boolean | Partial<DevframeInstanceRecord> | undefined, defaults: {
+  id: string;
+  name?: string;
+  rootDir?: string;
+}): InstanceRegisterConfig | undefined;
+/** Live internals the first-party adapters read off an instance. */
+interface InstanceShellInternals {
+  readonly started?: StartedServer;
+  readonly authHandler?: DevframeAuthHandler;
+}
+interface InstanceShell<TContext extends DevframeNodeContext> {
+  base: string;
+  handler: (request: Request) => Promise<Response>;
+  nodeMiddleware: (req: IncomingMessage, res: ServerResponse, next?: (err?: unknown) => void) => void;
+  ready: Promise<void>;
+  context: Promise<TContext>;
+  connectionMeta: () => ConnectionMeta;
+  /** Complete a host server's `upgrade` event on the instance's socket. */
+  handleUpgrade: (req: IncomingMessage, socket: Duplex, head: Buffer) => void;
+  /** Route a host server's `upgrade` events to the instance's socket. */
+  attach: (server: Server) => () => void;
+  close: () => Promise<void>;
+  internals: InstanceShellInternals;
+}
+/** Compare two URL paths ignoring a trailing slash. */
+declare function samePath(a: string, b: string): boolean;
+/**
+ * The shared machinery behind `initDevframe` and `initHub`: one mount base,
+ * one h3 app, one lazily-derived public origin (and the auth banner that waits
+ * for it), one WebSocket binding, and the fetch / connect-middleware pair that
+ * serves them. Each factory supplies only what makes it itself — its context,
+ * its routes, its diagnostics — through `init` / `mount`.
+ *
+ * Nothing here listens on a port unless a side-car was explicitly requested:
+ * the default tier leaves the socket `unbound`, so a host chains it onto its
+ * own server through {@link InstanceShell.attach} /
+ * {@link InstanceShell.handleUpgrade}.
+ *
+ * @internal
+ */
+declare function createInstanceShell<TContext extends DevframeNodeContext>(options: CreateInstanceShellOptions<TContext>): InstanceShell<TContext>;
+//#endregion
+export { InstanceShellInit as a, StartedServer as c, samePath as d, DevframeInstanceRecord as f, registerDevframeInstance as h, InstanceShellApi as i, createInstanceShell as l, listLiveDevframeInstances as m, InstanceRegisterConfig as n, InstanceShellInternals as o, DevframeInstanceRegistration as p, InstanceShell as r, InstanceWsTier as s, CreateInstanceShellOptions as t, resolveInstanceRegister as u };

package/dist/internal/index.d.mts

@@ -0,0 +1,397 @@
+import { Ct as DevframeAgentHost$1, P as DevframeHost, St as AgentToolProviderHandle, Tt as EventEmitter, _t as AgentResourceContent, bt as AgentToolInput, g as DevframeNodeContext, gt as AgentResource, ht as AgentManifest, mt as AgentHandle, vt as AgentResourceInput, wt as DevframeAgentHostEvents, xt as AgentToolProvider, yt as AgentTool } from "../devframe-DJMg0WLe.mjs";
+import { v as RpcFunctionDefinitionAny } from "../types-Djq7CBXh.mjs";
+import { a as RemoteAssetsStore } from "../remote-assets-Bg4gCUZ_.mjs";
+import { a as InstanceShellInit, c as StartedServer, d as samePath, f as DevframeInstanceRecord, h as registerDevframeInstance, i as InstanceShellApi, l as createInstanceShell, m as listLiveDevframeInstances, n as InstanceRegisterConfig, o as InstanceShellInternals, p as DevframeInstanceRegistration, r as InstanceShell, s as InstanceWsTier, t as CreateInstanceShellOptions, u as resolveInstanceRegister } from "../instance-shell-CljiKq1c.mjs";
+import { n as normalizeBasePath, r as resolveBasePath } from "../_shared-BPmX9fqK.mjs";
+import { n as CreateContextRpcServerOptions, r as createContextRpcServer, t as ContextRpcServer } from "../rpc-core-Cc4lucI0.mjs";
+//#region src/node/agent-args.d.ts
+/**
+ * How {@link coerceAgentPositionalArgs} treats an args object that carries
+ * neither declared schemas nor `arg0`/`arg1`/… keys:
+ *
+ * - `'wrap'` — pass the object itself as the single positional argument.
+ *   RPC-backed tools use this: an untyped RPC may take one raw object.
+ * - `'drop'` — call with zero arguments. Command-backed tools use this:
+ *   a handler's positional parameters come solely from its declared
+ *   `agent.args` schemas, so undeclared payload is ignored.
+ */
+type AgentArgsFallback = 'wrap' | 'drop';
+/**
+ * Map the args payload an agent surface receives (MCP sends an object
+ * keyed `arg0`/`arg1`/…, matching the schema the adapter advertises) onto
+ * a handler's positional parameters. Shared by the agent host's RPC
+ * bridge and the hub's command-derived tools so the coercion cannot
+ * drift between them.
+ *
+ * - an array passes through as-is
+ * - `null`/`undefined` become a zero-argument call
+ * - with declared schemas, each schema reads its own `argN` key, in order
+ * - without schemas, `arg0`/`arg1`/… keys are collected when present
+ * - an empty object becomes a zero-argument call
+ * - anything else follows the {@link AgentArgsFallback}
+ */
+declare function coerceAgentPositionalArgs(args: unknown, schemas: readonly unknown[] | undefined, fallback?: AgentArgsFallback): unknown[];
+//#endregion
+//#region src/node/diagnostics.d.ts
+declare const diagnostics: import("nostics").Diagnostics<{
+  readonly DF0006: {
+    readonly why: (p: {
+      name: string;
+    }) => string;
+  };
+  readonly DF0007: {
+    readonly why: "AsyncLocalStorage is not set, it likely to be an internal bug of the Devframe foundation";
+  };
+  readonly DF0008: {
+    readonly why: (p: {
+      distDir: string;
+    }) => string;
+  };
+  readonly DF0012: {
+    readonly why: (p: {
+      filepath: string;
+    }) => string;
+  };
+  readonly DF0013: {
+    readonly why: (p: {
+      key: string;
+    }) => string;
+  };
+  readonly DF0014: {
+    readonly why: (p: {
+      name: string;
+    }) => string;
+    readonly fix: "Provide a short description (~1–3 sentences) explaining what the tool does and when agents should invoke it.";
+  };
+  readonly DF0015: {
+    readonly why: (p: {
+      id: string;
+    }) => string;
+    readonly fix: "Tool ids must be unique across RPC functions with an `agent` field and tools registered via `ctx.agent.registerTool()`.";
+  };
+  readonly DF0016: {
+    readonly why: (p: {
+      id: string;
+    }) => string;
+  };
+  readonly DF0017: {
+    readonly why: (p: {
+      transport: string;
+      reason: string;
+    }) => string;
+  };
+  readonly DF0029: {
+    readonly why: (p: {
+      channel: string;
+      id: string;
+      dropped: number;
+    }) => string;
+    readonly fix: "The consumer is too slow for the producer. Raise `highWaterMark` on the subscription, slow the producer, or batch chunks.";
+  };
+  readonly DF0030: {
+    readonly why: (p: {
+      channel: string;
+      id: string;
+    }) => string;
+    readonly fix: "Ensure the server-side producer is running before clients subscribe, or check for typos in the stream id.";
+  };
+  readonly DF0031: {
+    readonly why: (p: {
+      channel: string;
+      id: string;
+    }) => string;
+    readonly fix: "Track the producer lifecycle — guard writes with the `stream.signal.aborted` flag.";
+  };
+  readonly DF0032: {
+    readonly why: (p: {
+      channel: string;
+    }) => string;
+    readonly fix: "Each channel name must be unique within a context. Pick a different name or reuse the existing channel handle.";
+  };
+  readonly DF0033: {
+    readonly why: (p: {
+      id: string;
+      reason: string;
+    }) => string;
+    readonly fix: "Verify the bridge port is free and the devframe setup function does not throw. Pin a port via `cli.port` / `cli.portRange` on the definition, or via `port` on `devframeViteBridge` (`@devframes/vite`).";
+  };
+  readonly DF0034: {
+    readonly why: (p: {
+      namespace: string;
+      name: string;
+    }) => string;
+    readonly fix: "A scoped context auto-namespaces ids. Pass a bare name without a \":\" separator (e.g. `register({ name: \"get-cwd\" })`), or use the unscoped `ctx.base.rpc.register` for a fully-qualified name.";
+  };
+  readonly DF0035: {
+    readonly why: (p: {
+      filepath: string;
+    }) => string;
+    readonly fix: "Check that the storage directory is writable and has free space.";
+  };
+  readonly DF0036: {
+    readonly why: (p: {
+      name: string;
+    }) => string;
+    readonly fix: "Complete the auth handshake (or connect with a static/pre-shared token) before calling a trusted method. Untrusted callers may only call `anonymous:`-prefixed methods — see `isAnonymousRpcMethod`.";
+  };
+  readonly DF0037: {
+    readonly why: (p: {
+      id: string;
+    }) => string;
+    readonly fix: "Service ids are unique per context. Revoke the existing provider first (the `provide()` call returns a revoke function), or namespace the id with your plugin id to avoid collisions.";
+  };
+  readonly DF0042: {
+    readonly why: (p: {
+      id: string;
+    }) => string;
+    readonly fix: "Pass `{ force: true }` to `createBuild()` if the degraded export is still useful to you, or drop `capabilities.build: false` on the definition.";
+  };
+  readonly DF0045: {
+    readonly why: (p: {
+      file: string;
+      reason: string;
+    }) => string;
+    readonly fix: "Discovery tooling (`devframe connect`) will not see this instance. Check that the registry directory is writable, point `DEVFRAME_INSTANCES_DIR` at a writable directory, or set `DEVFRAME_DISABLE_INSTANCE_REGISTRY=1` to opt out of registration.";
+  };
+  readonly DF0046: {
+    readonly why: (p: {
+      reason: string;
+    }) => string;
+    readonly fix: "Install it next to devframe (e.g. `npm install @modelcontextprotocol/server`) and run `devframe connect` again.";
+  };
+  readonly DF0047: {
+    readonly why: (p: {
+      name: string;
+      id: string;
+      existing: string;
+    }) => string;
+    readonly fix: "Wire names derive from tool ids (characters outside [a-zA-Z0-9_-] become \"_\"). Rename one of the two ids so they sanitize to distinct names.";
+  };
+  readonly DF0048: {
+    readonly why: (p: {
+      key: string;
+    }) => string;
+    readonly fix: "Call the devframe_state_read tool without arguments to list the available keys, then retry with one of them.";
+  };
+  readonly DF0049: {
+    readonly why: "The devframe_connect_call-tool tool requires { port: number, tool: string }.";
+    readonly fix: "Call devframe_connect_list-instances to get the port and tool names, then retry.";
+  };
+  readonly DF0050: {
+    readonly why: (p: {
+      port: number;
+    }) => string;
+    readonly fix: "Call devframe_connect_list-instances for the current instance list — the instance may have stopped or changed port.";
+  };
+  readonly DF0051: {
+    readonly why: (p: {
+      port: number;
+    }) => string;
+    readonly fix: "Restart the instance with the --mcp flag (or set `cli.mcp: true` on its definition) to expose its tools, then list instances again.";
+  };
+  readonly DF0052: {
+    readonly why: (p: {
+      host: string;
+      port: number;
+      reason: string;
+    }) => string;
+    readonly fix: "The port is likely already taken by another process (often a previous devframe instance). Free it, or pick another via `--port`, `cli.port` / `cli.portRange` on the definition, or `port` on `devframeViteBridge` (`@devframes/vite`). The original node error is available as `error.cause`.";
+  };
+  readonly DF0054: {
+    readonly why: (p: {
+      id: string;
+    }) => string;
+    readonly fix: "Await `instance.ready` (or any request through `instance.handler`) before reading `connectionMeta()` — the WebSocket binding it describes is only known once initialization completes.";
+  };
+  readonly DF0055: {
+    readonly why: (p: {
+      tier: string;
+    }) => string;
+    readonly fix: "Drop `handleUpgrade`/`attach` and let the configured transport serve the socket, or remove `server` / `ws.port` / `ws.sidecar` from the options so the instance leaves the binding to you.";
+  };
+  readonly DF0056: {
+    readonly why: (p: {
+      url: string;
+    }) => string;
+    readonly fix: "The server behind `ws.url` owns the transport (and its auth). Drop `ws.url` to have the instance serve the socket, or pair it with `server` / `ws.port` / `ws.sidecar` for the tunnel pattern, where a local binding is advertised through the relay.";
+  };
+  readonly DF0057: {
+    readonly why: () => string;
+    readonly fix: "Clients connect over the SSE endpoint instead — no upgrade wiring is needed. Remove `ws: false` if the instance should serve a WebSocket after all.";
+  };
+  readonly DF0058: {
+    readonly why: (p: {
+      id: string;
+    }) => string;
+    readonly fix: "Pass `{ force: true }` to `createDevServer()` to run it anyway, or drop `capabilities.dev: false` on the definition.";
+  };
+  readonly DF0059: {
+    readonly why: (p: {
+      package: string;
+      version: string;
+      provider: string;
+      reason: string;
+    }) => string;
+    readonly fix: "Requests fall back to probing the provider per file. Check network access to the provider, or install the assets package locally so no listing is needed.";
+  };
+  readonly DF0060: {
+    readonly why: (p: {
+      url: string;
+      package: string;
+      reason: string;
+    }) => string;
+    readonly fix: "Install the assets package locally (`npm install <package>`) to serve it with zero network, or check network access to the configured provider.";
+  };
+  readonly DF0061: {
+    readonly why: (p: {
+      package: string;
+      required: string;
+      installed: string;
+    }) => string;
+    readonly fix: "Align the installed assets package with the version its node package declares — they are published in lockstep.";
+  };
+  readonly DF0062: {
+    readonly why: (p: {
+      package: string;
+      required: string;
+      installed: string;
+    }) => string;
+    readonly fix: "Install the exact declared version to serve byte-identical assets.";
+  };
+  readonly DF0063: {
+    readonly why: (p: {
+      filepath: string;
+      reason: string;
+    }) => string;
+    readonly fix: "The response was still served; only caching failed. Check that the cache directory is writable and has free space.";
+  };
+  readonly DF0064: {
+    readonly why: (p: {
+      package: string;
+      version: string;
+      reason: string;
+    }) => string;
+    readonly fix: "Static builds need every asset file up front. Install the assets package locally, or ensure the provider (and its file-listing API) is reachable during the build.";
+  };
+  readonly DF0065: {
+    readonly why: (p: {
+      field: "package" | "version";
+      value: string;
+    }) => string;
+    readonly fix: "A remote-assets `package` must be a valid npm package name and `version` an exact semver version (e.g. `1.2.3`) — they are interpolated into CDN URLs and the cache path.";
+  };
+}, readonly [(d: import("nostics").Diagnostic, { method }?: {
+  method?: "log" | "warn" | "error";
+}) => void]>;
+//#endregion
+//#region src/node/host-agent.d.ts
+/**
+ * Framework-neutral host aggregating the agent-exposed surface of a
+ * devframe. Auto-discovers RPC functions with an `agent` field from
+ * `ctx.rpc.definitions`, and accepts plugin-registered tools /
+ * resources via `registerTool` / `registerResource`.
+ */
+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(context: DevframeNodeContext);
+  registerTool(input: AgentToolInput): AgentHandle;
+  unregisterTool(id: string): boolean;
+  registerToolProvider(provider: AgentToolProvider): AgentToolProviderHandle;
+  registerResource(input: AgentResourceInput): AgentHandle;
+  unregisterResource(id: string): boolean;
+  list(): AgentManifest;
+  getTool(id: string): AgentTool | undefined;
+  getResource(id: string): AgentResource | undefined;
+  invoke(id: string, args: unknown): Promise<unknown>;
+  read(id: string): Promise<AgentResourceContent>;
+  /** @internal */
+  _dispose(): void;
+  private _validateToolId;
+  private _projectTool;
+  /** Query every registered provider, projecting inputs to serializable tools. */
+  private _collectProviderTools;
+  private _collectRpcTools;
+  private _findRpcDefinition;
+}
+//#endregion
+//#region src/node/host-h3.d.ts
+interface CreateH3DevframeHostOptions {
+  /**
+   * Host the standalone server listens on, e.g. `http://localhost:9999`.
+   * Consumed by `resolveOrigin` for dock entries that need an absolute URL.
+   * Pass a function for hosts that only learn their public origin later
+   * (e.g. `createHandler` derives it from the first incoming request).
+   */
+  origin: string | (() => string);
+  /**
+   * Register a static-file handler at `base` serving files from `source` —
+   * a local directory or a resolved remote-assets back-proxy store (both
+   * accepted by `devframe/utils/serve-static`). `mountStatic` forwards to
+   * it; when omitted the host serves no SPA (bridge mode, where the SPA is
+   * hosted elsewhere).
+   */
+  mount?: (base: string, source: string | RemoteAssetsStore) => void | Promise<void>;
+  /**
+   * Namespace for storage paths returned by `getStorageDir`. Workspace
+   * state (committable) lives under `${workspaceRoot}/.devframe/`, project
+   * state under `${workspaceRoot}/node_modules/.<appName>/devframe/`, and
+   * global state under `${homedir()}/.<appName>/devframe/`. Pick the
+   * devtool's id (or another stable, filesystem-safe identifier) so the
+   * standalone host doesn't collide with other tools' storage.
+   */
+  appName: string;
+  /**
+   * Workspace root used as the parent of the per-project storage
+   * directory. Defaults to `process.cwd()`.
+   */
+  workspaceRoot?: string;
+}
+/**
+ * h3-backed {@link DevframeHost} — used by the standalone CLI adapter.
+ */
+declare function createH3DevframeHost(options: CreateH3DevframeHostOptions): DevframeHost;
+//#endregion
+//#region src/node/utils.d.ts
+declare function normalizeHttpServerUrl(host: string, port: number | string): string;
+//#endregion
+//#region src/rpc/wire-codec.d.ts
+/**
+ * The per-connection `serialize`/`deserialize` pair for a live RPC wire.
+ *
+ * @internal
+ */
+interface RpcWireCodec {
+  serialize: (msg: any) => string;
+  deserialize: (raw: string) => any;
+}
+/**
+ * Build the per-connection wire codec every live transport (WS server, WS
+ * client, SSE server, SSE client) shares: per-method dispatch between strict
+ * JSON (methods declared `jsonSerializable: true`) and `s:`-prefixed
+ * structured-clone (everything else, including all error envelopes), with a
+ * request-id → method map so a response independently picks the same
+ * encoder as its request. One codec per connection — request-id spaces
+ * don't collide across connections.
+ *
+ * @internal
+ */
+declare function createRpcWireCodec(definitions?: ReadonlyMap<string, Pick<RpcFunctionDefinitionAny, 'jsonSerializable'>>): RpcWireCodec;
+/**
+ * Peek at a wire frame's birpc envelope without engaging a codec's
+ * request-id bookkeeping — used by the SSE transport to route a frame
+ * (park a POST for its response / answer with a bare 202) before it is
+ * handed to birpc proper.
+ *
+ * @internal
+ */
+declare function peekRpcWireFrame(raw: string): {
+  t?: string;
+  i?: string;
+};
+//#endregion
+export { type AgentArgsFallback, type ContextRpcServer, type CreateContextRpcServerOptions, CreateH3DevframeHostOptions, type CreateInstanceShellOptions, DevframeAgentHost, type DevframeInstanceRecord, type DevframeInstanceRegistration, type InstanceRegisterConfig, type InstanceShell, type InstanceShellApi, type InstanceShellInit, type InstanceShellInternals, type InstanceWsTier, type RpcWireCodec, type StartedServer, coerceAgentPositionalArgs, createContextRpcServer, createH3DevframeHost, createInstanceShell, createRpcWireCodec, diagnostics, listLiveDevframeInstances, normalizeBasePath, normalizeHttpServerUrl, peekRpcWireFrame, registerDevframeInstance, resolveBasePath, resolveInstanceRegister, samePath };

package/dist/internal/index.mjs

@@ -0,0 +1,9 @@
+import { n as peekRpcWireFrame, t as createRpcWireCodec } from "../wire-codec-0K-o5MYW.mjs";
+import { t as diagnostics } from "../diagnostics-DOQPnQmX.mjs";
+import { n as coerceAgentPositionalArgs, t as DevframeAgentHost } from "../host-agent-xLCSe65D.mjs";
+import { n as resolveBasePath, t as normalizeBasePath } from "../_shared-CbZ_yhbz.mjs";
+import { t as createH3DevframeHost } from "../host-h3-Crkzm42q.mjs";
+import { i as registerDevframeInstance, n as listLiveDevframeInstances } from "../instance-registry-WvQkt42E.mjs";
+import { i as normalizeHttpServerUrl, n as resolveInstanceRegister, r as samePath, t as createInstanceShell } from "../instance-shell-CMFyszWJ.mjs";
+import { t as createContextRpcServer } from "../rpc-core-DMTe-hLo.mjs";
+export { DevframeAgentHost, coerceAgentPositionalArgs, createContextRpcServer, createH3DevframeHost, createInstanceShell, createRpcWireCodec, diagnostics, listLiveDevframeInstances, normalizeBasePath, normalizeHttpServerUrl, peekRpcWireFrame, registerDevframeInstance, resolveBasePath, resolveInstanceRegister, samePath };

package/dist/node/auth.d.mts

@@ -1,3 +1,3 @@
-import { p as DevframeAuthHandler } from "../devframe-mQ4qZAuo.mjs";
-import { a as verifyAuthToken, i as refreshTempAuthCode, n as exchangeTempAuthCode, o as revokeActiveConnectionsForToken, r as getTempAuthCode, s as revokeAuthToken, t as buildOtpAuthUrl } from "../index-b64Uuhy2.mjs";
+import { u as DevframeAuthHandler } from "../devframe-DJMg0WLe.mjs";
+import { a as verifyAuthToken, i as refreshTempAuthCode, n as exchangeTempAuthCode, o as revokeActiveConnectionsForToken, r as getTempAuthCode, s as revokeAuthToken, t as buildOtpAuthUrl } from "../index-CB-fSUyn.mjs";
 export { DevframeAuthHandler, buildOtpAuthUrl, exchangeTempAuthCode, getTempAuthCode, refreshTempAuthCode, revokeActiveConnectionsForToken, revokeAuthToken, verifyAuthToken };

package/dist/node/auth.mjs

@@ -1,3 +1,3 @@
 import { n as revokeAuthToken, t as revokeActiveConnectionsForToken } from "../revoke-DZbJ7Cl0.mjs";
-import { a as verifyAuthToken, i as refreshTempAuthCode, n as exchangeTempAuthCode, r as getTempAuthCode, t as buildOtpAuthUrl } from "../state-BeUHDDjk.mjs";
+import { a as verifyAuthToken, i as refreshTempAuthCode, n as exchangeTempAuthCode, r as getTempAuthCode, t as buildOtpAuthUrl } from "../state-Cc1IeSmQ.mjs";
 export { buildOtpAuthUrl, exchangeTempAuthCode, getTempAuthCode, refreshTempAuthCode, revokeActiveConnectionsForToken, revokeAuthToken, verifyAuthToken };