@rivet-dev/agentos-core 0.2.20-rc.1 → 0.2.21

package/dist/agent-os.js

@@ -5,8 +5,8 @@ import { join, posix as posixPath, resolve as resolveHostPath, } from "node:path
 import { fileURLToPath } from "node:url";
 import * as executionProtocol from "@rivet-dev/agentos-runtime-core/protocol";
 import { SidecarRejectedError } from "@rivet-dev/agentos-runtime-core/sidecar-errors";
-import { validateBindings } from "./bindings.js";
-import { zodToJsonSchema } from "./bindings-zod.js";
+import { hostFunctionDescription, resolveHostFunctions, } from "@rivet-dev/agentos-runtime-core/host-functions";
+import { zodToJsonSchema } from "@rivet-dev/agentos-runtime-core/host-functions-zod";
 import { parseAgentOsOptions } from "./options-schema.js";
 import { getSandboxDisposeHooks, resolveSandboxOptions, } from "./sandbox.js";
 import { resolvePublishedSidecarBinary } from "./sidecar/binary.js";
@@ -168,7 +168,6 @@ import { resolveDefaultSoftware } from "./default-software.js";
 import { snapshotVirtualFilesystem, sortFilesystemEntries, } from "./filesystem-snapshot.js";
 import { serializeMountConfigForSidecar, } from "./js-bridge.js";
 import { createSnapshotExport, } from "./layers.js";
-import { allowAll } from "./runtime-compat.js";
 import { decodeAcpCallback, decodeAcpEvent, decodeAcpResponse, encodeAcpCallbackResponse, encodeAcpRequest, } from "./sidecar/agentos-protocol.js";
 import { serializePermissionsForSidecar } from "./sidecar/permissions.js";
 import { createAgentOsSidecarClient, NativeSidecarKernelProxy, SidecarProcess, serializeRootFilesystemForSidecar, } from "./sidecar/rpc-client.js";
@@ -773,13 +772,13 @@ function collectSidecarMountPlan(options) {
     hostPathMappings.sort((left, right) => right.vmPath.length - left.vmPath.length);
     return { sidecarMounts, hostMounts, hostPathMappings };
 }
-function collectBindingBootstrapCommands(bindings) {
-    if (bindings.length === 0) {
+function collectHostFunctionBootstrapCommands(hostFunctions) {
+    if (hostFunctions.length === 0) {
         return [];
     }
     return [
         "agentos",
-        ...bindings.map((bindingCollection) => `agentos-${bindingCollection.name}`),
+        ...hostFunctions.map((hostFunctionCollection) => `agentos-${hostFunctionCollection.name}`),
     ];
 }
 function validationMessage(error) {
@@ -798,9 +797,9 @@ function validationMessage(error) {
     }
     return error instanceof Error ? error.message : String(error);
 }
-function bindingToSidecarDefinition(definition) {
+function hostFunctionToSidecarDefinition(definition) {
     return {
-        description: definition.description,
+        description: hostFunctionDescription(definition),
         inputSchema: zodToJsonSchema(definition.inputSchema),
         ...(definition.timeout !== undefined
             ? { timeoutMs: definition.timeout }
@@ -815,8 +814,8 @@ function bindingToSidecarDefinition(definition) {
             : {}),
     };
 }
-function combineInstructions(additionalInstructions, bindingReference) {
-    const parts = [additionalInstructions, bindingReference]
+function combineInstructions(additionalInstructions, hostFunctionReference) {
+    const parts = [additionalInstructions, hostFunctionReference]
         .map((part) => part?.trim())
         .filter((part) => Boolean(part));
     if (parts.length === 0) {
@@ -824,48 +823,49 @@ function combineInstructions(additionalInstructions, bindingReference) {
     }
     return parts.join("\n\n");
 }
-function buildBindingReference(bindings) {
-    if (bindings.length === 0) {
+function buildHostFunctionReference(hostFunctions) {
+    if (hostFunctions.length === 0) {
         return "";
     }
     const lines = [
-        "## Available Host Bindings",
+        "## Available Host Functions",
         "",
-        "Run `agentos list-bindings` to see all available bindings.",
+        "Run `agentos list-host-functions` to see all available host functions.",
         "",
     ];
-    for (const bindingCollection of bindings) {
-        lines.push(`### ${bindingCollection.name}`);
+    for (const hostFunctionCollection of hostFunctions) {
+        lines.push(`### ${hostFunctionCollection.name}`);
         lines.push("");
-        lines.push(bindingCollection.description);
-        lines.push("");
-        for (const [bindingName, definition] of Object.entries(bindingCollection.bindings)) {
-            const sidecarBinding = bindingToSidecarDefinition(definition);
-            const signature = buildBindingFlagSignature(sidecarBinding.inputSchema);
+        for (const [functionName, definition] of Object.entries(hostFunctionCollection.functions)) {
+            const sidecarHostFunction = hostFunctionToSidecarDefinition(definition);
+            const signature = buildHostFunctionFlagSignature(sidecarHostFunction.inputSchema);
             const suffix = signature.length > 0 ? ` ${signature}` : "";
-            lines.push(`- \`agentos-${bindingCollection.name} ${bindingName}${suffix}\` — ${definition.description}`);
+            const description = hostFunctionDescription(definition);
+            lines.push(description.length > 0
+                ? `- \`agentos-${hostFunctionCollection.name} ${functionName}${suffix}\` - ${description}`
+                : `- \`agentos-${hostFunctionCollection.name} ${functionName}${suffix}\``);
         }
         lines.push("");
-        const bindingsWithExamples = Object.entries(bindingCollection.bindings).filter(([, definition]) => definition.examples && definition.examples.length > 0);
-        if (bindingsWithExamples.length > 0) {
+        const functionsWithExamples = Object.entries(hostFunctionCollection.functions).filter(([, definition]) => definition.examples && definition.examples.length > 0);
+        if (functionsWithExamples.length > 0) {
             lines.push("**Examples:**");
             lines.push("");
-            for (const [bindingName, definition] of bindingsWithExamples) {
+            for (const [functionName, definition] of functionsWithExamples) {
                 for (const example of definition.examples ?? []) {
-                    const args = inputToBindingFlags(example.input);
+                    const args = inputToHostFunctionFlags(example.input);
                     const suffix = args.length > 0 ? ` ${args}` : "";
-                    lines.push(`- ${example.description}: \`agentos-${bindingCollection.name} ${bindingName}${suffix}\``);
+                    lines.push(`- ${example.description}: \`agentos-${hostFunctionCollection.name} ${functionName}${suffix}\``);
                 }
             }
             lines.push("");
         }
-        lines.push(`Run \`agentos-${bindingCollection.name} <binding> --help\` for details.`);
+        lines.push(`Run \`agentos-${hostFunctionCollection.name} <function> --help\` for details.`);
         lines.push("");
     }
     return lines.join("\n");
 }
-function buildBindingFlagSignature(schema) {
-    return describeBindingFlags(schema)
+function buildHostFunctionFlagSignature(schema) {
+    return describeHostFunctionFlags(schema)
         .map((flag) => {
         if (flag.required) {
             return `${flag.name} <${flag.type}>`;
@@ -874,7 +874,7 @@ function buildBindingFlagSignature(schema) {
     })
         .join(" ");
 }
-function describeBindingFlags(schema) {
+function describeHostFunctionFlags(schema) {
     const schemaObject = asRecord(schema);
     const properties = asRecord(schemaObject.properties);
     const required = Array.isArray(schemaObject.required)
@@ -882,11 +882,11 @@ function describeBindingFlags(schema) {
         : new Set();
     return Object.entries(properties).map(([fieldName, fieldSchema]) => ({
         name: `--${camelToKebab(fieldName)}`,
-        type: describeBindingFlagType(fieldSchema),
+        type: describeHostFunctionFlagType(fieldSchema),
         required: required.has(fieldName),
     }));
 }
-function describeBindingFlagType(schema) {
+function describeHostFunctionFlagType(schema) {
     const schemaObject = asRecord(schema);
     const type = typeof schemaObject.type === "string" ? schemaObject.type : undefined;
     if (type === "array") {
@@ -905,7 +905,7 @@ function describeJsonSchemaScalarType(schema) {
     const schemaObject = asRecord(schema);
     return typeof schemaObject.type === "string" ? schemaObject.type : "string";
 }
-function inputToBindingFlags(input) {
+function inputToHostFunctionFlags(input) {
     const inputObject = asRecord(input);
     return Object.entries(inputObject)
         .flatMap(([key, value]) => {
@@ -917,13 +917,13 @@ function inputToBindingFlags(input) {
             return [`--no-${camelToKebab(key)}`];
         }
         if (Array.isArray(value)) {
-            return value.map((item) => `${flag} ${bindingCliString(item)}`);
+            return value.map((item) => `${flag} ${hostFunctionCliString(item)}`);
         }
-        return [`${flag} ${bindingCliString(value)}`];
+        return [`${flag} ${hostFunctionCliString(value)}`];
     })
         .join(" ");
 }
-function bindingCliString(value) {
+function hostFunctionCliString(value) {
     return typeof value === "string" ? value : (JSON.stringify(value) ?? "null");
 }
 function camelToKebab(value) {
@@ -961,22 +961,16 @@ async function handleHostCallback(request, context) {
             };
         }
     }
-    const definition = context.bindingMap.get(payload.callback_key);
+    const definition = context.hostFunctionMap.get(payload.callback_key);
     if (!definition) {
         return {
             type: "host_callback_result",
             invocation_id: payload.invocation_id,
-            error: `Unknown binding "${payload.callback_key}"`,
-        };
-    }
-    const permissionMode = bindingPermissionMode(context.permissions, payload.callback_key);
-    if (permissionMode !== "allow") {
-        return {
-            type: "host_callback_result",
-            invocation_id: payload.invocation_id,
-            error: `EACCES: blocked by binding.invoke policy for ${payload.callback_key}`,
+            error: `Unknown host function "${payload.callback_key}"`,
         };
     }
+    // The sidecar checks the `hostFunction` permission scope before it forwards a
+    // host function call, so a call that reaches the host is already permitted.
     const parsed = definition.inputSchema.safeParse(payload.input);
     if (!parsed.success) {
         return {
@@ -989,7 +983,7 @@ async function handleHostCallback(request, context) {
         return {
             type: "host_callback_result",
             invocation_id: payload.invocation_id,
-            result: await executeBinding(definition, payload.callback_key, parsed.data),
+            result: await executeHostFunction(definition, payload.callback_key, parsed.data),
         };
     }
     catch (error) {
@@ -1000,14 +994,14 @@ async function handleHostCallback(request, context) {
         };
     }
 }
-function buildBindingMap(bindings) {
-    const bindingMap = new Map();
-    for (const bindingCollection of bindings) {
-        for (const [bindingName, definition] of Object.entries(bindingCollection.bindings)) {
-            bindingMap.set(`${bindingCollection.name}:${bindingName}`, definition);
+function buildHostFunctionMap(hostFunctions) {
+    const hostFunctionMap = new Map();
+    for (const hostFunctionCollection of hostFunctions) {
+        for (const [functionName, definition] of Object.entries(hostFunctionCollection.functions)) {
+            hostFunctionMap.set(`${hostFunctionCollection.name}:${functionName}`, definition);
         }
     }
-    return bindingMap;
+    return hostFunctionMap;
 }
 function bridgeErrorMessage(error) {
     return error instanceof Error ? error.message : String(error);
@@ -1154,75 +1148,73 @@ function parseHostCommandCallbackInput(input) {
     };
 }
 async function handleHostCommandCallback(command, context) {
-    const directBindings = context.bindings.find((bindingCollection) => `agentos-${bindingCollection.name}` === command.command);
+    const directHostFunctions = context.hostFunctions.find((hostFunctionCollection) => `agentos-${hostFunctionCollection.name}` === command.command);
     if (command.command === "agentos") {
         return handleAgentOsRegistryCommand(command, context);
     }
-    if (directBindings) {
-        return handleAgentOsBindingCommand(command, context, directBindings);
+    if (directHostFunctions) {
+        return handleAgentOsHostFunctionCommand(command, context, directHostFunctions);
     }
     throw new Error(`Unknown host callback command "${command.command}"`);
 }
 async function handleAgentOsRegistryCommand(command, context) {
-    const [subcommand, collectionName, bindingName, ...bindingArgs] = command.args;
+    const [subcommand, collectionName, functionName, ...functionArgs] = command.args;
     if (!subcommand || isHelpFlag(subcommand)) {
         return {
-            usage: "agentos <command>: list-bindings [collection], <collection> --help, or <collection> <binding> ...",
+            usage: "agentos <command>: list-host-functions [collection], <collection> --help, or <collection> <function> ...",
         };
     }
-    if (subcommand === "list-bindings") {
+    if (subcommand === "list-host-functions" || subcommand === "list-bindings") {
         return collectionName
-            ? describeBindingsPayload(context.bindings, collectionName)
-            : listBindingsPayload(context.bindings);
+            ? describeHostFunctionsPayload(context.hostFunctions, collectionName)
+            : listHostFunctionsPayload(context.hostFunctions);
     }
-    const bindingCollection = context.bindings.find((collection) => collection.name === subcommand);
-    if (!bindingCollection) {
-        throw new Error(`No binding collection "${subcommand}". Available: ${bindingsNames(context.bindings)}`);
+    const hostFunctionCollection = context.hostFunctions.find((collection) => collection.name === subcommand);
+    if (!hostFunctionCollection) {
+        throw new Error(`No host function collection "${subcommand}". Available: ${hostFunctionsNames(context.hostFunctions)}`);
     }
     if (!collectionName || isHelpFlag(collectionName)) {
-        return describeBindingsPayload(context.bindings, subcommand);
+        return describeHostFunctionsPayload(context.hostFunctions, subcommand);
     }
-    if (bindingName && isHelpFlag(bindingName)) {
-        return describeBindingPayload(bindingCollection, collectionName);
+    if (functionName && isHelpFlag(functionName)) {
+        return describeHostFunctionPayload(hostFunctionCollection, collectionName);
     }
-    return invokeBinding({
-        bindingCollection,
-        bindingName: collectionName,
-        args: [bindingName, ...bindingArgs].filter((value) => typeof value === "string"),
+    return invokeHostFunction({
+        hostFunctionCollection,
+        functionName: collectionName,
+        args: [functionName, ...functionArgs].filter((value) => typeof value === "string"),
         cwd: command.cwd,
         context,
     });
 }
-async function handleAgentOsBindingCommand(command, context, bindingCollection) {
-    const [bindingName, helpOrFirstArg, ...rest] = command.args;
-    if (!bindingName || isHelpFlag(bindingName)) {
-        return describeBindingsPayload(context.bindings, bindingCollection.name);
+async function handleAgentOsHostFunctionCommand(command, context, hostFunctionCollection) {
+    const [functionName, helpOrFirstArg, ...rest] = command.args;
+    if (!functionName || isHelpFlag(functionName)) {
+        return describeHostFunctionsPayload(context.hostFunctions, hostFunctionCollection.name);
     }
     if (helpOrFirstArg && isHelpFlag(helpOrFirstArg)) {
-        return describeBindingPayload(bindingCollection, bindingName);
+        return describeHostFunctionPayload(hostFunctionCollection, functionName);
     }
-    return invokeBinding({
-        bindingCollection,
-        bindingName,
+    return invokeHostFunction({
+        hostFunctionCollection,
+        functionName,
         args: [helpOrFirstArg, ...rest].filter((value) => typeof value === "string"),
         cwd: command.cwd,
         context,
     });
 }
-async function invokeBinding({ bindingCollection, bindingName, args, cwd, context, }) {
-    const definition = bindingCollection.bindings[bindingName];
+async function invokeHostFunction({ hostFunctionCollection, functionName, args, cwd, context, }) {
+    const definition = hostFunctionCollection.functions[functionName];
     if (!definition) {
-        throw new Error(`No binding "${bindingName}" in collection "${bindingCollection.name}". Available: ${bindingNames(bindingCollection)}`);
-    }
-    const callbackKey = `${bindingCollection.name}:${bindingName}`;
-    const permissionMode = bindingPermissionMode(context.permissions, callbackKey);
-    if (permissionMode !== "allow") {
-        throw new Error(`EACCES: blocked by binding.invoke policy for ${callbackKey}`);
+        throw new Error(`No host function "${functionName}" in collection "${hostFunctionCollection.name}". Available: ${hostFunctionNames(hostFunctionCollection)}`);
     }
-    const input = await parseBindingInput(definition, args, cwd, context.readFile);
-    return executeBinding(definition, callbackKey, input);
+    // The sidecar checks the `hostFunction` permission scope for registry commands
+    // before forwarding them, the same as for collection commands.
+    const callbackKey = `${hostFunctionCollection.name}:${functionName}`;
+    const input = await parseHostFunctionInput(definition, args, cwd, context.readFile);
+    return executeHostFunction(definition, callbackKey, input);
 }
-async function executeBinding(definition, callbackKey, input) {
+async function executeHostFunction(definition, callbackKey, input) {
     const parsed = definition.inputSchema.safeParse(input);
     if (!parsed.success) {
         throw new Error(validationMessage(parsed.error));
@@ -1233,11 +1225,11 @@ async function executeBinding(definition, callbackKey, input) {
             if (definition.timeout === undefined) {
                 return;
             }
-            setTimeout(() => reject(new Error(`Binding "${callbackKey}" timed out after ${definition.timeout}ms`)), definition.timeout);
+            setTimeout(() => reject(new Error(`Host function "${callbackKey}" timed out after ${definition.timeout}ms`)), definition.timeout);
         }),
     ]);
 }
-async function parseBindingInput(definition, args, cwd, readFile) {
+async function parseHostFunctionInput(definition, args, cwd, readFile) {
     if (args[0] === "--json") {
         const value = args[1];
         if (value === undefined) {
@@ -1256,9 +1248,9 @@ async function parseBindingInput(definition, args, cwd, readFile) {
         const text = new TextDecoder().decode(await readFile(guestPath));
         return JSON.parse(text);
     }
-    return parseBindingArgv(bindingToSidecarDefinition(definition).inputSchema, args);
+    return parseHostFunctionArgv(hostFunctionToSidecarDefinition(definition).inputSchema, args);
 }
-function parseBindingArgv(schema, argv) {
+function parseHostFunctionArgv(schema, argv) {
     const schemaObject = asRecord(schema);
     const properties = asRecord(schemaObject.properties);
     const required = Array.isArray(schemaObject.required)
@@ -1330,88 +1322,53 @@ function parseBindingArgv(schema, argv) {
     }
     return input;
 }
-function listBindingsPayload(bindings) {
+function listHostFunctionsPayload(hostFunctions) {
     return {
-        bindings: bindings.map((bindingCollection) => ({
-            name: bindingCollection.name,
-            description: bindingCollection.description,
-            bindings: Object.keys(bindingCollection.bindings),
+        hostFunctions: hostFunctions.map((hostFunctionCollection) => ({
+            name: hostFunctionCollection.name,
+            functions: Object.keys(hostFunctionCollection.functions),
         })),
     };
 }
-function describeBindingsPayload(bindings, collectionName) {
-    const bindingCollection = bindings.find((collection) => collection.name === collectionName);
-    if (!bindingCollection) {
-        throw new Error(`No binding collection "${collectionName}". Available: ${bindingsNames(bindings)}`);
+function describeHostFunctionsPayload(hostFunctions, collectionName) {
+    const hostFunctionCollection = hostFunctions.find((collection) => collection.name === collectionName);
+    if (!hostFunctionCollection) {
+        throw new Error(`No host function collection "${collectionName}". Available: ${hostFunctionsNames(hostFunctions)}`);
     }
     return {
-        name: bindingCollection.name,
-        description: bindingCollection.description,
-        bindings: Object.fromEntries(Object.entries(bindingCollection.bindings).map(([bindingName, definition]) => [
-            bindingName,
+        name: hostFunctionCollection.name,
+        functions: Object.fromEntries(Object.entries(hostFunctionCollection.functions).map(([functionName, definition]) => [
+            functionName,
             {
-                description: definition.description,
-                flags: describeBindingFlags(bindingToSidecarDefinition(definition).inputSchema),
+                description: hostFunctionDescription(definition),
+                flags: describeHostFunctionFlags(hostFunctionToSidecarDefinition(definition).inputSchema),
             },
         ])),
     };
 }
-function describeBindingPayload(bindingCollection, bindingName) {
-    const definition = bindingCollection.bindings[bindingName];
+function describeHostFunctionPayload(hostFunctionCollection, functionName) {
+    const definition = hostFunctionCollection.functions[functionName];
     if (!definition) {
-        throw new Error(`No binding "${bindingName}" in collection "${bindingCollection.name}". Available: ${bindingNames(bindingCollection)}`);
+        throw new Error(`No host function "${functionName}" in collection "${hostFunctionCollection.name}". Available: ${hostFunctionNames(hostFunctionCollection)}`);
     }
     return {
-        collection: bindingCollection.name,
-        binding: bindingName,
-        description: definition.description,
-        flags: describeBindingFlags(bindingToSidecarDefinition(definition).inputSchema),
+        collection: hostFunctionCollection.name,
+        function: functionName,
+        description: hostFunctionDescription(definition),
+        flags: describeHostFunctionFlags(hostFunctionToSidecarDefinition(definition).inputSchema),
         examples: definition.examples?.map((example) => ({
             description: example.description,
             input: example.input,
         })) ?? [],
     };
 }
-function bindingPermissionMode(permissions, callbackKey) {
-    const scope = permissions.binding;
-    if (!scope) {
-        return "deny";
-    }
-    if (typeof scope === "string") {
-        return scope;
-    }
-    let mode = scope.default ?? "deny";
-    for (const rule of scope.rules) {
-        const operations = rule.operations ?? ["*"];
-        const patterns = rule.patterns ?? ["**"];
-        if (operations.some((operation) => operation === "*" || operation === "invoke") &&
-            patterns.some((pattern) => permissionPatternMatches(pattern, callbackKey))) {
-            mode = rule.mode;
-        }
-    }
-    return mode;
-}
-function permissionPatternMatches(pattern, value) {
-    if (pattern === "*" || pattern === "**" || pattern === value) {
-        return true;
-    }
-    const parts = pattern.split(/(\*\*|\*)/u);
-    const source = parts
-        .map((part) => {
-        if (part === "**")
-            return ".*";
-        if (part === "*")
-            return "[^:]*";
-        return part.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
-    })
-        .join("");
-    return new RegExp(`^${source}$`).test(value);
+function hostFunctionsNames(hostFunctions) {
+    return hostFunctions
+        .map((hostFunctionCollection) => hostFunctionCollection.name)
+        .join(", ");
 }
-function bindingsNames(bindings) {
-    return bindings.map((bindingCollection) => bindingCollection.name).join(", ");
-}
-function bindingNames(bindingCollection) {
-    return Object.keys(bindingCollection.bindings).join(", ");
+function hostFunctionNames(hostFunctionCollection) {
+    return Object.keys(hostFunctionCollection.functions).join(", ");
 }
 function isHelpFlag(value) {
     return value === "--help" || value === "-h";
@@ -1420,23 +1377,23 @@ function jsonSchemaType(schema) {
     const schemaObject = asRecord(schema);
     return typeof schemaObject.type === "string" ? schemaObject.type : undefined;
 }
-async function registerBindingsOnSidecar(client, session, vm, bindings) {
-    if (bindings.length === 0) {
+async function registerHostFunctionsOnSidecar(client, session, vm, hostFunctions) {
+    if (hostFunctions.length === 0) {
         return "";
     }
-    for (const bindingCollection of bindings) {
+    for (const hostFunctionCollection of hostFunctions) {
         await client.registerHostCallbacks(session, vm, {
-            name: bindingCollection.name,
-            description: bindingCollection.description,
-            commandAliases: [`agentos-${bindingCollection.name}`],
+            name: hostFunctionCollection.name,
+            description: "",
+            commandAliases: [`agentos-${hostFunctionCollection.name}`],
             registryCommandAliases: ["agentos"],
-            callbacks: Object.fromEntries(Object.entries(bindingCollection.bindings).map(([bindingName, definition]) => [
-                bindingName,
-                bindingToSidecarDefinition(definition),
+            callbacks: Object.fromEntries(Object.entries(hostFunctionCollection.functions).map(([functionName, definition]) => [
+                functionName,
+                hostFunctionToSidecarDefinition(definition),
             ])),
         });
     }
-    return buildBindingReference(bindings);
+    return buildHostFunctionReference(hostFunctions);
 }
 function executionIdentity(options) {
     return {
@@ -1654,9 +1611,8 @@ export class AgentOs {
     _acpTerminalCounter = 0;
     _softwareRoots;
     _cronManager;
-    _bindings = [];
-    _bindingReference = "";
-    _permissions = allowAll;
+    _hostFunctions = [];
+    _hostFunctionReference = "";
     _hostMounts;
     _env;
     _rootFilesystem;
@@ -1811,8 +1767,11 @@ export class AgentOs {
     static async getSharedSidecar(options = {}) {
         return getSharedAgentOsSidecarInternal(options);
     }
-    static async create(options) {
-        options = parseAgentOsOptions(options);
+    static async create(callerOptions) {
+        // The generic exists only so each `execute` infers its input from its own
+        // `inputSchema`. Past this point the concrete schemas carry no meaning, so
+        // the rest of `create()` works with the plain option type.
+        let options = parseAgentOsOptions(callerOptions);
         // Default software is FULLY DYNAMIC: this package's own NON-agent
         // @agentos-software/* dependencies (e.g. common), each default-exporting
         // its registry-built descriptor. Agent packages are NOT projected here —
@@ -1847,27 +1806,29 @@ export class AgentOs {
         // sidecar owns agent resolution, agent enumeration, and agent snapshot
         // bundle loading from the projected package dirs.
         const localMounts = await resolveCompatLocalMounts(options?.mounts);
-        if (options?.bindings && options.bindings.length > 0) {
-            validateBindings(options.bindings);
-        }
+        // Keys become command names, so resolve and check them before anything
+        // else in `create()` allocates a sidecar or a sandbox.
+        const resolvedHostFunctions = options?.hostFunctions
+            ? resolveHostFunctions(options.hostFunctions)
+            : [];
         // Resolve the sidecar handle before starting an external sandbox so option
         // validation failures cannot leak provider resources.
         const sidecar = resolveAgentOsSidecar(options?.sidecar);
         options = await resolveSandboxOptions(options);
         const sandboxDisposeHooks = getSandboxDisposeHooks(options);
-        const bindings = options.bindings;
+        const hostFunctions = resolvedHostFunctions;
         const createVmAdmin = async () => {
             // The `/opt/agentos` projection is built by the sidecar from the
             // forwarded `packages` (it owns the staging dir + read-only mount, and
             // runtime `linkSoftware` appends to that live dir). The client no longer
             // stages packages host-side.
-            const bindingBootstrapCommands = collectBindingBootstrapCommands(bindings ?? []);
+            const hostFunctionBootstrapCommands = collectHostFunctionBootstrapCommands(hostFunctions);
             const bootstrapCommands = [
                 ...RUNTIME_BOOTSTRAP_COMMANDS,
-                ...bindingBootstrapCommands,
+                ...hostFunctionBootstrapCommands,
             ];
             const bootstrapLower = createKernelBootstrapLower(options?.rootFilesystem);
-            let bindingReference = "";
+            let hostFunctionReference = "";
             let rootBridge = null;
             let kernel = null;
             let client = null;
@@ -1884,7 +1845,7 @@ export class AgentOs {
                 const env = getBaseEnvironment();
                 // Guest command paths. The sidecar owns the `/opt/agentos` projection and
                 // reports the exact projected package commands after `configureVm`.
-                // Binding-shim commands are added below.
+                // HostFunction-shim commands are added below.
                 const commandGuestPaths = new Map();
                 const { sidecarMounts, hostMounts, hostPathMappings } = collectSidecarMountPlan({
                     mounts: options?.mounts,
@@ -1895,11 +1856,7 @@ export class AgentOs {
                 client = shared.client;
                 const session = shared.session;
                 nativeSession = session;
-                const hostPermissions = options?.permissions ?? {
-                    ...allowAll,
-                    binding: "allow",
-                };
-                const sidecarPermissions = serializePermissionsForSidecar(hostPermissions);
+                const sidecarPermissions = serializePermissionsForSidecar(options?.permissions);
                 const createVmConfig = {
                     env,
                     database: options?.database,
@@ -1960,16 +1917,16 @@ export class AgentOs {
                     loopbackExemptPorts: options?.loopbackExemptPorts,
                     packages: sidecarPackages,
                     packagesMountAt: OPT_AGENTOS_ROOT,
-                    bindingShimCommands: bindingBootstrapCommands,
+                    hostFunctionShimCommands: hostFunctionBootstrapCommands,
                 });
                 for (const command of configuredVm.projectedCommands) {
                     commandGuestPaths.set(command.name, command.guestPath);
                 }
-                if (bindings && bindings.length > 0) {
-                    bindingReference = await registerBindingsOnSidecar(client, session, nativeVm, bindings);
+                if (hostFunctions.length > 0) {
+                    hostFunctionReference = await registerHostFunctionsOnSidecar(client, session, nativeVm, hostFunctions);
                     commandGuestPaths.set("agentos", "/bin/agentos");
-                    for (const bindingCollection of bindings) {
-                        commandGuestPaths.set(`agentos-${bindingCollection.name}`, `/bin/agentos-${bindingCollection.name}`);
+                    for (const hostFunctionCollection of hostFunctions) {
+                        commandGuestPaths.set(`agentos-${hostFunctionCollection.name}`, `/bin/agentos-${hostFunctionCollection.name}`);
                     }
                 }
                 rootBridge = new NativeSidecarKernelProxy({
@@ -1985,10 +1942,10 @@ export class AgentOs {
                     loopbackExemptPorts: options?.loopbackExemptPorts,
                     // Retained for runtime mount reconfigures: `configure_vm` is
                     // replace-on-write for the whole payload, so post-boot mountFs
-                    // must resend the boot packages and binding shims.
+                    // must resend the boot packages and host-function shims.
                     packages: sidecarPackages,
                     packagesMountAt: OPT_AGENTOS_ROOT,
-                    bindingShimCommands: bindingBootstrapCommands,
+                    hostFunctionShimCommands: hostFunctionBootstrapCommands,
                     commandGuestPaths,
                     onDispose: cleanup,
                     // The native process is owned by the AgentOsSidecar handle and
@@ -2012,10 +1969,9 @@ export class AgentOs {
                     sidecarClient: client,
                     sidecarSession: session,
                     sidecarVm: nativeVm,
-                    permissions: hostPermissions,
                     snapshotRootFilesystem: async (maxBytes) => createSnapshotExport(convertSidecarRootSnapshotEntries(await snapshotClient.snapshotRootFilesystem(session, nativeVm, maxBytes))),
-                    bindings: bindings ?? [],
-                    bindingReference,
+                    hostFunctions,
+                    hostFunctionReference,
                     async dispose() {
                         if (kernel) {
                             const currentKernel = kernel;
@@ -2060,9 +2016,8 @@ export class AgentOs {
             const vmAdmin = sidecarLease.admin;
             const vm = new AgentOs(vmAdmin.kernel, sidecar, [], vmAdmin.hostMounts, vmAdmin.env, vmAdmin.rootView, vmAdmin.sidecarClient, vmAdmin.sidecarSession, vmAdmin.sidecarVm, options?.onAgentStderr ?? defaultAgentStderrHandler, options?.onAgentExit ?? defaultAgentExitHandler, options?.onLimitWarning);
             vm._sidecarLease = sidecarLease;
-            vm._bindings = vmAdmin.bindings;
-            vm._bindingReference = vmAdmin.bindingReference;
-            vm._permissions = vmAdmin.permissions;
+            vm._hostFunctions = vmAdmin.hostFunctions;
+            vm._hostFunctionReference = vmAdmin.hostFunctionReference;
             vm._disposeHooks.push(...sandboxDisposeHooks);
             vm._installSidecarRequestHandler();
             vm._cronManager = new CronManager(vm, options?.scheduleDriver ?? new TimerScheduleDriver());
@@ -3568,7 +3523,7 @@ export class AgentOs {
                     : JSON.stringify(input.mcpServers),
                 permissionPolicy: input.permissionPolicy ?? null,
                 skipOsInstructions: input.skipOsInstructions ?? null,
-                additionalInstructions: combineInstructions(input.additionalInstructions, this._bindingReference) ?? null,
+                additionalInstructions: combineInstructions(input.additionalInstructions, this._hostFunctionReference) ?? null,
             },
         });
         if (response.tag !== "AcpOpenSessionResponse") {
@@ -4089,9 +4044,8 @@ export class AgentOs {
     }
     _installSidecarRequestHandler() {
         const context = {
-            bindings: this._bindings,
-            bindingMap: buildBindingMap(this._bindings),
-            permissions: this._permissions,
+            hostFunctions: this._hostFunctions,
+            hostFunctionMap: buildHostFunctionMap(this._hostFunctions),
             readFile: (path) => this.readFile(path),
         };
         this._sidecarClient.setSidecarRequestHandler((request) => {