@vibesdotdev/runtime-client 0.0.1

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

@@ -0,0 +1,466 @@
+import type { DocsTopicDescriptor } from './types.ts';
+
+/**
+ * Descriptor for runtime-client.surface
+ * How surfaces (CLI, SSR, browser, worker) initialize runtime clients
+ */
+const descriptor: DocsTopicDescriptor = {
+  kind: 'docs/topic',
+  id: 'runtime-client.surface',
+  title: 'Surface Initialization',
+  summary: 'How different surfaces (CLI, SSR, browser, worker) initialize runtime clients',
+  body: {
+    type: 'markdown',
+    sourceType: 'raw',
+    source: `---
+title: Surface Initialization
+summary: How different surfaces (CLI, SSR, browser, worker) initialize runtime clients
+tags: [runtime-client, surfaces, initialization, cli, ssr, browser, worker]
+parent: runtime-client
+order: 3
+surfaces: [cli, web, in-app]
+hardware: [consumer, cloud]
+---
+
+# Surface Initialization
+
+Runtime clients are initialized differently depending on the **surface** (CLI, SSR, browser, worker) and **hardware** (consumer, cloud). This guide covers initialization patterns for each surface type.
+
+## Surface Types
+
+The Vibes runtime supports four surface types:
+
+| Surface | Description | Typical Use | Hardware |
+|---------|-------------|-------------|----------|
+| \`cli\` | Command-line interface | CLI commands, scripts | consumer |
+| \`ssr\` | Server-side rendering | SvelteKit +page.server.ts | consumer |
+| \`browser\` | Client-side browser | SvelteKit +page.svelte | consumer |
+| \`worker\` | Cloudflare Workers | Edge functions, queues | cloud |
+
+Each surface gets its own runtime instance with appropriate scope bindings:
+
+\`\`\`ts
+runtime.scope;
+// {
+//   surface: 'cli' | 'ssr' | 'browser' | 'worker',
+//   hardware: 'consumer' | 'cloud',
+//   purpose?: 'direct' | 'embedded'
+// }
+\`\`\`
+
+## CLI Surface
+
+### Bootstrap Flow
+
+The CLI bootstrap is defined in \`@vibesdotdev/cli/bootstrap\`:
+
+\`\`\`ts
+// packages/cli/src/bootstrap.ts
+import { getVibesRuntime } from '@vibesdotdev/runtime';
+import { CLISurface } from './surface';
+
+export async function createVibesCliApp() {
+  const runtime = getVibesRuntime();
+  
+  // Set CLI scope
+  runtime.setScope({ 
+    surface: 'cli', 
+    hardware: 'consumer', 
+    purpose: 'direct' 
+  });
+  
+  // Register core plugins (order matters)
+  await registerCorePlugins(runtime);
+  
+  // Register project plugins
+  // ...
+  
+  // Activate plugins (fires onActivate hooks)
+  await runtime.activatePlugins();
+  
+  // Create CLI surface
+  const cli = new CLISurface(runtime, program);
+  
+  return { runtime, program, cli };
+}
+
+async function registerCorePlugins(runtime: VibesRuntime) {
+  // Order: context → cli → runtime-client → hooks → logging → runtime.docs
+  const runtimeClientPlugin = (
+    await import('@vibesdotdev/runtime-client/plugin')
+  ).default;
+  await runtime.registerPlugin(runtimeClientPlugin);
+  
+  // ... other plugins
+}
+\`\`\`
+
+### Key Points
+
+1. **runtime-client plugin registered early** — Before module plugins (ai, tools, etc.)
+2. **Plugin activation deferred** — \`activatePlugins()\` fires after all plugins registered
+3. **Module plugins register loaders** — In \`onActivate()\` hook, they register \`runtime/client\` loaders
+
+### Module Plugin Pattern
+
+\`\`\`ts
+// packages/ai/src/ai.plugin.ts
+import { createRuntimePlugin } from '@vibesdotdev/runtime';
+
+export const aiPlugin = createRuntimePlugin({
+  id: 'ai',
+  name: 'AI Module',
+  dependencies: ['runtime-client'],  // Declare dependency
+  
+  onActivate(runtime) {
+    // Register per-id loader for runtime/client kind
+    runtime.registerLoader('runtime/client', 'ai', async () => {
+      const { AIClient } = await import('./client/ai-client');
+      return new AIClient({
+        kind: 'runtime/client',
+        id: 'ai',
+        configManifestId: 'ai/config'
+      });
+    });
+  }
+});
+\`\`\`
+
+### Usage in CLI Commands
+
+\`\`\`ts
+// packages/cli/src/commands/ai/generate.ts
+import { getVibesClient } from '@vibesdotdev/runtime-client';
+
+export async function generateCommand(options: { prompt: string }) {
+  // Resolve client (runtime already bootstrapped by CLI)
+  const ai = await getVibesClient('ai');
+  
+  // Generate
+  const response = await ai.generate({ prompt: options.prompt });
+  console.log(response);
+}
+\`\`\`
+
+## SSR Surface (SvelteKit)
+
+### Bootstrap Flow
+
+SSR surfaces bootstrap in SvelteKit's \`hooks.server.ts\`:
+
+\`\`\`ts
+// apps/ai-web/src/hooks.server.ts
+import { bootstrapVibesRuntime } from '@vibesdotdev/runtime';
+import { consumerRuntimePlugin } from './runtime/consumer.plugin';
+
+export async function handle({ event, resolve }) {
+  // Bootstrap runtime once per request (or use singleton)
+  await bootstrapVibesRuntime({
+    plugins: [consumerRuntimePlugin],
+    scope: { 
+      surface: 'ssr', 
+      hardware: 'consumer', 
+      purpose: 'direct' 
+    }
+  });
+  
+  return resolve(event);
+}
+\`\`\`
+
+### Usage in +page.server.ts
+
+\`\`\`ts
+// apps/ai-web/src/routes/chat/+page.server.ts
+import { getVibesClient } from '@vibesdotdev/runtime-client';
+import type { PageServerLoad } from './$types';
+
+export const load: PageServerLoad = async () => {
+  // Resolve client (runtime bootstrapped in hooks.server.ts)
+  const ai = await getVibesClient('ai');
+  
+  // Use client
+  const models = await ai.listModels();
+  
+  return { models };
+};
+\`\`\`
+
+### SSR-Specific Considerations
+
+1. **Request isolation** — Each request may get its own runtime instance
+2. **No global state** — Don't store client references in module scope
+3. **Lazy initialization** — Clients initialize on first use
+4. **Config loading** — Happens per-request if not cached
+
+## Browser Surface
+
+### Bootstrap Flow
+
+Browser surfaces bootstrap in SvelteKit's \`+layout.svelte\` or \`app.html\`:
+
+\`\`\`ts
+// apps/ai-web/src/routes/+layout.svelte
+<script lang="ts">
+  import { onMount } from 'svelte';
+  import { bootstrapVibesRuntime } from '@vibesdotdev/runtime';
+  import { browserRuntimePlugin } from '$lib/runtime/browser.plugin';
+
+  onMount(async () => {
+    await bootstrapVibesRuntime({
+      plugins: [browserRuntimePlugin],
+      scope: { 
+        surface: 'browser', 
+        hardware: 'consumer', 
+        purpose: 'direct' 
+      }
+    });
+  });
+</script>
+
+<slot />
+\`\`\`
+
+### Usage in +page.svelte
+
+\`\`\`ts
+// apps/ai-web/src/routes/chat/+page.svelte
+<script lang="ts">
+  import { onMount } from 'svelte';
+  import { getVibesClient } from '@vibesdotdev/runtime-client';
+  import type { AIClient } from '@vibesdotdev/ai/client';
+
+  let aiClient: AIClient | null = null;
+
+  onMount(async () => {
+    // Resolve client (runtime bootstrapped in +layout.svelte)
+    aiClient = await getVibesClient<AIClient>('ai');
+  });
+
+  async function generate(prompt: string) {
+    if (!aiClient) return;
+    const response = await aiClient.generate({ prompt });
+    // Handle response...
+  }
+</script>
+
+<button on:click={() => generate('Hello')}>Generate</button>
+\`\`\`
+
+### Browser-Specific Considerations
+
+1. **Client-side only** — Browser surface can't access server-only plugins
+2. **API boundaries** — Use bridge pattern for server operations
+3. **Memory constraints** — Dispose clients on unmount if needed
+4. **Network latency** — Client methods may involve network calls
+
+## Worker Surface (Cloudflare)
+
+### Bootstrap Flow
+
+Worker surfaces bootstrap in worker entrypoint:
+
+\`\`\`ts
+// workers/jobs/src/entrypoint.ts
+import { bootstrapVibesRuntime } from '@vibesdotdev/runtime';
+import { runtimeClientPlugin } from '@vibesdotdev/runtime-client';
+import { workersPlugin } from '@vibesdotdev/workers';
+
+export default {
+  async fetch(request, env, ctx) {
+    // Bootstrap runtime
+    await bootstrapVibesRuntime({
+      plugins: [runtimeClientPlugin, workersPlugin],
+      scope: { 
+        surface: 'worker', 
+        hardware: 'cloud', 
+        purpose: 'direct' 
+      },
+      env  // Cloudflare env bindings
+    });
+    
+    // Handle request
+    const runtime = getVibesRuntime();
+    const workers = await runtime
+      .query('runtime/client')
+      .withId('workers')
+      .resolve();
+    
+    // ...
+  }
+};
+\`\`\`
+
+### Worker-Specific Considerations
+
+1. **Cold starts** — First request pays bootstrap cost
+2. **Stateless** — No persistent memory between requests
+3. **Env bindings** — Pass Cloudflare env to bootstrap
+4. **Limited plugins** — Only cloud-compatible plugins work
+
+## Cross-Surface Patterns
+
+### Pattern 1: Surface-Agnostic Services
+
+Write services that work in any surface:
+
+\`\`\`ts
+// packages/my-lib/src/content-generator.ts
+import { getVibesClient } from '@vibesdotdev/runtime-client';
+import type { AIClient } from '@vibesdotdev/ai/client';
+
+export class ContentGenerator {
+  async generate(topic: string): Promise<string> {
+    // Works in CLI, SSR, browser, worker
+    const ai = await getVibesClient<AIClient>('ai');
+    return ai.generate({ 
+      prompt: \`Write about \${topic}\` 
+    });
+  }
+}
+\`\`\`
+
+### Pattern 2: Surface Detection
+
+Detect current surface via runtime scope:
+
+\`\`\`ts
+import { getVibesRuntime } from '@vibesdotdev/runtime';
+
+const runtime = getVibesRuntime();
+const { surface, hardware } = runtime.scope;
+
+if (surface === 'browser') {
+  // Browser-specific logic
+} else if (surface === 'ssr') {
+  // SSR-specific logic
+}
+\`\`\`
+
+### Pattern 3: Surface-Specific Implementations
+
+Register different implementations per surface:
+
+\`\`\`ts
+// packages/storage/src/storage.plugin.ts
+import { createRuntimePlugin } from '@vibesdotdev/runtime';
+
+export const storagePlugin = createRuntimePlugin({
+  id: 'storage',
+  onActivate(runtime) {
+    const { surface, hardware } = runtime.scope;
+    
+    if (hardware === 'cloud') {
+      // Cloud implementation
+      runtime.registerLoader('runtime/client', 'storage', async () => {
+        const { CloudStorageClient } = await import('./client/cloud');
+        return new CloudStorageClient();
+      });
+    } else {
+      // Consumer implementation
+      runtime.registerLoader('runtime/client', 'storage', async () => {
+        const { LocalStorageClient } = await import('./client/local');
+        return new LocalStorageClient();
+      });
+    }
+  }
+});
+\`\`\`
+
+## WRONG patterns
+
+:::card{title="Anti-patterns"}
+- ❌ **Manual runtime instantiation** — Use \`bootstrapVibesRuntime()\` or surface helpers
+- ❌ **Cross-surface state sharing** — Each surface has its own runtime instance
+- ❌ **Storing clients in module scope** — Resolve at call site with \`getVibesClient()\`
+- ❌ **Assuming surface** — Check \`runtime.scope\` if behavior differs
+- ❌ **Skipping plugin activation** — Call \`activatePlugins()\` after registration
+:::
+
+## Example: Multi-surface service
+
+\`\`\`ts
+// packages/notification-service/src/index.ts
+import { getVibesRuntime, getVibesClient } from '@vibesdotdev/runtime';
+import type { AIClient } from '@vibesdotdev/ai/client';
+
+export class NotificationService {
+  async sendNotification(
+    userId: string,
+    message: string
+  ): Promise<void> {
+    const runtime = getVibesRuntime();
+    const { surface, hardware } = runtime.scope;
+    
+    // Surface-specific notification strategy
+    if (surface === 'browser') {
+      // Browser: show toast notification
+      this.showBrowserNotification(message);
+    } else if (surface === 'ssr') {
+      // SSR: send email via server
+      const ai = await getVibesClient<AIClient>('ai');
+      const emailBody = await ai.generate({
+        prompt: \`Write email: \${message}\`
+      });
+      await this.sendEmail(userId, emailBody);
+    } else if (surface === 'worker') {
+      // Worker: queue notification job
+      await this.queueNotification(userId, message);
+    }
+  }
+  
+  private showBrowserNotification(message: string) {
+    // Browser-specific: toast, badge, etc.
+  }
+  
+  private async sendEmail(userId: string, body: string) {
+    // SSR-specific: email service
+  }
+  
+  private async queueNotification(userId: string, message: string) {
+    // Worker-specific: job queue
+  }
+}
+\`\`\`
+
+## Code paths
+
+- CLI bootstrap: [\`packages/cli/src/bootstrap.ts\`](https://github.com/vibesdotdev/monorepo/tree/main/packages/cli/src/bootstrap.ts)
+- Runtime bootstrap: [\`packages/runtime/src/bootstrap/index.ts\`](https://github.com/vibesdotdev/monorepo/tree/main/packages/runtime/src/bootstrap/index.ts)
+- Helper: [\`packages/runtime-client/src/helper.ts\`](https://github.com/vibesdotdev/monorepo/tree/main/packages/runtime-client/src/helper.ts)
+- Plugin: [\`packages/runtime-client/src/plugin.ts\`](https://github.com/vibesdotdev/monorepo/tree/main/packages/runtime-client/src/plugin.ts)
+
+:::card{title="See also"}
+- [\`runtime-client.api\`](runtime-client.api) — BaseRuntimeClient and extension patterns
+- [\`runtime-client.helpers\`](runtime-client.helpers) — getVibesClient() helper functions
+- [\`runtime.scopes\`](runtime.scopes) — Consumer vs cloud scopes
+- [\`bootstrapVibesRuntime\`](bootstrap) — Runtime bootstrap API
+:::
+`
+  },
+  parent: 'runtime-client',
+  order: 3,
+  tags: ['runtime-client', 'surfaces', 'initialization', 'cli', 'ssr', 'browser', 'worker'],
+  surfaces: ['cli', 'web', 'in-app'],
+  hardware: ['consumer', 'cloud'],
+  enabled: true,
+  man: {
+    name: 'runtime-client.surface — surface initialization patterns',
+    section: 1,
+    synopsis: 'vibes man runtime-client.surface',
+    options: [],
+    examples: [
+      {
+        description: 'CLI surface bootstrap',
+        command: 'await createVibesCliApp()'
+      },
+      {
+        description: 'SSR surface in SvelteKit',
+        command: 'await bootstrapVibesRuntime({ scope: { surface: "ssr" } })'
+      }
+    ],
+    seeAlso: ['runtime-client.api', 'runtime-client.helpers', 'runtime.scopes']
+  }
+};
+
+export default descriptor;

package/src/docs/types.ts

@@ -0,0 +1,18 @@
+export type DocsTopicDescriptor = {
+	kind: 'docs/topic';
+	id: string;
+	title: string;
+	summary?: string;
+	body: {
+		type: 'markdown';
+		sourceType: 'raw';
+		source: string;
+	};
+	parent?: string;
+	order?: number;
+	enabled?: boolean;
+	man?: unknown;
+	tags?: string[];
+	surfaces?: string[];
+	hardware?: string[];
+};

package/src/helper.ts

@@ -0,0 +1,32 @@
+import { getVibesRuntime } from '@vibesdotdev/runtime';
+import type { RuntimeClient } from './contract.ts';
+import { runtimeClientPlugin } from './plugin.ts';
+
+/**
+ * Ambient helper to resolve a module-level client by id.
+ *
+ * ```ts
+ * const ai = await getVibesClient<AIClient>('ai');
+ * const response = await ai.generate({ prompt: 'Hello' });
+ * ```
+ *
+ * Equivalent to calling `runtime.query('runtime/client').withId(id).resolve()`
+ * on the ambient runtime, with a clearer error when the client isn't registered.
+ */
+export async function getVibesClient<T extends RuntimeClient = RuntimeClient>(
+	id: string
+): Promise<T> {
+	const runtime = getVibesRuntime();
+	if (!runtime.hasKind('runtime/client')) {
+		await runtime.registerPlugin(runtimeClientPlugin);
+	}
+	const client = await runtime.query('runtime/client').withId(id).resolve();
+	if (!client) {
+		throw new Error(
+			`No runtime client registered with id "${id}". ` +
+				`Compose the owning module's plugin (e.g. aiPlugin for id="ai") before use, ` +
+				`and ensure runtimeClientPlugin is registered.`
+		);
+	}
+	return client as T;
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+// @vibesdotdev/runtime-client
+// One-client-per-module pattern: shared base, kind, and resolver helper.
+
+export { runtimeClientPlugin } from './plugin.ts';
+export { runtimeClientKind } from './kind.ts';
+export { BaseRuntimeClient } from './base.ts';
+export { getVibesClient } from './helper.ts';
+
+export type { RuntimeClient } from './contract.ts';
+export type { RuntimeClientDescriptor } from './schema.ts';
+export { RuntimeClientDescriptorSchema } from './schema.ts';

package/src/kind.ts

@@ -0,0 +1,14 @@
+import type { RuntimeKindDescriptorRecord } from '@vibesdotdev/runtime';
+import { RuntimeClientDescriptorSchema } from './schema.ts';
+import type { RuntimeClient } from './contract.ts';
+
+/**
+ * `runtime/client` kind descriptor record.
+ *
+ * No `defaultImplementation` — each module registers its own class via a
+ * per-descriptor loader (see `runtime.registerLoader('runtime/client', '<id>', …)`).
+ */
+export const runtimeClientKind: RuntimeKindDescriptorRecord<RuntimeClient> = {
+	id: 'runtime/client',
+	descriptorSchema: RuntimeClientDescriptorSchema
+};

package/src/plugin.ts

@@ -0,0 +1,19 @@
+import { createRuntimePlugin } from '@vibesdotdev/runtime';
+import { runtimeClientKind } from './kind.ts';
+
+/**
+ * Registers the `runtime/client` kind.
+ *
+ * Compose this plugin once at app bootstrap. Module plugins (ai, tools,
+ * knowledge, …) declare `dependencies: ['runtime-client', …]` and register
+ * their per-id loaders in their `onRegister` hook.
+ */
+export const runtimeClientPlugin = createRuntimePlugin({
+	id: 'runtime-client',
+	name: 'Runtime Client',
+	description:
+		'Shared `runtime/client` kind. Each module registers one descriptor; consumers resolve via `runtime.query(\"runtime/client\").withId(\"ai\")`.',
+	kinds: [runtimeClientKind]
+});
+
+export default runtimeClientPlugin;

package/src/runtime-client.plugin.ts

@@ -0,0 +1,32 @@
+/**
+ * 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.ts';
+import runtimeClientHelpersDocs from './docs/runtime-client.helpers.docs.descriptor.ts';
+import runtimeClientSurfaceDocs from './docs/runtime-client.surface.docs.descriptor.ts';
+
+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;

package/src/schema.ts

@@ -0,0 +1,27 @@
+import * as z from 'zod/v4';
+import {
+	RuntimeDescriptorSchema,
+	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 const RuntimeClientDescriptorSchema = RuntimeDescriptorSchema.extend({
+	kind: z.literal('runtime/client'),
+	configManifestId: z.string().optional(),
+	description: z.string().optional()
+});