comisai 1.0.33 → 1.0.36

package/node_modules/@comis/memory/dist/oauth-profile-store-encrypted.js

@@ -0,0 +1,144 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Encrypted SQLite-backed OAuthCredentialStorePort adapter.
+ *
+ * Mirrors credential-mapping-store's factory pattern (takes a pre-opened
+ * Database instance, does NOT open its own). The lifecycle is owned by
+ * the caller — we share the existing secrets.db connection to keep all
+ * encrypted-at-rest data in one DB file.
+ *
+ * The entire OAuthProfile JSON payload is encrypted as one AES-256-GCM
+ * blob per row. One ciphertext+iv+authTag+salt set per profile. Atomic
+ * update — no half-rotated state where access changes but refresh doesn't.
+ *
+ * Denormalized expires_at column stays in sync on every write so the
+ * doctor can query expiring profiles without decrypting any blob.
+ *
+ * @module
+ */
+import { ok, err, fromPromise } from "@comis/shared";
+import { validateProfileId } from "@comis/core";
+import { initOAuthProfileSchema } from "./oauth-profile-schema.js";
+const SCHEMA_VERSION = 1;
+/**
+ * Create an encrypted OAuthCredentialStorePort backed by a shared SQLite DB.
+ *
+ * The adapter does NOT own the db lifecycle — the caller supplies an
+ * already-open Database (typically the secrets.db chain). Initializes its
+ * own oauth_profiles table via initOAuthProfileSchema (idempotent).
+ */
+export function createOAuthProfileStoreEncrypted(db, crypto) {
+    initOAuthProfileSchema(db);
+    const upsertStmt = db.prepare(`
+    INSERT INTO oauth_profiles (
+      profile_id, provider, identity,
+      credentials_ciphertext, credentials_iv, credentials_auth_tag, credentials_salt,
+      expires_at, version, created_at, updated_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(profile_id) DO UPDATE SET
+      provider = excluded.provider,
+      identity = excluded.identity,
+      credentials_ciphertext = excluded.credentials_ciphertext,
+      credentials_iv = excluded.credentials_iv,
+      credentials_auth_tag = excluded.credentials_auth_tag,
+      credentials_salt = excluded.credentials_salt,
+      expires_at = excluded.expires_at,
+      version = excluded.version,
+      updated_at = excluded.updated_at
+  `);
+    const getStmt = db.prepare("SELECT * FROM oauth_profiles WHERE profile_id = ?");
+    const deleteStmt = db.prepare("DELETE FROM oauth_profiles WHERE profile_id = ?");
+    const listAllStmt = db.prepare("SELECT * FROM oauth_profiles");
+    const listByProviderStmt = db.prepare("SELECT * FROM oauth_profiles WHERE provider = ?");
+    const existsStmt = db.prepare("SELECT 1 FROM oauth_profiles WHERE profile_id = ?");
+    function rowToProfile(row) {
+        if (row.version !== SCHEMA_VERSION) {
+            return err(new Error("OAuth profile store version mismatch: expected " +
+                SCHEMA_VERSION +
+                ", got " +
+                String(row.version) +
+                ". Hint: drop the oauth_profiles table and re-run `comis auth login` to recreate. Stored profiles for unknown schema versions cannot be migrated."));
+        }
+        const decryptResult = crypto.decrypt({
+            ciphertext: row.credentials_ciphertext,
+            iv: row.credentials_iv,
+            authTag: row.credentials_auth_tag,
+            salt: row.credentials_salt,
+        });
+        if (!decryptResult.ok)
+            return err(decryptResult.error);
+        let parsed;
+        try {
+            parsed = JSON.parse(decryptResult.value);
+        }
+        catch (e) {
+            return err(new Error("OAuth profile decryption produced invalid JSON: " + String(e)));
+        }
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return err(new Error("OAuth profile decryption produced non-object payload"));
+        }
+        return ok(parsed);
+    }
+    const port = {
+        async get(profileId) {
+            const validation = validateProfileId(profileId);
+            if (!validation.ok)
+                return err(validation.error);
+            return fromPromise((async () => {
+                const row = getStmt.get(profileId);
+                if (!row)
+                    return undefined;
+                const r = rowToProfile(row);
+                if (!r.ok)
+                    throw r.error;
+                return r.value;
+            })());
+        },
+        async set(profileId, profile) {
+            const validation = validateProfileId(profileId);
+            if (!validation.ok)
+                return err(validation.error);
+            const fullProfile = { ...profile, profileId, version: SCHEMA_VERSION };
+            const payload = JSON.stringify(fullProfile);
+            const encryptResult = crypto.encrypt(payload);
+            if (!encryptResult.ok)
+                return err(encryptResult.error);
+            const enc = encryptResult.value;
+            const now = Date.now();
+            return fromPromise((async () => {
+                upsertStmt.run(profileId, validation.value.provider, validation.value.identity, enc.ciphertext, enc.iv, enc.authTag, enc.salt, fullProfile.expires, SCHEMA_VERSION, now, now);
+            })());
+        },
+        async delete(profileId) {
+            const validation = validateProfileId(profileId);
+            if (!validation.ok)
+                return err(validation.error);
+            return fromPromise((async () => {
+                const result = deleteStmt.run(profileId);
+                return result.changes > 0;
+            })());
+        },
+        async list(filter) {
+            return fromPromise((async () => {
+                const rows = filter?.provider
+                    ? listByProviderStmt.all(filter.provider)
+                    : listAllStmt.all();
+                const profiles = [];
+                for (const row of rows) {
+                    const r = rowToProfile(row);
+                    if (!r.ok)
+                        throw r.error;
+                    profiles.push(r.value);
+                }
+                return profiles;
+            })());
+        },
+        async has(profileId) {
+            const validation = validateProfileId(profileId);
+            if (!validation.ok)
+                return err(validation.error);
+            return fromPromise((async () => existsStmt.get(profileId) !== undefined)());
+        },
+    };
+    return Object.freeze(port);
+}

package/node_modules/@comis/memory/dist/session-store.d.ts

@@ -5,7 +5,7 @@
  * prepared statements. Sessions survive process restarts since they are
  * stored in SQLite.
  *
- * Factory function pattern (createSessionStore) consistent with Phase 1
+ * Factory function pattern (createSessionStore) consistent with
  * createSecretManager for minimal public surface area.
  */
 import type Database from "better-sqlite3";

package/node_modules/@comis/memory/dist/session-store.js

@@ -6,7 +6,7 @@
  * prepared statements. Sessions survive process restarts since they are
  * stored in SQLite.
  *
- * Factory function pattern (createSessionStore) consistent with Phase 1
+ * Factory function pattern (createSessionStore) consistent with
  * createSecretManager for minimal public surface area.
  */
 import { formatSessionKey } from "@comis/core";

package/node_modules/@comis/memory/dist/sqlite-secret-store.d.ts

@@ -10,7 +10,32 @@
  *
  * Persists encrypted secrets across daemon restarts.
  */
+import type Database from "better-sqlite3";
 import type { SecretStorePort, SecretsCrypto } from "@comis/core";
+/**
+ * Concrete return type of createSqliteSecretStore.
+ *
+ * Implements SecretStorePort and additionally exposes the underlying
+ * better-sqlite3 handle for adapters that need to share the same
+ * connection (e.g., the encrypted OAuth profile store).
+ *
+ * The `db` field is intentionally additive — `SecretStorePort` itself is
+ * unchanged and remains the canonical port boundary. Consumers that only
+ * need port-level operations should accept `SecretStorePort`, not
+ * `SqliteSecretStoreHandle`.
+ */
+export interface SqliteSecretStoreHandle extends SecretStorePort {
+    /**
+     * Underlying better-sqlite3 handle.
+     *
+     * Use for sharing the connection with sibling tables in the same DB
+     * file (e.g., `oauth_profiles` alongside `secrets`). Eliminates the
+     * dual-handle hazard (close-order, schema-init double-execution,
+     * prepared-statement cache fragmentation) that two separate handles
+     * to the same WAL-mode SQLite file would introduce.
+     */
+    readonly db: Database.Database;
+}
 /**
  * Create a SqliteSecretStore bound to the given database path.
  *
@@ -22,11 +47,12 @@ import type { SecretStorePort, SecretsCrypto } from "@comis/core";
  * 5. Validate canary (master key mismatch detection)
  * 6. Second chmod pass (SQLite may create WAL/SHM during canary)
  * 7. Prepare all SQL statements once
- * 8. Return frozen SecretStorePort object
+ * 8. Return frozen SqliteSecretStoreHandle (SecretStorePort + db field)
  *
  * @param dbPath - Absolute path to the secrets.db file
  * @param crypto - SecretsCrypto engine bound to the current master key
- * @returns SecretStorePort implementation
+ * @returns SqliteSecretStoreHandle — a SecretStorePort that also exposes
+ *          the underlying better-sqlite3 handle on `.db`
  * @throws Error if schema init, canary validation, or DB open fails
  */
-export declare function createSqliteSecretStore(dbPath: string, crypto: SecretsCrypto): SecretStorePort;
+export declare function createSqliteSecretStore(dbPath: string, crypto: SecretsCrypto): SqliteSecretStoreHandle;

package/node_modules/@comis/memory/dist/sqlite-secret-store.js

@@ -25,11 +25,12 @@ import { openSqliteDatabase, chmodDbFiles } from "./sqlite-adapter-base.js";
  * 5. Validate canary (master key mismatch detection)
  * 6. Second chmod pass (SQLite may create WAL/SHM during canary)
  * 7. Prepare all SQL statements once
- * 8. Return frozen SecretStorePort object
+ * 8. Return frozen SqliteSecretStoreHandle (SecretStorePort + db field)
  *
  * @param dbPath - Absolute path to the secrets.db file
  * @param crypto - SecretsCrypto engine bound to the current master key
- * @returns SecretStorePort implementation
+ * @returns SqliteSecretStoreHandle — a SecretStorePort that also exposes
+ *          the underlying better-sqlite3 handle on `.db`
  * @throws Error if schema init, canary validation, or DB open fails
  */
 export function createSqliteSecretStore(dbPath, crypto) {
@@ -149,5 +150,12 @@ export function createSqliteSecretStore(dbPath, crypto) {
             db.close();
         },
     };
-    return Object.freeze(store);
+    // Expose the underlying db handle on the factory return so the encrypted
+    // OAuth profile adapter (oauth-profile-store-encrypted) can share this same
+    // connection rather than opening a second handle to the same secrets.db
+    // file. The SecretStorePort surface itself is unchanged — consumers that
+    // only need port-level operations should accept SecretStorePort, not
+    // SqliteSecretStoreHandle.
+    const handle = { ...store, db };
+    return Object.freeze(handle);
 }

package/node_modules/@comis/memory/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@comis/memory",
   "private": true,
-  "version": "1.0.33",
+  "version": "1.0.36",
   "author": "Moshe Anconina",
   "license": "Apache-2.0",
   "description": "SQLite memory, embeddings, and RAG storage for Comis agents",

package/node_modules/@comis/scheduler/dist/execution/execution-lock.d.ts

@@ -14,6 +14,19 @@ export interface ExecutionLockOptions {
     updateMs: number;
     /** Callback when lock is compromised (e.g., external release). */
     onCompromised?: (err: Error) => void;
+    /**
+     * Optional lock-acquisition retry budget. Forwarded to proper-lockfile's
+     * own retry option (uses a built-in incremental backoff). When undefined
+     * (default), retries: 0 — fail fast on contention. Lets the OAuth manager
+     * wait for a sibling refresh to complete (concurrent-refresh acceptance)
+     * without callers having to roll their own retry loop.
+     */
+    retries?: number | {
+        retries: number;
+        minTimeout?: number;
+        maxTimeout?: number;
+        factor?: number;
+    };
 }
 /**
  * Acquire a file lock, execute the function, and release the lock.

package/node_modules/@comis/scheduler/dist/execution/execution-lock.js

@@ -41,7 +41,7 @@ export async function withExecutionLock(lockPath, fn, options) {
         release = await lockfile.lock(lockPath, {
             stale: opts.staleMs,
             update: opts.updateMs,
-            retries: 0,
+            retries: opts.retries ?? 0,
             onCompromised: opts.onCompromised ?? (() => { }),
         });
     }

package/node_modules/@comis/scheduler/dist/execution/index.d.ts

@@ -1,2 +1,4 @@
 export { createExecutionTracker } from "./execution-tracker.js";
 export type { ExecutionTracker, ExecutionLogEntry } from "./execution-tracker.js";
+export { withExecutionLock, isLocked } from "./execution-lock.js";
+export type { ExecutionLockOptions } from "./execution-lock.js";

package/node_modules/@comis/scheduler/dist/execution/index.js

@@ -2,3 +2,5 @@
 // @comis/scheduler/execution — execution safety primitives
 // Execution tracking
 export { createExecutionTracker } from "./execution-tracker.js";
+// File-based execution lock
+export { withExecutionLock, isLocked } from "./execution-lock.js";

package/node_modules/@comis/scheduler/dist/heartbeat/agent-heartbeat-source.js

@@ -158,7 +158,7 @@ export function createAgentHeartbeatSource(deps) {
                 },
             };
             // 9. Resolve model (for logging)
-            const model = resolveHeartbeatModel(undefined, // per-agent heartbeat model removed in Phase 2
+            const model = resolveHeartbeatModel(undefined, // per-agent heartbeat model not in schema
             undefined, // global heartbeat model not yet in schema
             agentConfig.model);
             logger.info({ agentId, trigger, model, channelType: msg.channelType }, "Heartbeat run starting");

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

@@ -7,6 +7,8 @@ export { createCronScheduler } from "./cron/index.js";
 export type { CronScheduler } from "./cron/index.js";
 export { createExecutionTracker } from "./execution/index.js";
 export type { ExecutionTracker, ExecutionLogEntry } from "./execution/index.js";
+export { withExecutionLock, isLocked } from "./execution/execution-lock.js";
+export type { ExecutionLockOptions } from "./execution/execution-lock.js";
 export { HEARTBEAT_OK_TOKEN, createHeartbeatRunner } from "./heartbeat/index.js";
 export type { HeartbeatCheckResult, HeartbeatSourcePort, HeartbeatRunner } from "./heartbeat/index.js";
 export { resolveEffectiveHeartbeatConfig } from "./heartbeat/index.js";

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

@@ -7,6 +7,8 @@ export { createCronStore } from "./cron/index.js";
 export { createCronScheduler } from "./cron/index.js";
 // Execution safety
 export { createExecutionTracker } from "./execution/index.js";
+// File-based execution lock (consumed by @comis/agent OAuth file adapter + token manager)
+export { withExecutionLock, isLocked } from "./execution/execution-lock.js";
 // Heartbeat monitoring
 export { HEARTBEAT_OK_TOKEN, createHeartbeatRunner } from "./heartbeat/index.js";
 // Per-agent heartbeat config resolution

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

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

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

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

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;

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

@@ -0,0 +1,169 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * 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 { levenshteinSimilarity } from "../builtin/file/path-suggest.js";
+/**
+ * Min similarity for did-you-mean suggestion. Below this we say "unknown"
+ * with no suggestion to avoid misleading the LLM.
+ *
+ * We score with `tokenAwareSimilarity` (max of full-string similarity and
+ * the best per-token similarity after splitting on `_`/`-`). This catches
+ * payloads like `server_name -> name` (token "name" matches exactly,
+ * score 1.0) without spurious matches against short unrelated keys (`x`,
+ * `srver` -> max < 0.3 across all candidates in the 7-key mcp_manage
+ * shape, well below threshold).
+ *
+ * 0.5 was chosen empirically: `conect -> connect` scores 0.857 (fires);
+ * `srver -> headers` scores 0.286 (does not fire); the closest false
+ * positive across the manage-tool corpus is below 0.5.
+ */
+const SUGGEST_THRESHOLD = 0.5;
+/**
+ * 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 function validateToolEntry(params, meta) {
+    // Skip if no entry-shape metadata registered.
+    if (meta === undefined
+        || (meta.validActions === undefined
+            && meta.validKeys === undefined
+            && meta.requiredByAction === undefined)) {
+        return undefined;
+    }
+    // Shape gate: params MUST be a plain object. Reject null, primitives,
+    // and arrays. (Arrays would otherwise pass typeof === "object".)
+    if (params === null || typeof params !== "object" || Array.isArray(params)) {
+        return "params must be an object";
+    }
+    const p = params;
+    const segments = [];
+    // Action gate.
+    let action;
+    if (meta.validActions !== undefined) {
+        const raw = p.action;
+        if (raw === undefined) {
+            segments.push(`Missing required parameter: action. valid actions: ${meta.validActions.join(", ")}`);
+        }
+        else if (typeof raw !== "string") {
+            segments.push("action must be a string");
+        }
+        else if (!meta.validActions.includes(raw)) {
+            const suggestion = bestMatch(raw, meta.validActions);
+            const didYouMean = suggestion !== undefined ? ` -- did you mean '${suggestion}'?` : "";
+            segments.push(`invalid action '${raw}'${didYouMean}. valid actions: ${meta.validActions.join(", ")}`);
+        }
+        else {
+            action = raw;
+        }
+    }
+    else if (typeof p.action === "string") {
+        // No validActions registered but the tool still uses an action field
+        // (rare). Use it for requiredByAction lookup.
+        action = p.action;
+    }
+    // Unknown-key gate.
+    if (meta.validKeys !== undefined) {
+        const validSet = new Set(meta.validKeys);
+        const unknowns = [];
+        for (const key of Object.keys(p)) {
+            if (!validSet.has(key))
+                unknowns.push(key);
+        }
+        if (unknowns.length > 0) {
+            const parts = unknowns.map((k) => {
+                const suggestion = bestMatch(k, meta.validKeys);
+                return suggestion !== undefined
+                    ? `unknown key '${k}' -- did you mean '${suggestion}'?`
+                    : `unknown key '${k}'`;
+            });
+            segments.push(parts.join("; "));
+        }
+    }
+    // Required-fields gate (only when we have a known action).
+    if (action !== undefined && meta.requiredByAction !== undefined) {
+        const required = meta.requiredByAction[action];
+        if (required !== undefined && required.length > 0) {
+            const missing = required.filter((k) => !(k in p) || p[k] === undefined);
+            if (missing.length > 0) {
+                segments.push(`missing for action='${action}': ${missing.join(", ")}`);
+            }
+        }
+    }
+    if (segments.length === 0)
+        return undefined;
+    // Always append valid-keys list when registered -- closes the LLM's
+    // self-correction loop in one turn.
+    if (meta.validKeys !== undefined) {
+        segments.push(`valid keys: ${meta.validKeys.join(", ")}`);
+    }
+    return segments.join(". ");
+}
+/** Pick the best-matching candidate above SUGGEST_THRESHOLD, or undefined. */
+function bestMatch(input, candidates) {
+    let best;
+    const lowered = input.toLowerCase();
+    for (const candidate of candidates) {
+        const score = tokenAwareSimilarity(lowered, candidate.toLowerCase());
+        if (score >= SUGGEST_THRESHOLD && (best === undefined || score > best.score)) {
+            best = { value: candidate, score };
+        }
+    }
+    return best?.value;
+}
+/**
+ * Token-aware similarity: max of full-string similarity and the best
+ * per-token similarity after splitting `input` on `_`/`-`.
+ *
+ * Plain Levenshtein on full strings misses snake_case key suggestions:
+ * `server_name` vs `name` is similarity 0.36, well below any reasonable
+ * threshold. Splitting on `_` exposes the `name` token (similarity 1.0
+ * vs `name`), which is the LLM-self-correction signal we want to surface.
+ *
+ * Inputs are assumed lowercased by the caller.
+ */
+function tokenAwareSimilarity(input, candidate) {
+    let best = levenshteinSimilarity(input, candidate);
+    // Split on '_' or '-' (skill, manage-tool, snake_case conventions). Empty
+    // tokens are dropped so leading/trailing/double-separators do not produce
+    // 0-length strings that would skew similarity to 1.0 against an empty
+    // candidate (defensive -- candidate is non-empty in practice).
+    const tokens = input.split(/[_-]+/);
+    for (const t of tokens) {
+        if (t.length === 0)
+            continue;
+        const score = levenshteinSimilarity(t, candidate);
+        if (score > best)
+            best = score;
+    }
+    return best;
+}

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

@@ -11,6 +11,7 @@
  * @module
  */
 import { getToolMetadata, truncateContentBlocks } from "@comis/core";
+import { validateToolEntry } from "./schema-validator.js";
 /**
  * Check whether a tool result's content is effectively empty.
  *
@@ -60,6 +61,17 @@ export function wrapWithMetadataEnforcement(tool) {
         ...tool,
         async execute(toolCallId, params, signal, onUpdate) {
             const meta = getToolMetadata(tool.name);
+            // Generic tool-entry schema validation (260504-cac).
+            // Runs BEFORE per-tool validateInput so action-shape errors short-circuit
+            // before tool-specific business rules. Skips silently when the tool has
+            // not registered validActions / validKeys / requiredByAction.
+            const schemaError = validateToolEntry(params, meta);
+            if (schemaError !== undefined) {
+                const err = new Error(`[invalid_value] ${schemaError}`);
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any -- match existing errorKind propagation pattern
+                err.errorKind = "validation";
+                throw err;
+            }
             // Pre-flight validation
             if (meta?.validateInput) {
                 const validationError = await meta.validateInput(params);