comisai 1.0.19 → 1.0.22

package/node_modules/@comis/core/dist/config/managed-sections.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Single source of truth: which immutable config sections delegate to which
+ * dedicated management tool, and what an LLM-readable redirect looks like.
+ *
+ * gateway/apply, gateway/patch, and config.* RPC immutability guards all
+ * consume this module so their hints stay in sync. Adding a new managed
+ * section is a one-line entry here -- no code changes anywhere else.
+ *
+ * Designed to be model-agnostic: the hint includes the tool name, the
+ * discover_tools call to load it, and a parameter-correct example call body
+ * (verified against each tool's TypeBox schema). Every capable LLM --
+ * Opus/Sonnet/Haiku, GPT-5, Gemini 2.5/3 Flash/Pro, Mistral -- can imitate
+ * the JSON example verbatim without further prompting.
+ *
+ * @module
+ */
+/** A single redirect entry: which tool, and a parameter-correct example. */
+export interface ManagedSectionRedirect {
+    /** Path prefix that triggers this redirect (e.g., "agents", "integrations.mcp.servers"). */
+    pathPrefix: string;
+    /** Tool name (matches the registered AgentTool name). */
+    tool: string;
+    /** One-line description that includes the tool's full action list. */
+    description: string;
+    /**
+     * Concrete example arguments for the most common create-equivalent action.
+     * Shape MUST match the tool's TypeBox parameter schema exactly -- verified
+     * against the tool source as of this commit. Omit when the tool has no
+     * "create" semantics (e.g., channels_manage cannot add new platform types).
+     */
+    exampleArgs?: Record<string, unknown>;
+    /**
+     * True when the tool fully replaces gateway-patch for this section
+     * (create + update + delete). False when it can only operate on entries
+     * already present in config.
+     */
+    fullyManaged: boolean;
+}
+/**
+ * Registered managed sections.
+ *
+ * Order matters: longest pathPrefix first, so getManagedSectionRedirect picks
+ * the most specific match (e.g., "integrations.mcp.servers" wins over a
+ * hypothetical "integrations" entry).
+ */
+export declare const MANAGED_SECTIONS: readonly ManagedSectionRedirect[];
+/**
+ * Resolve the management redirect for a given section/key path.
+ *
+ * Picks the longest matching pathPrefix. Matches when fullPath equals or is a
+ * child of a redirect's pathPrefix. Returns undefined when no dedicated tool
+ * covers this path -- callers fall back to the generic immutable message.
+ */
+export declare function getManagedSectionRedirect(section: string | undefined, key?: string): ManagedSectionRedirect | undefined;
+/**
+ * Format an LLM-readable hint for an immutability rejection.
+ *
+ * The output uses an explicit two-step "Recovery:" framing because smaller
+ * models (Haiku 4.5, Gemini Flash, GPT-OSS-20b) parse numbered steps more
+ * reliably than prose. The example call is JSON-stringified compactly so it
+ * can be copy-pasted into the next tool invocation.
+ *
+ * @param redirect - The matched managed-section entry
+ * @param mutablePaths - Optional override paths for in-place patching of
+ *                      EXISTING entries (from getMutableOverridesForSection)
+ */
+export declare function formatRedirectHint(redirect: ManagedSectionRedirect, mutablePaths?: readonly string[]): string;

package/node_modules/@comis/core/dist/config/managed-sections.js

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Single source of truth: which immutable config sections delegate to which
+ * dedicated management tool, and what an LLM-readable redirect looks like.
+ *
+ * gateway/apply, gateway/patch, and config.* RPC immutability guards all
+ * consume this module so their hints stay in sync. Adding a new managed
+ * section is a one-line entry here -- no code changes anywhere else.
+ *
+ * Designed to be model-agnostic: the hint includes the tool name, the
+ * discover_tools call to load it, and a parameter-correct example call body
+ * (verified against each tool's TypeBox schema). Every capable LLM --
+ * Opus/Sonnet/Haiku, GPT-5, Gemini 2.5/3 Flash/Pro, Mistral -- can imitate
+ * the JSON example verbatim without further prompting.
+ *
+ * @module
+ */
+/**
+ * Registered managed sections.
+ *
+ * Order matters: longest pathPrefix first, so getManagedSectionRedirect picks
+ * the most specific match (e.g., "integrations.mcp.servers" wins over a
+ * hypothetical "integrations" entry).
+ */
+export const MANAGED_SECTIONS = [
+    {
+        pathPrefix: "integrations.mcp.servers",
+        tool: "mcp_manage",
+        description: "Manage MCP server connections (list, status, connect, disconnect, reconnect).",
+        // Flat parameter shape -- verified against mcp-manage-tool.ts McpManageToolParams.
+        exampleArgs: {
+            action: "connect",
+            name: "<server-name>",
+            transport: "stdio",
+            command: "<command>",
+            args: [],
+        },
+        fullyManaged: true,
+    },
+    {
+        pathPrefix: "gateway.tokens",
+        tool: "tokens_manage",
+        description: "Manage gateway tokens (list, create, revoke, rotate).",
+        // Verified against tokens-manage-tool.ts TokensManageToolParams.
+        exampleArgs: { action: "create", token_id: "<token-id>", scopes: ["rpc", "ws"] },
+        fullyManaged: true,
+    },
+    {
+        pathPrefix: "channels",
+        tool: "channels_manage",
+        description: "Manage channel adapters (list, get, enable, disable, restart, configure).",
+        // No exampleArgs -- no create-equivalent action; channels are configured
+        // via operator config + media-setting toggles only.
+        fullyManaged: false,
+    },
+    {
+        pathPrefix: "agents",
+        tool: "agents_manage",
+        description: "Manage agent fleet (create, get, update, delete, suspend, resume).",
+        // Verified against agents-manage-tool.ts AgentsManageToolParams.
+        exampleArgs: {
+            action: "create",
+            agent_id: "<new-agent-id>",
+            config: {
+                name: "<display-name>",
+                model: "<model-id>",
+                provider: "<provider>",
+                maxSteps: 100,
+            },
+        },
+        fullyManaged: true,
+    },
+];
+/**
+ * Resolve the management redirect for a given section/key path.
+ *
+ * Picks the longest matching pathPrefix. Matches when fullPath equals or is a
+ * child of a redirect's pathPrefix. Returns undefined when no dedicated tool
+ * covers this path -- callers fall back to the generic immutable message.
+ */
+export function getManagedSectionRedirect(section, key) {
+    if (!section)
+        return undefined;
+    const fullPath = key ? `${section}.${key}` : section;
+    let best;
+    for (const candidate of MANAGED_SECTIONS) {
+        const matches = fullPath === candidate.pathPrefix ||
+            fullPath.startsWith(candidate.pathPrefix + ".");
+        if (matches && (!best || candidate.pathPrefix.length > best.pathPrefix.length)) {
+            best = candidate;
+        }
+    }
+    return best;
+}
+/**
+ * Format an LLM-readable hint for an immutability rejection.
+ *
+ * The output uses an explicit two-step "Recovery:" framing because smaller
+ * models (Haiku 4.5, Gemini Flash, GPT-OSS-20b) parse numbered steps more
+ * reliably than prose. The example call is JSON-stringified compactly so it
+ * can be copy-pasted into the next tool invocation.
+ *
+ * @param redirect - The matched managed-section entry
+ * @param mutablePaths - Optional override paths for in-place patching of
+ *                      EXISTING entries (from getMutableOverridesForSection)
+ */
+export function formatRedirectHint(redirect, mutablePaths) {
+    const parts = [];
+    parts.push(`Use the "${redirect.tool}" tool: ${redirect.description}`);
+    if (redirect.exampleArgs) {
+        const example = JSON.stringify(redirect.exampleArgs);
+        parts.push(`Recovery: (1) call discover_tools("${redirect.tool}") to load the schema, then (2) call ${redirect.tool}(${example}).`);
+    }
+    else {
+        parts.push(`Load it via discover_tools("${redirect.tool}") if not yet available.`);
+    }
+    if (mutablePaths && mutablePaths.length > 0) {
+        parts.push(`For in-place updates of an entry that ALREADY exists, gateway/patch also accepts these specific paths: ${mutablePaths.join(", ")}.`);
+    }
+    if (!redirect.fullyManaged) {
+        parts.push(`Note: this tool operates on entries already present in config; adding brand-new platform types still requires operator config edits.`);
+    }
+    return parts.join(" ");
+}

package/node_modules/@comis/core/dist/config/schema-agent.d.ts

@@ -391,6 +391,12 @@ export declare const ContextEngineConfigSchema: z.ZodObject<{
     }>>;
     /** Number of recent assistant turns that retain thinking blocks (older turns get stripped). */
     thinkingKeepTurns: z.ZodDefault<z.ZodNumber>;
+    /** Idle gap (ms) above which signed thinking state is treated as drifted and
+     *  scrubbed pre-send to avoid provider replay-rejection. Default 30 min —
+     *  below long-TTL caches and below the 74-min production incident gap. Also
+     *  triggers on model id / provider / api change (those checks are
+     *  unconditional regardless of this idle threshold). Range: 1 min .. 24 h. */
+    replayDriftIdleMs: z.ZodDefault<z.ZodNumber>;
     /** Model for LLM compaction in "provider:modelId" format. Defaults to Haiku for cost efficiency. Empty string falls through to session model. */
     compactionModel: z.ZodDefault<z.ZodString>;
     /** Minimum age (in tool result positions) before content is eligible for dead content eviction. */
@@ -550,9 +556,9 @@ export declare const BootstrapConfigSchema: z.ZodObject<{
     maxChars: z.ZodDefault<z.ZodNumber>;
     /** System prompt verbosity mode: full (all sections), minimal (sub-agents), none (identity only) */
     promptMode: z.ZodDefault<z.ZodEnum<{
-        none: "none";
-        full: "full";
         minimal: "minimal";
+        full: "full";
+        none: "none";
     }>>;
     /** When true, USER.md is excluded from bootstrap context in group chat sessions (privacy). Default: true. */
     groupChatFiltering: z.ZodDefault<z.ZodBoolean>;
@@ -826,9 +832,9 @@ export declare const AgentConfigSchema: z.ZodObject<{
         maxChars: z.ZodDefault<z.ZodNumber>;
         /** System prompt verbosity mode: full (all sections), minimal (sub-agents), none (identity only) */
         promptMode: z.ZodDefault<z.ZodEnum<{
-            none: "none";
-            full: "full";
             minimal: "minimal";
+            full: "full";
+            none: "none";
         }>>;
         /** When true, USER.md is excluded from bootstrap context in group chat sessions (privacy). Default: true. */
         groupChatFiltering: z.ZodDefault<z.ZodBoolean>;
@@ -1179,9 +1185,9 @@ export declare const PerAgentConfigSchema: z.ZodObject<{
         maxChars: z.ZodDefault<z.ZodNumber>;
         /** System prompt verbosity mode: full (all sections), minimal (sub-agents), none (identity only) */
         promptMode: z.ZodDefault<z.ZodEnum<{
-            none: "none";
-            full: "full";
             minimal: "minimal";
+            full: "full";
+            none: "none";
         }>>;
         /** When true, USER.md is excluded from bootstrap context in group chat sessions (privacy). Default: true. */
         groupChatFiltering: z.ZodDefault<z.ZodBoolean>;
@@ -1288,11 +1294,11 @@ export declare const PerAgentConfigSchema: z.ZodObject<{
         }, z.core.$strict>>;
         toolPolicy: z.ZodDefault<z.ZodObject<{
             profile: z.ZodDefault<z.ZodEnum<{
-                full: "full";
                 minimal: "minimal";
                 coding: "coding";
                 messaging: "messaging";
                 supervisor: "supervisor";
+                full: "full";
             }>>;
             allow: z.ZodDefault<z.ZodArray<z.ZodString>>;
             deny: z.ZodDefault<z.ZodArray<z.ZodString>>;
@@ -1591,6 +1597,12 @@ export declare const PerAgentConfigSchema: z.ZodObject<{
         }>>;
         /** Number of recent assistant turns that retain thinking blocks (older turns get stripped). */
         thinkingKeepTurns: z.ZodDefault<z.ZodNumber>;
+        /** Idle gap (ms) above which signed thinking state is treated as drifted and
+         *  scrubbed pre-send to avoid provider replay-rejection. Default 30 min —
+         *  below long-TTL caches and below the 74-min production incident gap. Also
+         *  triggers on model id / provider / api change (those checks are
+         *  unconditional regardless of this idle threshold). Range: 1 min .. 24 h. */
+        replayDriftIdleMs: z.ZodDefault<z.ZodNumber>;
         /** Model for LLM compaction in "provider:modelId" format. Defaults to Haiku for cost efficiency. Empty string falls through to session model. */
         compactionModel: z.ZodDefault<z.ZodString>;
         /** Minimum age (in tool result positions) before content is eligible for dead content eviction. */
@@ -1853,9 +1865,9 @@ export declare const AgentsMapSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
         maxChars: z.ZodDefault<z.ZodNumber>;
         /** System prompt verbosity mode: full (all sections), minimal (sub-agents), none (identity only) */
         promptMode: z.ZodDefault<z.ZodEnum<{
-            none: "none";
-            full: "full";
             minimal: "minimal";
+            full: "full";
+            none: "none";
         }>>;
         /** When true, USER.md is excluded from bootstrap context in group chat sessions (privacy). Default: true. */
         groupChatFiltering: z.ZodDefault<z.ZodBoolean>;
@@ -1962,11 +1974,11 @@ export declare const AgentsMapSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
         }, z.core.$strict>>;
         toolPolicy: z.ZodDefault<z.ZodObject<{
             profile: z.ZodDefault<z.ZodEnum<{
-                full: "full";
                 minimal: "minimal";
                 coding: "coding";
                 messaging: "messaging";
                 supervisor: "supervisor";
+                full: "full";
             }>>;
             allow: z.ZodDefault<z.ZodArray<z.ZodString>>;
             deny: z.ZodDefault<z.ZodArray<z.ZodString>>;
@@ -2265,6 +2277,12 @@ export declare const AgentsMapSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
         }>>;
         /** Number of recent assistant turns that retain thinking blocks (older turns get stripped). */
         thinkingKeepTurns: z.ZodDefault<z.ZodNumber>;
+        /** Idle gap (ms) above which signed thinking state is treated as drifted and
+         *  scrubbed pre-send to avoid provider replay-rejection. Default 30 min —
+         *  below long-TTL caches and below the 74-min production incident gap. Also
+         *  triggers on model id / provider / api change (those checks are
+         *  unconditional regardless of this idle threshold). Range: 1 min .. 24 h. */
+        replayDriftIdleMs: z.ZodDefault<z.ZodNumber>;
         /** Model for LLM compaction in "provider:modelId" format. Defaults to Haiku for cost efficiency. Empty string falls through to session model. */
         compactionModel: z.ZodDefault<z.ZodString>;
         /** Minimum age (in tool result positions) before content is eligible for dead content eviction. */

package/node_modules/@comis/core/dist/config/schema-agent.js

@@ -288,6 +288,12 @@ export const ContextEngineConfigSchema = z.strictObject({
     // --- Shared (both modes) ---
     /** Number of recent assistant turns that retain thinking blocks (older turns get stripped). */
     thinkingKeepTurns: z.number().int().min(1).max(50).default(10),
+    /** Idle gap (ms) above which signed thinking state is treated as drifted and
+     *  scrubbed pre-send to avoid provider replay-rejection. Default 30 min —
+     *  below long-TTL caches and below the 74-min production incident gap. Also
+     *  triggers on model id / provider / api change (those checks are
+     *  unconditional regardless of this idle threshold). Range: 1 min .. 24 h. */
+    replayDriftIdleMs: z.number().int().min(60_000).max(24 * 60 * 60_000).default(30 * 60_000),
     /** Model for LLM compaction in "provider:modelId" format. Defaults to Haiku for cost efficiency. Empty string falls through to session model. */
     compactionModel: z.string().default("anthropic:claude-haiku-4-5-20250929"),
     /** Minimum age (in tool result positions) before content is eligible for dead content eviction. */

package/node_modules/@comis/core/dist/config/schema-gateway.d.ts

@@ -29,9 +29,9 @@ export declare const GatewayTokenSchema: z.ZodObject<{
     /** The secret value (min 32 chars; resolved at runtime if omitted; string or SecretRef) */
     secret: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
         source: z.ZodEnum<{
-            env: "env";
             file: "file";
             exec: "exec";
+            env: "env";
         }>;
         provider: z.ZodString;
         id: z.ZodString;
@@ -88,9 +88,9 @@ export declare const GatewayConfigSchema: z.ZodObject<{
         /** The secret value (min 32 chars; resolved at runtime if omitted; string or SecretRef) */
         secret: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
             source: z.ZodEnum<{
-                env: "env";
                 file: "file";
                 exec: "exec";
+                env: "env";
             }>;
             provider: z.ZodString;
             id: z.ZodString;