@kamilio/wire 0.1.9 → 0.1.11

package/node_modules/toolcraft/dist/mcp.js

@@ -1,31 +1,32 @@
-import { access, lstat, readFile, rename, unlink, writeFile } from "node:fs/promises";
-import { createServer, JSON_RPC_ERROR_CODES, ToolError } from "tiny-stdio-mcp-server";
-import { toJsonSchema } from "toolcraft-schema";
+import "./node-require-shim.js";
+import { createServer, JSON_RPC_ERROR_CODES, ToolError, toContentBlocks } from "tiny-stdio-mcp-server";
+import { cloneDefaultValue, compileJsonSchema, formatIssues, isPlainRecord, nativeJsonSchema, toJsonSchema, unicodeLength, validate } from "toolcraft-schema";
 import { createHttpErrorEnvelope, isHttpErrorLike } from "./api-error-summary.js";
 import { ToolcraftBugError, UserError, assertCommandRequirements, resolveCommandSecrets } from "./index.js";
 import { writeErrorReport } from "./error-report.js";
-import { mergeApprovalsGroup } from "./human-in-loop/approvals-commands.js";
-import { ApprovalDeclinedError, invokeWithHumanInLoop } from "./human-in-loop/index.js";
+import { ApprovalDeclinedError } from "./human-in-loop/types.js";
+import { assertHumanInLoopWired, mergeApprovalsRoot } from "./human-in-loop/wiring.js";
 import { hasMcpProxyGroups, resolveMcpProxies } from "./mcp-proxy.js";
+import { isMCPResult } from "./mcp-result.js";
 import { getExpectedNumberDescription, isValidNumberSchemaValue } from "./number-schema.js";
+import { validateAppliedDefault } from "./applied-default.js";
 import { findEntrypointPackageMetadata } from "./package-metadata.js";
 import { filterSchemaForScope } from "./schema-scope.js";
+import { validateCasedSchemaMembers } from "./schema-member-names.js";
 import { enableSourceMaps } from "./stack-trim.js";
 import { suggest } from "./suggest.js";
 import { throwValidationErrors } from "./validation-errors.js";
+import { resolveDiscriminatedBranch } from "./discriminator.js";
+import { validateUnionSchema } from "./union-validation.js";
 import { createRuntimeLogger } from "./runtime-logging.js";
-const RESERVED_SERVICE_NAMES = new Set([
-    "params",
-    "secrets",
-    "fetch",
-    "fs",
-    "env",
-    "diagnostics",
-    "progress",
-    "runtimeOptions",
-    "root"
-]);
-const RESERVED_SERVICE_NAMES_MESSAGE = "Available reserved names: params, secrets, fetch, fs, env, diagnostics, progress, runtimeOptions, root.";
+import { createEnv, createFs, validateServices } from "./runtime/io.js";
+import { createManagedStream } from "./stream.js";
+export const MCP_STREAM_METHODS = {
+    list: "toolcraft/streams/list",
+    subscribe: "toolcraft/streams/subscribe",
+    unsubscribe: "toolcraft/streams/unsubscribe",
+    notification: "notifications/toolcraft/stream"
+};
 function normalizeRoots(roots) {
     if (!Array.isArray(roots)) {
         return roots;
@@ -90,75 +91,80 @@ function unwrapOptional(schema) {
 function isOptional(schema) {
     return schema.kind === "optional";
 }
-function isPlainObject(value) {
+function isObjectRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function createFs() {
-    return {
-        readFile: async (path, encoding = "utf8") => readFile(path, { encoding }),
-        writeFile: async (path, contents, options) => {
-            await writeFile(path, contents, options);
-        },
-        exists: async (path) => {
-            try {
-                await access(path);
-                return true;
-            }
-            catch {
-                return false;
-            }
-        },
-        lstat: async (path) => lstat(path),
-        rename: async (fromPath, toPath) => rename(fromPath, toPath),
-        unlink: async (path) => unlink(path)
-    };
-}
-function createEnv(values = process.env) {
-    return {
-        get(key) {
-            return values[key];
-        }
-    };
-}
-function validateServices(services) {
-    for (const name of Object.keys(services)) {
-        if (RESERVED_SERVICE_NAMES.has(name)) {
-            throw new Error(`Service name "${name}" is reserved. Choose a different name. ${RESERVED_SERVICE_NAMES_MESSAGE}`);
-        }
-    }
-}
 function formatAvailableList(values) {
     return `Available: ${[...values].sort().join(", ")}.`;
 }
-function applySchemaCasing(schema, casing) {
-    const oneOf = schema.oneOf?.map((child) => applySchemaCasing(child, casing));
-    const additionalProperties = typeof schema.additionalProperties === "object" && schema.additionalProperties !== null
-        ? applySchemaCasing(schema.additionalProperties, casing)
+function applySchemaCasing(source, casing, direction = "output", schema = toJsonSchema(source)) {
+    const canonical = unwrapOptional(source);
+    if (canonical[nativeJsonSchema] !== undefined)
+        return schema;
+    const branches = canonical.kind === "oneOf"
+        ? Object.values(canonical.branches)
+        : canonical.kind === "union" ? canonical.branches : [];
+    const oneOf = schema.oneOf?.map((child, index) => {
+        const branch = branches[index];
+        if (branch === undefined)
+            return child;
+        const converted = applySchemaCasing(branch, casing, direction, child);
+        if (canonical.kind === "oneOf" && child.default !== undefined) {
+            converted.default = serializeResultValue(canonical, cloneDefaultValue(child.default), casing, "default", []);
+            if (!validate({ kind: "json" }, converted.default).ok)
+                delete converted.default;
+        }
+        return converted;
+    });
+    const additionalProperties = canonical.kind === "record"
+        ? applySchemaCasing(canonical.value, casing, direction, schema.additionalProperties)
         : schema.additionalProperties;
-    if (schema.type !== "object" || schema.properties === undefined) {
-        if (schema.type === "array" && schema.items !== undefined) {
+    const metadata = { ...schema };
+    if (schema.default !== undefined) {
+        metadata.default = serializeResultValue(canonical, cloneDefaultValue(canonical.default), casing, "default", []);
+        if (!validate({ kind: "json" }, metadata.default).ok)
+            delete metadata.default;
+    }
+    if (canonical.kind !== "object") {
+        if (canonical.kind === "array") {
             return {
-                ...schema,
+                ...metadata,
                 ...(additionalProperties === undefined ? {} : { additionalProperties }),
-                items: applySchemaCasing(schema.items, casing),
+                items: applySchemaCasing(canonical.item, casing, direction, schema.items),
                 ...(oneOf === undefined ? {} : { oneOf })
             };
         }
         return {
-            ...schema,
+            ...metadata,
             ...(additionalProperties === undefined ? {} : { additionalProperties }),
             ...(oneOf === undefined ? {} : { oneOf })
         };
     }
-    const properties = Object.fromEntries(Object.entries(schema.properties).map(([key, value]) => [
+    const properties = Object.fromEntries(Object.entries(schema.properties ?? {}).map(([key, value]) => [
         formatSegment(key, casing),
-        applySchemaCasing(value, casing)
+        Object.prototype.hasOwnProperty.call(canonical.shape, key)
+            ? applySchemaCasing(canonical.shape[key], casing, direction, value)
+            : value
     ]));
-    const required = schema.required?.map((key) => formatSegment(key, casing));
+    const required = schema.required
+        ?.filter((key) => direction === "output"
+        || !Object.hasOwn(canonical.shape, key)
+        || unwrapOptional(canonical.shape[key]).default === undefined)
+        .map((key) => formatSegment(key, casing));
+    const aliasConditions = direction === "input" && canonical.additionalProperties === true
+        ? Object.entries(canonical.shape).flatMap(([key, child]) => {
+            const childSchema = child;
+            const callerKey = formatSegment(key, casing);
+            return callerKey !== key && isOptional(childSchema) && unwrapOptional(childSchema).default === undefined
+                ? [{ anyOf: [{ not: { required: [key] } }, { required: [callerKey] }] }]
+                : [];
+        })
+        : [];
     return {
-        ...schema,
+        ...metadata,
         ...(additionalProperties === undefined ? {} : { additionalProperties }),
         properties,
+        ...(aliasConditions.length === 0 ? {} : { allOf: [...(schema.allOf ?? []), ...aliasConditions] }),
         ...(required === undefined ? {} : { required }),
         ...(oneOf === undefined ? {} : { oneOf })
     };
@@ -168,7 +174,7 @@ function collectParamSummaries(schema, casing, path = [], inheritedOptional = fa
     for (const [key, rawChildSchema] of Object.entries(schema.shape)) {
         const childSchema = unwrapOptional(rawChildSchema);
         const nextPath = [...path, formatSegment(key, casing)];
-        const optional = inheritedOptional || isOptional(rawChildSchema);
+        const optional = inheritedOptional || isOptional(rawChildSchema) || childSchema.default !== undefined;
         if (childSchema.kind === "object") {
             summaries.push(...collectParamSummaries(childSchema, casing, nextPath, optional));
             continue;
@@ -215,21 +221,6 @@ function matchesAllowlist(toolName, allowlist) {
 function formatToolName(path) {
     return path.map((segment) => formatSegment(segment, "snake")).join("__");
 }
-function validateUniqueMCPParameterFields(schema, casing) {
-    const sourceKeysByField = new Map();
-    for (const [key, rawChildSchema] of Object.entries(schema.shape)) {
-        const field = formatSegment(key, casing);
-        const existingKey = sourceKeysByField.get(field);
-        if (existingKey !== undefined) {
-            throw new UserError(`Parameters "${existingKey}" and "${key}" use conflicting MCP field "${field}".`);
-        }
-        sourceKeysByField.set(field, key);
-        const childSchema = unwrapOptional(rawChildSchema);
-        if (childSchema.kind === "object") {
-            validateUniqueMCPParameterFields(childSchema, casing);
-        }
-    }
-}
 function enumerateTools(root, casing, allowlist, omitRootToolNamePrefix) {
     const tools = [];
     const commandPathsByToolName = new Map();
@@ -246,9 +237,12 @@ function enumerateTools(root, casing, allowlist, omitRootToolNamePrefix) {
             if (params === undefined || params.kind !== "object") {
                 throw new ToolcraftBugError(`command "${name}" must define an object params schema for MCP.`);
             }
-            validateUniqueMCPParameterFields(params, casing);
+            validateCasedSchemaMembers(params, (key) => formatSegment(key, casing), "MCP field");
             if (node.result !== undefined) {
-                validateUniqueMCPParameterFields(node.result, casing);
+                validateCasedSchemaMembers(node.result, (key) => formatSegment(key, casing), "MCP field");
+            }
+            if (node.stream !== undefined) {
+                validateCasedSchemaMembers(node.stream.event, (key) => formatSegment(key, casing), "MCP field");
             }
             const resolvedCommandPath = [...commandPath, node.name].join(".");
             const existingPath = commandPathsByToolName.get(name);
@@ -257,15 +251,18 @@ function enumerateTools(root, casing, allowlist, omitRootToolNamePrefix) {
             }
             commandPathsByToolName.set(name, resolvedCommandPath);
             tools.push({
+                ...(node.annotations === undefined ? {} : { annotations: { ...node.annotations } }),
                 command: node,
                 commandPath: resolvedCommandPath,
                 name,
+                ...(node.title === undefined ? {} : { title: node.title }),
                 description: buildToolDescription(node.description, params, node.examples, node.name, casing),
-                inputSchema: applySchemaCasing(toJsonSchema(params), casing),
+                inputSchema: applySchemaCasing(params, casing, "input"),
+                paramsSchema: params,
                 ...(node.result === undefined
                     ? {}
                     : {
-                        outputSchema: applySchemaCasing(toJsonSchema(node.result), casing),
+                        outputSchema: applySchemaCasing(node.result, casing),
                         resultSchema: node.result
                     })
             });
@@ -297,7 +294,7 @@ function renderPendingApproval(pending) {
         content: [
             {
                 type: "text",
-                text: `Queued for human approval (id: ${pending.approvalId}). Track with \`toolcraft approvals show ${pending.approvalId}\`.`
+                text: `Queued for human approval (id: ${pending.approvalId}). Track with \`toolcraft approvals show --approval-id ${pending.approvalId}\`.`
             },
             {
                 type: "text",
@@ -343,15 +340,31 @@ function describeReceived(value) {
     if (Array.isArray(value))
         return `array(${value.length})`;
     if (typeof value === "object")
-        return "object";
+        return isPlainRecord(value) ? "object" : "non-plain object";
     if (typeof value === "string") {
         const s = value.length > 40 ? `${value.slice(0, 40)}…` : value;
         return `${JSON.stringify(s)}`;
     }
     return JSON.stringify(value);
 }
+function validateNativeMCPValue(schema, value, label, errors) {
+    const result = validate(schema, value);
+    if (!result.ok) {
+        errors.push(...result.issues.map((issue) => ({
+            path: [label, ...issue.path].filter((part) => part !== "").join("."),
+            message: formatIssues([issue])
+        })));
+    }
+    return value;
+}
 function validateSchemaValue(schema, value, casing, label, errors) {
     const unwrappedSchema = unwrapOptional(schema);
+    if (isOptional(schema) && value === undefined) {
+        return validateAppliedDefault(unwrappedSchema, label, errors);
+    }
+    if (unwrappedSchema[nativeJsonSchema] !== undefined) {
+        return validateNativeMCPValue(unwrappedSchema, value, label, errors);
+    }
     if (value === null && unwrappedSchema.nullable === true) {
         return null;
     }
@@ -400,10 +413,15 @@ function validateSchemaValue(schema, value, casing, label, errors) {
             return value.map((item, index) => validateSchemaValue(unwrappedSchema.item, item, casing, `${label}[${index}]`, errors));
         case "object":
             return validateObjectSchema(unwrappedSchema, value, casing, label, errors);
-        case "json":
+        case "json": {
+            const validation = validate(unwrappedSchema, value);
+            if (!validation.ok) {
+                errors.push(...validation.issues.map((issue) => ({ path: label, message: issue.message })));
+            }
             return value;
+        }
         case "record": {
-            if (!isPlainObject(value)) {
+            if (!isPlainRecord(value)) {
                 errors.push({
                     path: label,
                     message: `Invalid value for "${label}". Expected an object, got ${describeReceived(value)}.`
@@ -416,45 +434,32 @@ function validateSchemaValue(schema, value, casing, label, errors) {
             ]));
         }
         case "oneOf": {
-            if (!isPlainObject(value)) {
-                return value;
-            }
-            const discriminatorKey = formatSegment(unwrappedSchema.discriminator, casing);
-            const discriminator = value[discriminatorKey];
-            const branch = typeof discriminator === "string" ? unwrappedSchema.branches[discriminator] : undefined;
-            if (branch === undefined) {
+            const resolved = resolveDiscriminatedBranch(unwrappedSchema, value, formatSegment(unwrappedSchema.discriminator, casing), label, errors);
+            if (resolved === undefined) {
                 return value;
             }
-            const { [discriminatorKey]: ignoredDiscriminator, ...branchValue } = value;
-            void ignoredDiscriminator;
             return {
-                [unwrappedSchema.discriminator]: discriminator,
-                ...validateObjectSchema(branch, branchValue, casing, label, errors)
+                ...validateObjectSchema(resolved.branch, resolved.value, casing, label, errors),
+                [unwrappedSchema.discriminator]: resolved.discriminator
             };
         }
         case "union": {
-            if (!isPlainObject(value)) {
-                return value;
-            }
-            const branch = unwrappedSchema.branches.find((candidate) => Object.keys(candidate.shape).every((key) => candidate.shape[key]?.kind === "optional" ||
-                Object.prototype.hasOwnProperty.call(value, formatSegment(key, casing))));
-            return branch === undefined
-                ? value
-                : validateObjectSchema(branch, value, casing, label, errors);
+            return validateUnionSchema(unwrappedSchema, value, label, errors, (branch, branchErrors) => validateObjectSchema(branch, value, casing, label, branchErrors));
         }
     }
 }
 function validateStringConstraints(schema, value, label, errors) {
-    if (schema.minLength !== undefined && value.length < schema.minLength) {
+    const length = unicodeLength(value);
+    if (schema.minLength !== undefined && length < schema.minLength) {
         errors.push({
             path: label,
-            message: `Invalid value for "${label}". Expected a string with length at least ${schema.minLength}, got string with length ${value.length}.`
+            message: `Invalid value for "${label}". Expected a string with length at least ${schema.minLength}, got string with length ${length}.`
         });
     }
-    if (schema.maxLength !== undefined && value.length > schema.maxLength) {
+    if (schema.maxLength !== undefined && length > schema.maxLength) {
         errors.push({
             path: label,
-            message: `Invalid value for "${label}". Expected a string with length at most ${schema.maxLength}, got string with length ${value.length}.`
+            message: `Invalid value for "${label}". Expected a string with length at most ${schema.maxLength}, got string with length ${length}.`
         });
     }
     if (schema.pattern !== undefined && !new RegExp(schema.pattern).test(value)) {
@@ -479,7 +484,10 @@ function validateArrayConstraints(schema, value, label, errors) {
     }
 }
 function validateObjectSchema(schema, value, casing, label, errors) {
-    if (!isPlainObject(value)) {
+    if (schema[nativeJsonSchema] !== undefined) {
+        return validateNativeMCPValue(schema, value, label, errors);
+    }
+    if (!isPlainRecord(value)) {
         errors.push({
             path: label,
             message: `Invalid value for "${label}". Expected an object, got ${describeReceived(value)}.`
@@ -513,10 +521,10 @@ function validateObjectSchema(schema, value, casing, label, errors) {
         const childSchema = unwrapOptional(rawChildSchema);
         const hasValue = Object.prototype.hasOwnProperty.call(value, inputKey);
         const fieldLabel = label.length === 0 ? inputKey : `${label}.${inputKey}`;
-        if (!hasValue) {
+        if (!hasValue || (isOptional(rawChildSchema) && value[inputKey] === undefined)) {
             if (childSchema.default !== undefined) {
                 Object.defineProperty(result, outputKey, {
-                    value: childSchema.default,
+                    value: validateAppliedDefault(childSchema, fieldLabel, errors),
                     enumerable: true,
                     configurable: true,
                     writable: true
@@ -524,6 +532,13 @@ function validateObjectSchema(schema, value, casing, label, errors) {
                 continue;
             }
             if (isOptional(rawChildSchema)) {
+                if (inputKey !== outputKey && Object.hasOwn(result, outputKey)) {
+                    const aliasLabel = label.length === 0 ? outputKey : `${label}.${outputKey}`;
+                    errors.push({
+                        path: aliasLabel,
+                        message: `Unexpected parameter "${aliasLabel}". Use "${fieldLabel}" for this declared parameter.`
+                    });
+                }
                 continue;
             }
             errors.push({ path: fieldLabel, message: `Missing required parameter "${fieldLabel}".` });
@@ -546,6 +561,14 @@ function validateToolArguments(schema, argumentsValue, casing) {
 }
 function serializeResultValue(schema, value, casing, label, errors) {
     const unwrappedSchema = unwrapOptional(schema);
+    if (unwrappedSchema[nativeJsonSchema] !== undefined) {
+        return validateNativeMCPValue(unwrappedSchema, value, label, errors);
+    }
+    if (isOptional(schema) && value === undefined) {
+        return unwrappedSchema.default === undefined
+            ? undefined
+            : serializeResultValue(unwrappedSchema, cloneDefaultValue(unwrappedSchema.default), casing, label, errors);
+    }
     if (value === null && unwrappedSchema.nullable === true) {
         return null;
     }
@@ -560,9 +583,10 @@ function serializeResultValue(schema, value, casing, label, errors) {
                 });
                 return value;
             }
+            validateArrayConstraints(unwrappedSchema, value, label, errors);
             return value.map((item, index) => serializeResultValue(unwrappedSchema.item, item, casing, `${label}[${index}]`, errors));
         case "record":
-            if (!isPlainObject(value)) {
+            if (!isPlainRecord(value)) {
                 errors.push({
                     path: label,
                     message: `Invalid value for "${label}". Expected an object, got ${describeReceived(value)}.`
@@ -574,57 +598,24 @@ function serializeResultValue(schema, value, casing, label, errors) {
                 serializeResultValue(unwrappedSchema.value, item, casing, `${label}.${key}`, errors)
             ]));
         case "oneOf": {
-            if (!isPlainObject(value)) {
-                errors.push({
-                    path: label,
-                    message: `Invalid value for "${label}". Expected an object, got ${describeReceived(value)}.`
-                });
+            const resolved = resolveDiscriminatedBranch(unwrappedSchema, value, unwrappedSchema.discriminator, label, errors);
+            if (resolved === undefined) {
                 return value;
             }
-            const discriminator = value[unwrappedSchema.discriminator];
-            const branch = typeof discriminator === "string" ? unwrappedSchema.branches[discriminator] : undefined;
-            if (branch === undefined) {
-                const branchNames = Object.keys(unwrappedSchema.branches);
-                errors.push({
-                    path: label.length === 0
-                        ? unwrappedSchema.discriminator
-                        : `${label}.${unwrappedSchema.discriminator}`,
-                    message: `Invalid value for "${label.length === 0 ? unwrappedSchema.discriminator : `${label}.${unwrappedSchema.discriminator}`}". Expected one of: ${branchNames.join(", ")}, got ${describeReceived(discriminator)}.`
-                });
-                return value;
-            }
-            const { [unwrappedSchema.discriminator]: ignoredDiscriminator, ...branchValue } = value;
-            void ignoredDiscriminator;
             return {
-                [formatSegment(unwrappedSchema.discriminator, casing)]: discriminator,
-                ...serializeResultObject(branch, branchValue, casing, label, errors)
+                ...serializeResultObject(resolved.branch, resolved.value, casing, label, errors),
+                [formatSegment(unwrappedSchema.discriminator, casing)]: resolved.discriminator
             };
         }
         case "union": {
-            if (!isPlainObject(value)) {
-                errors.push({
-                    path: label,
-                    message: `Invalid value for "${label}". Expected an object, got ${describeReceived(value)}.`
-                });
-                return value;
-            }
-            const branch = unwrappedSchema.branches.find((candidate) => Object.keys(candidate.shape).every((key) => candidate.shape[key]?.kind === "optional" ||
-                Object.prototype.hasOwnProperty.call(value, key)));
-            if (branch === undefined) {
-                errors.push({
-                    path: label,
-                    message: `Invalid value for "${label}". Expected one union branch, got ${describeReceived(value)}.`
-                });
-                return value;
-            }
-            return serializeResultObject(branch, value, casing, label, errors);
+            return validateUnionSchema(unwrappedSchema, value, label, errors, (branch, branchErrors) => serializeResultObject(branch, value, casing, label, branchErrors));
         }
         default:
             return validateSchemaValue(schema, value, casing, label, errors);
     }
 }
 function serializeResultObject(schema, value, casing, label, errors) {
-    if (!isPlainObject(value)) {
+    if (!isPlainRecord(value)) {
         errors.push({
             path: label,
             message: `Invalid value for "${label}". Expected an object, got ${describeReceived(value)}.`
@@ -647,10 +638,10 @@ function serializeResultObject(schema, value, casing, label, errors) {
         const hasValue = Object.prototype.hasOwnProperty.call(value, sourceKey);
         const wireKey = formatSegment(sourceKey, casing);
         const fieldLabel = label.length === 0 ? sourceKey : `${label}.${sourceKey}`;
-        if (!hasValue) {
+        if (!hasValue || (isOptional(rawChildSchema) && value[sourceKey] === undefined)) {
             if (childSchema.default !== undefined) {
                 Object.defineProperty(result, wireKey, {
-                    value: childSchema.default,
+                    value: serializeResultValue(childSchema, cloneDefaultValue(childSchema.default), casing, fieldLabel, errors),
                     enumerable: true,
                     configurable: true,
                     writable: true
@@ -671,8 +662,9 @@ function serializeResultObject(schema, value, casing, label, errors) {
         });
     }
     if (schema.additionalProperties === true) {
+        const wireKeys = new Set([...expectedKeys].map((key) => formatSegment(key, casing)));
         for (const key of Object.keys(value)) {
-            if (!expectedKeys.has(key)) {
+            if (!expectedKeys.has(key) && !wireKeys.has(key)) {
                 Object.defineProperty(result, key, {
                     value: value[key],
                     enumerable: true,
@@ -686,7 +678,7 @@ function serializeResultObject(schema, value, casing, label, errors) {
 }
 function validateCommandResult(schema, value, casing) {
     const errors = [];
-    const result = serializeResultObject(schema, value, casing, "", errors);
+    const result = serializeResultValue(schema, value, casing, "", errors);
     throwResultValidationErrors(errors);
     return result;
 }
@@ -704,35 +696,6 @@ function throwResultValidationErrors(errors) {
     }
     throw new ToolError(JSON_RPC_ERROR_CODES.INTERNAL_ERROR, `${errors.length} result errors:\n${rendered.join("\n")}`);
 }
-function isContentBlock(value) {
-    if (!isPlainObject(value) || typeof value.type !== "string") {
-        return false;
-    }
-    return (value.type === "text" ||
-        value.type === "image" ||
-        value.type === "audio" ||
-        value.type === "resource");
-}
-function toToolContent(result) {
-    if (result === undefined) {
-        return [];
-    }
-    if (Array.isArray(result)) {
-        return result.flatMap((item) => toToolContent(item));
-    }
-    if (typeof result === "string" || typeof result === "number" || typeof result === "boolean") {
-        return [{ type: "text", text: String(result) }];
-    }
-    if (result === null) {
-        return [{ type: "text", text: "null" }];
-    }
-    if (isContentBlock(result)) {
-        return [result];
-    }
-    const fallbackValue = result;
-    const fallbackText = JSON.stringify(fallbackValue);
-    return [{ type: "text", text: fallbackText }];
-}
 function toToolError(error, reportPath) {
     if (error instanceof ToolError) {
         return error;
@@ -752,64 +715,256 @@ function toToolError(error, reportPath) {
     }
     return new ToolError(JSON_RPC_ERROR_CODES.INTERNAL_ERROR, String(error));
 }
-function createResolvedMCPServer(root, options) {
+function withToolErrorMapping(handler) {
+    return async (params, session) => {
+        try {
+            return await handler(params, session);
+        }
+        catch (error) {
+            throw toToolError(error);
+        }
+    };
+}
+function createResolvedMCPServer(root, options, runtime = {}) {
     const casing = options.casing ?? "snake";
     const services = (options.services ?? {});
-    const runtimeOptions = options.humanInLoop ?? {};
+    const humanInLoop = options.humanInLoop;
     const runtimeFetch = options.fetch ?? globalThis.fetch;
     const diagnostics = createRuntimeLogger({
         level: options.logLevel,
         logger: options.logger
     });
-    const servicesWithBuiltIns = {
-        ...services,
-        runtimeOptions,
-        root
-    };
     validateServices(services);
     const tools = enumerateTools(root, casing, options.tools, options.omitRootToolNamePrefix ?? false);
+    const streamTools = tools.filter((tool) => tool.command.stream !== undefined);
+    if (runtime.supportsStreaming === false && streamTools.length > 0) {
+        throw new UserError("MCP streams require a transport with session-scoped notifications. " +
+            `Unsupported streams: ${streamTools.map((tool) => JSON.stringify(tool.name)).join(", ")}. ` +
+            "Use stateful HTTP or stdio, or exclude these streams with the tools option.");
+    }
     const version = resolveMCPVersion(options.version);
-    const server = createServer({
+    const server = runtime.createServer?.({
         name: options.name,
         version,
         validateToolArguments: false
+    }) ??
+        createServer({
+            name: options.name,
+            version,
+            validateToolArguments: false
+        });
+    const subscriptions = new Map();
+    let nextSubscriptionId = 0;
+    server.method(MCP_STREAM_METHODS.list, () => ({
+        streams: streamTools.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            eventSchema: applySchemaCasing(tool.command.stream.event, casing),
+            bufferSize: tool.command.stream.bufferSize
+        }))
+    }));
+    server.method(MCP_STREAM_METHODS.subscribe, withToolErrorMapping(async (request, session) => {
+        const name = typeof request?.name === "string" ? request.name : undefined;
+        const tool = streamTools.find((candidate) => candidate.name === name);
+        if (tool === undefined) {
+            throw new UserError(`Stream not found: ${name ?? ""}`);
+        }
+        const streamDefinition = tool.command.stream;
+        if (streamDefinition === undefined) {
+            throw new ToolcraftBugError(`Command "${tool.commandPath}" is not a stream.`);
+        }
+        const eventSchema = applySchemaCasing(streamDefinition.event, casing);
+        const eventValidator = compileJsonSchema(eventSchema);
+        const argumentsValue = isObjectRecord(request?.arguments) ? request.arguments : {};
+        const secrets = resolveCommandSecrets(tool.command, options.env);
+        const requestServices = await runtime.requestServices?.(runtime.getRequestContext?.());
+        const baseContext = {
+            ...services,
+            ...requestServices,
+            humanInLoop,
+            root,
+            secrets,
+            fetch: runtimeFetch,
+            fs: createFs(options.fs),
+            env: createEnv(options.env),
+            diagnostics,
+            progress(message) {
+                diagnostics.emit({ level: "info", message, category: "progress" });
+            }
+        };
+        await assertCommandRequirements(tool.command, { ...baseContext, params: undefined }, { apiVersion: options.apiVersion, env: options.env });
+        const params = validateToolArguments(tool.paramsSchema, argumentsValue, casing);
+        const subscriptionId = `stream-${++nextSubscriptionId}`;
+        let notificationQueue = Promise.resolve();
+        let notificationFailed = false;
+        const notify = (params) => {
+            notificationQueue = notificationQueue.then(async () => {
+                if (notificationFailed || session.signal.aborted)
+                    return;
+                try {
+                    await session.notify(MCP_STREAM_METHODS.notification, params);
+                }
+                catch (error) {
+                    notificationFailed = true;
+                    subscriptions.delete(subscriptionId);
+                    void stream.cancel(error).catch(() => undefined);
+                    if (!session.signal.aborted) {
+                        diagnostics.emit({
+                            level: "error",
+                            category: "runtime",
+                            message: "MCP stream notification delivery failed.",
+                            data: { subscriptionId, notificationType: params.type }
+                        });
+                    }
+                }
+            }).catch(() => undefined);
+            return notificationQueue;
+        };
+        const stream = createManagedStream({
+            eventSchema: streamDefinition.event,
+            signal: session.signal,
+            onStatus(event) {
+                void notify({
+                    subscriptionId,
+                    type: "status",
+                    status: event
+                });
+            },
+            async create(signal, status) {
+                return await tool.command.handler({
+                    ...baseContext,
+                    params,
+                    signal,
+                    status,
+                    async refreshSecrets() {
+                        return resolveCommandSecrets(tool.command, options.env);
+                    }
+                });
+            }
+        });
+        subscriptions.set(subscriptionId, { signal: session.signal, stream });
+        void (async () => {
+            try {
+                for await (const event of stream) {
+                    const errors = [];
+                    const serialized = serializeResultValue(streamDefinition.event, event, casing, "", errors);
+                    throwResultValidationErrors(errors);
+                    const validation = eventValidator.validate(serialized);
+                    if (!validation.ok) {
+                        throw new ToolError(JSON_RPC_ERROR_CODES.INTERNAL_ERROR, `Invalid stream event: ${formatIssues(validation.issues)}`);
+                    }
+                    await notify({
+                        subscriptionId,
+                        type: "data",
+                        event: serialized
+                    });
+                }
+                if (!session.signal.aborted) {
+                    await notify({
+                        subscriptionId,
+                        type: "end"
+                    });
+                }
+            }
+            catch (error) {
+                if (!session.signal.aborted) {
+                    await notify({
+                        subscriptionId,
+                        type: "error",
+                        error: error instanceof Error ? error.message : String(error)
+                    });
+                }
+            }
+            finally {
+                subscriptions.delete(subscriptionId);
+                await stream.cancel().catch(() => undefined);
+            }
+        })();
+        return {
+            subscriptionId,
+            eventSchema
+        };
+    }));
+    server.method(MCP_STREAM_METHODS.unsubscribe, async (request, session) => {
+        const subscriptionId = typeof request?.subscriptionId === "string" ? request.subscriptionId : undefined;
+        const subscription = subscriptionId === undefined ? undefined : subscriptions.get(subscriptionId);
+        if (subscriptionId === undefined ||
+            subscription === undefined ||
+            subscription.signal !== session.signal) {
+            return { unsubscribed: false };
+        }
+        await subscription.stream.cancel();
+        subscriptions.delete(subscriptionId);
+        return { unsubscribed: true };
     });
-    for (const tool of tools) {
-        const handler = async (argumentsValue) => {
+    for (const tool of tools.filter((candidate) => candidate.command.stream === undefined)) {
+        const handler = async (argumentsValue, transportContext) => {
             let params;
             let secrets;
             try {
-                secrets = resolveCommandSecrets(tool.command);
+                transportContext?.signal.throwIfAborted();
+                secrets = resolveCommandSecrets(tool.command, options.env);
+                const requestServices = await runtime.requestServices?.(transportContext);
+                transportContext?.signal.throwIfAborted();
                 const baseContext = {
-                    ...servicesWithBuiltIns,
+                    ...services,
+                    ...requestServices,
+                    humanInLoop,
+                    root,
                     secrets,
                     fetch: runtimeFetch,
-                    fs: createFs(),
-                    env: createEnv(),
+                    fs: createFs(options.fs),
+                    env: createEnv(options.env),
                     diagnostics,
+                    signal: transportContext?.signal,
                     progress(message) {
                         diagnostics.emit({ level: "info", message, category: "progress" });
                     }
                 };
-                await assertCommandRequirements(tool.command, { ...baseContext, params: undefined });
-                params = validateToolArguments(tool.command.params, argumentsValue, casing);
-                const result = await invokeWithHumanInLoop(tool.command, {
+                await assertCommandRequirements(tool.command, { ...baseContext, params: undefined }, {
+                    apiVersion: options.apiVersion,
+                    env: options.env
+                });
+                transportContext?.signal.throwIfAborted();
+                params = validateToolArguments(tool.paramsSchema, argumentsValue, casing);
+                const handlerContext = {
                     ...baseContext,
                     params
-                }, runtimeOptions, tool.commandPath);
+                };
+                const result = humanInLoop === undefined
+                    ? await tool.command.handler(handlerContext)
+                    : await humanInLoop.invoke(tool.command, handlerContext, tool.commandPath);
                 if (isHumanInLoopPending(result)) {
                     return renderPendingApproval(result);
                 }
+                if (isMCPResult(result) && (result.isError === true || tool.resultSchema === undefined)) {
+                    return result;
+                }
                 if (tool.resultSchema !== undefined) {
-                    const structuredContent = validateCommandResult(tool.resultSchema, result, casing);
+                    let mcpResult = isMCPResult(result) ? result.structuredContent : result;
+                    if (tool.command.mcpResult !== undefined) {
+                        try {
+                            mcpResult = tool.command.mcpResult(result);
+                        }
+                        catch (error) {
+                            throw new ToolError(JSON_RPC_ERROR_CODES.INTERNAL_ERROR, error instanceof Error ? error.message : String(error));
+                        }
+                    }
+                    const structuredContent = validateCommandResult(tool.resultSchema, mcpResult, casing);
+                    if (isMCPResult(result)) {
+                        return { ...result, structuredContent };
+                    }
                     return {
                         content: [{ type: "text", text: JSON.stringify(structuredContent) }],
                         structuredContent
                     };
                 }
-                return toToolContent(result);
+                return toContentBlocks(result);
             }
             catch (error) {
+                if (transportContext?.signal.aborted)
+                    transportContext.signal.throwIfAborted();
                 if (error instanceof ApprovalDeclinedError) {
                     return renderDeclinedApproval(error);
                 }
@@ -826,12 +981,18 @@ function createResolvedMCPServer(root, options) {
                 throw toToolError(error, report?.displayPath);
             }
         };
-        if (tool.outputSchema === undefined) {
-            server.tool(tool.name, tool.description, tool.inputSchema, handler);
-        }
-        else {
-            server.tool(tool.name, tool.description, tool.inputSchema, handler, tool.outputSchema);
-        }
+        server.registerTool({
+            name: tool.name,
+            ...(tool.title === undefined ? {} : { title: tool.title }),
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            ...(tool.outputSchema === undefined
+                ? {}
+                : {
+                    outputSchema: tool.outputSchema
+                }),
+            ...(tool.annotations === undefined ? {} : { annotations: tool.annotations })
+        }, handler);
     }
     return {
         ...server,
@@ -853,7 +1014,10 @@ function createDeferredMCPServer(root, options) {
         serverPromise ??= (async () => {
             await resolveMcpProxies(root, { projectRoot: options.projectRoot });
             return createResolvedMCPServer(root, options);
-        })();
+        })().catch((error) => {
+            serverPromise = undefined;
+            throw error;
+        });
         return serverPromise;
     };
     return new Proxy({
@@ -874,16 +1038,26 @@ function createDeferredMCPServer(root, options) {
 }
 export function createMCPServer(roots, options) {
     const normalizedRoot = normalizeRoots(roots);
-    const root = options.approvals === true ? mergeApprovalsGroup(normalizedRoot) : normalizedRoot;
+    const root = mergeApprovalsRoot(normalizedRoot, options);
+    assertHumanInLoopWired(root, options.humanInLoop);
     if (!hasMcpProxyGroups(root)) {
         return createResolvedMCPServer(root, options);
     }
     return createDeferredMCPServer(root, options);
 }
+/** @internal */
+export async function createMCPServerForTransport(roots, options, runtime) {
+    const normalizedRoot = normalizeRoots(roots);
+    const root = mergeApprovalsRoot(normalizedRoot, options);
+    assertHumanInLoopWired(root, options.humanInLoop);
+    await resolveMcpProxies(root, { projectRoot: options.projectRoot });
+    createResolvedMCPServer(root, options, runtime);
+}
 export async function runMCP(roots, options) {
     enableSourceMaps();
     const normalizedRoot = normalizeRoots(roots);
-    const root = options.approvals === true ? mergeApprovalsGroup(normalizedRoot) : normalizedRoot;
+    const root = mergeApprovalsRoot(normalizedRoot, options);
+    assertHumanInLoopWired(root, options.humanInLoop);
     await resolveMcpProxies(root, { projectRoot: options.projectRoot });
     const server = createResolvedMCPServer(root, options);
     await server.listen();