@vibesdotdev/runtime-client 0.0.1

package/dist/runtime-client.plugin.js

@@ -0,0 +1,27 @@
+/**
+ * Runtime Client Docs Plugin
+ *
+ * Registers documentation descriptors for runtime-client APIs:
+ * - runtime-client.api — BaseRuntimeClient class, client patterns, how to extend
+ * - runtime-client.helpers — getVibesClient() helper functions, surface detection
+ * - runtime-client.surface — How surfaces (CLI, SSR, browser, worker) initialize clients
+ *
+ * This plugin is surface-neutral — docs descriptors work in CLI, SSR, and worker contexts.
+ */
+import { createRuntimePlugin } from '@vibesdotdev/runtime';
+// Docs descriptors
+import runtimeClientApiDocs from "./docs/runtime-client.api.docs.descriptor.js";
+import runtimeClientHelpersDocs from "./docs/runtime-client.helpers.docs.descriptor.js";
+import runtimeClientSurfaceDocs from "./docs/runtime-client.surface.docs.descriptor.js";
+export const runtimeClientDocsPlugin = createRuntimePlugin({
+    id: 'runtime-client.docs',
+    name: 'Runtime Client Documentation',
+    description: 'Runtime client APIs: BaseRuntimeClient, getVibesClient helpers, surface initialization',
+    descriptors: [
+        runtimeClientApiDocs,
+        runtimeClientHelpersDocs,
+        runtimeClientSurfaceDocs
+    ]
+});
+export default runtimeClientDocsPlugin;
+//# sourceMappingURL=runtime-client.plugin.js.map

package/dist/runtime-client.plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-client.plugin.js","sourceRoot":"","sources":["../src/runtime-client.plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,mBAAmB;AACnB,OAAO,oBAAoB,MAAM,8CAA8C,CAAC;AAChF,OAAO,wBAAwB,MAAM,kDAAkD,CAAC;AACxF,OAAO,wBAAwB,MAAM,kDAAkD,CAAC;AAExF,MAAM,CAAC,MAAM,uBAAuB,GAAG,mBAAmB,CAAC;IACzD,EAAE,EAAE,qBAAqB;IACzB,IAAI,EAAE,8BAA8B;IACpC,WAAW,EACT,wFAAwF;IAE1F,WAAW,EAAE;QACX,oBAAoB;QACpB,wBAAwB;QACxB,wBAAwB;KACzB;CACF,CAAC,CAAC;AAEH,eAAe,uBAAuB,CAAC"}

package/dist/schema.d.ts

@@ -0,0 +1,32 @@
+import * as z from 'zod/v4';
+import { type RuntimeDescriptor } from '@vibesdotdev/runtime/schemas/descriptor';
+/**
+ * Descriptor for the `runtime/client` kind.
+ *
+ * Every module that exposes a top-level client registers exactly one of these.
+ * The descriptor id matches the module name (`ai`, `tools`, `knowledge`, …).
+ *
+ * `configManifestId`, if set, causes `BaseRuntimeClient.onLoad()` to load the
+ * corresponding config manifest and expose its values to subclasses.
+ */
+export interface RuntimeClientDescriptor extends RuntimeDescriptor {
+    /** Narrows the base `kind: string` to the literal `'runtime/client'`. */
+    kind: 'runtime/client';
+    /** If set, BaseRuntimeClient.onLoad() loads the corresponding config manifest. */
+    configManifestId?: string;
+}
+export declare const RuntimeClientDescriptorSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    hardware: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    priority: z.ZodOptional<z.ZodNumber>;
+    requiredContext: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    optionalContext: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    kind: z.ZodLiteral<"runtime/client">;
+    configManifestId: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAEN,KAAK,iBAAiB,EACtB,MAAM,yCAAyC,CAAC;AAEjD;;;;;;;;GAQG;AACH,MAAM,WAAW,uBAAwB,SAAQ,iBAAiB;IACjE,yEAAyE;IACzE,IAAI,EAAE,gBAAgB,CAAC;IACvB,kFAAkF;IAClF,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;iBAIxC,CAAC"}

package/dist/schema.js

@@ -0,0 +1,8 @@
+import * as z from 'zod/v4';
+import { RuntimeDescriptorSchema } from '@vibesdotdev/runtime/schemas/descriptor';
+export const RuntimeClientDescriptorSchema = RuntimeDescriptorSchema.extend({
+    kind: z.literal('runtime/client'),
+    configManifestId: z.string().optional(),
+    description: z.string().optional()
+});
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAC5B,OAAO,EACN,uBAAuB,EAEvB,MAAM,yCAAyC,CAAC;AAkBjD,MAAM,CAAC,MAAM,6BAA6B,GAAG,uBAAuB,CAAC,MAAM,CAAC;IAC3E,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,gBAAgB,CAAC;IACjC,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACvC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAClC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@vibesdotdev/runtime-client",
+  "version": "0.0.1",
+  "description": "Shared base + `runtime/client` kind for module-level vibes clients (one client per module, runtime-resolved).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "bun": "./src/plugin.ts",
+      "import": "./dist/plugin.js",
+      "default": "./dist/plugin.js"
+    }
+  },
+  "dependencies": {
+    "@vibesdotdev/runtime": "0.0.1"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "bun --bun tsc -p tsconfig.json --noEmit"
+  },
+  "license": "MIT",
+  "files": [
+    "dist",
+    "src",
+    "bin",
+    "README.md",
+    "SPEC.md",
+    "LICENSE",
+    "!src/**/__tests__/**",
+    "!src/**/__stubs__/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.spec.ts",
+    "!src/**/*.spec.tsx",
+    "!dist/**/__tests__/**",
+    "!dist/**/__stubs__/**",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.d.ts.map",
+    "!dist/**/*.spec.js",
+    "!dist/**/*.spec.js.map",
+    "!dist/**/*.spec.d.ts",
+    "!dist/**/*.spec.d.ts.map"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "vibes": {
+    "visibility": "public-framework"
+  }
+}

package/src/base.ts

@@ -0,0 +1,100 @@
+import { getVibesRuntime, 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 abstract class BaseRuntimeClient implements RuntimeClient {
+	readonly id: string;
+	readonly runtime: VibesRuntime;
+
+	protected readonly descriptor: RuntimeClientDescriptor;
+	protected configValues: unknown | null = null;
+
+	private loadPromise?: Promise<void>;
+
+	constructor(
+		descriptor: RuntimeClientDescriptor,
+		_context?: unknown,
+		runtime?: VibesRuntime
+	) {
+		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(): Promise<void> {
+		if (!this.loadPromise) {
+			this.loadPromise = this.runLoad();
+		}
+		return this.loadPromise;
+	}
+
+	/** Public `load()` matching the `RuntimeClient` contract. Alias of `ensureLoaded()`. */
+	async load(): Promise<void> {
+		return this.ensureLoaded();
+	}
+
+	dispose(): void {
+		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`.
+	 */
+	protected async onLoad(): Promise<void> {
+		const manifestId = this.descriptor.configManifestId;
+		if (!manifestId) return;
+		try {
+			const manifest = (await this.runtime
+				.query('config/manifest')
+				.withId(manifestId)
+				.resolve()) as { load?: () => Promise<unknown> } | undefined;
+			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;
+		}
+	}
+
+	protected onDispose(): void {}
+
+	/** Subclass accessor for loaded config values (null if load hasn't run or failed). */
+	protected getConfigValues<T = unknown>(): T | null {
+		return this.configValues as T | null;
+	}
+
+	private async runLoad(): Promise<void> {
+		await this.onLoad();
+	}
+}

package/src/contract.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;
+}

package/src/docs/runtime-client.api.docs.descriptor.ts

@@ -0,0 +1,346 @@
+import type { DocsTopicDescriptor } from './types.ts';
+
+/**
+ * Descriptor for runtime-client.api
+ * BaseRuntimeClient class, client patterns, how to extend
+ */
+const descriptor: DocsTopicDescriptor = {
+  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;