comisai 1.0.34 → 1.0.37

package/node_modules/@comis/scheduler/dist/tasks/task-types.d.ts

@@ -23,40 +23,28 @@ export type TaskStatus = z.infer<typeof TaskStatusSchema>;
  * A task extracted from conversation by the LLM.
  */
 export declare const ExtractedTaskSchema: z.ZodObject<{
-    /** Unique task identifier */
     id: z.ZodString;
-    /** Short title for the task */
     title: z.ZodString;
-    /** Detailed description */
     description: z.ZodDefault<z.ZodString>;
-    /** Optional due date (ISO 8601) */
     dueDate: z.ZodOptional<z.ZodString>;
-    /** Task priority */
     priority: z.ZodEnum<{
         low: "low";
         medium: "medium";
         high: "high";
         critical: "critical";
     }>;
-    /** Source provenance */
     source: z.ZodObject<{
-        /** Session key where task was extracted */
         sessionKey: z.ZodString;
-        /** Message index within the session */
         messageIndex: z.ZodNumber;
-        /** Timestamp when extraction occurred (ms since epoch) */
         extractedAt: z.ZodNumber;
     }, z.core.$strict>;
-    /** Confidence score from the LLM extraction (0-1) */
     confidence: z.ZodNumber;
-    /** Task lifecycle status */
     status: z.ZodDefault<z.ZodEnum<{
         completed: "completed";
         pending: "pending";
         cancelled: "cancelled";
         scheduled: "scheduled";
     }>>;
-    /** Task creation timestamp (ms since epoch) */
     createdAtMs: z.ZodNumber;
 }, z.core.$strict>;
 export type ExtractedTask = z.infer<typeof ExtractedTaskSchema>;
@@ -65,7 +53,6 @@ export type ExtractedTask = z.infer<typeof ExtractedTaskSchema>;
  * Tasks here lack id, createdAtMs, and status (assigned by the system).
  */
 export declare const TaskExtractionResultSchema: z.ZodObject<{
-    /** Extracted tasks (without system-assigned fields) */
     tasks: z.ZodArray<z.ZodObject<{
         priority: z.ZodEnum<{
             low: "low";
@@ -77,16 +64,12 @@ export declare const TaskExtractionResultSchema: z.ZodObject<{
         description: z.ZodDefault<z.ZodString>;
         dueDate: z.ZodOptional<z.ZodString>;
         source: z.ZodObject<{
-            /** Session key where task was extracted */
             sessionKey: z.ZodString;
-            /** Message index within the session */
             messageIndex: z.ZodNumber;
-            /** Timestamp when extraction occurred (ms since epoch) */
             extractedAt: z.ZodNumber;
         }, z.core.$strict>;
         confidence: z.ZodNumber;
     }, z.core.$strict>>;
-    /** Optional reasoning from the LLM about extraction */
     reasoning: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export type TaskExtractionResult = z.infer<typeof TaskExtractionResultSchema>;

package/node_modules/@comis/scheduler/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@comis/scheduler",
   "private": true,
-  "version": "1.0.34",
+  "version": "1.0.37",
   "author": "Moshe Anconina",
   "license": "Apache-2.0",
   "description": "Task scheduling and cron management for Comis",

package/node_modules/@comis/shared/dist/index.d.ts

@@ -5,3 +5,6 @@ export { withTimeout, TimeoutError } from "./timeout.js";
 export { checkAborted } from "./abort.js";
 export { createTTLCache } from "./ttl-cache.js";
 export type { TTLCache, TTLCacheOptions } from "./ttl-cache.js";
+export { stripReplyTags, isSilentResponse, NO_REPLY_TOKEN, HEARTBEAT_OK_TOKEN, SILENT_PREFIX, } from "./silent-tokens.js";
+export type { VisibleDeliveryKind, VisibleDeliveryRecord } from "./visible-delivery.js";
+export { extractMcpServerName, parseSanitizedMcpToolName } from "./mcp-tool-name.js";

package/node_modules/@comis/shared/dist/index.js

@@ -5,3 +5,7 @@ export { suppressError } from "./suppress-error.js";
 export { withTimeout, TimeoutError } from "./timeout.js";
 export { checkAborted } from "./abort.js";
 export { createTTLCache } from "./ttl-cache.js";
+// Silent-token detection for agent responses.
+export { stripReplyTags, isSilentResponse, NO_REPLY_TOKEN, HEARTBEAT_OK_TOKEN, SILENT_PREFIX, } from "./silent-tokens.js";
+// Canonical sanitized MCP tool name parsers.
+export { extractMcpServerName, parseSanitizedMcpToolName } from "./mcp-tool-name.js";

package/node_modules/@comis/shared/dist/mcp-tool-name.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Canonical sanitized MCP tool name parsers.
+ *
+ * Sanitized MCP tool names use the format `mcp__serverName--toolName`,
+ * produced by `sanitizeMcpToolName` in @comis/skills' mcp-tool-bridge
+ * (replaces `:` with `__`, `/` with `--` to satisfy LLM API constraints
+ * that tool names match `^[a-zA-Z0-9_-]{1,128}$`).
+ *
+ * Both parsers split on the FIRST `--` after the `mcp__` prefix, which:
+ *   - Correctly handles hyphenated server names (`mcp__foo-bar--baz`
+ *     -> server="foo-bar", tool="baz")
+ *   - Correctly handles underscored server names (`mcp__srv__v2--ns--tool`
+ *     -> server="srv__v2", tool="ns--tool")
+ *   - Returns undefined for non-MCP tools (`Read`) and malformed names
+ *     (`mcp__`, `mcp__foo`, `mcp__--baz`)
+ *
+ * Asymmetry between the two functions is intentional:
+ *   - `extractMcpServerName("mcp__foo--")` returns "foo" — callers that
+ *     only need to GROUP by server (e.g., DeferredToolEntry grouping in
+ *     tool-deferral.ts) tolerate empty tool names.
+ *   - `parseSanitizedMcpToolName("mcp__foo--")` returns undefined —
+ *     callers that need a complete (server, tool) pair require both
+ *     halves to be non-empty.
+ *
+ * Used by:
+ * - `packages/skills/src/bridge/mcp-tool-bridge.ts` — re-exports for
+ *   public API surface (`packages/skills/src/index.ts:174`).
+ * - `packages/agent/src/bridge/bridge-event-handlers.ts` — re-exports
+ *   for in-package callers (`pi-event-bridge.ts:42`,
+ *   `tool-deferral.ts:23`).
+ * - `packages/agent/src/bridge/pi-event-bridge.ts:347` — log decoration
+ *   when an MCP tool errors at the event-bus boundary.
+ * - `packages/agent/src/executor/tool-deferral.ts:293,912,917` —
+ *   grouping `DeferredToolEntry[]` by server name.
+ * - Future install-detour parser will consume `parseSanitizedMcpToolName`
+ *   for `{server, tool}` pair-matching.
+ *
+ * @module
+ */
+/**
+ * Extract the MCP server name from a sanitized tool name.
+ *
+ * Sanitized MCP tool names use the format `mcp__serverName--toolName`.
+ * Returns `undefined` for non-MCP tools, malformed names with no
+ * `--` separator, or names with an empty server (`mcp__--baz`).
+ *
+ * @example
+ * extractMcpServerName("mcp__context7--resolve-library-id") // "context7"
+ * extractMcpServerName("mcp__foo-bar--baz")                 // "foo-bar"
+ * extractMcpServerName("mcp__srv__v2--ns--tool")            // "srv__v2"
+ * extractMcpServerName("Read")                              // undefined
+ * extractMcpServerName("mcp__")                             // undefined
+ * extractMcpServerName("mcp__foo")                          // undefined
+ * extractMcpServerName("mcp__--baz")                        // undefined
+ */
+export declare function extractMcpServerName(toolName: string): string | undefined;
+/**
+ * Parse a sanitized MCP tool name into its server and tool components.
+ *
+ * Returns `undefined` for non-MCP tools, malformed names, or names where
+ * either the server or tool component would be empty.
+ *
+ * Stricter than `extractMcpServerName`: this function ALSO rejects names
+ * with an empty tool (`mcp__foo--` returns `undefined` here, but
+ * `extractMcpServerName` returns `"foo"`).
+ *
+ * @example
+ * parseSanitizedMcpToolName("mcp__context7--resolve-library-id")
+ *   // { server: "context7", tool: "resolve-library-id" }
+ * parseSanitizedMcpToolName("mcp__foo--bar--baz")
+ *   // { server: "foo", tool: "bar--baz" }   // splits on FIRST "--"
+ * parseSanitizedMcpToolName("mcp__foo--")    // undefined
+ * parseSanitizedMcpToolName("Read")          // undefined
+ */
+export declare function parseSanitizedMcpToolName(toolName: string): {
+    server: string;
+    tool: string;
+} | undefined;

package/node_modules/@comis/shared/dist/mcp-tool-name.js

@@ -0,0 +1,92 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Canonical sanitized MCP tool name parsers.
+ *
+ * Sanitized MCP tool names use the format `mcp__serverName--toolName`,
+ * produced by `sanitizeMcpToolName` in @comis/skills' mcp-tool-bridge
+ * (replaces `:` with `__`, `/` with `--` to satisfy LLM API constraints
+ * that tool names match `^[a-zA-Z0-9_-]{1,128}$`).
+ *
+ * Both parsers split on the FIRST `--` after the `mcp__` prefix, which:
+ *   - Correctly handles hyphenated server names (`mcp__foo-bar--baz`
+ *     -> server="foo-bar", tool="baz")
+ *   - Correctly handles underscored server names (`mcp__srv__v2--ns--tool`
+ *     -> server="srv__v2", tool="ns--tool")
+ *   - Returns undefined for non-MCP tools (`Read`) and malformed names
+ *     (`mcp__`, `mcp__foo`, `mcp__--baz`)
+ *
+ * Asymmetry between the two functions is intentional:
+ *   - `extractMcpServerName("mcp__foo--")` returns "foo" — callers that
+ *     only need to GROUP by server (e.g., DeferredToolEntry grouping in
+ *     tool-deferral.ts) tolerate empty tool names.
+ *   - `parseSanitizedMcpToolName("mcp__foo--")` returns undefined —
+ *     callers that need a complete (server, tool) pair require both
+ *     halves to be non-empty.
+ *
+ * Used by:
+ * - `packages/skills/src/bridge/mcp-tool-bridge.ts` — re-exports for
+ *   public API surface (`packages/skills/src/index.ts:174`).
+ * - `packages/agent/src/bridge/bridge-event-handlers.ts` — re-exports
+ *   for in-package callers (`pi-event-bridge.ts:42`,
+ *   `tool-deferral.ts:23`).
+ * - `packages/agent/src/bridge/pi-event-bridge.ts:347` — log decoration
+ *   when an MCP tool errors at the event-bus boundary.
+ * - `packages/agent/src/executor/tool-deferral.ts:293,912,917` —
+ *   grouping `DeferredToolEntry[]` by server name.
+ * - Future install-detour parser will consume `parseSanitizedMcpToolName`
+ *   for `{server, tool}` pair-matching.
+ *
+ * @module
+ */
+/**
+ * Extract the MCP server name from a sanitized tool name.
+ *
+ * Sanitized MCP tool names use the format `mcp__serverName--toolName`.
+ * Returns `undefined` for non-MCP tools, malformed names with no
+ * `--` separator, or names with an empty server (`mcp__--baz`).
+ *
+ * @example
+ * extractMcpServerName("mcp__context7--resolve-library-id") // "context7"
+ * extractMcpServerName("mcp__foo-bar--baz")                 // "foo-bar"
+ * extractMcpServerName("mcp__srv__v2--ns--tool")            // "srv__v2"
+ * extractMcpServerName("Read")                              // undefined
+ * extractMcpServerName("mcp__")                             // undefined
+ * extractMcpServerName("mcp__foo")                          // undefined
+ * extractMcpServerName("mcp__--baz")                        // undefined
+ */
+export function extractMcpServerName(toolName) {
+    if (!toolName.startsWith("mcp__"))
+        return undefined;
+    const rest = toolName.slice(5);
+    const sepIdx = rest.indexOf("--");
+    if (sepIdx <= 0)
+        return undefined;
+    return rest.slice(0, sepIdx);
+}
+/**
+ * Parse a sanitized MCP tool name into its server and tool components.
+ *
+ * Returns `undefined` for non-MCP tools, malformed names, or names where
+ * either the server or tool component would be empty.
+ *
+ * Stricter than `extractMcpServerName`: this function ALSO rejects names
+ * with an empty tool (`mcp__foo--` returns `undefined` here, but
+ * `extractMcpServerName` returns `"foo"`).
+ *
+ * @example
+ * parseSanitizedMcpToolName("mcp__context7--resolve-library-id")
+ *   // { server: "context7", tool: "resolve-library-id" }
+ * parseSanitizedMcpToolName("mcp__foo--bar--baz")
+ *   // { server: "foo", tool: "bar--baz" }   // splits on FIRST "--"
+ * parseSanitizedMcpToolName("mcp__foo--")    // undefined
+ * parseSanitizedMcpToolName("Read")          // undefined
+ */
+export function parseSanitizedMcpToolName(toolName) {
+    if (!toolName.startsWith("mcp__"))
+        return undefined;
+    const rest = toolName.slice(5);
+    const sepIdx = rest.indexOf("--");
+    if (sepIdx <= 0 || sepIdx >= rest.length - 2)
+        return undefined;
+    return { server: rest.slice(0, sepIdx), tool: rest.slice(sepIdx + 2) };
+}

package/node_modules/@comis/shared/dist/silent-tokens.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Silent-token detection for agent responses.
+ *
+ * Symbols + helpers that detect "silent" agent responses — exact-match
+ * sentinels (`NO_REPLY`, `HEARTBEAT_OK`) and a `[SILENT]`-prefix marker —
+ * after stripping `<reply>` / `</reply>` XML tags and trimming whitespace.
+ *
+ * Used by:
+ * - `packages/agent/src/executor/executor-post-execution.ts` — silent-sentinel
+ *   pre-gate before paired-memory persistence.
+ * - `packages/channels/src/shared/response-filter.ts` — channel-delivery
+ *   suppression (helper-delegating).
+ *
+ * @module
+ */
+export declare const NO_REPLY_TOKEN = "NO_REPLY";
+export declare const HEARTBEAT_OK_TOKEN = "HEARTBEAT_OK";
+export declare const SILENT_PREFIX = "[SILENT]";
+/**
+ * Strip `<reply>` / `<reply to="...">` opening tags and `</reply>` closing
+ * tags from a response, then trim whitespace.
+ */
+export declare function stripReplyTags(s: string): string;
+/**
+ * Returns true iff the response, after stripping `<reply>` / `</reply>` tags
+ * and trimming whitespace, is exactly a silent sentinel (`NO_REPLY`,
+ * `HEARTBEAT_OK`, `[SILENT]`-prefix) or empty.
+ *
+ * **Contract:** idempotent under `stripReplyTags + trim`. For all
+ * inputs, `isSilentResponse(response) === isSilentResponse(stripReplyTags(response))`.
+ * Callers may pass raw or pre-stripped input; the helper does the strip+trim
+ * internally as defense-in-depth.
+ *
+ * Behavior matches the legacy `filterResponse` in
+ * `packages/channels/src/shared/response-filter.ts` byte-for-byte (this
+ * helper is the canonical home; `filterResponse` delegates to it).
+ */
+export declare function isSilentResponse(response: string | undefined): boolean;

package/node_modules/@comis/shared/dist/silent-tokens.js

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Silent-token detection for agent responses.
+ *
+ * Symbols + helpers that detect "silent" agent responses — exact-match
+ * sentinels (`NO_REPLY`, `HEARTBEAT_OK`) and a `[SILENT]`-prefix marker —
+ * after stripping `<reply>` / `</reply>` XML tags and trimming whitespace.
+ *
+ * Used by:
+ * - `packages/agent/src/executor/executor-post-execution.ts` — silent-sentinel
+ *   pre-gate before paired-memory persistence.
+ * - `packages/channels/src/shared/response-filter.ts` — channel-delivery
+ *   suppression (helper-delegating).
+ *
+ * @module
+ */
+export const NO_REPLY_TOKEN = "NO_REPLY";
+export const HEARTBEAT_OK_TOKEN = "HEARTBEAT_OK";
+export const SILENT_PREFIX = "[SILENT]";
+const REPLY_TAG_RE = /<\/?reply(?:\s[^>]*)?>|<reply>/gi;
+/**
+ * Strip `<reply>` / `<reply to="...">` opening tags and `</reply>` closing
+ * tags from a response, then trim whitespace.
+ */
+export function stripReplyTags(s) {
+    return s.replace(REPLY_TAG_RE, "").trim();
+}
+/**
+ * Returns true iff the response, after stripping `<reply>` / `</reply>` tags
+ * and trimming whitespace, is exactly a silent sentinel (`NO_REPLY`,
+ * `HEARTBEAT_OK`, `[SILENT]`-prefix) or empty.
+ *
+ * **Contract:** idempotent under `stripReplyTags + trim`. For all
+ * inputs, `isSilentResponse(response) === isSilentResponse(stripReplyTags(response))`.
+ * Callers may pass raw or pre-stripped input; the helper does the strip+trim
+ * internally as defense-in-depth.
+ *
+ * Behavior matches the legacy `filterResponse` in
+ * `packages/channels/src/shared/response-filter.ts` byte-for-byte (this
+ * helper is the canonical home; `filterResponse` delegates to it).
+ */
+export function isSilentResponse(response) {
+    if (!response)
+        return true;
+    const trimmed = stripReplyTags(response);
+    if (!trimmed)
+        return true;
+    if (trimmed.toUpperCase().startsWith(SILENT_PREFIX))
+        return true;
+    return trimmed === NO_REPLY_TOKEN || trimmed === HEARTBEAT_OK_TOKEN;
+}

package/node_modules/@comis/shared/dist/visible-delivery.d.ts

@@ -0,0 +1,28 @@
+/**
+ * VisibleDeliveryRecord: structured metadata for outbound channel deliveries
+ * captured in JSONL `details` for offline analysis (output retention housekeeper consumes this).
+ *
+ * Persisted in `details.visibleDelivery` on `message(action='attach')` toolResult
+ * entries; visible to operators inspecting JSONL but NOT injected back into the
+ * model's context window across turns.
+ *
+ * Plain TypeScript interface (no Zod) per AGENTS §2.3 KISS — `@comis/shared`
+ * has zero runtime deps, and this type is JSONL-persisted only (no port-bus
+ * payload validation needed).
+ *
+ * @module
+ */
+/** Kind of visible delivery captured. Open-ended union for forward extensibility. */
+export type VisibleDeliveryKind = "attachment" | "text" | "reaction";
+export interface VisibleDeliveryRecord {
+    /** What kind of delivery this records. */
+    kind: VisibleDeliveryKind;
+    /** Channel adapter that delivered (e.g., "telegram"). */
+    channelType: string;
+    /** Channel-specific identifier (e.g., user/group/peer id). */
+    channelId: string;
+    /** Human-readable caption for attachments; brief text for text/reaction. */
+    caption?: string;
+    /** Wall-clock millis when delivery completed (Date.now()). */
+    deliveredAt: number;
+}

package/node_modules/@comis/shared/dist/visible-delivery.js

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * VisibleDeliveryRecord: structured metadata for outbound channel deliveries
+ * captured in JSONL `details` for offline analysis (output retention housekeeper consumes this).
+ *
+ * Persisted in `details.visibleDelivery` on `message(action='attach')` toolResult
+ * entries; visible to operators inspecting JSONL but NOT injected back into the
+ * model's context window across turns.
+ *
+ * Plain TypeScript interface (no Zod) per AGENTS §2.3 KISS — `@comis/shared`
+ * has zero runtime deps, and this type is JSONL-persisted only (no port-bus
+ * payload validation needed).
+ *
+ * @module
+ */
+export {};

package/node_modules/@comis/shared/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@comis/shared",
   "private": true,
-  "version": "1.0.34",
+  "version": "1.0.37",
   "author": "Moshe Anconina",
   "license": "Apache-2.0",
   "description": "Shared types and utilities for the Comis platform",

package/node_modules/@comis/skills/dist/bridge/mcp-tool-bridge.d.ts

@@ -13,24 +13,14 @@
  */
 import type { AgentTool } from "@mariozechner/pi-agent-core";
 import { type TSchema } from "typebox";
+import { extractMcpServerName } from "@comis/shared";
+export { extractMcpServerName };
 import { type ToolSourceProfile } from "../builtin/tool-source-profiles.js";
 import type { McpToolDefinition, McpClientManager } from "../integrations/mcp-client.js";
 /** Minimal pino-compatible logger for MCP bridge diagnostic logging. */
 interface McpBridgeLogger {
     debug(obj: Record<string, unknown>, msg: string): void;
 }
-/**
- * Extract the MCP server name from a sanitized tool name.
- *
- * Sanitized MCP tool names use the format `mcp__serverName--toolName`.
- * Returns `undefined` for non-MCP tools or malformed names.
- *
- * @example
- * extractMcpServerName("mcp__context7--resolve-library-id") // "context7"
- * extractMcpServerName("mcp__srv__v2--ns--tool") // "srv__v2"
- * extractMcpServerName("bash") // undefined
- */
-export declare function extractMcpServerName(toolName: string): string | undefined;
 /**
  * Classify an MCP error message into a category for observability.
  *
@@ -78,4 +68,3 @@ export declare function sanitizeMcpToolName(qualifiedName: string): string;
  * @returns AgentTool instances ready for the agent executor
  */
 export declare function mcpToolsToAgentTools(tools: McpToolDefinition[], callTool: McpClientManager["callTool"], toolSourceProfiles?: Record<string, Partial<ToolSourceProfile>>, logger?: McpBridgeLogger): AgentTool<any>[];
-export {};

package/node_modules/@comis/skills/dist/bridge/mcp-tool-bridge.js

@@ -14,32 +14,14 @@
  */
 import { Type } from "typebox";
 import { registerToolMetadata } from "@comis/core";
+import { extractMcpServerName } from "@comis/shared";
+export { extractMcpServerName };
 import { resolveSourceProfile } from "../builtin/tool-source-profiles.js";
 import { sanitizeMcpToolResult } from "../integrations/mcp-result-sanitizer.js";
 import { truncateJsonAware } from "./json-truncate.js";
 // ---------------------------------------------------------------------------
-// MCP tool name parsing and error classification
+// MCP error classification
 // ---------------------------------------------------------------------------
-/**
- * Extract the MCP server name from a sanitized tool name.
- *
- * Sanitized MCP tool names use the format `mcp__serverName--toolName`.
- * Returns `undefined` for non-MCP tools or malformed names.
- *
- * @example
- * extractMcpServerName("mcp__context7--resolve-library-id") // "context7"
- * extractMcpServerName("mcp__srv__v2--ns--tool") // "srv__v2"
- * extractMcpServerName("bash") // undefined
- */
-export function extractMcpServerName(toolName) {
-    if (!toolName.startsWith("mcp__"))
-        return undefined;
-    const rest = toolName.slice(5); // strip "mcp__"
-    const sepIdx = rest.indexOf("--");
-    if (sepIdx <= 0)
-        return undefined; // no separator or empty server name
-    return rest.slice(0, sepIdx);
-}
 /**
  * Classify an MCP error message into a category for observability.
  *

package/node_modules/@comis/skills/dist/bridge/schema-validator.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Generic tool-entry schema validator.
+ *
+ * Pre-flight, action-aware shape gate that runs BEFORE per-tool
+ * `validateInput`. Catches malformed shapes such as
+ * `mcp_manage({action:"connect", server_name:"yfinance"})` at the
+ * tool-entry boundary and produces a self-correcting message:
+ *
+ *     "[invalid_value] unknown key 'server_name' -- did you mean 'name'?.
+ *      missing for action='connect': transport.
+ *      valid keys: action, name, transport, command, args, url, headers"
+ *
+ * Generic by construction: every per-tool branch lives in the metadata
+ * registered via `registerToolMetadata({ validActions, validKeys,
+ *   requiredByAction })`. This file contains zero tool-name conditionals.
+ *
+ * Reuses `levenshteinSimilarity` from
+ * ../builtin/file/path-suggest.js -- DO NOT duplicate the helper.
+ *
+ * Returns a single error string on failure (matches the
+ * `validateInput` contract used by `wrapWithMetadataEnforcement`),
+ * `undefined` on success. Caller prepends `[invalid_value]`.
+ *
+ * @module
+ */
+import type { ComisToolMetadata } from "@comis/core";
+/**
+ * Validate tool-entry shape against registered metadata.
+ *
+ * @param params - Raw params object as the SDK would pass to `execute()`.
+ * @param meta - Metadata returned from `getToolMetadata(toolName)`. May be
+ *   undefined or missing the entry-shape fields -- in either case this
+ *   function returns undefined (no-op) so existing tools without
+ *   registered shape metadata pass through unchanged.
+ * @returns A single error string when validation fails (caller prepends
+ *   `[invalid_value]`), or `undefined` when validation passes / is skipped.
+ */
+export declare function validateToolEntry(params: unknown, meta: ComisToolMetadata | undefined): string | undefined;