@vibesdotdev/kernel-rpc 0.0.0-stage → 1.0.0-rc.2

package/dist/docs/system.docs.descriptor.js

@@ -0,0 +1,115 @@
+/**
+ * Descriptor for runtime-plugin.system
+ * Plugin system architecture, createRuntimePlugin(), kind registration
+ */
+const systemMarkdown = `# Runtime Plugin System
+
+Plugins contribute kinds, descriptors, lazy loaders and remote exposures to the
+kernel. The kernel owns registry, resolution, scope and lifecycle; feature
+packages own their capability contracts and implementations.
+
+## Compose a capability
+
+\`createRuntimePlugin\` comes from \`@vibesdotdev/kernel\`. Declare the owning kind's
+schema in \`kinds\`, its assets in \`descriptors\`, and lazy implementations in
+\`loaders\`. A loader names its asset id and kind; its constraints describe the
+scope where that implementation serves. The kernel chooses the implementation
+at resolution time.
+
+For example, this package's RPC plugin registers \`runtime/rpc\`, while each
+transport plugin contributes its transport descriptors and implementations.
+Transport plugins register the kind only when absent, so hosts can compose them
+in any order. A feature does not select a transport implementation with its own
+lookup table.
+
+\`\`\`ts
+import rpcPlugin from '@vibesdotdev/kernel-rpc/plugin';
+import { createRuntimeRpcUnixPlugin, createUnixRpcDescriptor }
+  from '@vibesdotdev/kernel-rpc/unix';
+
+await runtime.registerPlugin(rpcPlugin);
+await runtime.registerPlugin(createRuntimeRpcUnixPlugin({
+  descriptors: [createUnixRpcDescriptor(socketPath, 'workspace-daemon')]
+}));
+\`\`\`
+
+The host supplies \`runtime\` and its resolved \`socketPath\`. The runtime environment
+provides sockets; the RPC package carries the transport-neutral protocol.
+
+## Lazy loaders and dependencies
+
+Use \`loader(id, { kind, scope }, () => import('./implementation.ts'))\` for a
+scoped implementation. Keep the import lazy. Registration installs the loader;
+resolution loads the implementation through the kernel. Declare required plugin
+ids with \`dependencies\`, and optional composition with \`optionalDependencies\`.
+
+Descriptors are validated through their owning kind schemas. Metadata travels
+through \`./descriptor-wire\`, preserving feature fields while serializing schema
+metadata. Boundary types derive from the owning schemas rather than a parallel
+wire interface.
+
+## Resolve through the runtime
+
+\`\`\`ts
+const descriptor = runtime.query('runtime/rpc').withId('workspace-daemon');
+const connection = await descriptor.resolve();
+\`\`\`
+
+Use the capability owner's runtime client for its supported operations. Async
+client resolution uses \`getVibesClient\`; synchronous access after activation
+uses \`tryGetVibesClient\` from \`@vibesdotdev/kernel/client\`. Keep implementation
+selection and caching in the kernel.
+
+## This package's composition entrypoints
+
+- \`./plugin\`: the transport-neutral RPC kind.
+- Transport \`/plugin\` exports: Unix, TCP, HTTP, MessagePort, CEF and Tauri.
+  Relay registration helpers are on \`./relay\`.
+- \`./daemon/plugin\`: daemon contexts, lifecycle topics and optional PM adapters.
+- \`./daemon/cli/plugin\`: command-line projection.
+- \`./docs/plugin\`: five documentation topics without registering the RPC kind.
+
+PM implementation imports remain lazy and its contracts are type-only. A host
+that does not compose PM can still load every public RPC entrypoint.
+
+## Failure and lifetime
+
+Registration and resolution failures remain observable. Connections and stream
+bindings belong to the lifecycle that acquired them; shutdown joins cleanup and
+reports typed failures. See \`runtime-plugin.lifecycle\` for those responsibilities.
+
+:::card{title="See also"}
+- [\`runtime-plugin.lifecycle\`](runtime-plugin.lifecycle) — Resource lifetime
+- [\`runtime.rpc\`](runtime.rpc) — Public protocol and transport contracts
+- [\`runtime.query\`](runtime.query) — Discovery and resolution
+:::
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'runtime-plugin.system',
+    title: 'Runtime Plugin System',
+    summary: 'Plugin architecture, createRuntimePlugin(), and kind registration',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: systemMarkdown
+    },
+    parent: 'runtime',
+    order: 5,
+    tags: ['runtime', 'plugins', 'architecture', 'kinds', 'registration'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    man: {
+        name: 'runtime-plugin.system — Plugin system architecture',
+        section: 1,
+        synopsis: 'vibes man runtime-plugin.system',
+        seeAlso: ['runtime-plugin.lifecycle', 'runtime.query', 'runtime.plugins']
+    },
+    subject: {
+        kind: 'docs/topic',
+        id: 'runtime-plugin.system'
+    },
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=system.docs.descriptor.js.map

package/dist/docs/system.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/system.docs.descriptor.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiFtB,CAAC;AAEF,MAAM,UAAU,GAAwB;IACtC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,uBAAuB;IAC3B,KAAK,EAAE,uBAAuB;IAC9B,OAAO,EAAE,mEAAmE;IAC5E,IAAI,EAAE;QACJ,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE,cAAc;KACvB;IACD,MAAM,EAAE,SAAS;IACjB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,SAAS,EAAE,SAAS,EAAE,cAAc,EAAE,OAAO,EAAE,cAAc,CAAC;IACrE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,GAAG,EAAE;QACH,IAAI,EAAE,oDAAoD;QAC1D,OAAO,EAAE,CAAC;QACV,QAAQ,EAAE,iCAAiC;QAC3C,OAAO,EAAE,CAAC,0BAA0B,EAAE,eAAe,EAAE,iBAAiB,CAAC;KAC1E;IACD,OAAO,EAAE;QACP,IAAI,EAAE,YAAY;QAClB,EAAE,EAAE,uBAAuB;KAC5B;IACD,OAAO,EAAE,IAAI;CACd,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/execution/execution.client.impl.d.ts

@@ -0,0 +1,8 @@
+import { BaseRuntimeClient } from '@vibesdotdev/kernel/client';
+import type { WireProcessAdapter, WireProcessOwner, WireProcessPort, WireProcessAcquisition, ProcessHandle } from '@vibesdotdev/kernel/execution';
+/** Runtime-owned adapter; process custody remains with the caller's owner. */
+export declare class ExecutionWireClient extends BaseRuntimeClient implements WireProcessAdapter {
+    adaptWireProcessHandle(owner: WireProcessOwner, port: WireProcessPort): Promise<ProcessHandle>;
+    acquireWireProcess(owner: WireProcessOwner, dispatch: () => Promise<WireProcessPort>): WireProcessAcquisition;
+}
+//# sourceMappingURL=execution.client.impl.d.ts.map

package/dist/execution/execution.client.impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution.client.impl.d.ts","sourceRoot":"","sources":["../../src/execution/execution.client.impl.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,KAAK,EACX,kBAAkB,EAAE,gBAAgB,EAAE,eAAe,EACrD,sBAAsB,EAAE,aAAa,EACrC,MAAM,+BAA+B,CAAC;AAGvC,8EAA8E;AAC9E,qBAAa,mBAAoB,SAAQ,iBAAkB,YAAW,kBAAkB;IACvF,sBAAsB,CAAC,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC;IAI9F,kBAAkB,CAAC,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,GAAG,sBAAsB;CAG7G"}

package/dist/execution/execution.client.impl.js

@@ -0,0 +1,12 @@
+import { BaseRuntimeClient } from '@vibesdotdev/kernel/client';
+import { adaptWireProcessHandle, acquireWireProcess } from "./wire-process.js";
+/** Runtime-owned adapter; process custody remains with the caller's owner. */
+export class ExecutionWireClient extends BaseRuntimeClient {
+    adaptWireProcessHandle(owner, port) {
+        return adaptWireProcessHandle(owner, port);
+    }
+    acquireWireProcess(owner, dispatch) {
+        return acquireWireProcess(owner, dispatch);
+    }
+}
+//# sourceMappingURL=execution.client.impl.js.map

package/dist/execution/execution.client.impl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution.client.impl.js","sourceRoot":"","sources":["../../src/execution/execution.client.impl.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAK/D,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE/E,8EAA8E;AAC9E,MAAM,OAAO,mBAAoB,SAAQ,iBAAiB;IACzD,sBAAsB,CAAC,KAAuB,EAAE,IAAqB;QACpE,OAAO,sBAAsB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAC5C,CAAC;IAED,kBAAkB,CAAC,KAAuB,EAAE,QAAwC;QACnF,OAAO,kBAAkB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAC5C,CAAC;CACD"}

package/dist/execution/execution.plugin.d.ts

@@ -0,0 +1,4 @@
+/** Universal process wire adapter, independent of any host transport. */
+export declare const runtimeRpcExecutionPlugin: import("@vibesdotdev/kernel").RuntimePlugin;
+export default runtimeRpcExecutionPlugin;
+//# sourceMappingURL=execution.plugin.d.ts.map

package/dist/execution/execution.plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution.plugin.d.ts","sourceRoot":"","sources":["../../src/execution/execution.plugin.ts"],"names":[],"mappings":"AAIA,yEAAyE;AACzE,eAAO,MAAM,yBAAyB,6CAapC,CAAC;AAEH,eAAe,yBAAyB,CAAC"}

package/dist/execution/execution.plugin.js

@@ -0,0 +1,20 @@
+import { createRuntimePlugin } from '@vibesdotdev/kernel';
+import { getVibesClient, runtimeClientPlugin } from '@vibesdotdev/kernel/client';
+/** Universal process wire adapter, independent of any host transport. */
+export const runtimeRpcExecutionPlugin = createRuntimePlugin({
+    id: 'runtime-rpc-execution',
+    name: 'Runtime RPC — execution wire',
+    async onRegister(runtime) {
+        if (!runtime.hasKind('runtime/client'))
+            await runtime.registerPlugin(runtimeClientPlugin);
+        runtime.registerDescriptor('runtime/client', { kind: 'runtime/client', id: 'execution-wire' });
+        runtime.registerLoader('runtime/client', 'execution-wire', async () => ({
+            impl: (await import("./execution.client.impl.js")).ExecutionWireClient
+        }));
+    },
+    async onActivate(runtime) {
+        await getVibesClient('execution-wire', runtime);
+    }
+});
+export default runtimeRpcExecutionPlugin;
+//# sourceMappingURL=execution.plugin.js.map

package/dist/execution/execution.plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution.plugin.js","sourceRoot":"","sources":["../../src/execution/execution.plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAGjF,yEAAyE;AACzE,MAAM,CAAC,MAAM,yBAAyB,GAAG,mBAAmB,CAAC;IAC5D,EAAE,EAAE,uBAAuB;IAC3B,IAAI,EAAE,8BAA8B;IACpC,KAAK,CAAC,UAAU,CAAC,OAAO;QACvB,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,gBAAgB,CAAC;YAAE,MAAM,OAAO,CAAC,cAAc,CAAC,mBAAmB,CAAC,CAAC;QAC1F,OAAO,CAAC,kBAAkB,CAAC,gBAAgB,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,EAAE,EAAE,gBAAgB,EAAE,CAAC,CAAC;QAC/F,OAAO,CAAC,cAAc,CAAC,gBAAgB,EAAE,gBAAgB,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;YACvE,IAAI,EAAE,CAAC,MAAM,MAAM,CAAC,4BAA4B,CAAC,CAAC,CAAC,mBAAmB;SACtE,CAAC,CAAC,CAAC;IACL,CAAC;IACD,KAAK,CAAC,UAAU,CAAC,OAAO;QACvB,MAAM,cAAc,CAAqB,gBAAgB,EAAE,OAAO,CAAC,CAAC;IACrE,CAAC;CACD,CAAC,CAAC;AAEH,eAAe,yBAAyB,CAAC"}

package/dist/execution/index.d.ts

@@ -0,0 +1,5 @@
+/** Concrete process wire lifecycle owner. Kernel retains the public contracts. */
+export { adaptWireProcessHandle, acquireWireProcess } from './wire-process.ts';
+export { runtimeRpcExecutionPlugin } from './execution.plugin.ts';
+export type { WireProcessOwner, WireProcessPort, WireProcessChannel, WireChannelCloseAck, WireProcessAcquisition, WireAcquisitionOutcome, WireAcquisitionSettlement, WireProcessAdapter } from '@vibesdotdev/kernel/execution';
+//# sourceMappingURL=index.d.ts.map

package/dist/execution/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/execution/index.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAClE,YAAY,EACX,gBAAgB,EAAE,eAAe,EAAE,kBAAkB,EAAE,mBAAmB,EAC1E,sBAAsB,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,kBAAkB,EAC7F,MAAM,+BAA+B,CAAC"}

package/dist/execution/index.js

@@ -0,0 +1,4 @@
+/** Concrete process wire lifecycle owner. Kernel retains the public contracts. */
+export { adaptWireProcessHandle, acquireWireProcess } from "./wire-process.js";
+export { runtimeRpcExecutionPlugin } from "./execution.plugin.js";
+//# sourceMappingURL=index.js.map

package/dist/execution/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/execution/index.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/execution/wire-process.d.ts

@@ -0,0 +1,10 @@
+import { type ProcessHandle, type WireProcessOwner, type WireProcessPort, type WireProcessAcquisition } from '@vibesdotdev/kernel/execution';
+/**
+ * Adapt advertised process channels; exit includes delivery of both output
+ * streams. `port` is what the remote's declared execution contract returns
+ * (an RPC stub); a port that does not honor it is refused `setup` here.
+ */
+export declare function adaptWireProcessHandle(owner: WireProcessOwner, port: WireProcessPort): Promise<ProcessHandle>;
+/** Dispatch a remote spawn now and own its setup (see {@link WireProcessAcquisition}). */
+export declare function acquireWireProcess(owner: WireProcessOwner, dispatch: () => Promise<WireProcessPort>): WireProcessAcquisition;
+//# sourceMappingURL=wire-process.d.ts.map

package/dist/execution/wire-process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire-process.d.ts","sourceRoot":"","sources":["../../src/execution/wire-process.ts"],"names":[],"mappings":"AACA,OAAO,EAEN,KAAK,aAAa,EAAE,KAAK,gBAAgB,EAAE,KAAK,eAAe,EACtC,KAAK,sBAAsB,EACpD,MAAM,+BAA+B,CAAC;AAyHvC;;;;GAIG;AACH,wBAAsB,sBAAsB,CAAC,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC,CAMnH;AAmMD,0FAA0F;AAC1F,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,GAAG,sBAAsB,CA6G5H"}