comisai 1.0.34 → 1.0.37

package/node_modules/@comis/core/dist/exports/ports.js

@@ -1,3 +1,3 @@
 // SPDX-License-Identifier: Apache-2.0
 // @comis/core exports — Port interfaces (hexagonal architecture boundaries)
-export { ChannelCapabilitySchema, createNoOpDeliveryQueue, createNoOpDeliveryMirror } from "../ports/index.js";
+export { ChannelCapabilitySchema, createNoOpDeliveryQueue, createNoOpDeliveryMirror, createNoOpCapabilityPort, validateProfileId, PROFILE_ID_RE, } from "../ports/index.js";

package/node_modules/@comis/core/dist/ports/channel-plugin.d.ts

@@ -2,7 +2,6 @@ import { z } from "zod";
 import type { PluginPort } from "./plugin.js";
 import type { ChannelPort } from "./channel.js";
 export declare const ChannelCapabilitySchema: z.ZodObject<{
-    /** Chat types this channel supports */
     chatTypes: z.ZodArray<z.ZodEnum<{
         channel: "channel";
         dm: "dm";
@@ -10,7 +9,6 @@ export declare const ChannelCapabilitySchema: z.ZodObject<{
         thread: "thread";
         forum: "forum";
     }>>;
-    /** Feature flags for optional capabilities */
     features: z.ZodDefault<z.ZodObject<{
         reactions: z.ZodDefault<z.ZodBoolean>;
         editMessages: z.ZodDefault<z.ZodBoolean>;
@@ -20,44 +18,33 @@ export declare const ChannelCapabilitySchema: z.ZodObject<{
         threads: z.ZodDefault<z.ZodBoolean>;
         mentions: z.ZodDefault<z.ZodBoolean>;
         formatting: z.ZodDefault<z.ZodArray<z.ZodString>>;
-        /** Whether the channel supports interactive buttons */
         buttons: z.ZodDefault<z.ZodBoolean>;
-        /** Whether the channel supports rich card embeds */
         cards: z.ZodDefault<z.ZodBoolean>;
-        /** Whether the channel supports message delivery effects (spoiler, silent) */
         effects: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strict>>;
-    /** Platform-specific message and attachment size limits */
     limits: z.ZodObject<{
         maxMessageChars: z.ZodNumber;
         maxAttachmentSizeMb: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>;
-    /** Streaming support configuration */
     streaming: z.ZodDefault<z.ZodObject<{
         supported: z.ZodDefault<z.ZodBoolean>;
         throttleMs: z.ZodDefault<z.ZodNumber>;
         maxChars: z.ZodOptional<z.ZodNumber>;
-        /** Streaming delivery method: "edit" = edit message in-place, "block" = sequential messages, "none" = no streaming */
         method: z.ZodDefault<z.ZodEnum<{
             edit: "edit";
             none: "none";
             block: "block";
         }>>;
     }, z.core.$strict>>;
-    /** Threading capability metadata (extends features.threads with detail) */
     threading: z.ZodDefault<z.ZodObject<{
-        /** Whether threading is supported at all (mirrors features.threads for convenience) */
         supported: z.ZodDefault<z.ZodBoolean>;
-        /** Type of threading: "native" = platform threads (Discord), "reply-chain" = thread_ts reply chains (Slack), "none" = no threading */
         threadType: z.ZodDefault<z.ZodEnum<{
             none: "none";
             native: "native";
             "reply-chain": "reply-chain";
         }>>;
-        /** Maximum thread nesting depth (undefined = unlimited within a thread) */
         maxDepth: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
-    /** Metadata key used for reply-to references (platform-specific) */
     replyToMetaKey: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 /** Inferred type from ChannelCapabilitySchema */

package/node_modules/@comis/core/dist/ports/delivery-queue.d.ts

@@ -65,6 +65,19 @@ export interface DeliveryQueuePort {
      * @returns The assigned entry ID on success.
      */
     enqueue(entry: DeliveryQueueEnqueueInput): Promise<Result<string, Error>>;
+    /**
+     * Enqueue a new outbound message with status='in_flight' (process-local lease).
+     *
+     * Used by the channel-side synchronous-send path: insert as 'in_flight' so the
+     * recurring drainer's `WHERE status='pending'` filter does not race-pick the row
+     * mid-send. Same semantics as enqueue() except for the initial status.
+     * On crash, the startup sweep (recoverInFlight) resets these rows back to 'pending'.
+     *
+     * Emits delivery:enqueued (same event as enqueue()) -- universal observability.
+     *
+     * @returns The assigned entry ID on success.
+     */
+    enqueueInFlight(entry: DeliveryQueueEnqueueInput): Promise<Result<string, Error>>;
     /**
      * Mark an entry as successfully delivered.
      * @param id - The queue entry ID
@@ -103,6 +116,16 @@ export interface DeliveryQueuePort {
      * @param channelType - Optional filter to restrict counts to a specific channel.
      */
     statusCounts(channelType?: string): Promise<Result<DeliveryQueueStatusCounts, Error>>;
+    /**
+     * Reset all rows with status='in_flight' to status='pending', clearing last_error.
+     *
+     * Called once at daemon startup before the existing startup drain. Treats
+     * 'in_flight' as a process-local lease -- any in_flight row left over from a
+     * prior daemon process is by definition stale and must be re-attempted.
+     *
+     * @returns The number of rows recovered (transitioned in_flight -> pending).
+     */
+    recoverInFlight(): Promise<Result<number, Error>>;
 }
 /**
  * No-op delivery queue for when the queue feature is disabled.

package/node_modules/@comis/core/dist/ports/delivery-queue.js

@@ -22,6 +22,7 @@ import { ok } from "@comis/shared";
 export function createNoOpDeliveryQueue() {
     return Object.freeze({
         enqueue: () => Promise.resolve(ok(randomUUID())),
+        enqueueInFlight: () => Promise.resolve(ok(randomUUID())),
         ack: () => Promise.resolve(ok(undefined)),
         nack: () => Promise.resolve(ok(undefined)),
         fail: () => Promise.resolve(ok(undefined)),
@@ -29,5 +30,6 @@ export function createNoOpDeliveryQueue() {
         pruneExpired: () => Promise.resolve(ok(0)),
         depth: () => Promise.resolve(ok(0)),
         statusCounts: () => Promise.resolve(ok({ pending: 0, inFlight: 0, failed: 0, delivered: 0, expired: 0 })),
+        recoverInFlight: () => Promise.resolve(ok(0)),
     });
 }

package/node_modules/@comis/core/dist/ports/index.d.ts

@@ -16,8 +16,12 @@ export type { DeviceIdentity, DeviceIdentityPort, PairingRequest, PairedDevice,
 export type { OutputGuardPort, OutputGuardFinding, OutputGuardResult, } from "./output-guard.js";
 export type { SecretStorePort, SecretMetadata, } from "./secret-store.js";
 export type { CredentialMappingPort } from "./credential-mapping.js";
+export type { OAuthCredentialStorePort, OAuthProfile } from "./oauth-credential-store.js";
+export { validateProfileId, PROFILE_ID_RE } from "./oauth-credential-store.js";
 export type { Provider, ImageGenInput, ImageGenOutput, ImageGenerationPort } from "./provider.js";
 export type { DeliveryQueuePort, DeliveryQueueEntry, DeliveryQueueEnqueueInput, DeliveryQueueStatusCounts, } from "./delivery-queue.js";
 export { createNoOpDeliveryQueue } from "./delivery-queue.js";
 export type { DeliveryMirrorPort, DeliveryMirrorEntry, DeliveryMirrorRecordInput, } from "./delivery-mirror.js";
 export { createNoOpDeliveryMirror } from "./delivery-mirror.js";
+export type { ToolCapabilityPort, PromptSkillCapability, CapabilitySourceRef, ClusterConfig, McpServerHint, SkillHint, } from "./tool-capability.js";
+export { createNoOpCapabilityPort } from "./no-op-tool-capability.js";

package/node_modules/@comis/core/dist/ports/index.js

@@ -1,5 +1,10 @@
 // SPDX-License-Identifier: Apache-2.0
 // Port interfaces - Hexagonal architecture boundaries
 export { ChannelCapabilitySchema } from "./channel-plugin.js";
+export { validateProfileId, PROFILE_ID_RE } from "./oauth-credential-store.js";
 export { createNoOpDeliveryQueue } from "./delivery-queue.js";
 export { createNoOpDeliveryMirror } from "./delivery-mirror.js";
+export { createNoOpCapabilityPort } from "./no-op-tool-capability.js";
+// NOTE: the test-only stub factory in `__test-helpers/` is intentionally NOT
+// re-exported here. It must NEVER appear on this barrel (the architecture-grep
+// test enforces this).

package/node_modules/@comis/core/dist/ports/no-op-tool-capability.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Production no-op factory for ToolCapabilityPort.
+ *
+ * Returns an empty-defaults adapter that is safe to inject from any production
+ * code path. Used as the production no-op until the live daemon-side adapter
+ * is wired.
+ *
+ * With the no-op port:
+ * - The capability-index renderer sees no clusters/skills/servers -> returns
+ *   empty text -> executor-prompt-runner.ts filters it out.
+ * - The install-detour parser sees no overlaps -> no events emitted, no hints,
+ *   no soft-stop refusals.
+ * Both subsystems are inert but not broken.
+ *
+ * IMPORTANT -- boundary discipline:
+ * Test code must NOT import this. Tests use the test-only stub factory in
+ * `__test-helpers/` instead. The architecture-grep test in
+ * `packages/<pkg>/src/__tests__/architecture.test.ts` enforces this both ways.
+ *
+ * @module
+ */
+import type { ToolCapabilityPort } from "./tool-capability.js";
+/**
+ * Production no-op factory. Production-OK; safe to import from any production
+ * code path. Tests must NOT import this -- use the test-only stub factory in
+ * `__test-helpers/` instead.
+ *
+ * @returns A frozen ToolCapabilityPort with empty defaults for all 9 methods.
+ */
+export declare function createNoOpCapabilityPort(): ToolCapabilityPort;

package/node_modules/@comis/core/dist/ports/no-op-tool-capability.js

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Production no-op factory for ToolCapabilityPort.
+ *
+ * Returns an empty-defaults adapter that is safe to inject from any production
+ * code path. Used as the production no-op until the live daemon-side adapter
+ * is wired.
+ *
+ * With the no-op port:
+ * - The capability-index renderer sees no clusters/skills/servers -> returns
+ *   empty text -> executor-prompt-runner.ts filters it out.
+ * - The install-detour parser sees no overlaps -> no events emitted, no hints,
+ *   no soft-stop refusals.
+ * Both subsystems are inert but not broken.
+ *
+ * IMPORTANT -- boundary discipline:
+ * Test code must NOT import this. Tests use the test-only stub factory in
+ * `__test-helpers/` instead. The architecture-grep test in
+ * `packages/<pkg>/src/__tests__/architecture.test.ts` enforces this both ways.
+ *
+ * @module
+ */
+// Module-level constants -- returned by every call so callers can rely on
+// reference-stability for cheap equality checks.
+const EMPTY_ALIAS_MAP = new Map();
+const EMPTY_SERVERS = Object.freeze([]);
+const EMPTY_SKILLS = Object.freeze([]);
+/**
+ * Production no-op factory. Production-OK; safe to import from any production
+ * code path. Tests must NOT import this -- use the test-only stub factory in
+ * `__test-helpers/` instead.
+ *
+ * @returns A frozen ToolCapabilityPort with empty defaults for all 9 methods.
+ */
+export function createNoOpCapabilityPort() {
+    return Object.freeze({
+        isCapabilityIndexEnabled: () => true,
+        getInstallDetourMode: () => "advise",
+        getBuiltinCluster: () => undefined,
+        getClusterConfig: () => undefined,
+        getMcpServerHint: () => undefined,
+        getSkillHint: () => undefined,
+        getPackageAliasMap: () => EMPTY_ALIAS_MAP,
+        getConnectedMcpServers: () => EMPTY_SERVERS,
+        getPromptSkillCapabilities: () => EMPTY_SKILLS,
+    });
+}

package/node_modules/@comis/core/dist/ports/oauth-credential-store.d.ts

@@ -0,0 +1,64 @@
+import type { Result } from "@comis/shared";
+/**
+ * Persisted OAuth profile shape.
+ *
+ * Maps to pi-ai's OAuthCredentials plus comis-managed metadata
+ * (provider, profileId, identity claims). The expires field is
+ * milliseconds since epoch (matches pi-ai — the JWT exp claim is
+ * seconds, but pi-ai stores ms).
+ */
+export interface OAuthProfile {
+    /** OAuth provider id (e.g. "openai-codex", "anthropic"). */
+    provider: string;
+    /** Canonical profile identifier in the form "<provider>:<identity>". */
+    profileId: string;
+    /** OAuth access token (JWT for OpenAI Codex). NEVER log this value. */
+    access: string;
+    /** OAuth refresh token. NEVER log this value. */
+    refresh: string;
+    /** Access-token expiry in ms since epoch. */
+    expires: number;
+    /** Provider-specific account identifier (e.g. Codex chatgpt_account_id). */
+    accountId?: string;
+    /** Identity email (when JWT decode produced one). */
+    email?: string;
+    /** Human-friendly display name (when available). */
+    displayName?: string;
+    /** Schema version. Currently always 1. Hard-fail on mismatch. */
+    version: 1;
+}
+/**
+ * OAuthCredentialStorePort: Hexagonal architecture boundary for mutable
+ * OAuth credential persistence.
+ *
+ * Distinct from SecretStorePort (which is read-only). Every storage
+ * backend (file-based, encrypted SQLite) implements this interface.
+ *
+ * All operations are asynchronous and return Result<T, Error> for
+ * explicit error handling — never throw at the public boundary.
+ */
+export interface OAuthCredentialStorePort {
+    get(profileId: string): Promise<Result<OAuthProfile | undefined, Error>>;
+    set(profileId: string, profile: OAuthProfile): Promise<Result<void, Error>>;
+    delete(profileId: string): Promise<Result<boolean, Error>>;
+    list(filter?: {
+        provider?: string;
+    }): Promise<Result<OAuthProfile[], Error>>;
+    has(profileId: string): Promise<Result<boolean, Error>>;
+}
+/**
+ * Profile-ID format regex: <provider>:<identity>.
+ * Provider must start with letter; alphanumeric + hyphen only.
+ * Identity is non-empty and may contain @, ., etc.
+ */
+export declare const PROFILE_ID_RE: RegExp;
+/**
+ * Validate a profile-ID string against the <provider>:<identity> shape.
+ * Returns parsed parts on success; an Error describing the violation otherwise.
+ * Defense-in-depth: also rejects identities containing path-traversal or
+ * control characters (newline, null, slash, backslash, ..).
+ */
+export declare function validateProfileId(id: string): Result<{
+    provider: string;
+    identity: string;
+}, Error>;

package/node_modules/@comis/core/dist/ports/oauth-credential-store.js

@@ -0,0 +1,37 @@
+import { ok, err } from "@comis/shared";
+/**
+ * Profile-ID format regex: <provider>:<identity>.
+ * Provider must start with letter; alphanumeric + hyphen only.
+ * Identity is non-empty and may contain @, ., etc.
+ */
+export const PROFILE_ID_RE = /^[a-z][a-z0-9-]*:.+$/i;
+/**
+ * Validate a profile-ID string against the <provider>:<identity> shape.
+ * Returns parsed parts on success; an Error describing the violation otherwise.
+ * Defense-in-depth: also rejects identities containing path-traversal or
+ * control characters (newline, null, slash, backslash, ..).
+ */
+export function validateProfileId(id) {
+    if (typeof id !== "string" || id.length === 0) {
+        return err(new Error("Invalid profile ID: empty or non-string"));
+    }
+    if (!PROFILE_ID_RE.test(id)) {
+        return err(new Error('Invalid profile ID "' + id + '": expected "<provider>:<identity>"'));
+    }
+    const colonIdx = id.indexOf(":");
+    const provider = id.slice(0, colonIdx);
+    const identity = id.slice(colonIdx + 1);
+    if (!provider)
+        return err(new Error('Invalid profile ID "' + id + '": empty provider'));
+    if (!identity)
+        return err(new Error('Invalid profile ID "' + id + '": empty identity'));
+    if (identity.includes("\0") ||
+        identity.includes("\n") ||
+        identity.includes("\r") ||
+        identity.includes("..") ||
+        identity.includes("/") ||
+        identity.includes("\\")) {
+        return err(new Error('Invalid profile ID "' + id + '": identity contains forbidden characters'));
+    }
+    return ok({ provider, identity });
+}

package/node_modules/@comis/core/dist/ports/tool-capability.d.ts

@@ -0,0 +1,165 @@
+/**
+ * ToolCapabilityPort -- hexagonal architecture boundary for the v1.1 capability layer.
+ *
+ * Provides both a static config-derived view (clusters, hints, aliases) AND a
+ * live runtime view (connected MCP servers, visible prompt skills). One port,
+ * two views -- exec runs per-tool-call (not per-turn) and needs a live getter.
+ *
+ * Adapters: live daemon-side adapter, createNoOpCapabilityPort (production
+ * no-op, this package), test-only stub factory (lives in `__test-helpers/` --
+ * production source MUST NOT import).
+ *
+ * @module
+ */
+/**
+ * Capability source reference -- discriminated union pointing at either a
+ * connected MCP server or a visible prompt skill. Used in the package-alias
+ * map to resolve "import yfinance" or "pip install pandas" back to a connected
+ * tool/skill that should be preferred over the install.
+ */
+export type CapabilitySourceRef = {
+    readonly type: "mcp";
+    readonly name: string;
+} | {
+    readonly type: "skill";
+    readonly name: string;
+};
+/**
+ * Merged capability view of a single visible prompt skill.
+ *
+ * All operator overrides, manifest `comis.capability` values, and skill-key
+ * fallbacks are pre-merged in the adapter (precedence:
+ * operator(skillKey) > operator(skillName) > comis.capability > fallback).
+ * Consumers see the final merged shape.
+ */
+export interface PromptSkillCapability {
+    /** Stable skill identifier used by the agent runtime. */
+    readonly name: string;
+    /** Optional canonical key (`<author>::<slug>`) for cross-host portability. */
+    readonly skillKey?: string;
+    /** Human-readable description (falls back to manifest description if no override). */
+    readonly description: string;
+    /** Cluster ID for capability-index grouping (e.g. "data-fetching-financial"). */
+    readonly cluster?: string;
+    /** Operator-tunable display summary; falls back to description when absent. */
+    readonly summary?: string;
+    /** Package names this skill replaces (for install-detour overlap detection). */
+    readonly replacesPackages: readonly string[];
+    /** Where the skill was discovered from. */
+    readonly source?: "bundled" | "workspace" | "local";
+}
+/**
+ * Cluster metadata used by the capability-index renderer.
+ */
+export interface ClusterConfig {
+    readonly label: string;
+    readonly priority: number;
+    readonly preferOverInstalls: boolean;
+}
+/**
+ * Hint metadata for a connected MCP server.
+ */
+export interface McpServerHint {
+    readonly cluster: string;
+    readonly description: string;
+    readonly replacesPackages: readonly string[];
+}
+/**
+ * Hint metadata for a visible prompt skill (operator-supplied overrides).
+ */
+export interface SkillHint {
+    readonly cluster: string;
+    readonly description?: string;
+    readonly replacesPackages: readonly string[];
+}
+/**
+ * The capability port. Covers both the static config-derived view and a live
+ * runtime view. Adapter implementation lives in @comis/daemon; the in-package
+ * createNoOpCapabilityPort serves as the production no-op.
+ *
+ * Adapters: createNoOpCapabilityPort (production no-op, this package),
+ * test-only stub factory in `__test-helpers/`, live daemon-side adapter.
+ */
+export interface ToolCapabilityPort {
+    /**
+     * Whether the per-turn capability index renderer should fire at all. When
+     * false, the renderer returns empty text and the executor-prompt-runner
+     * filters it out.
+     *
+     * @returns `true` if the operator has enabled the capability index.
+     */
+    isCapabilityIndexEnabled(): boolean;
+    /**
+     * Install-detour mode for pip/npm/pnpm/yarn detection.
+     * - `observe`: log only, no agent-visible response.
+     * - `advise`: emit a non-blocking advisory next turn.
+     * - `soft-stop`: refuse the exec call with an operator-overridable message.
+     *
+     * @returns The currently-configured mode.
+     */
+    getInstallDetourMode(): "observe" | "advise" | "soft-stop";
+    /**
+     * Cluster ID for a builtin tool (exec, read, write, ...).
+     *
+     * @param toolName - The builtin tool's registered name.
+     * @returns The cluster ID, or undefined if the tool is uncategorized.
+     */
+    getBuiltinCluster(toolName: string): string | undefined;
+    /**
+     * Cluster metadata (label, priority, preferOverInstalls flag).
+     *
+     * @param clusterId - The cluster identifier.
+     * @returns The cluster config, or undefined if the cluster is unknown.
+     */
+    getClusterConfig(clusterId: string): ClusterConfig | undefined;
+    /**
+     * Hint metadata for a connected MCP server (operator-supplied overrides).
+     *
+     * @param serverName - The MCP server name (sanitized form).
+     * @returns The hint, or undefined if no operator override exists.
+     */
+    getMcpServerHint(serverName: string): McpServerHint | undefined;
+    /**
+     * Hint metadata for a visible prompt skill (operator-supplied overrides).
+     *
+     * @param skillName - The skill's runtime name.
+     * @param skillKey - Optional canonical key (`<author>::<slug>`).
+     * @returns The hint, or undefined if no operator override exists.
+     */
+    getSkillHint(skillName: string, skillKey?: string): SkillHint | undefined;
+    /**
+     * Pre-normalized package alias map (PEP-503-like keys for Python:
+     * lowercase, `_` and `.` collapsed to `-`).
+     *
+     * Build fresh on each call (no memoization in v1.1) -- visible skills can
+     * change mid-session (skill discovery, allow/deny edits), connected MCP
+     * servers can connect/disconnect, capturing at construction would freeze
+     * stale state.
+     *
+     * @returns A read-only map keyed by normalized package name pointing at
+     *   the matching MCP server or prompt skill.
+     */
+    getPackageAliasMap(): ReadonlyMap<string, CapabilitySourceRef>;
+    /**
+     * Currently-connected MCP server names (sanitized form).
+     *
+     * @returns A read-only array of server names. Order is undefined.
+     */
+    getConnectedMcpServers(): readonly string[];
+    /**
+     * Visible eligible prompt skills with merged capability metadata.
+     * Filters: allowedSkills/deniedSkills, runtime eligibility (os/bins/env),
+     * AND `disableModelInvocation !== true`.
+     * Merging: operator(skillKey) > operator(skillName) > comis.capability > fallback.
+     *
+     * IMPORTANT -- cache fence:
+     * This method MUST NOT be consumed by `assembleRichSystemPrompt`'s
+     * `assemblerParams` in `packages/agent/src/executor/prompt-assembly.ts`.
+     * If a skill discovery sweep runs between turns, the cached system-prompt
+     * prefix MUST stay byte-identical. Consumers: per-turn capability index
+     * renderer + install-detour parser ONLY.
+     *
+     * @returns A read-only array of merged capability views.
+     */
+    getPromptSkillCapabilities(): readonly PromptSkillCapability[];
+}

package/node_modules/@comis/core/dist/ports/tool-capability.js

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * ToolCapabilityPort -- hexagonal architecture boundary for the v1.1 capability layer.
+ *
+ * Provides both a static config-derived view (clusters, hints, aliases) AND a
+ * live runtime view (connected MCP servers, visible prompt skills). One port,
+ * two views -- exec runs per-tool-call (not per-turn) and needs a live getter.
+ *
+ * Adapters: live daemon-side adapter, createNoOpCapabilityPort (production
+ * no-op, this package), test-only stub factory (lives in `__test-helpers/` --
+ * production source MUST NOT import).
+ *
+ * @module
+ */
+export {};

package/node_modules/@comis/core/dist/security/audit.d.ts

@@ -7,35 +7,24 @@ import type { ActionClassification } from "./action-classifier.js";
  * classification, outcome, tracing, and timing information.
  */
 export declare const AuditEventSchema: z.ZodObject<{
-    /** Unique event identifier (UUIDv4). */
     id: z.ZodGUID;
-    /** ISO 8601 timestamp of when the event occurred. */
     timestamp: z.ZodISODateTime;
-    /** Tenant identifier for multi-tenant isolation. */
     tenantId: z.ZodString;
-    /** Agent that performed the action (may be system). */
     agentId: z.ZodString;
-    /** User who triggered or owns the action (may be "system"). */
     userId: z.ZodString;
-    /** The action that was performed (e.g., "file.delete"). */
     actionType: z.ZodString;
-    /** Risk classification of the action. */
     classification: z.ZodEnum<{
         read: "read";
         mutate: "mutate";
         destructive: "destructive";
     }>;
-    /** Whether the action succeeded or failed. */
     outcome: z.ZodEnum<{
         success: "success";
         failure: "failure";
         denied: "denied";
     }>;
-    /** Arbitrary metadata about the event. */
     metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    /** Distributed tracing identifier for correlating events. */
     traceId: z.ZodOptional<z.ZodString>;
-    /** Duration of the action in milliseconds. */
     duration: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
 /** TypeScript type inferred from the AuditEvent Zod schema. */

package/node_modules/@comis/core/dist/tool-metadata.d.ts

@@ -8,6 +8,24 @@
  * Registry supports incremental registration via spread-merge semantics:
  * different sources can register different fields for the same tool.
  */
+/**
+ * Capability metadata for a builtin/platform tool -- used by the v1.1 capability
+ * layer to route tools into clusters and detect install-detour overlap.
+ *
+ * All fields optional. Operators may override `cluster` per-tool via
+ * `tooling.capabilityClusters.builtinAssignments[toolName]`. The metadata
+ * default applies when no operator override is present.
+ *
+ * `getBuiltinCluster` precedence: operator override > metadata default > undefined.
+ */
+export interface ToolCapabilityMetadata {
+    /** Cluster ID this tool belongs to (e.g., "data-fetching-financial"). */
+    readonly cluster?: string;
+    /** Operator-tunable display summary; falls back to tool description if absent. */
+    readonly summary?: string;
+    /** Package names this tool replaces (for install-detour overlap detection). */
+    readonly replacesPackages?: readonly string[];
+}
 /** Per-tool metadata stored in the side-channel registry. All fields optional. */
 export interface ComisToolMetadata {
     /** Per-tool result size cap in characters. */
@@ -22,12 +40,34 @@ export interface ComisToolMetadata {
     outputSchema?: Record<string, unknown>;
     /** Tool names that should be co-discovered whenever this tool is discovered (bidirectional). */
     coDiscoverWith?: string[];
+    /** Valid `action` enum values for action-discriminated tools. Used by the
+     *  generic schema-validator in @comis/skills/bridge to gate unknown actions
+     *  before the per-tool validateInput runs. Field shape mirrors
+     *  `ManagedSectionRedirect.schemaFragment.actions` in
+     *  @comis/core/src/config/managed-sections.ts so cross-consistency tests
+     *  can compare them. */
+    validActions?: readonly string[];
+    /** Full set of accepted top-level parameter keys. Unknown keys trigger a
+     *  Levenshtein "did you mean" hint via the schema-validator. Action-
+     *  discriminated tools list the union across all actions; non-discriminated
+     *  tools list every accepted key. Omit when the tool's params are open-
+     *  ended (e.g. exec). */
+    validKeys?: readonly string[];
+    /** Required keys per action value (action-discriminated tools only). Maps
+     *  each `action` literal to the list of params that MUST be present beyond
+     *  `action` itself. Field name + shape mirror
+     *  `ManagedSectionRedirect.schemaFragment.requiredByAction` in
+     *  @comis/core/src/config/managed-sections.ts. Omit actions with no
+     *  required fields beyond `action`. */
+    requiredByAction?: Readonly<Record<string, readonly string[]>>;
     /** Pre-flight input validator. Returns error string on failure, undefined on success. */
     validateInput?: (params: Record<string, unknown>) => string | undefined | Promise<string | undefined>;
+    /** Capability metadata for tool-first routing (v1.1). */
+    capability?: ToolCapabilityMetadata;
 }
 /**
  * Register metadata for a tool. Merges with any existing metadata via spread,
- * allowing incremental registration from different phases.
+ * allowing incremental registration from different sources.
  */
 export declare function registerToolMetadata(name: string, meta: ComisToolMetadata): void;
 /**

package/node_modules/@comis/core/dist/tool-metadata.js

@@ -15,7 +15,7 @@
 const registry = new Map();
 /**
  * Register metadata for a tool. Merges with any existing metadata via spread,
- * allowing incremental registration from different phases.
+ * allowing incremental registration from different sources.
  */
 export function registerToolMetadata(name, meta) {
     registry.set(name, { ...registry.get(name), ...meta });

package/node_modules/@comis/core/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@comis/core",
   "private": true,
-  "version": "1.0.34",
+  "version": "1.0.37",
   "author": "Moshe Anconina",
   "license": "Apache-2.0",
   "description": "Core domain types, ports, event bus, security, and config for Comis",

package/node_modules/@comis/daemon/bundled-skills/skill-creator/scripts/validate-skill.py

@@ -31,7 +31,7 @@ VALID_TOP_FIELDS = {
 }
 
 VALID_COMIS_FIELDS = {
-    "os", "requires", "skill-key", "primary-env", "command-dispatch",
+    "os", "requires", "skill-key", "primary-env", "command-dispatch", "capability",
 }
 
 VALID_PERMISSIONS_FIELDS = {"fsRead", "fsWrite", "net", "env"}