@rivet-dev/agentos-runtime-core 0.2.20 → 0.2.21

package/dist/test-runtime.js

@@ -85,6 +85,21 @@ const SIDECAR_BUILD_INPUTS = [
     path.join(REPO_ROOT, "pnpm-lock.yaml"),
 ];
 let ensuredSidecarBinary = null;
+/**
+ * A host-side function that guest code can invoke as a shell command. The guest
+ * runs the host function by name and the invocation round-trips back to the host JS
+ * `handler`, whose return value is passed back to the guest. Host functions never run
+ * inside the guest: they execute on the host, so they are the bridge for giving
+ * sandboxed guest code controlled, named capabilities (the kind AI agents call
+ * as tools).
+ */
+import { hostFunctionDescription, resolveHostFunctions, } from "./host-functions.js";
+import { zodToJsonSchema } from "./host-functions-zod.js";
+/** The description the agent sees, taken from the input schema. */
+function jsonSchemaDescription(inputSchema) {
+    const description = inputSchema.description;
+    return typeof description === "string" ? description : "";
+}
 export class KernelError extends Error {
     code;
     constructor(code, message) {
@@ -677,7 +692,7 @@ function normalizePermissionsPolicy(permissions) {
         childProcess: normalizePatternPermissionScope(permissions.childProcess),
         process: normalizePatternPermissionScope(permissions.process),
         env: normalizePatternPermissionScope(permissions.env),
-        binding: normalizePatternPermissionScope(permissions.binding),
+        hostFunction: normalizePatternPermissionScope(permissions.hostFunction),
     };
 }
 export function filterEnv(env, permissions) {
@@ -1788,11 +1803,11 @@ class NativeKernel {
     mountedRuntimeDrivers = [];
     runtimeDriverCommandDirStarts = new Map();
     loopbackExemptPorts;
-    // Bindings registered with the VM, keyed by the callback key the sidecar
-    // sends back on a host_callback request (the binding name). Installed lazily
-    // on the first registerBindings call.
-    bindingHandlers = new Map();
-    bindingRequestHandlerInstalled = false;
+    // Host functions registered with the VM, keyed by the callback key the sidecar
+    // sends back on a host_callback request (the host-function name). Installed lazily
+    // on the first registerHostFunctions call.
+    hostFunctionHandlers = new Map();
+    hostFunctionRequestHandlerInstalled = false;
     constructor(options) {
         this.options = options;
         this.env = { ...(options.env ?? {}) };
@@ -2017,7 +2032,7 @@ class NativeKernel {
         await this.ensureReady();
         return this.proxy.vmFetch(request);
     }
-    async registerBindings(bindings) {
+    async registerHostFunctions(hostFunctions) {
         await this.ensureReady();
         if (!this.client || !this.session || !this.vm) {
             throw new Error("kernel is not ready");
@@ -2025,64 +2040,58 @@ class NativeKernel {
         // Install the dispatcher once. It routes every host_callback request the
         // sidecar emits to the matching registered handler and replies with a
         // host_callback_result frame.
-        if (!this.bindingRequestHandlerInstalled) {
-            this.client.setSidecarRequestHandler((request) => this.dispatchBindingRequest(request));
-            this.bindingRequestHandlerInstalled = true;
-        }
-        for (const [name, binding] of Object.entries(bindings)) {
-            this.bindingHandlers.set(name, binding.handler);
-            const definition = {
-                description: binding.description,
-                inputSchema: binding.inputSchema,
-                ...(binding.timeoutMs !== undefined
-                    ? { timeoutMs: binding.timeoutMs }
-                    : {}),
-                ...(binding.examples && binding.examples.length > 0
-                    ? {
-                        examples: binding.examples.map((example) => ({
-                            description: example.description,
-                            input: example.input,
-                        })),
-                    }
-                    : {}),
-            };
-            // Register each binding as its own single-callback binding collection so the guest
-            // can invoke it directly by name (or by any caller-provided alias). The
-            // sidecar exposes the binding collection name as a guest command; the single
-            // callback carries the binding's schema and gates the `binding`
-            // permission.
+        if (!this.hostFunctionRequestHandlerInstalled) {
+            this.client.setSidecarRequestHandler((request) => this.dispatchHostFunctionRequest(request));
+            this.hostFunctionRequestHandlerInstalled = true;
+        }
+        for (const collection of resolveHostFunctions(hostFunctions)) {
+            const callbacks = {};
+            for (const [functionName, definition] of Object.entries(collection.functions)) {
+                this.hostFunctionHandlers.set(`${collection.name}:${functionName}`, definition.execute);
+                callbacks[functionName] = {
+                    description: hostFunctionDescription(definition),
+                    inputSchema: zodToJsonSchema(definition.inputSchema),
+                    ...(definition.timeout !== undefined
+                        ? { timeoutMs: definition.timeout }
+                        : {}),
+                    ...(definition.examples && definition.examples.length > 0
+                        ? {
+                            examples: definition.examples.map((example) => ({
+                                description: example.description,
+                                input: example.input,
+                            })),
+                        }
+                        : {}),
+                };
+            }
+            // One registration per collection, exposed to the guest as the command
+            // `agentos-<collection>` with each function as a subcommand. This is the
+            // same shape `AgentOs.create()` registers.
+            const command = `agentos-${collection.name}`;
             await this.client.registerHostCallbacks(this.session, this.vm, {
-                name,
-                description: binding.description,
-                commandAliases: [name, ...(binding.commandAliases ?? [])],
-                callbacks: { [name]: definition },
+                name: collection.name,
+                description: "",
+                commandAliases: [command],
+                registryCommandAliases: ["agentos"],
+                callbacks,
             });
-            this.commands.set(name, "wasmvm");
-            for (const alias of binding.commandAliases ?? []) {
-                this.commands.set(alias, "wasmvm");
-            }
+            this.commands.set(command, "wasmvm");
         }
     }
-    async dispatchBindingRequest(request) {
+    async dispatchHostFunctionRequest(request) {
         const { payload } = request;
         if (payload.type !== "host_callback") {
-            throw new Error(`unsupported sidecar request for bindings: ${payload.type}`);
+            throw new Error(`unsupported sidecar request for host functions: ${payload.type}`);
         }
-        // Callback keys arrive as `${collection}:${binding}` for collection invocations
-        // and as the bare command name otherwise. The collection and binding name are
-        // the same here, so the registered binding name is the segment after the last
-        // colon (or the whole key when no colon is present).
+        // Callback keys arrive as `<collection>:<function>`, the key each handler
+        // was registered under.
         const callbackKey = payload.callback_key;
-        const bindingName = callbackKey.includes(":")
-            ? callbackKey.slice(callbackKey.lastIndexOf(":") + 1)
-            : callbackKey;
-        const handler = this.bindingHandlers.get(bindingName) ??
-            this.bindingHandlers.get(callbackKey);
+        const handler = this.hostFunctionHandlers.get(callbackKey);
         if (!handler) {
             return {
                 type: "host_callback_result",
                 invocation_id: payload.invocation_id,
-                error: `no binding registered for ${callbackKey}`,
+                error: `no host function registered for ${callbackKey}`,
             };
         }
         try {

package/dist/vm-config.d.ts

@@ -28,7 +28,7 @@ export type { RootFilesystemEntryEncoding } from "./generated/RootFilesystemEntr
 export type { RootFilesystemEntryKind } from "./generated/RootFilesystemEntryKind.js";
 export type { RootFilesystemLowerDescriptor } from "./generated/RootFilesystemLowerDescriptor.js";
 export type { RootFilesystemMode } from "./generated/RootFilesystemMode.js";
-export type { BindingLimitsConfig } from "./generated/BindingLimitsConfig.js";
+export type { HostFunctionLimitsConfig } from "./generated/HostFunctionLimitsConfig.js";
 export type { VmDnsConfig } from "./generated/VmDnsConfig.js";
 export type { VmLimitsConfig } from "./generated/VmLimitsConfig.js";
 export type { VmListenPolicyConfig } from "./generated/VmListenPolicyConfig.js";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rivet-dev/agentos-runtime-core",
-	"version": "0.2.20",
+	"version": "0.2.21",
 	"type": "module",
 	"license": "Apache-2.0",
 	"main": "./dist/index.js",
@@ -21,6 +21,16 @@
 			"import": "./dist/generated-protocol.js",
 			"default": "./dist/generated-protocol.js"
 		},
+		"./host-functions": {
+			"types": "./dist/host-functions.d.ts",
+			"import": "./dist/host-functions.js",
+			"default": "./dist/host-functions.js"
+		},
+		"./host-functions-zod": {
+			"types": "./dist/host-functions-zod.d.ts",
+			"import": "./dist/host-functions-zod.js",
+			"default": "./dist/host-functions-zod.js"
+		},
 		"./vm-config": {
 			"types": "./dist/vm-config.d.ts",
 			"import": "./dist/vm-config.js",
@@ -197,9 +207,10 @@
 		"test:npm-workflows": "AGENTOS_NPM_WORKFLOWS_E2E=1 vitest run tests/integration/e2e-npm-*.nightly.test.ts tests/integration/e2e-npx-and-pipes.nightly.test.ts tests/integration/e2e-concurrently.nightly.test.ts tests/integration/e2e-nextjs-build.nightly.test.ts --reporter=verbose"
 	},
 	"dependencies": {
-		"@rivet-dev/agentos-runtime-sidecar": "0.2.20",
+		"@rivet-dev/agentos-runtime-sidecar": "0.2.21",
 		"@rivetkit/bare-ts": "^0.6.2",
-		"zod": "^4.1.11"
+		"zod": "^4.1.11",
+		"zod-to-json-schema": "^3.25.2"
 	},
 	"devDependencies": {
 		"@types/node": "^22.10.2",

package/dist/generated/BindingLimitsConfig.d.ts

@@ -1,10 +0,0 @@
-export type BindingLimitsConfig = {
-    defaultBindingTimeoutMs?: number;
-    maxBindingTimeoutMs?: number;
-    maxRegisteredCollections?: number;
-    maxRegisteredBindingsPerVm?: number;
-    maxBindingsPerCollection?: number;
-    maxBindingSchemaBytes?: number;
-    maxExamplesPerBinding?: number;
-    maxBindingExampleInputBytes?: number;
-};