@vibesdotdev/runtime-client 0.0.1

package/README.md

@@ -0,0 +1,97 @@
+# @vibesdotdev/runtime-client
+
+The `runtime/client` kind and `BaseRuntimeClient`. Every module that exposes
+functionality across the monorepo does so through exactly one client registered
+under this kind.
+
+## Authoring a new client
+
+Mechanical recipe. No variation.
+
+### 1. Define the client class
+
+```ts
+// <module>/src/lib/client/runtime-client.ts
+import { BaseRuntimeClient, type RuntimeClientDescriptor } from '@vibesdotdev/runtime-client';
+import type { VibesRuntime } from '@vibesdotdev/runtime';
+
+export class MyModuleClient extends BaseRuntimeClient {
+  constructor(
+    descriptor: RuntimeClientDescriptor = { id: 'my-module', kind: 'runtime/client' },
+    context?: unknown,
+    runtime?: VibesRuntime,
+  ) {
+    super(descriptor, context, runtime);
+  }
+
+  async doSomething(/* … */) {
+    // resolve other kinds via this.runtime.query(...)
+  }
+}
+```
+
+### 2. Register in the module's plugin
+
+```ts
+export default createRuntimePlugin({
+  id: 'my-module',
+  dependencies: ['runtime-client', /* … */],
+  onRegister(runtime) {
+    runtime.registerDescriptor('runtime/client', {
+      id: 'my-module',
+      kind: 'runtime/client',
+      description: 'Canonical MyModule client',
+    });
+    runtime.registerLoader('runtime/client', 'my-module', async () => {
+      const { MyModuleClient } = await import('./client/runtime-client.js');
+      return { impl: MyModuleClient };
+    });
+  },
+});
+```
+
+### 3. Export the ambient helper
+
+```ts
+// <module>/src/lib/client/helper.ts
+import { getVibesClient } from '@vibesdotdev/runtime-client';
+import type { MyModuleClient } from './runtime-client';
+
+export async function getVibesMyModuleClient(): Promise<MyModuleClient> {
+  return getVibesClient<MyModuleClient>('my-module');
+}
+```
+
+### 4. Expose via module barrel + `package.json` subpath
+
+```ts
+// <module>/src/lib/client/index.ts
+export { MyModuleClient } from './runtime-client';
+export { getVibesMyModuleClient } from './helper';
+export type * from './contracts';
+```
+
+Add `"./client"` to the module's `package.json#exports`.
+
+## Consuming another module's client
+
+```ts
+import { getVibesToolsClient } from '@vibesdotdev/tools/client';
+const tools = await getVibesToolsClient();
+const agent = await tools.getAgent('assistant');
+```
+
+If the other module exposes only kinds (no client), use `runtime.query('<kind>').…`
+directly. Never deep-import another module's internals.
+
+## Test
+
+```bash
+bun test src/__tests__/
+```
+
+## Docs
+
+- [SPEC.md](./SPEC.md) — package contract, owned surfaces, hard rules
+- [runtime](../runtime/SPEC.md) — registry/query layer this builds on
+- [client](../client/SPEC.md) — sister `api/client` kind for HTTP clients

package/SPEC.md

@@ -0,0 +1,44 @@
+# @vibesdotdev/runtime-client
+
+The `runtime/client` kind + the shared base every module-level client extends. One client per module, runtime-resolved.
+
+## Owns
+
+- `runtime/client` kind (registered via `./plugin`)
+- `BaseRuntimeClient` abstract class — ambient runtime acquisition, idempotent `load()`/`ensureLoaded()`, optional `config/manifest` auto-load via `descriptor.configManifestId`, `onLoad`/`onDispose` hooks, `(descriptor, context?, runtime?)` constructor signature
+- `RuntimeClient` interface (`./contract`)
+- `RuntimeClientDescriptor` zod schema (`./schema`)
+- `getVibesClient<T>(id)` ambient helper
+
+## Does not own
+
+- HTTP abstraction → [`@vibesdotdev/client`](../client/SPEC.md) (`api/client` kind)
+- Config manager → [`@vibesdotdev/config`](../config/SPEC.md) (`config/manifest` kind)
+- Registry / kind resolution → [`@vibesdotdev/runtime`](../runtime/SPEC.md)
+- Any module's domain methods — those live on each module's subclass
+
+## Hard rules
+
+- **One client per module.** No split HTTP-vs-in-process clients. No module-specific factories competing with the canonical one.
+- **All module clients extend `BaseRuntimeClient`.** They do not reimplement lifecycle, config-load, or runtime acquisition.
+- **Scope selection lives inside the client**, never in consumers. Consumers call `client.foo()` and never branch on hardware/connection mode.
+- **Cross-module access goes through (1) the other module's client, or (2) direct `runtime.query('<kind>')` for primitives.** Never deep-import another module's internals. Never duplicate another module's types.
+- **Two sanctioned client flavors only:** `runtime/client` (this package) and `api/client` ([`@vibesdotdev/client`](../client/SPEC.md)). New flavors require a SPEC update.
+- This package depends only on `@vibesdotdev/runtime` and `zod`. It does not import any module's domain code.
+
+## Public entrypoints
+
+- `.` — `BaseRuntimeClient`, `getVibesClient`, `RuntimeClient` type, descriptor schema (barrel)
+- `./plugin` — `runtimeClientPlugin` (registers the kind)
+- `./contract` — `RuntimeClient` (type-only)
+- `./schema` — `RuntimeClientDescriptor` zod schema
+- `./base` — `BaseRuntimeClient`
+
+## Verification
+
+`bun test src/__tests__/`. Covers kind registration, base lifecycle, `getVibesClient` resolution, descriptor schema.
+
+## Links
+
+- [runtime/SPEC.md](../runtime/SPEC.md)
+- [client/SPEC.md](../client/SPEC.md) — sister `api/client` kind

package/dist/base.d.ts

@@ -0,0 +1,49 @@
+import { type VibesRuntime } from '@vibesdotdev/runtime';
+import type { RuntimeClient } from './contract.ts';
+import type { RuntimeClientDescriptor } from './schema.ts';
+/**
+ * Shared base for module-level clients.
+ *
+ * Handles:
+ *  - ambient runtime acquisition (via `getVibesRuntime()`)
+ *  - idempotent lazy init (`ensureLoaded()`)
+ *  - `config/manifest` auto-loading when `descriptor.configManifestId` is set
+ *  - lifecycle hooks (`onLoad`, `onDispose`) for subclasses
+ *
+ * Subclasses (AIClient, ToolsClient, …) add their domain methods and call
+ * `this.ensureLoaded()` at method entry points when their behavior depends
+ * on loaded config.
+ *
+ * Constructor signature matches the runtime's kind-instantiation contract:
+ * `(descriptor, context?)`. Context is not currently consumed — runtime
+ * access goes through the ambient singleton — but remains a parameter for
+ * forward compatibility with kind contexts that carry scope metadata.
+ */
+export declare abstract class BaseRuntimeClient implements RuntimeClient {
+    readonly id: string;
+    readonly runtime: VibesRuntime;
+    protected readonly descriptor: RuntimeClientDescriptor;
+    protected configValues: unknown | null;
+    private loadPromise?;
+    constructor(descriptor: RuntimeClientDescriptor, _context?: unknown, runtime?: VibesRuntime);
+    /**
+     * Idempotent lazy init. First call drives `onLoad()`; subsequent calls
+     * await the same promise. Subclasses call this at method entry points
+     * when they need config loaded.
+     */
+    ensureLoaded(): Promise<void>;
+    /** Public `load()` matching the `RuntimeClient` contract. Alias of `ensureLoaded()`. */
+    load(): Promise<void>;
+    dispose(): void;
+    /**
+     * Override to perform module-specific initialization. Default behavior:
+     * if `descriptor.configManifestId` is set, resolve the corresponding
+     * `config/manifest` and load its values into `this.configValues`.
+     */
+    protected onLoad(): Promise<void>;
+    protected onDispose(): void;
+    /** Subclass accessor for loaded config values (null if load hasn't run or failed). */
+    protected getConfigValues<T = unknown>(): T | null;
+    private runLoad;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../src/base.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAE3D;;;;;;;;;;;;;;;;;GAiBG;AACH,8BAAsB,iBAAkB,YAAW,aAAa;IAC/D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAE/B,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,uBAAuB,CAAC;IACvD,SAAS,CAAC,YAAY,EAAE,OAAO,GAAG,IAAI,CAAQ;IAE9C,OAAO,CAAC,WAAW,CAAC,CAAgB;gBAGnC,UAAU,EAAE,uBAAuB,EACnC,QAAQ,CAAC,EAAE,OAAO,EAClB,OAAO,CAAC,EAAE,YAAY;IAUvB;;;;OAIG;IACG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAOnC,wFAAwF;IAClF,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,OAAO,IAAI,IAAI;IAMf;;;;OAIG;cACa,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBvC,SAAS,CAAC,SAAS,IAAI,IAAI;IAE3B,sFAAsF;IACtF,SAAS,CAAC,eAAe,CAAC,CAAC,GAAG,OAAO,KAAK,CAAC,GAAG,IAAI;YAIpC,OAAO;CAGrB"}

package/dist/base.js

@@ -0,0 +1,86 @@
+import { getVibesRuntime } from '@vibesdotdev/runtime';
+/**
+ * Shared base for module-level clients.
+ *
+ * Handles:
+ *  - ambient runtime acquisition (via `getVibesRuntime()`)
+ *  - idempotent lazy init (`ensureLoaded()`)
+ *  - `config/manifest` auto-loading when `descriptor.configManifestId` is set
+ *  - lifecycle hooks (`onLoad`, `onDispose`) for subclasses
+ *
+ * Subclasses (AIClient, ToolsClient, …) add their domain methods and call
+ * `this.ensureLoaded()` at method entry points when their behavior depends
+ * on loaded config.
+ *
+ * Constructor signature matches the runtime's kind-instantiation contract:
+ * `(descriptor, context?)`. Context is not currently consumed — runtime
+ * access goes through the ambient singleton — but remains a parameter for
+ * forward compatibility with kind contexts that carry scope metadata.
+ */
+export class BaseRuntimeClient {
+    id;
+    runtime;
+    descriptor;
+    configValues = null;
+    loadPromise;
+    constructor(descriptor, _context, runtime) {
+        this.descriptor = descriptor;
+        this.id = descriptor.id;
+        // Ambient runtime is the default path (matches `getVibesClient<T>(id)`).
+        // Explicit runtime override is available for legacy factory callers and
+        // advanced scenarios (e.g. multi-runtime test harnesses).
+        this.runtime = runtime ?? getVibesRuntime();
+    }
+    /**
+     * Idempotent lazy init. First call drives `onLoad()`; subsequent calls
+     * await the same promise. Subclasses call this at method entry points
+     * when they need config loaded.
+     */
+    async ensureLoaded() {
+        if (!this.loadPromise) {
+            this.loadPromise = this.runLoad();
+        }
+        return this.loadPromise;
+    }
+    /** Public `load()` matching the `RuntimeClient` contract. Alias of `ensureLoaded()`. */
+    async load() {
+        return this.ensureLoaded();
+    }
+    dispose() {
+        this.loadPromise = undefined;
+        this.configValues = null;
+        this.onDispose();
+    }
+    /**
+     * Override to perform module-specific initialization. Default behavior:
+     * if `descriptor.configManifestId` is set, resolve the corresponding
+     * `config/manifest` and load its values into `this.configValues`.
+     */
+    async onLoad() {
+        const manifestId = this.descriptor.configManifestId;
+        if (!manifestId)
+            return;
+        try {
+            const manifest = (await this.runtime
+                .query('config/manifest')
+                .withId(manifestId)
+                .resolve());
+            if (manifest?.load) {
+                this.configValues = await manifest.load();
+            }
+        }
+        catch {
+            // Config is best-effort at the base layer. Subclasses handle required/missing config.
+            this.configValues = null;
+        }
+    }
+    onDispose() { }
+    /** Subclass accessor for loaded config values (null if load hasn't run or failed). */
+    getConfigValues() {
+        return this.configValues;
+    }
+    async runLoad() {
+        await this.onLoad();
+    }
+}
+//# sourceMappingURL=base.js.map

package/dist/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../src/base.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAqB,MAAM,sBAAsB,CAAC;AAI1E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAgB,iBAAiB;IAC7B,EAAE,CAAS;IACX,OAAO,CAAe;IAEZ,UAAU,CAA0B;IAC7C,YAAY,GAAmB,IAAI,CAAC;IAEtC,WAAW,CAAiB;IAEpC,YACC,UAAmC,EACnC,QAAkB,EAClB,OAAsB;QAEtB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,EAAE,GAAG,UAAU,CAAC,EAAE,CAAC;QACxB,yEAAyE;QACzE,wEAAwE;QACxE,0DAA0D;QAC1D,IAAI,CAAC,OAAO,GAAG,OAAO,IAAI,eAAe,EAAE,CAAC;IAC7C,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,YAAY;QACjB,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACvB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;QACnC,CAAC;QACD,OAAO,IAAI,CAAC,WAAW,CAAC;IACzB,CAAC;IAED,wFAAwF;IACxF,KAAK,CAAC,IAAI;QACT,OAAO,IAAI,CAAC,YAAY,EAAE,CAAC;IAC5B,CAAC;IAED,OAAO;QACN,IAAI,CAAC,WAAW,GAAG,SAAS,CAAC;QAC7B,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QACzB,IAAI,CAAC,SAAS,EAAE,CAAC;IAClB,CAAC;IAED;;;;OAIG;IACO,KAAK,CAAC,MAAM;QACrB,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,gBAAgB,CAAC;QACpD,IAAI,CAAC,UAAU;YAAE,OAAO;QACxB,IAAI,CAAC;YACJ,MAAM,QAAQ,GAAG,CAAC,MAAM,IAAI,CAAC,OAAO;iBAClC,KAAK,CAAC,iBAAiB,CAAC;iBACxB,MAAM,CAAC,UAAU,CAAC;iBAClB,OAAO,EAAE,CAAkD,CAAC;YAC9D,IAAI,QAAQ,EAAE,IAAI,EAAE,CAAC;gBACpB,IAAI,CAAC,YAAY,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YAC3C,CAAC;QACF,CAAC;QAAC,MAAM,CAAC;YACR,sFAAsF;YACtF,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QAC1B,CAAC;IACF,CAAC;IAES,SAAS,KAAU,CAAC;IAE9B,sFAAsF;IAC5E,eAAe;QACxB,OAAO,IAAI,CAAC,YAAwB,CAAC;IACtC,CAAC;IAEO,KAAK,CAAC,OAAO;QACpB,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;IACrB,CAAC;CACD"}

package/dist/contract.d.ts

@@ -0,0 +1,23 @@
+import type { VibesRuntime } from '@vibesdotdev/runtime';
+/**
+ * Base contract every module-level client satisfies.
+ *
+ * Module-specific clients extend this with domain methods:
+ *   AIClient adds `generate`, `getProvider`, `listModels`, …
+ *   ToolsClient adds `listTools`, `runTool`, …
+ *   KnowledgeClient adds `search`, `ingest`, …
+ *
+ * All clients share the same shape for lifecycle + runtime access so that
+ * consumers, tests, and tooling can treat them uniformly.
+ */
+export interface RuntimeClient {
+    /** The descriptor id this client was registered with. */
+    readonly id: string;
+    /** Runtime reference the client uses for internal resolution. */
+    readonly runtime: VibesRuntime;
+    /** Idempotent load. Safe to call repeatedly; internal state cached. */
+    load(): Promise<void>;
+    /** Release any client-held resources (subscriptions, caches, etc.). */
+    dispose(): void;
+}
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC7B,yDAAyD;IACzD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,uEAAuE;IACvE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,uEAAuE;IACvE,OAAO,IAAI,IAAI,CAAC;CAChB"}

package/dist/contract.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":""}

package/dist/docs/runtime-client.api.docs.descriptor.d.ts

@@ -0,0 +1,8 @@
+import type { DocsTopicDescriptor } from './types.ts';
+/**
+ * Descriptor for runtime-client.api
+ * BaseRuntimeClient class, client patterns, how to extend
+ */
+declare const descriptor: DocsTopicDescriptor;
+export default descriptor;
+//# sourceMappingURL=runtime-client.api.docs.descriptor.d.ts.map

package/dist/docs/runtime-client.api.docs.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-client.api.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/runtime-client.api.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD;;;GAGG;AACH,QAAA,MAAM,UAAU,EAAE,mBAiVjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/runtime-client.api.docs.descriptor.js

@@ -0,0 +1,344 @@
+/**
+ * Descriptor for runtime-client.api
+ * BaseRuntimeClient class, client patterns, how to extend
+ */
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'runtime-client.api',
+    title: 'Runtime Client API',
+    summary: 'BaseRuntimeClient base class and patterns for extending module-level clients',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: `---
+title: Runtime Client API
+summary: BaseRuntimeClient base class and patterns for extending module-level clients
+tags: [runtime-client, base-class, extension, api, patterns]
+parent: runtime-client
+order: 1
+surfaces: [cli, web, in-app]
+hardware: [consumer, cloud]
+---
+
+# Runtime Client API
+
+The \`BaseRuntimeClient\` class provides a shared foundation for module-level clients (AIClient, ToolsClient, KnowledgeClient, etc.). It handles runtime acquisition, idempotent lazy initialization, config loading, and lifecycle management.
+
+## Architecture
+
+Module clients follow a **one-client-per-module** pattern:
+
+\`\`\`
+┌─────────────────────────────────────────────────────────┐
+│  Module Plugin (ai, tools, knowledge, etc.)            │
+│  - Registers runtime/client descriptor                  │
+│  - Provides implementation class via loader             │
+└─────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────┐
+│  RuntimeClient Implementation (extends BaseRuntimeClient)│
+│  - Domain methods (generate, listTools, search, etc.)   │
+│  - Config access via this.getConfigValues<T>()          │
+│  - Runtime access via this.runtime                      │
+└─────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────┐
+│  BaseRuntimeClient (shared base)                        │
+│  - Ambient runtime acquisition                          │
+│  - Idempotent lazy init (ensureLoaded())                │
+│  - Config manifest auto-loading                         │
+│  - Lifecycle hooks (onLoad, onDispose)                  │
+└─────────────────────────────────────────────────────────┘
+\`\`\`
+
+## BaseRuntimeClient
+
+### Constructor
+
+\`\`\`ts
+constructor(
+  descriptor: RuntimeClientDescriptor,
+  _context?: unknown,
+  runtime?: VibesRuntime
+)
+\`\`\`
+
+**Parameters:**
+- \`descriptor\` — The \`runtime/client\` descriptor this client represents
+- \`_context\` — Reserved for future scope metadata (not currently used)
+- \`runtime\` — Optional explicit runtime override (defaults to \`getVibesRuntime()\`)
+
+### Properties
+
+\`\`\`ts
+readonly id: string;              // From descriptor.id
+readonly runtime: VibesRuntime;   // Ambient runtime singleton
+\`\`\`
+
+### Lifecycle Methods
+
+#### ensureLoaded() / load()
+
+Idempotent lazy initialization. First call drives \`onLoad()\`; subsequent calls await the same promise.
+
+\`\`\`ts
+async ensureLoaded(): Promise<void>
+async load(): Promise<void>  // Alias of ensureLoaded()
+\`\`\`
+
+**When to call:** At method entry points when your client depends on loaded config.
+
+\`\`\`ts
+export class AIClient extends BaseRuntimeClient {
+  async generate(prompt: string): Promise<GenerationResponse> {
+    await this.ensureLoaded();  // Ensure config is loaded
+    
+    const config = this.getConfigValues<AIConfig>();
+    const provider = await this.runtime.query('ai/provider')
+      .withId(config?.defaultProvider ?? 'anthropic')
+      .resolve();
+    
+    return provider.generate({ prompt });
+  }
+}
+\`\`\`
+
+#### dispose()
+
+Releases client-held resources:
+
+\`\`\`ts
+dispose(): void {
+  this.loadPromise = undefined;
+  this.configValues = null;
+  this.onDispose();  // Subclass hook
+}
+\`\`\`
+
+Call when shutting down the client (e.g., test teardown, hot reload).
+
+### Protected Hooks for Subclasses
+
+#### onLoad()
+
+Override to perform module-specific initialization. Default behavior: if \`descriptor.configManifestId\` is set, resolves the corresponding \`config/manifest\` and loads its values.
+
+\`\`\`ts
+protected async onLoad(): Promise<void> {
+  // Default: load config manifest if specified
+  const manifestId = this.descriptor.configManifestId;
+  if (!manifestId) return;
+  
+  try {
+    const manifest = await this.runtime
+      .query('config/manifest')
+      .withId(manifestId)
+      .resolve();
+    
+    if (manifest?.load) {
+      this.configValues = await manifest.load();
+    }
+  } catch {
+    // Config is best-effort at base layer
+    this.configValues = null;
+  }
+  
+  // Subclasses can extend:
+  // - Initialize domain-specific caches
+  // - Validate required config
+  // - Establish connections
+}
+\`\`\`
+
+#### onDispose()
+
+Override to release resources:
+
+\`\`\`ts
+protected onDispose(): void {
+  // Close connections, clear caches, cancel subscriptions
+}
+\`\`\`
+
+#### getConfigValues<T>()
+
+Accessor for loaded config values (null if load hasn't run or failed):
+
+\`\`\`ts
+protected getConfigValues<T = unknown>(): T | null
+\`\`\`
+
+## Extending BaseRuntimeClient
+
+### Minimal Example
+
+\`\`\`ts
+// packages/my-module/src/client.ts
+import { BaseRuntimeClient, type RuntimeClientDescriptor } from '@vibesdotdev/runtime-client';
+
+export interface MyModuleDescriptor extends RuntimeClientDescriptor {
+  kind: 'runtime/client';
+  id: 'my-module';
+  configManifestId?: string;
+}
+
+export class MyModuleClient extends BaseRuntimeClient {
+  constructor(descriptor: MyModuleDescriptor) {
+    super(descriptor);
+  }
+
+  async doSomething(input: string): Promise<string> {
+    await this.ensureLoaded();
+    
+    const runtime = this.runtime;
+    // Use runtime APIs...
+    return \`Processed: \${input}\`;
+  }
+}
+\`\`\`
+
+### Full Example with Config
+
+\`\`\`ts
+// packages/ai/src/client/ai-client.ts
+import { BaseRuntimeClient, type RuntimeClientDescriptor } from '@vibesdotdev/runtime-client';
+
+interface AIConfig {
+  defaultProvider: string;
+  maxTokens: number;
+  temperature: number;
+}
+
+export class AIClient extends BaseRuntimeClient {
+  constructor(descriptor: RuntimeClientDescriptor) {
+    super(descriptor);
+  }
+
+  async generate(options: {
+    prompt: string;
+    model?: string;
+    maxTokens?: number;
+  }): Promise<string> {
+    await this.ensureLoaded();
+    
+    const config = this.getConfigValues<AIConfig>();
+    if (!config) {
+      throw new Error('AI config not loaded');
+    }
+
+    const provider = await this.runtime
+      .query('ai/provider')
+      .withId(config.defaultProvider)
+      .resolve();
+
+    const response = await provider.generate({
+      prompt: options.prompt,
+      model: options.model,
+      maxTokens: options.maxTokens ?? config.maxTokens,
+      temperature: config.temperature
+    });
+
+    return response.text;
+  }
+
+  async listModels(): Promise<string[]> {
+    await this.ensureLoaded();
+    
+    const models = await this.runtime
+      .query('ai/model')
+      .descriptors();
+    
+    return models.map(m => m.id);
+  }
+
+  protected async onLoad(): Promise<void> {
+    await super.onLoad();  // Load config manifest
+    
+    // Additional AI-specific initialization
+    // e.g., warm provider caches, validate API keys
+  }
+
+  protected onDispose(): void {
+    // Cancel pending generations, clear caches
+    super.onDispose();
+  }
+}
+\`\`\`
+
+### Registering the Client
+
+\`\`\`ts
+// packages/ai/src/ai.plugin.ts
+import { createRuntimePlugin } from '@vibesdotdev/runtime';
+import { AIClient } from './client/ai-client';
+
+export const aiPlugin = createRuntimePlugin({
+  id: 'ai',
+  name: 'AI Module',
+  onRegister(runtime) {
+    // Register per-id loader for runtime/client kind
+    runtime.registerLoader('runtime/client', 'ai', async () => {
+      return new AIClient({
+        kind: 'runtime/client',
+        id: 'ai',
+        configManifestId: 'ai/config'
+      });
+    });
+  }
+});
+\`\`\`
+
+## WRONG patterns
+
+:::card{title="Anti-patterns"}
+- ❌ **Direct runtime instantiation** — Don't \`new VibesRuntime()\`; use ambient \`this.runtime\`
+- ❌ **Storing runtime references** — Call \`getVibesRuntime()\` at construction, store as \`this.runtime\`
+- ❌ **Skipping ensureLoaded()** — Always call at method entry if you need config
+- ❌ **Multiple config loads** — Base class handles idempotent loading; don't re-implement
+- ❌ **Throwing on missing config** — Config is best-effort; validate in subclass if required
+- ❌ **Direct config manifest resolution** — Use base class \`onLoad()\` pattern
+:::
+
+## Code paths
+
+- Base class: [\`packages/runtime-client/src/base.ts\`](https://github.com/vibesdotdev/monorepo/tree/main/packages/runtime-client/src/base.ts)
+- Contract: [\`packages/runtime-client/src/contract.ts\`](https://github.com/vibesdotdev/monorepo/tree/main/packages/runtime-client/src/contract.ts)
+- Schema: [\`packages/runtime-client/src/schema.ts\`](https://github.com/vibesdotdev/monorepo/tree/main/packages/runtime-client/src/schema.ts)
+- Kind: [\`packages/runtime-client/src/kind.ts\`](https://github.com/vibesdotdev/monorepo/tree/main/packages/runtime-client/src/kind.ts)
+
+:::card{title="See also"}
+- [\`runtime-client.helpers\`](runtime-client.helpers) — \`getVibesClient()\` helper functions
+- [\`runtime-client.surface\`](runtime-client.surface) — Surface initialization patterns
+- [\`runtime.query\`](runtime.query) — Runtime query API for resolving clients
+- [\`runtime.plugins\`](runtime.plugins) — Plugin registration and loaders
+:::
+`
+    },
+    parent: 'runtime-client',
+    order: 1,
+    tags: ['runtime-client', 'base-class', 'extension', 'api', 'patterns'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true,
+    man: {
+        name: 'runtime-client.api — BaseRuntimeClient and extension patterns',
+        section: 1,
+        synopsis: 'vibes man runtime-client.api',
+        options: [],
+        examples: [
+            {
+                description: 'Extend BaseRuntimeClient',
+                command: 'class MyClient extends BaseRuntimeClient { ... }'
+            },
+            {
+                description: 'Load config in onLoad()',
+                command: 'protected async onLoad() { await super.onLoad(); ... }'
+            }
+        ],
+        seeAlso: ['runtime-client.helpers', 'runtime-client.surface', 'runtime.query']
+    }
+};
+export default descriptor;
+//# sourceMappingURL=runtime-client.api.docs.descriptor.js.map

package/dist/docs/runtime-client.api.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-client.api.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/runtime-client.api.docs.descriptor.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,GAAwB;IACtC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,oBAAoB;IACxB,KAAK,EAAE,oBAAoB;IAC3B,OAAO,EAAE,8EAA8E;IACvF,IAAI,EAAE;QACJ,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgTX;KACE;IACD,MAAM,EAAE,gBAAgB;IACxB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,gBAAgB,EAAE,YAAY,EAAE,WAAW,EAAE,KAAK,EAAE,UAAU,CAAC;IACtE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;IACb,GAAG,EAAE;QACH,IAAI,EAAE,+DAA+D;QACrE,OAAO,EAAE,CAAC;QACV,QAAQ,EAAE,8BAA8B;QACxC,OAAO,EAAE,EAAE;QACX,QAAQ,EAAE;YACR;gBACE,WAAW,EAAE,0BAA0B;gBACvC,OAAO,EAAE,kDAAkD;aAC5D;YACD;gBACE,WAAW,EAAE,yBAAyB;gBACtC,OAAO,EAAE,wDAAwD;aAClE;SACF;QACD,OAAO,EAAE,CAAC,wBAAwB,EAAE,wBAAwB,EAAE,eAAe,CAAC;KAC/E;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}