@abot-ai/runtime 1.0.0 → 1.1.0

package/README.md

@@ -12,6 +12,7 @@ hardcoded defaults.
 
 - Configurable local and hosted model providers
 - Persistent conversations, request events, and replay
+- Optional passive long-term memory across sessions
 - Planning, execution, and review workflows
 - Manifest-based tools and plugins with explicit runtime boundaries
 - Workspace, file, skill, and memory capabilities
@@ -32,6 +33,7 @@ The Web UI supports:
 - streaming messages, current activity, tool progress, and failures
 - steering an active request or queuing the next message
 - editing runtime configuration
+- configuring passive long-term memory with a consumer-selected embedding model
 - inspecting runtime status, logs, and health
 
 The UI is a client of the runtime; persisted sessions, events, and request state
@@ -81,6 +83,16 @@ OpenAI profiles created by `abot init` or `abot add-model` use the recommended
 `execution-agent-v1` execution policy. Existing profiles are preserved unless
 the user explicitly requests replacement.
 
+Passive long-term memory is disabled by default. After configuring a provider,
+choose and probe an embedding model from the Config workspace or CLI:
+
+```bash
+npx abot memory enable --provider <provider-id> --model <embedding-model-id>
+```
+
+See [Passive Long-Term Memory](docs/long-term-memory.md) for its privacy,
+storage, retrieval, and management contracts.
+
 ## Quick Start From Source
 
 From a checkout of this repository:
@@ -199,9 +211,10 @@ Step](docs/configuration.md#calibrating-a-model-by-step).
 
 The distribution includes a curated public plugin catalog for development and
 agent workflows: filesystem operations, command execution, document reading,
-local search, memory, project inspection, JSON inspection, system probing, and
-Web access. Hosts can add plugins under their own runtime root; duplicate plugin
-IDs fail closed.
+local search, explicit memory operations, project inspection, JSON inspection,
+system probing, and Web access. Hosts can add plugins under their own runtime
+root; duplicate plugin IDs fail closed. The explicit memory plugin is separate
+from core-owned passive long-term memory.
 
 The Web plugin exposes two distinct capabilities:
 
@@ -231,6 +244,7 @@ For a deeper view, see [Architecture](docs/architecture.md).
 - [Running Locally](docs/running-locally.md)
 - [Configuration](docs/configuration.md)
 - [Runtime Library](docs/runtime-library.md)
+- [Passive Long-Term Memory](docs/long-term-memory.md)
 - [Plugins](docs/plugins.md)
 - [Troubleshooting](docs/troubleshooting.md)
 

package/dist/scripts/add-runtime-model.js

@@ -2,6 +2,7 @@ import { constants } from "node:fs";
 import { access, mkdir } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
+import { parseRequestRunnerConfig } from "../src/runtime/config/runner/versioned-config.js";
 import { buildModelConfig, buildProviderConfig, isRecord, parseBaseUrl, parseProvider, readJsonObject, resolveRuntimePackageRoot, writeJsonObject, } from "./runtime-setup-files.js";
 import { getAddModelUsage, getMissingInitializationInstruction, getRestartInstruction, } from "./runtime-setup-presentation.js";
 const RUNTIME_CONFIG_FILE = "local/runtime.config.json";
@@ -207,6 +208,9 @@ export async function runAddRuntimeModel(argv = process.argv.slice(2), runOption
         readJsonObject(runnerConfigPath),
         readJsonObject(join(resolveRuntimePackageRoot(import.meta.dirname), MODEL_TEMPLATE_FILE)),
     ]);
+    if (options.setDefault) {
+        parseRequestRunnerConfig(runnerConfig, runnerConfigPath);
+    }
     const merged = mergeRuntimeConfig(runtimeConfig, options);
     const nextRunnerConfig = options.setDefault
         ? selectDefaultProfile(runnerConfig, options.profile)

package/dist/scripts/configure-long-term-memory.d.ts

@@ -0,0 +1,6 @@
+import type { ModelProviderAdapterRegistry } from "../src/model-gateway/index.js";
+import type { RuntimeSetupCommandMode } from "./runtime-setup-presentation.js";
+export declare function runConfigureLongTermMemory(argv?: string[], options?: Readonly<{
+    commandMode?: RuntimeSetupCommandMode;
+    providerAdapters?: ModelProviderAdapterRegistry;
+}>): Promise<void>;

package/dist/scripts/configure-long-term-memory.js

@@ -0,0 +1,139 @@
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { createLocalLongTermMemoryOnboardingService } from "../src/runtime/adapters/long-term-memory/onboarding-service.js";
+import { resolveProviderAdapters } from "../src/model-gateway/server/index.js";
+import { loadDotEnvFile } from "../src/shared/load-dotenv.js";
+export async function runConfigureLongTermMemory(argv = process.argv.slice(2), options = {}) {
+    const commandMode = options.commandMode ?? "source";
+    const input = parseMemoryCommand(argv, commandMode);
+    loadDotEnvFile(join(input.rootDir, ".env"));
+    const providerAdapters = resolveProviderAdapters({
+        providerAdapters: options.providerAdapters,
+    });
+    const service = createLocalLongTermMemoryOnboardingService({
+        rootDir: input.rootDir,
+        providerAdapters,
+        ...(process.env.LLM_RUNTIME_CONFIG_FILE
+            ? { configPath: process.env.LLM_RUNTIME_CONFIG_FILE }
+            : {}),
+    });
+    if (input.command === "status") {
+        printJson(await service.status());
+        return;
+    }
+    if (input.command === "models") {
+        printJson(await service.discover({
+            providerId: requireOption(input, "providerId"),
+        }));
+        return;
+    }
+    if (input.command === "disable") {
+        printJson(await service.disable());
+        return;
+    }
+    printJson(await service.enable({
+        providerId: requireOption(input, "providerId"),
+        model: requireOption(input, "model"),
+        ...(input.profileId ? { profileId: input.profileId } : {}),
+        emitClientEvents: input.emitClientEvents,
+    }));
+}
+function parseMemoryCommand(argv, commandMode) {
+    const [commandValue, ...args] = argv;
+    if (commandValue === "--help" || commandValue === "-h") {
+        printHelp(commandMode);
+        process.exit(0);
+    }
+    const command = parseCommand(commandValue);
+    let rootDir = process.cwd();
+    let providerId;
+    let model;
+    let profileId;
+    let emitClientEvents = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === "--emit-events") {
+            emitClientEvents = true;
+            continue;
+        }
+        const parsed = readNamedArgument(args, index);
+        index = parsed.nextIndex;
+        if (parsed.name === "root")
+            rootDir = resolve(parsed.value);
+        else if (parsed.name === "provider")
+            providerId = parsed.value;
+        else if (parsed.name === "model")
+            model = parsed.value;
+        else if (parsed.name === "profile")
+            profileId = parsed.value;
+        else
+            throw new Error(`unknown argument: --${parsed.name}`);
+    }
+    assertCommandArguments({ command, providerId, model });
+    return {
+        command,
+        rootDir,
+        emitClientEvents,
+        ...(providerId ? { providerId } : {}),
+        ...(model ? { model } : {}),
+        ...(profileId ? { profileId } : {}),
+    };
+}
+function parseCommand(value) {
+    if (["status", "models", "enable", "disable"].includes(value ?? "")) {
+        return value;
+    }
+    throw new Error("memory command must be status, models, enable, or disable");
+}
+function readNamedArgument(args, index) {
+    const argument = args[index] ?? "";
+    if (!argument.startsWith("--")) {
+        throw new Error(`unknown argument: ${argument}`);
+    }
+    const separator = argument.indexOf("=");
+    const name = argument.slice(2, separator > 0 ? separator : undefined);
+    const inlineValue = separator > 0 ? argument.slice(separator + 1) : "";
+    const value = inlineValue || args[index + 1]?.trim() || "";
+    if (!value || value.startsWith("--")) {
+        throw new Error(`--${name} requires a value`);
+    }
+    return { name, value, nextIndex: inlineValue ? index : index + 1 };
+}
+function assertCommandArguments(input) {
+    const needsProvider = input.command === "models" || input.command === "enable";
+    if (needsProvider && !input.providerId) {
+        throw new Error("--provider is required");
+    }
+    if (input.command === "enable" && !input.model) {
+        throw new Error("--model is required");
+    }
+}
+function requireOption(input, key) {
+    const value = input[key];
+    if (!value) {
+        throw new Error(`memory ${key} is required`);
+    }
+    return value;
+}
+function printHelp(commandMode) {
+    const prefix = commandMode === "package" ? "abot memory" : "npm run memory --";
+    console.log([
+        `${prefix} status`,
+        `${prefix} models --provider <provider-id>`,
+        `${prefix} enable --provider <provider-id> --model <model-id> [--profile <profile-id>] [--emit-events]`,
+        `${prefix} disable`,
+        "",
+        "Enable performs a real embedding probe before changing runtime config.",
+        "The provider must already exist under models.providers.",
+    ].join("\n"));
+}
+function printJson(value) {
+    console.log(JSON.stringify(value, null, 2));
+}
+const invokedPath = process.argv[1] ? pathToFileURL(process.argv[1]).href : "";
+if (import.meta.url === invokedPath) {
+    runConfigureLongTermMemory().catch((error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    });
+}

package/dist/scripts/init-runtime.js

@@ -2,7 +2,7 @@ import { constants } from "node:fs";
 import { access, copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
-import { buildModelConfig, buildProviderConfig, isRecord, parseBaseUrl, parseProvider, readJsonObject, resolveRuntimePackageRoot, writeJsonObject, } from "./runtime-setup-files.js";
+import { buildModelConfig, buildProviderConfig, DEFAULT_ROOT_RESPONSE_METHODOLOGY_FILES, isRecord, parseBaseUrl, parseProvider, readJsonObject, resolveRuntimePackageRoot, writeJsonObject, } from "./runtime-setup-files.js";
 import { getInitNextSteps, getInitUsage, } from "./runtime-setup-presentation.js";
 const ENV_FILE = ".env";
 const ENV_EXAMPLE_FILE = "examples/env.example";
@@ -111,6 +111,7 @@ function printHelp(commandMode) {
         "- local/runtime.config.json",
         "- local/request-runner.config.json",
         "- local/models/default.config.json",
+        "- methodologies for root response authoring",
         "- .runtime/compiled",
         "- .runtime/shared/logs",
         "- .runtime/prod and .runtime/dev",
@@ -220,6 +221,14 @@ export async function runInitRuntime(argv = process.argv.slice(2), runOptions =
         targetPath: modelConfigPath,
         force: options.force,
     });
+    const methodologyStatuses = await Promise.all(DEFAULT_ROOT_RESPONSE_METHODOLOGY_FILES.map(async (relativePath) => ({
+        relativePath,
+        status: await writeIfMissing({
+            sourcePath: join(templateRoot, relativePath),
+            targetPath: join(options.rootDir, relativePath),
+            force: options.force,
+        }),
+    })));
     if (configStatus !== "kept") {
         await configureRuntimeProvider(configPath, options.provider, options.baseUrl);
     }
@@ -240,6 +249,7 @@ export async function runInitRuntime(argv = process.argv.slice(2), runOptions =
         `${LOCAL_CONFIG_FILE}: ${configStatus}`,
         `${LOCAL_REQUEST_RUNNER_CONFIG_FILE}: ${requestRunnerConfigStatus}`,
         `${LOCAL_MODEL_CONFIG_FILE}: ${modelConfigStatus}`,
+        ...methodologyStatuses.map(({ relativePath, status }) => `${relativePath}: ${status}`),
         "created runtime directories: .runtime/compiled, .runtime/shared/logs, .runtime/prod, .runtime/dev",
         "",
         ...getInitNextSteps(commandMode),

package/dist/scripts/runtime-setup-files.d.ts

@@ -1,5 +1,6 @@
 export type Provider = string;
 export type JsonObject = Record<string, unknown>;
+export declare const DEFAULT_ROOT_RESPONSE_METHODOLOGY_FILES: readonly string[];
 export declare function resolveRuntimePackageRoot(startDir: string): string;
 export declare function isRecord(value: unknown): value is JsonObject;
 export declare function parseProvider(value: string): Provider;

package/dist/scripts/runtime-setup-files.js

@@ -1,6 +1,10 @@
 import { existsSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
+export const DEFAULT_ROOT_RESPONSE_METHODOLOGY_FILES = Object.freeze([
+    "methodologies/response-ux.md",
+    "methodologies/memory-informed-response.md",
+]);
 export function resolveRuntimePackageRoot(startDir) {
     let current = resolve(startDir);
     while (true) {

package/dist/src/capabilities/normal-invocation/contracts.d.ts

@@ -55,6 +55,7 @@ export type ToolNormalInvocationOperation = Readonly<{
     operationId: string;
     summary: string;
     input: ToolNormalInvocationInput;
+    selectionControlIds?: readonly string[];
     fixedParams?: Readonly<Record<string, ToolNormalInvocationFixedValue>>;
     payload?: ToolNormalInvocationPayload;
     effect: ToolNormalInvocationEffect;

package/dist/src/capabilities/normal-invocation/validator.d.ts

@@ -4,6 +4,11 @@ type ToolNormalInvocationDefinition = Readonly<{
     name: string;
     params: Readonly<Record<string, string>>;
     executionEffect?: "read_only" | "mutating" | "mixed";
+    payloadChannelSpec?: Readonly<{
+        stages?: readonly Readonly<{
+            outputParam: string;
+        }>[];
+    }>;
     runtimePathBindings?: readonly Readonly<{
         operationId: string;
         param: string;

package/dist/src/capabilities/normal-invocation/validator.js

@@ -252,8 +252,8 @@ function parsePayload(toolName, path, raw) {
 }
 function parseOperation(toolName, path, raw) {
     if (!isPlainObject(raw) ||
-        !hasExactKeys(raw, ["operationId", "summary", "input", "effect", "approval"], ["fixedParams", "payload"])) {
-        fail(toolName, path, "operation must contain operationId/summary/input/effect/approval and optional fixedParams/payload");
+        !hasExactKeys(raw, ["operationId", "summary", "input", "effect", "approval"], ["selectionControlIds", "fixedParams", "payload"])) {
+        fail(toolName, path, "operation must contain operationId/summary/input/effect/approval and optional selectionControlIds/fixedParams/payload");
     }
     if (raw.effect !== "read_only" &&
         raw.effect !== "mutating" &&
@@ -264,6 +264,7 @@ function parseOperation(toolName, path, raw) {
         fail(toolName, `${path}.approval`, "expected request_policy or always");
     }
     const input = parseInput(toolName, `${path}.input`, raw.input);
+    const selectionControlIds = parseSelectionControlIds(toolName, `${path}.selectionControlIds`, input, raw.selectionControlIds);
     const fixedParams = parseFixedParams(toolName, `${path}.fixedParams`, raw.fixedParams);
     const payload = parsePayload(toolName, `${path}.payload`, raw.payload);
     const overlaps = new Set(Object.keys(input.properties));
@@ -280,12 +281,35 @@ function parseOperation(toolName, path, raw) {
         operationId: identifier(toolName, `${path}.operationId`, raw.operationId),
         summary: boundedText(toolName, `${path}.summary`, raw.summary, MAX_SUMMARY_LENGTH),
         input,
+        ...(selectionControlIds ? { selectionControlIds } : {}),
         ...(fixedParams ? { fixedParams } : {}),
         ...(payload ? { payload } : {}),
         effect: raw.effect,
         approval: raw.approval,
     });
 }
+function parseSelectionControlIds(toolName, path, input, value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) ||
+        value.length === 0 ||
+        value.length > MAX_PROPERTIES) {
+        fail(toolName, path, `expected a non-empty array of at most ${MAX_PROPERTIES} control identifiers`);
+    }
+    const controlIds = value.map((controlId, index) => identifier(toolName, `${path}.${index}`, controlId));
+    if (new Set(controlIds).size !== controlIds.length) {
+        fail(toolName, path, "expected unique control identifiers");
+    }
+    for (const controlId of controlIds) {
+        if (!Object.hasOwn(input.properties, controlId)) {
+            fail(toolName, path, `unknown input control ${controlId}`);
+        }
+        if (!input.required.includes(controlId)) {
+            fail(toolName, path, `selection control ${controlId} must be required`);
+        }
+    }
+    return Object.freeze(controlIds);
+}
 export function parseToolNormalInvocationContract(toolName, raw) {
     if (raw === undefined)
         return undefined;
@@ -362,6 +386,10 @@ export function parseToolNormalInvocationForDefinition(definition, raw) {
     const contract = parseToolNormalInvocationContract(definition.name, raw);
     if (!contract)
         return undefined;
+    const stagedOutputParams = definition.payloadChannelSpec?.stages &&
+        definition.payloadChannelSpec.stages.length >= 2
+        ? new Set(definition.payloadChannelSpec.stages.map(({ outputParam }) => outputParam))
+        : undefined;
     for (const [bindingIndex, binding] of (definition.runtimePathBindings ?? []).entries()) {
         const operation = contract.operations.find((candidate) => candidate.operationId === binding.operationId);
         const input = operation?.input.properties[binding.param];
@@ -376,6 +404,11 @@ export function parseToolNormalInvocationForDefinition(definition, raw) {
     }
     for (const [operationIndex, operation] of contract.operations.entries()) {
         const operationPath = `normalInvocation.operations.${operationIndex}`;
+        for (const selectionControlId of operation.selectionControlIds ?? []) {
+            if (stagedOutputParams?.has(selectionControlId)) {
+                fail(definition.name, `${operationPath}.selectionControlIds`, `selection control ${selectionControlId} must remain in the effective public input`);
+            }
+        }
         for (const [param, schema] of Object.entries(operation.input.properties)) {
             validateDeclaredParam(definition, `${operationPath}.input.properties.${param}`, param, projectedTypeForSchema(schema));
         }

package/dist/src/capabilities/tool-definition-validator/definition-fields.d.ts

@@ -0,0 +1,7 @@
+import type { ToolCatalogGroup, ToolDefinition, ToolDevelopmentRole, ToolExecutionEffect } from "../tool-types.js";
+export declare function isRoutingCapability(value: unknown): value is ToolDefinition["routingCapability"];
+export declare function isDevelopmentRole(value: unknown): value is ToolDevelopmentRole;
+export declare function isExecutionEffect(value: unknown): value is ToolExecutionEffect;
+export declare function parseToolCatalogGroups(toolName: string, value: unknown): ToolCatalogGroup[];
+export declare function parseParamsByCommand(toolName: string, raw: unknown): ToolDefinition["paramsByCommand"];
+export declare function parseRuntimePathBindings(toolName: string, raw: unknown): ToolDefinition["runtimePathBindings"];

package/dist/src/capabilities/tool-definition-validator/definition-fields.js

@@ -0,0 +1,156 @@
+import { isToolCatalogGroupId } from "../tool-types.js";
+import { isToolDefinitionRecordValue } from "./definition-shape.js";
+const ROUTING_CAPABILITIES = [
+    "filesystem_inspection",
+    "filesystem_mutation",
+    "semantic_lookup",
+    "semantic_mutation",
+    "web_lookup",
+];
+const DEVELOPMENT_ROLES = [
+    "inspect",
+    "establish",
+    "mutate",
+    "verify",
+    "auxiliary",
+];
+const EXECUTION_EFFECTS = [
+    "read_only",
+    "mutating",
+    "mixed",
+];
+export function isRoutingCapability(value) {
+    if (typeof value !== "string")
+        return false;
+    return ROUTING_CAPABILITIES.includes(value);
+}
+export function isDevelopmentRole(value) {
+    if (typeof value !== "string")
+        return false;
+    return DEVELOPMENT_ROLES.includes(value);
+}
+export function isExecutionEffect(value) {
+    if (typeof value !== "string")
+        return false;
+    return EXECUTION_EFFECTS.includes(value);
+}
+export function parseToolCatalogGroups(toolName, value) {
+    if (value === undefined)
+        return ["other"];
+    if (!hasUniqueSupportedToolCatalogGroups(value)) {
+        throw new Error(`Invalid tool definition for ${toolName} (catalogGroups)`);
+    }
+    return [...value];
+}
+function hasUniqueSupportedToolCatalogGroups(value) {
+    if (!Array.isArray(value))
+        return false;
+    if (value.length === 0)
+        return false;
+    if (value.some((group) => !isToolCatalogGroupId(group)))
+        return false;
+    return new Set(value).size === value.length;
+}
+export function parseParamsByCommand(toolName, raw) {
+    if (raw === undefined)
+        return undefined;
+    if (!isToolDefinitionRecordValue(raw)) {
+        throw new Error(`Invalid tool definition for ${toolName} (paramsByCommand)`);
+    }
+    const discriminator = raw.discriminator;
+    const rawVariants = raw.variants;
+    if (typeof discriminator !== "string" || discriminator.trim().length === 0) {
+        throw new Error(`Invalid tool definition for ${toolName} (paramsByCommand.discriminator)`);
+    }
+    if (!isToolDefinitionRecordValue(rawVariants)) {
+        throw new Error(`Invalid tool definition for ${toolName} (paramsByCommand.variants)`);
+    }
+    const variants = {};
+    for (const [variantName, variantParams] of Object.entries(rawVariants)) {
+        variants[variantName] = parseCommandVariantParameters(toolName, variantName, variantParams);
+    }
+    return { discriminator, variants };
+}
+function parseCommandVariantParameters(toolName, variantName, raw) {
+    if (!isToolDefinitionRecordValue(raw)) {
+        throw new Error(`Invalid tool definition for ${toolName} (paramsByCommand.variants.${variantName})`);
+    }
+    const parsed = {};
+    for (const [paramName, paramType] of Object.entries(raw)) {
+        if (typeof paramType !== "string") {
+            throw new Error(`Invalid tool definition for ${toolName} (paramsByCommand.variants.${variantName}.${paramName})`);
+        }
+        parsed[paramName] = paramType;
+    }
+    return parsed;
+}
+export function parseRuntimePathBindings(toolName, raw) {
+    if (raw === undefined)
+        return undefined;
+    if (!Array.isArray(raw) || raw.length === 0 || raw.length > 32) {
+        throw new Error(`Invalid tool definition for ${toolName} (runtimePathBindings)`);
+    }
+    const identities = new Set();
+    return raw.map((value, index) => parseRuntimePathBinding(toolName, value, index, identities));
+}
+function parseRuntimePathBinding(toolName, value, index, identities) {
+    if (!isToolDefinitionRecordValue(value)) {
+        throw invalidRuntimePathBinding(toolName, index);
+    }
+    const keys = Object.keys(value);
+    if (keys.length !== 3 && keys.length !== 4) {
+        throw invalidRuntimePathBinding(toolName, index);
+    }
+    if (!Object.hasOwn(value, "operationId")) {
+        throw invalidRuntimePathBinding(toolName, index);
+    }
+    if (!Object.hasOwn(value, "param")) {
+        throw invalidRuntimePathBinding(toolName, index);
+    }
+    if (!Object.hasOwn(value, "base")) {
+        throw invalidRuntimePathBinding(toolName, index);
+    }
+    if (keys.some((key) => !isRuntimePathBindingKey(key))) {
+        throw invalidRuntimePathBinding(toolName, index);
+    }
+    if (typeof value.operationId !== "string") {
+        throw invalidRuntimePathBinding(toolName, index);
+    }
+    if (value.operationId.trim().length === 0) {
+        throw invalidRuntimePathBinding(toolName, index);
+    }
+    if (typeof value.param !== "string" || value.param.trim().length === 0) {
+        throw invalidRuntimePathBinding(toolName, index);
+    }
+    if (value.base !== "worker_working_directory") {
+        throw invalidRuntimePathBinding(toolName, index);
+    }
+    if (value.default !== undefined && value.default !== ".") {
+        throw invalidRuntimePathBinding(toolName, index);
+    }
+    const operationId = value.operationId.trim();
+    const param = value.param.trim();
+    const identity = `${operationId}\u0000${param}`;
+    if (identities.has(identity)) {
+        throw new Error(`Invalid tool definition for ${toolName} (runtimePathBindings duplicate ${operationId}.${param})`);
+    }
+    identities.add(identity);
+    return Object.freeze({
+        operationId,
+        param,
+        base: "worker_working_directory",
+        ...(value.default === "." ? { default: "." } : {}),
+    });
+}
+function isRuntimePathBindingKey(key) {
+    if (key === "operationId")
+        return true;
+    if (key === "param")
+        return true;
+    if (key === "base")
+        return true;
+    return key === "default";
+}
+function invalidRuntimePathBinding(toolName, index) {
+    return new Error(`Invalid tool definition for ${toolName} (runtimePathBindings.${index})`);
+}

package/dist/src/capabilities/tool-definition-validator/definition-parser.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDefinition } from "../tool-types.js";
+export declare function parseToolDefinition(raw: unknown): ToolDefinition;

package/dist/src/capabilities/tool-definition-validator/definition-parser.js

@@ -0,0 +1,76 @@
+import { isDevelopmentRole, isExecutionEffect, isRoutingCapability, parseParamsByCommand, parseRuntimePathBindings, parseToolCatalogGroups, } from "./definition-fields.js";
+import { parseEventPresentation } from "./event-presentation.js";
+import { parsePayloadChannelSpec } from "./payload-channel-spec.js";
+import { isToolDefinitionRecordValue } from "./definition-shape.js";
+export function parseToolDefinition(raw) {
+    if (!isToolDefinitionRecordValue(raw)) {
+        throw new Error("Invalid tool definition entry (not an object)");
+    }
+    const name = raw.name;
+    const description = raw.description;
+    const routingCapability = raw.routingCapability;
+    const controlsRefinement = raw.controlsRefinement;
+    const catalogGroups = raw.catalogGroups;
+    const executionEffect = raw.executionEffect;
+    const developmentRoles = raw.developmentRoles;
+    const eventPresentation = raw.eventPresentation;
+    const params = raw.params;
+    if (typeof name !== "string" || name.trim().length === 0) {
+        throw new Error("Invalid tool definition entry (name)");
+    }
+    if (description !== undefined && typeof description !== "string") {
+        throw new Error(`Invalid tool definition for ${name} (description)`);
+    }
+    if (!isRoutingCapability(routingCapability)) {
+        throw new Error(`Invalid tool definition for ${name} (routingCapability)`);
+    }
+    if (controlsRefinement !== undefined &&
+        controlsRefinement !== "mechanical_when_complete") {
+        throw new Error(`Invalid tool definition for ${name} (controlsRefinement)`);
+    }
+    if (executionEffect !== undefined && !isExecutionEffect(executionEffect)) {
+        throw new Error(`Invalid tool definition for ${name} (executionEffect)`);
+    }
+    if (!isToolDefinitionRecordValue(params)) {
+        throw new Error(`Invalid tool definition for ${name} (params)`);
+    }
+    if (!hasSupportedDevelopmentRoles(developmentRoles)) {
+        throw new Error(`Invalid tool definition for ${name} (developmentRoles)`);
+    }
+    for (const [paramName, paramType] of Object.entries(params)) {
+        if (typeof paramType !== "string") {
+            throw new Error(`Invalid tool definition for ${name} (param type for ${paramName})`);
+        }
+    }
+    const paramsByCommand = parseParamsByCommand(name, raw.paramsByCommand);
+    const runtimePathBindings = parseRuntimePathBindings(name, raw.runtimePathBindings);
+    const payloadChannelSpec = parsePayloadChannelSpec(name, params, raw.payloadChannelSpec);
+    const parsedEventPresentation = parseEventPresentation(name, eventPresentation);
+    return {
+        name,
+        ...(typeof description === "string" ? { description } : {}),
+        routingCapability,
+        ...(controlsRefinement === "mechanical_when_complete"
+            ? { controlsRefinement }
+            : {}),
+        catalogGroups: parseToolCatalogGroups(name, catalogGroups),
+        ...(executionEffect ? { executionEffect } : {}),
+        ...(Array.isArray(developmentRoles)
+            ? { developmentRoles: [...developmentRoles] }
+            : {}),
+        ...(parsedEventPresentation
+            ? { eventPresentation: parsedEventPresentation }
+            : {}),
+        params: params,
+        ...(paramsByCommand ? { paramsByCommand } : {}),
+        ...(payloadChannelSpec ? { payloadChannelSpec } : {}),
+        ...(runtimePathBindings ? { runtimePathBindings } : {}),
+    };
+}
+function hasSupportedDevelopmentRoles(value) {
+    if (value === undefined)
+        return true;
+    if (!Array.isArray(value))
+        return false;
+    return value.every(isDevelopmentRole);
+}

package/dist/src/capabilities/tool-definition-validator/definition-shape.d.ts

@@ -0,0 +1,7 @@
+import type { ToolPayloadChannelSpec } from "../tool-types.js";
+export declare function isToolDefinitionRecordValue(value: unknown): value is Record<string, unknown>;
+export declare function readToolDefinitionName(raw: unknown): string;
+export declare function createInvalidToolDefinitionError(toolName: string, detail: string): Error;
+export declare function isPayloadContextScope(value: unknown): value is "standard" | "target_only" | "target_with_artifacts";
+export declare function isPayloadTargetContext(value: unknown): value is "bounded" | "full" | "full_numbered";
+export declare function isPayloadResponseFormat(value: unknown): value is NonNullable<ToolPayloadChannelSpec["responseFormat"]>;

package/dist/src/capabilities/tool-definition-validator/definition-shape.js

@@ -0,0 +1,34 @@
+export function isToolDefinitionRecordValue(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+export function readToolDefinitionName(raw) {
+    if (!isToolDefinitionRecordValue(raw)) {
+        throw new Error("Invalid tool definition entry (not an object)");
+    }
+    if (typeof raw.name !== "string" || raw.name.trim().length === 0) {
+        throw new Error("Invalid tool definition entry (name)");
+    }
+    return raw.name;
+}
+export function createInvalidToolDefinitionError(toolName, detail) {
+    return new Error(`Invalid tool definition for ${toolName} (${detail})`);
+}
+export function isPayloadContextScope(value) {
+    if (value === "standard")
+        return true;
+    if (value === "target_only")
+        return true;
+    return value === "target_with_artifacts";
+}
+export function isPayloadTargetContext(value) {
+    if (value === "bounded")
+        return true;
+    if (value === "full")
+        return true;
+    return value === "full_numbered";
+}
+export function isPayloadResponseFormat(value) {
+    if (value === "json")
+        return true;
+    return isToolDefinitionRecordValue(value);
+}